as

Settings
Sign out
Notifications
Alexa
亚马逊应用商店
Ring
AWS
文档
Support
Contact Us
My Cases
新手入门
设计和开发
应用发布
参考
支持
原生
Skip to main content
使用Vega,可以在单个应用中同时渲染多达四个视频流。多流播放支持以下用例:
  • 体育多机位视图
  • 安防摄像头控制面板
  • 画中画 (PIP) 布局
  • 并排视频比较

先决条件

将您的应用设置成使用W3C媒体播放器。有关更多信息,请参阅媒体播放器设置。

表面和播放器

Vega上的视频播放使用W3C媒体API的两个部分,均从以下@amazon-devices/react-native-w3cmedia导出:
  • KeplerVideoSurfaceView: 一个创建渲染表面的React Native组件。它不管理播放。
  • VideoPlayer: 一个处理初始化、源代码加载和播放控制的命令式类。您可以用句柄将其连接到表面。

架构

播放器和渲染表面是独立的对象。应分别创建这两个对象,然后在表面准备就绪后使用表面句柄将其连接起来。

添加依赖项

打开应用中的package.json文件。在dependencies部分中,添加以下条目。

配置清单

视频播放需要在manifest.toml文件中声明媒体服务依赖项和权限。没有这些,媒体管道将无法初始化,表面渲染黑色。

布局示例

渲染单个视频流

以下示例定义了渲染一个视频流的VideoPane组件。

并排布局

以下示例渲染了两条宽度相等的流。

包含四个流的网格布局

以下示例在二乘二的网格中同时渲染四个流。

画中画布局

以下示例在全屏流上渲染一个较小的流。

Playback controls

以下示例将播放、暂停和搜索控制添加到了单个窗格中。

完整的并排示例

以下示例是一个完整的App.tsx文件,它并排渲染了两个视频流。

局限性和最佳实践

支持的内容

  • 无需数字版权管理 (DRM) 的清晰内容: 最多四个并发流
  • DRM内容: 一次一个流,因为基于Vega的Fire TV设备提供单个安全的视频解码器实例

性能注意事项

  • 每个流都会消耗GPU内存和解码资源
  • Vega虚拟设备使用软件解码支持四个并发的非DRM流

最佳实践

  • 错开流初始化以防止资源争用。
  • 分别处理每个流的错误,这样一个失败的流就不会使整个布局崩溃。
  • 为每个流使用不同的URL,而不是对同一个源代码进行四次解码。
  • 在useEffect()清理函数中调用clearSurfaceHandle('')和pause(),在组件卸载时释放资源。
  • 等待onSurfaceViewCreated()然后再调用setSurfaceHandle()。

错开流初始化

同时在所有四个播放器上调用initialize()会导致资源争用。以下示例向VideoPane添加了initDelay属性并将初始化错开了500毫秒。

故障排除

下表描述了常见的多流播放问题及其解决方案。

在Vega虚拟设备上进行测试

您可以在Vega虚拟设备上验证多流播放。Vega虚拟设备通过VideoPlayer和KeplerVideoSurfaceView支持四个并发非DRM流。

从命令行中构建和运行

  1. 在命令提示符下,构建应用。
  2. 在连接的Vega虚拟设备上运行应用。以下示例以Mac M系列计算机为目标。将路径中的架构替换为与您的开发计算机匹配的架构,并将应用ID替换为manifest.toml文件中的架构。
    有关构建输出路径和特定于架构的命令的更多信息,请参阅运行您的应用。

从Vega Studio中构建和运行

  • 要构建和运行应用,请在Vega Studio中选择Run(运行)。

相关主题

供审查的拟议示例更改

本页正文中的示例与媒体播放器团队提供的版本相比没有变化。以下项是文件审查期间提出的拟议更改和未决问题。每一个在进入页面之前都需要经过测试和确认。

问题 1 — clearSurfaceHandle('')正确吗?

