// Package audio 提供基于 oto/v3 的音频播放功能。
//
// 播放模式:
//   - 一次性播放: PlayWav(), PlayMP3() - 阻塞直到完成或 context 取消
//   - 循环播放: PlayMP3Loop() - 非阻塞,返回 player 和清理函数
//
// 使用示例:
//
//	// 一次性播放 WAV
//	err := audio.PlayWav(ctx, wavReader)
//	if err != nil && !errors.Is(err, context.Canceled) {
//	    log.Printf("播放失败: %v", err)
//	}
//
//	// 循环播放 MP3
//	player, cleanup, err := audio.PlayMP3Loop(mp3Reader)
//	if err != nil {
//	    return err
//	}
//	defer cleanup()
//	// ... 播放中 ...
//
// 采样率说明:
//   - 统一采样率：固定使用 16000 Hz（TTS 原生采样率）
//   - oto/v3 只支持一个全局 Context，统一采样率可避免冲突
//   - 其他采样率会自动重采样到 16000 Hz（线性插值）
//   - 16000 Hz 音频（TTS）：正常速度 ✅
//   - 44100 Hz 音频（BGM）：自动重采样，正常速度 ✅
//   - 其他采样率：自动重采样，正常速度 ✅
//
// 资源管理:
//   - 一次性播放: 函数内部自动管理所有资源
//   - 循环播放: 调用者必须调用 defer cleanup() 清理资源
package audio