基于 react-360 的自定义视频播放器实战：CustomPlayerSample 与 MPEG-DASH 接入全解析

• 前端
• 3D渲染

react-360 的默认视频能力依赖浏览器原生<video>标签，但在播放 MPEG-DASH、HLS 这类自适应码率流时能力不足。官方示例 Samples/CustomPlayerSample 演示了如何通过customVideoPlayers选项接入自定义视频播放器（如 dash.js），本文以该示例为核心，结合 VideoPlayerManager.js、BrowserVideoPlayer.js 与 VideoModule.js 等底层实现，完整讲解自定义播放器的编写、注册、选型与调用全链路。读完本文，你将掌握在 react-360 应用中接入任意视频协议（DASH/HLS/自定义解码器）的标准方法。

一、示例概览：为什么需要自定义视频播放器

CustomPlayerSample的核心目标是：在 360 全景世界中，用 MPEG-DASH（通过 dash.js）播放自适应码率视频。默认情况下，react-360 使用 BrowserVideoPlayer 作为唯一的视频播放实现，它依赖浏览器的原生能力（video/mp4、video/webm等），不具备分片流协议的解析能力。

按照官方文档 example-customplayer.md 的描述，接入自定义播放器只需三个步骤：

1. 编写一个实现VideoPlayerImplementation接口的自定义视频播放器，通常直接继承BrowserVideoPlayer以复用大部分视频控制代码；
2. 在初始化ReactInstance时通过customVideoPlayers选项注册你的自定义播放器；
3. react-360 的 Video 模块会按自定义播放器的注册顺序逐一查询，选出第一个支持视频源fileFormat的播放器来实际播放。

示例目录结构如下：

Samples/CustomPlayerSample/ ├── DashVideoPlayer.js # 自定义播放器：继承 BrowserVideoPlayer + dash.js ├── client.js # 宿主侧：初始化 ReactInstance 并注册自定义播放器 ├── index.js # React 侧：创建播放器并开始播放 DASH 视频 ├── index.html └── static_assets/ # 静态资源（chess-world.jpg 全景背景）

二、编写自定义播放器：DashVideoPlayer 源码剖析

示例的自定义播放器位于 Samples/CustomPlayerSample/DashVideoPlayer.js，完整代码只有约 20 行：

/** * A very simple Mpeg-Dash video player. */ import {BrowserVideoPlayer} from 'react-360-web'; export default class DashVideoPlayer extends BrowserVideoPlayer { constructor() { super(); this.player = dashjs.MediaPlayer().create(); this.player.setScheduleWhilePaused(true); } setSource(src: string, stereoFormat: string, fileFormat: string) { super.setSource('', stereoFormat, fileFormat); this.player.initialize(this._element, src, false); } destroy() { this.player.reset(); super.dispose(); } }

2.1 为什么继承 BrowserVideoPlayer 是捷径

从 BrowserVideoPlayer.js 的实现可以看出，这个基类几乎完成了所有「脏活」：

• 媒体事件转发：构造器中监听seeked、ended、waiting、playing、timeupdate、pause等事件，并统一通过_updateStatus派发status事件（包含duration、position、isBuffering、volume、status等字段）；
• 纹理管理：setSource中在canplay回调里创建THREE.Texture，并设置ClampToEdgeWrapping与LinearFilter，将视频画面作为 WebGL 纹理供 3D 场景使用；
• 控制能力：play、pause、seekTo、setVolume、setMuted、setLoop、load、update一应俱全；
• 格式探测：静态方法getSupportedFormats()通过document.createElement('video').canPlayType(...)检测浏览器真实支持的容器格式（ogg、mp4、mkv、webm），并缓存结果。

因此自定义播放器只需关注「如何把视频内容喂给基类创建好的_element（HTMLVideoElement）」即可。这正是DashVideoPlayer的做法：

