如何使用

这是自定义的虚幻引擎像素流推送播放器，需要配合自建的Match Maker，不要浪费时间下载。

1 安装

使用pnpm从git仓库安装，具体的语法见：从git安装npm

pnpm install ueplayer

安装完成后的包名叫：ueplayer

2 更新与发布

这里分两种使用方式：

A. 通过 git 依赖安装

1. 更新代码后运行 pnpm run build
2. 提交并推送到 git 仓库
3. 依赖仓库执行 pnpm update ueplayer 或重新安装

B. 发布到 npm（推荐）

1. 先更新 package.json 的 version（或使用 npm version patch|minor|major）
2. 运行 pnpm run build
3. 执行 npm publish（或 pnpm publish）
4. 依赖仓库执行 pnpm update ueplayer

版本维护说明

• 如果走 npm 发布，每次发布都必须是新版本号（需要你自己维护）。
• 如果走 git 依赖，版本号不会被 npm 校验，但建议保持递增，方便追踪。

3 使用

import { Player } from 'ueplayer'; // for vite user

import { Player, Resolutions } from 'ueplayer/build/player' // for webpack user
import 'ueplayer/build/style.css' // for webpack user

function onVideoReady(player: UePlayer) {
    console.log('player loaded and ready to use')
    setTimeout(() => {
        player.emitUIInteraction({
            command: 'freezeFrame',
            params: null
        })
    }, 5000)
}
<Player
    appName="haitai"
    resolution={'auto'}
    enableAudio={true}
    afkTimeoutSeconds={180}
    videoReadyCallback={onVideoReady}
/>

4 参数

注意：api可能随时更新

| 参数 | 类型 | 默认值 | 说明 | |--------------------|----------|------|-------------------------------| | appName | string | - | 应用名称，必填，具体应用名称需要参考数据库 | | resolution | string | auto | 分辨率，可选值：auto、4k、2k、1080p、720p | | enableAudio | boolean | false | 是否协商音频，开启后需要用户首次点击播放区域解锁声音 | | afkTimeoutSeconds | number | 180 | 用户无操作超时断开（最小 60 秒，实际使用 max(60, value)） | | videoReadyCallback | function | null | 视频加载完成后的回调函数，传入UePlayer参数 |

videoReadyCallback的签名如下：

type videoReadyCallback = (player: UePlayer) => void

interface UePlayer {
    emitUIInteraction(descriptor: {
        command: string;
        params: any;
    }): void;
    emitCommand(descriptor: any): void;
    on(command: string, listener: (para: CommonUeSendCommand) => void): void;
}

type CommonUeSendCommand = {
    command: string;
    results: any;
}

5 音频策略说明

• enableAudio=false 时，前端不会协商音轨，UE 不会向浏览器发送音频。
• enableAudio=true 时，前端会协商音轨，但浏览器仍需要用户首次点击播放器区域才能解锁播放（自动播放策略限制）。
• UE 侧如果使用了 -NOSOUND 或 -PixelStreamingWebRTCDisableTransmitAudio=true，即使前端开启音频也不会有声音。

6 AFK（空闲断开）

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

• 先向 UE 发送 freeze frame
• 再主动关闭 WebRTC 与 WebSocket

7 UE 侧推荐参数

前端的 x-google-* 码率提示不一定能限制 UE 编码器输出，强制限码率建议在 UE 启动参数中配置。

分档建议（单位：bps，1 Mbps = 1000000 bps）：

| 目标 | PixelStreamingWebRTCMaxBitrate | PixelStreamingEncoderMaxBitrate | 备注 | |------|--------------------------------|---------------------------------|------| | 2K30 | 20000000 ~ 30000000 | 25000000 ~ 35000000 | 画质与带宽平衡 | | 2K60 | 30000000 ~ 50000000 | 35000000 ~ 60000000 | 动作场景更稳 | | 4K30 | 50000000 ~ 80000000 | 60000000 ~ 90000000 | 需要更高带宽 | | 4K60 | 80000000 ~ 120000000 | 90000000 ~ 140000000 | 高带宽场景 |

如果你的链路上限是 100Mbps 或需要转发，尽量取每档的下限。

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

-PixelStreamingWebRTCMaxBitrate=25000000
-PixelStreamingEncoderMaxBitrate=30000000

更保守（带宽更紧张）：

-PixelStreamingWebRTCMaxBitrate=20000000
-PixelStreamingEncoderMaxBitrate=25000000

音频建议：

• 需要播放声音：不要设置 -NOSOUND 和 -PixelStreamingWebRTCDisableTransmitAudio=true
• 不需要麦克风回传：可保留 -PixelStreamingWebRTCDisableReceiveAudio=true