# wrplayer

**Repository Path**: warom-org/wrplayer

## Basic Information

- **Project Name**: wrplayer
- **Description**: h5播放器
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-21
- **Last Updated**: 2026-02-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WRPlayer

WRPlayer 是一个统一的 Web 视频播放器 SDK，提供一致的 API 来播放多种流媒体协议（WebRTC、HLS、DASH、MP4 等），并可在原生 HTML 与 Next.js/React 环境中复用同一套核心代码。

## 特性

- **多协议支持**: WebRTC、HLS、DASH、MP4 等
- **自动类型检测**: 可从 URL 自动识别播放类型
- **统一 API**: `play/pause/stop/on/off` 等一致方法与事件
- **UMD + ESM 构建**: 一次构建，既可 `<script>` 引入（UMD），也可模块化 `import`（ESM）
- **SSR 友好**: 核心兼容 SSR，Next.js 适配器按需在客户端初始化
- **模块化架构**: `core`（核心）与 `adapters`（框架适配）清晰分离
- **WebRTC 增强**: 支持禁用音频（规避特定浏览器/流的音频解复用问题），并内置防重复协商的状态管理

## 项目结构

```
wrplayer/
├── core/                 # 核心播放器逻辑
│   ├── WRPlayer.js       # 播放器主类（直接内置 ZLMRTCClient）
│   └── ZLMRTCClient.js   # WebRTC 客户端库（已作为模块被 WRPlayer 引入）
├── adapters/
│   └── next/             # Next.js / React 适配器组件
├── demo/
│   ├── html/             # 原生 HTML + UMD 示例（可直接双击打开）
│   └── next/             # Next.js 示例项目
├── dist/                 # 构建产物（UMD / ESM）
├── rollup.config.js      # Rollup 构建配置
├── package.json          # 根项目脚本与依赖
└── README.md
```

## 构建

在项目根目录执行：

```bash
npm install
npm run build
```

生成产物：
- `dist/wrplayer.umd.js`（浏览器 `<script>` 直接引入）
- `dist/wrplayer.esm.js`（ES 模块）

> 提示：若要消除 Node 关于 ESM 的提示，可在根 `package.json` 增加 `"type": "module"`。

## 使用方法

### A. 原生 HTML（通过 UMD 包）

无需打包工具，只需在页面引入 UMD 文件：

```html
<!-- 1) 引入 UMD 包 -->
<script src="./dist/wrplayer.umd.js"></script>

<!-- 2) 视频与脚本 -->
<video id="player" controls autoplay muted style="width: 800px; height: 450px;"></video>
<script>
  const player = new WRPlayer({
    element: document.getElementById('player'),
    url: 'http://your-host/index/api/webrtc?...',
    // 可选：明确类型，也可不写走自动识别
    type: 'webrtc',
    autoplay: true,
    debug: true
    // 注意：ZLMRTCClient 已内置到 UMD 包，无需手动传入
  });

  player.on('ready', () => console.log('ready'));
  player.on('play', () => console.log('play'));
  player.on('connectionstatechange', ({ state }) => console.log('conn:', state));
  player.on('error', (err) => console.error('error', err));
</script>
```

**音频控制策略**：为避免常见的 SDP 协商问题，默认禁用音频。若需要音频，可手动启用：

```html
<script>
  // 方案一：默认配置（推荐）- 仅视频，避免 SDP 协商问题
  const player = new WRPlayer({
    element: document.getElementById('player'),
    url: 'http://your-host/index/api/webrtc?...',
    autoplay: true,
    debug: true
    // recvAudio 默认为 false，避免 "Failed to set up audio demuxing" 错误
  });

  // 方案二：明确禁用音频（与默认行为相同）
  const playerVideoOnly = new WRPlayer({
    element: document.getElementById('player'),
    url: 'http://your-host/index/api/webrtc?...',
    autoplay: true,
    debug: true,
    recvAudio: false,  // 明确禁用音频
    recvVideo: true    // 明确启用视频（默认值）
  });

  // 方案三：启用音频（实验性，有自动回退策略）
  const playerWithAudio = new WRPlayer({
    element: document.getElementById('player'),
    url: 'http://your-host/index/api/webrtc?...',
    autoplay: true,
    debug: true,
    recvAudio: true  // 启用音频，如失败会自动回退到仅视频
  });
</script>
```

**常见的 WebRTC 音频问题**：

如果您遇到类似的错误：
- `Failed to set up audio demuxing for mid='1'`
- `Session error description: Failed to set up audio demuxing`