setSource(src, stereoFormat, fileFormat) { super.setSource('', stereoFormat, fileFormat); // 复用基类纹理创建与状态机 this.player.initialize(this._element, src, false); // 让 dash.js 接管该 video 元素 }

dashjs.MediaPlayer().create()创建的播放器会接管this._element（基类构造器中创建的、隐藏的<video>元素），并实现分片下载、码率自适应等逻辑。setScheduleWhilePaused(true)表示暂停状态下也继续调度分片请求，方便预加载。

2.2 接口契约：VideoPlayerImplementation

如果不想继承BrowserVideoPlayer，也可以从零实现接口。接口定义位于 React360/js/Compositor/Video/Types.js：

export interface VideoPlayerImplementation { constructor(src: string): void; destroy(): void; load(): Promise<TextureMetadata>; pause(): void; play(): void; update(): void; seekTo(position: number): void; setMuted(muted: boolean): void; setLoop(loop: boolean): void; setSource(url: string, stereoformat: string, fileFormat: string, layout?: string): void; setVolume(vol: number): void; addEventListener(event: string, listener: VideoEventListener): void; removeEventListener(event: string, listener: VideoEventListener): void; } export type VideoPlayerStatics = { getSupportedFormats(): Array<string>, };

值得注意的关键约束：

• 静态方法getSupportedFormats()是必须实现的（VideoPlayerStatics），它返回该播放器支持的文件格式列表，是选型机制的核心依据；
• load()需要返回Promise<TextureMetadata>，其中包含format（立体格式）、layout、width、height、src和tex（THREE.Texture），Video 模块会据此在 3D 环境中正确呈现画面；
• 状态机取值见VideoPlayerStatus：closed / closing / failed / finished / paused / playing / seeking / ready / stopped，自定义实现需要通过status事件向上层同步状态。

三、注册自定义播放器：ReactInstance 的 customVideoPlayers 选项

宿主侧代码位于 Samples/CustomPlayerSample/client.js：

import {ReactInstance} from 'react-360-web'; import DashVideoPlayer from './DashVideoPlayer'; function init(bundle, parent, options = {}) { const r360 = new ReactInstance(bundle, parent, { fullScreen: true, customVideoPlayers: [DashVideoPlayer], ...options, }); r360.renderToSurface( r360.createRoot('CustomPlayerSample', { /* initial props */ }), r360.getDefaultSurface() ); r360.compositor.setBackground(r360.getAssetURL('chess-world.jpg')); } window.React360 = {init};

customVideoPlayers接受一个播放器实现类的数组（而非实例）。从 ReactInstance.js 的类型定义可见其类型为Array<Class<VideoPlayerImplementation>>，并在构造时透传给 Compositor：

this.compositor = new Compositor(this._eventLayer, this.scene, options.customVideoPlayers);

再看 Compositor.js 的构造逻辑——注册顺序至关重要：

this._videoPlayers = new VideoPlayerManager(); if (customVideoPlayers) { for (const player of customVideoPlayers) { this._videoPlayers.registerPlayerImplementation(player); } } this._videoPlayers.registerPlayerImplementation(BrowserVideoPlayer); // 兜底

也就是说：你提供的自定义播放器永远排在前面，内置的BrowserVideoPlayer永远作为最后的兜底。这意味着即使某个格式自定义播放器不支持，只要浏览器原生支持，视频仍可播放。

四、选型机制：VideoPlayerManager 如何「按顺序挑第一个」

选型的核心实现在 React360/js/Compositor/Video/VideoPlayerManager.js，三个关键方法：

registerPlayerImplementation(impl: Class<VideoPlayerImplementation>) { this._playerImplementations.push(impl); } createPlayerImplementation(format: string) { for (const Impl of this._playerImplementations) { const supported = Impl.getSupportedFormats(); if (supported.indexOf(format) > -1) { return new Impl(); } } throw new Error(`No registered player supports ${format} files.`); } getSupportedFormats() { // 汇总所有已注册播放器支持的格式，去重后缓存 }

机制可以归纳为：

1. 所有实现（自定义的在前，BrowserVideoPlayer兜底在后）被压入_playerImplementations数组；
2. 当需要创建播放器时，遍历数组，调用每个实现的静态getSupportedFormats()；
3. 命中第一个包含目标fileFormat的实现即实例化并返回；
4. 全部不命中则抛出No registered player supports ${format} files.错误。

而薄封装层 VideoPlayer.js 负责实现与上层解耦：setSource时先销毁旧实现，再由VideoPlayerManager按格式选出新实现，并将实现的status事件转发出去。这种「播放器生命周期与具体内容分离」的设计，允许同一 handle 在不同格式间动态切换实现。

五、VideoModule.play：fileFormat 的推导与匹配

React 侧通过VideoModule发起播放，示例 Samples/CustomPlayerSample/index.js 中定义了带多来源的播放参数：

import VideoModule from 'VideoModule'; import * as Environment from 'Environment'; const VIDEO_PLAYER = 'dash_video'; const VIDEO_SOURCE = [ { url: asset('video_dash_mp4/video_stream.mpd').uri, fileFormat: 'mp4', }, { url: asset('video_dash_webm/video_stream.mpd').uri, fileFormat: 'webm', } ]; class CustomPlayerSample extends React.Component { componentDidMount() { VideoModule.createPlayer(VIDEO_PLAYER); VideoModule.play(VIDEO_PLAYER, { source: VIDEO_SOURCE, stereo: '2D', }); Environment.setScreen('default', VIDEO_PLAYER, 'default', 0, 0, 1000, 600); } // ... }

在 VideoModule.js 的play实现中，当source是数组时会进行多来源回退协商：

if (Array.isArray(source)) { url = source[0].url; const supported = this._videoPlayers.getSupportedFormats(); for (let i = 0; i < source.length; i++) { const sourceOption = source[i]; const format = sourceOption.fileFormat || getExt(sourceOption.url); // 未显式指定时从扩展名推导 if (supported.indexOf(format) > -1) { url = sourceOption.url; fileFormat = format; break; } } }

对应到示例：

• 首选mp4格式的.mpd清单（video_dash_mp4/video_stream.mpd），由于自定义播放器声明支持mp4（继承了基类的getSupportedFormats），会命中DashVideoPlayer；
• 若该格式不被任何注册播放器支持，则继续检查webm来源；
• 若两者都不支持，抛出Cannot play video, unsupported format。

注意：getExt仅从 URL 末段提取扩展名（去掉 query 与 hash），因此.mpd文件若不显式声明fileFormat，会被误判为mpd格式——这正是示例必须为每个mpd来源显式写fileFormat: 'mp4' | 'webm'的原因。

此外VideoModule.play还依次处理了stereo（默认'2D'）、layout（默认'RECT'）、startPosition定位，并在load()完成后根据autoPlay（默认 true）自动调用play()。

六、在 VR 环境中呈现：Environment.setScreen

示例最后用Environment.setScreen('default', VIDEO_PLAYER, 'default', 0, 0, 1000, 600)把播放器画面放到一个 1000×600 的「屏幕」上，位置参数(x, y)为(0, 0)，表示位于默认摄像机前方。Environment模块是 react-360 官方的原生模块（见 Libraries/VRModules/Environment.js），setScreen用于把一个视频或图像内容挂载到 3D 空间中的矩形屏幕表面，是「在 VR 中观看平面视频」的标准姿势——即使 App 组件本身render() { return null; }，视频依然可以通过 compositor 渲染在场景中。

七、运行与验证

7.1 资源准备

官方文档（example-customplayer.md 与 Samples/CustomPlayerSample/README.md）明确指出：DASH 视频资源体积较大，未包含在仓库中，需从外部下载asset.tar.gz并解压到static_assets/目录。另外dashjs作为第三方库，也需要在index.html中引入（脚本标签方式即可，DashVideoPlayer.js中直接以全局dashjs引用）。

7.2 运行步骤

1. 使用 React 360 CLI 创建新项目；
2. 将Samples/CustomPlayerSample下的client.js、index.js、index.html、DashVideoPlayer.js复制到项目对应目录；
3. 将 DASH 资源解压到static_assets/；
4. 启动开发服务器，访问http://localhost:8081/index.html。

预期效果：看到 360 全景背景（chess-world.jpg），正面悬浮播放 MPEG-DASH 视频，播放行为（码率自适应等）由 dash.js 接管，而播放状态（进度、缓冲等）仍通过VideoModule的onVideoStatusChanged事件对外同步。

八、扩展要点与注意事项

• 多协议并存：customVideoPlayers数组可注册多个实现，选型按数组顺序进行；若你的自定义播放器恰好能支持浏览器原生格式，它也会被优先选中。
• 复用大于重写：绝大多数协议播放器（dash.js、hls.js 等）都能驱动 HTMLVideoElement，因此「继承BrowserVideoPlayer+ 协议库接管_element」是最省力的接入模式；只有需要完全自定义解码/渲染（如 360 视频特殊映射）时才需从零实现接口。
• 格式声明要准确：fileFormat既可通过source.fileFormat显式声明，也会从 URL 扩展名推导；流媒体清单文件（.mpd、.m3u8）务必显式声明其真实容器格式。
• 资源生命周期：自定义播放器应在destroy()中释放协议库资源（示例中调用dashjs的reset()），再调用基类的dispose()，避免播放器切换（VideoPlayer.setSource会先销毁旧实现）时泄漏。
• 兜底机制：即使自定义播放器无法处理某个格式，内置BrowserVideoPlayer仍可兜底，保证兼容性下限（详见 Compositor.js 的注册逻辑）。

通过 CustomPlayerSample、VideoPlayerManager.js 与 VideoModule.js 三者对照阅读，即可完整掌握 react-360 自定义视频播放器「实现 → 注册 → 选型 → 播放」的整套扩展机制。

</output_article>

• 前端
• 3D渲染