npm package: @songjianbo/opus-decoder-sdk
Description: 独立的 Opus 音频解码 SDK，支持 Ogg 容器解析、实时解码播放，无 UI 依赖
Author: songjianbo
Latest version: 1.0.3

# 📦 Opus 解码器 SDK

> 独立的 Opus 音频解码 SDK，支持 Ogg 容器解析、实时解码播放，无 UI 依赖，可在任何项目中使用

## 📚 目录

- [📚 目录](#目录)
- [📦 安装](#安装)
- [🚀 快速开始](#快速开始)
-   [最简单的使用（3行代码）](#最简单的使用3行代码)
-   [完整示例](#完整示例)
- [📖 使用场景](#使用场景)
-   [场景 1: 简单文件解码和播放](#场景-1-简单文件解码和播放)
-   [场景 2: 实时音频推送（WebSocket）](#场景-2-实时音频推送websocket)
-   [场景 3: 低延迟实时播放](#场景-3-低延迟实时播放)
- [📚 API 文档](#api-文档)
-   [OpusDecoderSDK（高级 API）](#opusdecodersdk高级-api)
-     [构造函数](#构造函数)
-     [主要方法](#主要方法)
-   [OpusFramePlayer（分块播放器）](#opusframeplayer分块播放器)
-     [构造函数](#构造函数)
-     [主要方法](#主要方法)
-   [RealtimeOpusService（实时流式服务）](#realtimeopusservice实时流式服务)
-     [构造函数](#构造函数)
-     [主要方法](#主要方法)
- [⚙️ 配置说明](#配置说明)
-   [采样率](#采样率)
-   [声道数](#声道数)
- [🎯 如何选择 API？](#如何选择-api)
- [📚 相关文档](#相关文档)
-   [📖 入门文档（推荐新手）](#入门文档推荐新手)
-   [📘 核心文档](#核心文档)
-   [🔧 技术文档](#技术文档)
-   [🌐 其他文档](#其他文档)
-   [在线访问](#在线访问)
- [⚠️ 重要提示](#重要提示)
-   [OpusDecoder 加载](#opusdecoder-加载)
- [🔧 故障排除](#故障排除)
-   [错误：OpusDecoder 未找到](#错误opusdecoder-未找到)
-   [错误：无法导入模块](#错误无法导入模块)
- [💡 最佳实践](#最佳实践)
-   [1. 资源管理](#1-资源管理)
-   [2. 错误处理](#2-错误处理)
-   [3. 采样率匹配](#3-采样率匹配)
- [📄 许可证](#许可证)
- [🔗 相关链接](#相关链接)

---

## 📦 安装

```bash
npm install @songjianbo/opus-decoder-sdk
```

---

## 🚀 快速开始

### 最简单的使用（3行代码）

```javascript
import { OpusDecoderSDK } from '@songjianbo/opus-decoder-sdk';

const sdk = new OpusDecoderSDK();
await sdk.decodeAndPlay(file);
```

### 完整示例

```javascript
import { OpusDecoderSDK } from '@songjianbo/opus-decoder-sdk';

// 创建 SDK 实例
const sdk = new OpusDecoderSDK({
    sampleRate: 48000,
    channels: 2
});

// 监听事件
sdk.on('progress', (progress, message) => {
    console.log(`进度: ${progress}% - ${message}`);
});

sdk.on('decodeComplete', (audio) => {
    console.log('解码完成！', audio);
});

// 处理文件
async function handleFile(file) {
    try {
        // 解码文件
        const decoded = await sdk.decodeFile(file);
        
        // 播放
        await sdk.play(decoded);
    } catch (error) {
        console.error('失败:', error);
    }
}

// 使用
document.getElementById('fileInput').addEventListener('change', (e) => {
    handleFile(e.target.files[0]);
});
```

---

## 📖 使用场景

### 场景 1: 简单文件解码和播放

**推荐使用：`OpusDecoderSDK`**

```javascript
import { OpusDecoderSDK } from '@songjianbo/opus-decoder-sdk';

const sdk = new OpusDecoderSDK();

// 方式 1: 一步到位（最简单）
await sdk.decodeAndPlay(file);

// 方式 2: 分步操作（更灵活）
const audio = await sdk.decodeFile(file);
await sdk.play(audio);

// 播放控制
sdk.pause();      // 暂停
await sdk.resume(); // 恢复
sdk.stop();       // 停止
```

### 场景 2: 实时音频推送（WebSocket）

**推荐使用：`OpusFramePlayer`**

```javascript
import { OpusFramePlayer } from '@songjianbo/opus-decoder-sdk';

const player = new OpusFramePlayer({
    sampleRate: 48000,
    channels: 2,
    autoPlay: true,
    batchSize: 5
});

// WebSocket 接收并推送帧
const websocket = new WebSocket('ws://example.com/audio');

websocket.onmessage = async (event) => {
    const opusFrame = new Uint8Array(event.data);
    await player.pushFrame(opusFrame);
};

// 播放控制
player.pause();      // 暂停
await player.resume(); // 恢复
player.stop();     // 停止
```

### 场景 3: 低延迟实时播放

**推荐使用：`RealtimeOpusService`**

```javascript
import { RealtimeOpusService } from '@songjianbo/opus-decoder-sdk';

const service = new RealtimeOpusService({
    sampleRate: 48000,
    channels: 2,
    bufferSize: 8192,
    minQueueSize: 5
});

// 初始化
await service.initialize();

// 开始播放
await service.start();

// WebSocket 接收并实时播放
const websocket = new WebSocket('ws://example.com/audio');

websocket.onmessage = async (event) => {
    const opusFrame = new Uint8Array(event.data);
    await service.decodeFrame(opusFrame);
};

// 停止播放
service.stop();
```

---

## 📚 API 文档

### OpusDecoderSDK（高级 API）

最简单的使用方式，适合大多数场景。

#### 构造函数

```javascript
const sdk = new OpusDecoderSDK({
    sampleRate: 48000,  // 采样率（默认：48000）
    channels: 2,        // 声道数（默认：2）
    useWorker: false    // 使用 Worker（默认：false）
});
```

#### 主要方法

- `decodeAndPlay(file, options)` - 解码并播放文件
- `decodeFile(file, options)` - 仅解码文件
- `play(decodedAudio)` - 播放已解码的音频
- `pause()` - 暂停播放
- `resume()` - 恢复播放
- `stop()` - 停止播放
- `isPlaying()` - 获取播放状态
- `dispose()` - 释放资源

### OpusFramePlayer（分块播放器）

适合实时推送场景，支持播放控制。

#### 构造函数

```javascript
const player = new OpusFramePlayer({
    sampleRate: 48000,
    channels: 2,
    autoPlay: true,
    batchSize: 5
});
```

#### 主要方法

- `loadFile(file)` - 从文件加载并解析所有 Opus 帧
- `pushFrame(opusFrame)` - 推送帧数据（立即解码并创建块）
- `play()` - 开始播放
- `pause()` - 暂停播放
- `resume()` - 恢复播放
- `stop()` - 停止播放
- `getDecodedChunkCount()` - 获取已解码的块数量
- `reset()` - 重置播放器状态
- `dispose()` - 释放资源

### RealtimeOpusService（实时流式服务）

适合低延迟实时播放场景。

#### 构造函数

```javascript
const service = new RealtimeOpusService({
    sampleRate: 48000,
    channels: 2,
    bufferSize: 8192,
    minQueueSize: 5,
    maxQueueSize: 50
});
```

#### 主要方法

- `initialize()` - 初始化解码器和音频上下文
- `decodeFrame(opusFrame)` - 解码单帧并加入播放队列
- `start()` - 开始播放
- `stop()` - 停止播放
- `dispose()` - 释放资源

---

## ⚙️ 配置说明

### 采样率

Opus 解码器支持以下采样率：`8000, 12000, 16000, 24000, 48000` Hz

```javascript
const sdk = new OpusDecoderSDK({
    sampleRate: 48000  // 推荐：音乐使用 48000，语音使用 16000
});
```

详细说明请查看 [采样率说明](https://github.com/xiaosongaccount/opus-decoder-web/blob/HEAD/docs/采样率说明.md)

### 声道数

支持单声道（1）和立体声（2）

```javascript
const sdk = new OpusDecoderSDK({
    channels: 2  // 1 = 单声道，2 = 立体声
});
```

---

## 🎯 如何选择 API？

| 场景 | 推荐 API | 原因 |
|------|---------|------|
| 简单文件播放 | `OpusDecoderSDK` | 最简单，3行代码 |
| 实时推送 + 播放控制 | `OpusFramePlayer` | 支持暂停/跳转 |
| 低延迟实时播放 | `RealtimeOpusService` | 延迟最低 |
| 细粒度控制 | 底层服务 | 完全控制 |

详细对比请查看 [OpusFramePlayer与RealtimeOpusService对比](https://github.com/xiaosongaccount/opus-decoder-web/blob/HEAD/docs/OpusFramePlayer与RealtimeOpusService对比.md)

---

## 📚 相关文档

> 💡 **提示**：所有文档都在 GitHub 仓库的 `docs/` 目录中，点击下面的链接即可查看。

### 📖 入门文档（推荐新手）

- **[安装和集成](https://github.com/xiaosongaccount/opus-decoder-web/blob/HEAD/docs/安装和集成.md)** ⭐ - npm 安装、opus-decoder.js 加载和集成方式
- **[学习指南](https://github.com/xiaosongaccount/opus-decoder-web/blob/HEAD/docs/学习指南.md)** ⭐⭐ - 从零开始学习 SDK 的完整指南（推荐新手）
- **[简单示例](https://github.com/xiaosongaccount/opus-decoder-web/blob/HEAD/docs/简单示例.md)** ⭐ - 最简单的使用方式（5行核心代码）

### 📘 核心文档

- **[使用指南](https://github.com/xiaosongaccount/opus-decoder-web/blob/HEAD/docs/使用指南.md)** ⭐ - 完整的 SDK 使用指南，涵盖所有使用场景和 API 参考

### 🔧 技术文档

- **[原理说明](https://github.com/xiaosongaccount/opus-decoder-web/blob/HEAD/docs/原理说明.md)** - 技术原理详解（Ogg、Opus、WebAssembly）
- **[架构说明](https://github.com/xiaosongaccount/opus-decoder-web/blob/HEAD/docs/架构说明.md)** - 项目架构设计
- **[采样率说明](https://github.com/xiaosongaccount/opus-decoder-web/blob/HEAD/docs/采样率说明.md)** - 采样率配置说明
- **[ArrayBuffer与Uint8Array区别](https://github.com/xiaosongaccount/opus-decoder-web/blob/HEAD/docs/ArrayBuffer与Uint8Array区别.md)** - 数据类型说明
- **[OpusFramePlayer与RealtimeOpusService对比](https://github.com/xiaosongaccount/opus-decoder-web/blob/HEAD/docs/OpusFramePlayer与RealtimeOpusService对比.md)** - 播放器对比

### 🌐 其他文档

- **[WebSocket 使用指南](https://github.com/xiaosongaccount/opus-decoder-web/blob/HEAD/docs/README-websocket.md)** - WebSocket 实时推送说明
- **[获取测试文件](https://github.com/xiaosongaccount/opus-decoder-web/blob/HEAD/docs/获取测试文件.md)** - 如何获取 Opus 测试文件
- **[贡献指南](https://github.com/xiaosongaccount/opus-decoder-web/blob/HEAD/docs/贡献指南.md)** - 如何贡献代码

### 在线访问
- **GitHub 仓库**: https://github.com/xiaosongaccount/opus-decoder-web
- **npm 包页面**: https://www.npmjs.com/package/@songjianbo/opus-decoder-sdk

---

## ⚠️ 重要提示

### OpusDecoder 加载

`opus-decoder.js` 是 UMD 格式，需要先加载才能使用 SDK。

**方式 1: script 标签（推荐）**

```html
<script src="./node_modules/@songjianbo/opus-decoder-sdk/dist/opus/opus-decoder.js"></script>
<script type="module">
    import { OpusDecoderSDK } from '@songjianbo/opus-decoder-sdk';
    // ...
</script>
```

**方式 2: 动态导入**

```javascript
await import('@songjianbo/opus-decoder-sdk/dist/opus/opus-decoder.js');
import { OpusDecoderSDK } from '@songjianbo/opus-decoder-sdk';
```

详细说明请查看 [安装和集成.md](../../docs/安装和集成.md)

---

## 🔧 故障排除

### 错误：OpusDecoder 未找到

**原因**：`opus-decoder.js` 未加载

**解决**：
1. 确保在 HTML 中添加了 script 标签
2. 检查文件路径是否正确
3. 检查浏览器控制台是否有加载错误

### 错误：无法导入模块

**原因**：构建工具配置问题

**解决**：
1. 确保使用支持 ES 模块的构建工具
2. 检查 `package.json` 中 `"type": "module"` 是否正确
3. 使用动态导入代替静态导入

---

## 💡 最佳实践

### 1. 资源管理

```javascript
const sdk = new OpusDecoderSDK();

try {
    await sdk.decodeAndPlay(file);
    // ... 使用音频
} finally {
    sdk.dispose();  // 释放资源
}
```

### 2. 错误处理

```javascript
try {
    const audio = await sdk.decodeFile(file);
    await sdk.play(audio);
} catch (error) {
    console.error('解码或播放失败:', error);
    // 处理错误
}
```

### 3. 采样率匹配

```javascript
// 确保采样率匹配（无损播放）
const sdk = new OpusDecoderSDK({
    sampleRate: 48000  // 与音频文件采样率一致
});
```

---

## 📄 许可证

[MIT License](./LICENSE)

---

## 🔗 相关链接

- **GitHub 仓库**: https://github.com/xiaosongaccount/opus-decoder-web
- **npm 包页面**: https://www.npmjs.com/package/@songjianbo/opus-decoder-sdk
- **问题反馈**: https://github.com/xiaosongaccount/opus-decoder-web/issues