此页面中的每个清理函数都使用空字符串调用clearSurfaceHandle('')。clearSurfaceHandle的API参考将参数记录为“KeplerVideoSurfaceView组件发出的onSurfaceViewCreated事件返回的表面句柄”,而不是空字符串。 相反,客户端广告插入文档会传递缓存的句柄。有关详细信息,请参阅使用JS方法实现客户端广告插入。
向团队提问:
  1. clearSurfaceHandle('')是释放表面,还是空操作?
  2. 如果是空操作,那么表面会一直泄漏,直到VideoPlayer实例被垃圾回收吗?
  3. 这能否解释故障排除表中的“只有两个流渲染,其他流为黑色”症状?
如果需要传递真实句柄,则每个示例都需要从onSurfaceViewCreated缓存句柄,以便清理函数可以传递该句柄。以下示例显示了对VideoPane的拟议更改。

问题 2 — 示例应该调用deinitialize()吗?

清理函数会调用pause(),但从不调用deinitialize()。媒体应用的一般要求规定,应用必须释放媒体资源,而释放是通过取消初始化VideoPlayer来实现的。应用商店的认证要求就是基于此要求。 向团队提问:
  1. 每个窗格都应该在卸载时调用await player.deinitialize()吗?
  2. 由于deinitialize()返回的是Promise<void>,而useEffect()清理函数不能等待,那么在这个位置调用deinitializeSync(timeoutInMs)是否正确? 您推荐的超时值是多少?
  3. 如果有四个并发播放器,同时将其取消初始化是否会导致与初始化相同的资源争用?

问题 3 — 播放控件示例没有泄漏任何内容

在播放控件示例中,play、pause和seek已声明但从未返回或调用。如上所述,该组件渲染了一个表面,并且任何父组件都无法访问这三个控件。TypeScript也会将其报告为未使用的局部变量。 以下示例是拟议的替代方案,它通过forwardRef()和useImperativeHandle()对外暴露这些控件。此模式已经出现在Vega Carousel中。
向团队提问:
  1. 您想要推荐useImperativeHandle()模式吗,还是更愿意在示例中显示带有方向键焦点处理的屏幕控件?
  2. currentTime += seconds是正确的跳转方式吗,还是有某个跳转API可以处理流开始和结尾处的边界钳制?

问题 4 — KeplerVideoSurfaceView是正确的组件吗?

API参考中对KeplerVideoSurfaceView和KeplerShareableSurfaceView的描述文字完全相同: “只有在使用VideoPlayer组件于预缓冲模式下运行时才使用此组件,在该模式下,可以同时用不同内容对多个播放器进行预缓冲。” 向团队提问:
  1. KeplerVideoSurfaceView与KeplerShareableSurfaceView和什么区别,多流应用应该使用哪一个?
  2. 参考中指出,“仅在预缓冲模式下运行时才使用这些组件。” 本页中的示例是否在预缓冲模式下运行? 如果预缓冲是前提条件,则页面需要说明并显示如何启用预缓冲。

问题 5 — 真正的并发流限制是多少?

页面在三个地方显示了四个并发流。该数字的每个来源都描述了具有软件解码功能的Vega虚拟设备。 向团队提问:
  1. 基于Vega支持的Fire TV Stick设备可以同时播放多少个清晰流? 是四个,还是特定于虚拟设备的四个?
  2. 媒体应用的一般要求规定,第一款基于Vega的Fire TV仅支持一个安全的视频解码器实例。本页顶部的DRM警告就是基于此要求。对于当前的硬件来说,这仍然准确吗?
  3. 四流限制是否因分辨率而异? 例如,四个1080p的流是否等同于一个4K的流?

问题 6 — 确认错开的初始化延迟

错开流初始化示例使用500毫秒的增量,在第四个流开始初始化之前总计1.5秒。 向团队提问:
  1. 500毫秒是测量值还是占位符?
  2. 是否有确定性的替代方案可以避免固定延迟,例如按顺序等待每个initialize()?