这通常是由于客户端与流媒体服务器的音频编解码器不匹配导致的。解决方案：

1. **推荐**：使用 `recvAudio: false` 禁用音频接收
2. **强制方案**：如果仍有问题，使用 `webrtcConfig` 强制禁用：
   ```javascript
   const player = new WRPlayer({
     element: document.getElementById('player'),
     url: 'http://your-host/index/api/webrtc?...',
     recvAudio: false,
     webrtcConfig: {
       audioEnable: false,  // 强制禁用音频 transceiver
       videoEnable: true,   // 确保视频启用
       recvOnly: true       // 确保仅接收模式
     }
   });
   ```
3. 检查流媒体服务器是否正确配置音频编码
4. 如果必须使用音频，播放器会自动进行回退重试

### B. Next.js / React

示例项目位于 `demo/next/`：

```bash
cd demo/next
npm install
npm run dev   # 开发模式
# 或
npm run build && npm run start   # 生产模式
```

在页面中使用适配器组件：

```jsx
'use client';
import WRPlayerComponent from '../../../adapters/next';

export default function Page() {
  return (
    <WRPlayerComponent
      url="http://your-host/index/api/webrtc?..."
      type="webrtc"
      autoplay={true}
      controls={true}
      muted={true}
      recvAudio={false} // 推荐禁用音频，避免 SDP 协商问题
      recvVideo={true}
      // 如果仍有音频协商问题，使用强制配置
      webrtcConfig={{
        audioEnable: false,  // 强制禁用音频
        videoEnable: true,   // 确保视频启用
        recvOnly: true       // 确保仅接收模式
      }}
      onReady={() => console.log('播放器准备就绪')}
      onError={(err) => console.error('播放错误:', err)}
      debug={true}
    />
  );
}
```

> 说明：适配器已封装客户端初始化流程，SSR 环境下不会触发浏览器 API。

## API（核心类 `WRPlayer`）

### 构造函数

```js
new WRPlayer(options)
```

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| options.element | HTMLVideoElement | 是 | 用于播放的 `<video>` 元素 |
| options.url | string | 是 | 流/视频 URL |
| options.type | string | 否 | `webrtc`/`hls`/`dash`/`mp4`，缺省自动检测 |
| options.autoplay | boolean | 否 | 默认 `true` |
| options.debug | boolean | 否 | 默认 `false` |
| options.dependencies.hlsPath | string | 否 | hls.js CDN 或本地路径（按需） |
| options.dependencies.dashPath | string | 否 | dash.js CDN 或本地路径（按需） |
| options.recvAudio | boolean | 否 | WebRTC 是否接收音频（默认 `false`，可设为 `true` 启用，支持回退策略） |
| options.recvVideo | boolean | 否 | WebRTC 是否接收视频（默认 `true`） |
| options.webrtcConfig | Object | 否 | 透传给 `ZLMRTCClient.Endpoint` 的高级配置 |

> 注意：`ZLMRTCClient` 已在内部以 ES 模块方式引入并随构建打包，无需在外部传入。

### 方法

| 方法 | 说明 |
| --- | --- |
| `play()` | 开始/继续播放（WebRTC 下防重复协商） |
| `pause()` | 暂停（对 WebRTC 无效） |
| `stop()` | 停止并清理资源（WebRTC 下会重置内部状态） |
| `on(event, cb)` | 绑定事件 |
| `off(event, cb)` | 解绑事件 |
| `getPlayer()` | 获取底层实例（如 Hls.js） |

### 事件

| 事件 | 数据 | 说明 |
| --- | --- | --- |
| `ready` | `{ streams? }` | 播放器就绪 |
| `play` | `void` | 开始播放 |
| `pause` | `void` | 暂停 |
| `ended` | `void` | 播放结束 |
| `error` | `{ type, details }` | 错误事件 |
| `connectionstatechange` | `{ state }` | WebRTC 连接状态：`connecting`/`connected`/`failed`/`disconnected` |

## 常见问题

- **浏览器自动播放策略**：若需自动播放，建议设置 `muted=true`，或在用户交互后再调用 `play()`。
- **音频解复用报错（WebRTC）**：默认已禁用音频以避免此问题。如需音频可设 `recvAudio: true`，遇错误时播放器会自动回退到仅视频模式。
- **CDN 动态依赖**：仅 HLS/DASH 按需加载 `hls.js`/`dash.js`，可通过 `dependencies.hlsPath/dashPath` 指定路径。

## 许可证

MIT