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. 发布与版本管理

一键发布（GitHub Actions + GitHub/Gitee 同步）

发布前需要具备：

• 已把仓库推到 GitHub，并配置好 GitHub Actions
• 已在 npm 包设置里把 GitHub Actions 设成 trusted publisher
• 当前 git 分支可推送到 github
• 若配置了 origin（Gitee），发版时会一并同步推送
• 工作区干净，没有未提交改动
• 当前平台已重新安装依赖；若从 Windows/WSL 混用 node_modules，请先重新执行 pnpm install

推荐直接使用：

pnpm release:patch
# 或
pnpm release:minor
# 或
pnpm release:major

也可以指定任意版本号：

pnpm release 2.0.4

默认流程：

1. 执行 pnpm run check
2. 执行 pnpm run build
3. 更新 package.json 版本号
4. 执行 pnpm pack --dry-run
5. 提交 chore(release): vX.Y.Z
6. 打 tag：vX.Y.Z
7. 推送当前分支和 tag 到 github
8. 若存在 origin，同步推送当前分支和 tag 到 Gitee
9. GitHub Actions 接收到 GitHub tag 后执行 npm publish

如果只想本地做版本号更新，不推仓库，可用：

pnpm release patch --no-push

如果只想推单个远程，可显式指定：

pnpm release patch --remote github
pnpm release patch --remote origin

如果还想保留本地直接发 npm 的旧流程，可显式加：

pnpm release patch --publish-npm

版本策略建议

• 遵循 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