问题 7 — 构建和运行命令需要验证

以下更改是根据周边文档做出的最佳猜测,团队需要对照实际的工具链对其进行确认或更正。 提供的内容要求开发人员在故障排除表中运行npx react-native build-kepler --build-type Release --target aarch64,在Vega虚拟设备上进行测试步骤中运行vega run-app build/aarch64-release/<your-app-name>_aarch64.vpkg。 发生了什么变化,为什么:
  1. build-kepler改为build-vega。build-kepler是旧命令名称。Vega CLI工具记载的是用于React Native Vega应用的npx react-native build-vega,而0.24版文档中其他地方出现的build-kepler只是在描述该名称,并非指示使用该命令,例如Vega Studio控制台输出以及一条标题为“Unrecognized command build-kepler”的故障排除条目。
  2. 删除了--target aarch64。 该标记没有在0.24版文档的任何地方与build-vega一起出现。记载的标记为--build-type、--build-version和--build-number。构建您的应用展示了一个生成aarch64-release、x86_64-release和armv7-release输出文件夹的单一构建,因此似乎不需要目标标记。
  3. run命令新增了应用ID和-d VirtualDevice。 Vega CLI工具给出的签名是vega run-app <Vpkg path> <App ID> -d <device>,而0.24版的其他所有示例都同时提供了这两项。按照所提供的内容,该命令将这两项都省略了。
**为什么这还需要验证:**0.24文档在React Native应用的构建方式上与自己不一致,而且这三种形式在任何地方都无法调和:
  • Vega CLI工具表示可以直接使用npx react-native build-vega,并注明vega build存在但不适用于React Native应用。
  • 构建您的应用(主要构建页面)提供了npm run build:app其Vega CLI路径,且从未提及build-vega。关于Vega无头任务和服务显示,build:app解析为build-vega --build-type Release和--build-type Debug,因此npm脚本大概是一个包装器。构建页面上从未说明过这一间接关系。
  • 步骤1: 依赖项更新称,@amazon-devices/kepler-cli-platform注册了**vega build**命令,并且删除@react-native-community/cli会导致npm run build:release失败,报错为“Unrecognized command vega build”(无法识别的vega命令构建)— 这意味着React Native的npm脚本调用的是vega build,这与Vega CLI工具页面相矛盾。
向团队提问:
  1. 从命令行中构建适用于Vega的React Native应用的当前正确方法是什么:npx react-native build-vega、npm run build:app还是vega build? build-vega和vega build是两个名称下的同一个命令,还是两个不同的命令?
  2. 此页面是否应该指示直接调用原始build-vega,还是应该与构建您的应用保持一致并使用npm run build:app,这就是遵循入门路径的开发者已经会使用的命令?
  3. build-vega是否接受--target标记? 如果是,这里是否需要一个目标,还是每个架构都需要一个构建?
  4. 确认vega run-app调用,包括应用ID模式com.amazondeveloper.<your-app-name>.main是否与示例附带的manifest.toml文件相匹配。
  5. “应用启动时崩溃”条目是否描述了真实的、可重现的故障? 最初的措辞将vega build归因于原生C++和Rust开发。该声明之所以被移除,是因为没有记录Vega的原生开发路径,而且Rust没有在本文档集中的其他地方出现。该条目现在只说明不支持vega build命令,并且会生成不完整的程序包。确认该说法是准确的,并且不完整的程序包不完整是导致崩溃的原因。请注意,此条目的前提取决于此列表中的第一个问题: 如果npm脚本在后台调用vega build,则“您使用了vega build”不可能是崩溃的原因。
**注意:**此页面上的示例大概是使用build-kepler构建和测试的。无论哪个命令是正确的,它们都需要在此页面发布之前进行重建。
最后修改于 2026年7月31日