ueplayer

自定义 UE Pixel Streaming 播放器组件库。

该库依赖你的 UE / MatchMaker / 信令服务端实现，不是开箱即用的通用播放器。

1. 安装

pnpm add ueplayer
# or
npm i ueplayer
# or
yarn add ueplayer

包名：ueplayer

2. Peer Dependencies（必须由业务项目安装）

本库不会把以下依赖打进产物，需由使用方自行安装：

• react：>=18.2.0 <20
• react-dom：>=18.2.0 <20
• lodash：^4.17.21

如果未安装或版本不满足，包管理器会给出 peer warning，运行时也可能异常。

3. 使用方式

Vite / Webpack / Rspack 都按根入口使用即可：

import { Player, Resolutions, UePlayer, type CommonUeSendCommand } from 'ueplayer';

function onVideoReady(player: UePlayer) {
  player.emitUIInteraction({
    command: 'freezeFrame',
    params: null,
  });

  player.on('closeClient', (payload: CommonUeSendCommand['results']) => {
    console.log('closeClient', payload);
  });
}

export default function App() {
  return (
    <Player
      appName="haitai"
      resolution={Resolutions.auto}
      enableAudio
      afkTimeoutSeconds={180}
      videoReadyCallback={onVideoReady}
    />
  );
}

4. Player 参数

| 参数 | 类型 | 默认值 | 说明 | |---|---|---|---| | appName | string | - | 应用名称（必填） | | resolution | ResolutionConfig | auto | auto / 4k / 2k / 1080p / 720p | | enableAudio | boolean | false | 是否协商音频 | | afkTimeoutSeconds | number | 180 | 用户无操作超时断开（最小 60 秒，内部按 max(60, value) 处理） | | videoReadyCallback | (player: UePlayer) => void | undefined | 视频流就绪回调 | | className | string | '' | 容器额外类名 | | style | CSSProperties | undefined | 容器样式 |

5. 发布与版本管理

发布流程（npm）

1. 更新版本号（建议使用 npm version patch|minor|major）
2. 构建并自测
3. 发布：npm publish 或 pnpm publish
4. 使用方升级：pnpm up ueplayer / npm update ueplayer

版本策略建议

• 遵循 SemVer：
  • patch：修复问题，不改 API
  • minor：新增兼容能力
  • major：不兼容变更
• 每次发布必须是新版本号；同版本不能重复发布到 npm。
• 若你同时维护 README / API，请保持与当前导出一致，避免示例失真。

6. 音频策略说明

• enableAudio=false：前端不会协商音轨。
• enableAudio=true：会协商音轨，但浏览器仍可能要求用户首次交互后才允许播放声音（自动播放策略）。
• UE 侧若设置 -NOSOUND 或 -PixelStreamingWebRTCDisableTransmitAudio=true，前端开音频也不会有声音。

7. AFK（空闲断开）

用户输入会重置计时器；达到 afkTimeoutSeconds 后：

1. 向 UE 发送 freeze frame
2. 主动关闭 WebRTC 与 WebSocket

8. UE 侧码率参数建议

前端 x-google-* 参数不一定能强限制 UE 编码输出；强制限码率请在 UE 启动参数里配置。

推荐（2K60、100Mbps、可能走转发）：

-PixelStreamingWebRTCMaxBitrate=25000000
-PixelStreamingEncoderMaxBitrate=30000000

更保守（带宽更紧张）：

-PixelStreamingWebRTCMaxBitrate=20000000
-PixelStreamingEncoderMaxBitrate=25000000