as

Settings
Sign out
Notifications
Alexa
亚马逊应用商店
AWS
文档
Support
Contact Us
My Cases
新手入门
设计和开发
应用发布
参考
支持

实现无头JavaScript播放

实现无头JavaScript播放

本指南介绍如何在您的应用中实现无头播放。无头播放可以在与用户界面不同的JavaScript线程上运行媒体播放,从而为具有复杂用户界面的应用将第一视频帧时间 (TTFVF) 最多缩短30%。

观看此视频(附带中文字幕),了解Vega的无头任务和服务。

关于无头集成

资源争用问题

在两个主要场景中于同一JavaScript线程上运行时,在以下情况下媒体播放和用户界面渲染可能会相互阻塞:当媒体播放阻碍用户界面响应能力时,或者当界面操作阻碍流畅的媒体播放时。

流媒体标准(例如MPEG DASH或HLS)的常见媒体播放器实现可能需要来自CPU和网络的大量系统资源。具体而言,播放和直播过程需要CPU密集型清单解析。当播放器与用户界面在同一线程上运行时,这些组件会争用资源,从而导致播放开始延迟、视频播放不稳定、用户界面元素无响应以及整体用户体验不佳。

无头实现通过在与用户界面分开的JS线程中运行播放器,为播放器创建服务组件来解决这些问题。这使用户界面控件能够与服务组件交互以控制媒体播放。在这种情况下,交互组件中的播放器用户界面是“客户端”,运行服务组件的播放器是“服务器”。

无头集成的好处包括缩短播放开始时间、增强用户界面响应能力和更好的整体播放性能。

要在应用中实现无头播放,您需要执行以下3项任务:

  1. 在应用中将播放器服务器创建为服务组件。
  2. 更改播放器代码以与服务交互而非直接控制播放器。
  3. 从应用启动服务。

下图概述了这些步骤,并提供了应用中无头播放的工作原理示意图。

有关详细的实施步骤,请参阅下面的实现无头服务

实现无头服务

要实现无头服务,请执行以下步骤:

  1. 向您的应用清单添加组件和功能。
  2. 创建service.js文件。
  3. 创建无头服务文件。
  4. 更新您的播放器代码。
    1. 初始化客户端。
    2. 处理视频加载。
    3. 处理播放控制。
  5. 安装其他依赖项。

以下部分将指导您完成每个步骤。

向应用清单中添加组件

Vega应用程序包必须包含一个名为manifest.toml的配置文件,此文件位于程序包的根目录下。此文件描述了有关程序包的基本信息。

要在应用中实现无头播放,您需要在componentsprocesseswantsoffers部分更新应用清单。以下示例向您展示了每个部分的具体更新。将 <应用程序包名称> 替换为您的应用程序的软件包名称。

已复制到剪贴板。

[[components.interactive]]
id = "<应用程序包名称>.main"
runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0" 
launch-type = "singleton"
categories = ["com.amazon.category.main"]

[[components.service]]
id = "<应用程序包名称>.service"
runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0"
launch-type = "singleton"
.
.
.

[processes]
# 确保播放器用户界面和无头JS播放器组件在同一个进程组中
[[processes.group]]
component-ids = ["<应用程序包名称>.main", "<应用程序包名称>.service"]

.
.
.

[wants]

[[wants.service]]
id = "<应用程序包名称>.service"

.
.
.

[offers]

[[offers.service]]
id = "<应用程序包名称>.service"

有关清单的更多信息,请参阅Vega应用清单

创建service.js文件

在项目根目录下创建service.js文件。service.js文件可让您注册无头JS服务的入口点(onStartServiceonStopService)。将<您的应用程序包名称>替换为上述manifest.toml文件中使用的应用程序包名称,以注册入口和退出点。

已复制到剪贴板。

import {HeadlessEntryPointRegistry} from '@amazon-devices/headless-task-manager';

import {onStartService, onStopService} from './src/PlayerService';

HeadlessEntryPointRegistry.registerHeadlessEntryPoint(
  '<应用程序包名称>.service::onStartService',
  () => onStartService,
);
HeadlessEntryPointRegistry.registerHeadlessEntryPoint(
  '<应用程序包名称>.service::onStopService',
  () => onStopService,
);

创建无头服务文件

创建帮助程序文件来处理播放器初始化和./src/PlayerService.ts文件内部控制。

更新您的播放器代码

初始化客户端

在您的App.tsx文件中,添加以下代码以初始化客户端。

处理视频加载

接下来,在您的App.tsx文件中,添加以下代码来处理视频加载。

处理播放控制

接下来,在您的App.tsx文件中,添加以下代码来处理播放控制。

集成Vega媒体控制

Vega媒体控制 (VMC) 所提供的功能可让Vega上的媒体应用开发者为媒体控制简化各种输入模式的集成。虽然媒体应用通常具有应用内用户界面控件,例如播放、暂停和停止,但客户通常需要额外的交互方式,例如使用遥控器或通过Alexa等服务使用语音命令。Vega媒体控制功能可处理这些不同的输入方法的集成,让您能够专注于流畅媒体播放的核心业务逻辑。

使用无头JS播放API播放其内容的应用现在可以免费获得KMC集成,用于基本的播放控制,例如暂停、播放和搜索。无头JS播放API在内部创建KMC服务器,发布服务器状态,并处理播放、暂停和搜索等基本命令。

无头JS播放只能更新与基本播放相关的数据的KMC服务器状态。如果应用自行处理KMC,则无需使用无头JS播放集成。它必须直接集成到KMC中才能处理命令。这种集成仅适用于将播放器与交互式组件集成的用例。应用不应调用player.setMediaControlFocus(componentInstance) 或实现覆盖功能。

选择加入KMC

  1. 启用KMC。按照开始使用Vega媒体控制概述中所述,将必要的清单条目添加到manifest.toml文件中。
  2. 更新您的package.json文件,以在@amazon-devices/kepler-media-controls上获取依赖项。
  3. 获取交互式组件的组件实例:

    已复制到剪贴板。

     import { useComponentInstance , IComponentInstance } from '@amazon-devices/react-native-kepler';
    
     const componentInstance: IComponentInstance = useComponentInstance();
    
  4. 在调用IPlayerClient.load API之前,将媒体控制焦点设置在播放器实例上。

    已复制到剪贴板。

     playerClient.current.setMediaControlFocus(componentInstance);
    

现在,playerClient实例将通过KMC启用,并支持暂停/播放和搜索遥控以及Alexa语音控制等基本功能。

覆盖某些控制命令

在某些情况下,应用可能希望覆盖默认由无头JS播放API处理的某些控制命令的处理。例如,您可以在直播内容播放期间禁用搜索。无头JS播放API也提供了一种实现这种体验的方法。

  1. 扩展@amazon-devices/kepler-player-client提供的PlayerClientMediaControlHandler并覆盖应用想要覆盖的函数。

    已复制到剪贴板。

     import { PlayerClientMediaControlHandler } from "@amazon-devices/kepler-player-client";
     import { IMediaSessionId } from '@amazon-devices/kepler-media-controls';
    
     class AppOverrideMediaControlHandler extends PlayerClientMediaControlHandler {
         async handlePlay(mediaSessionId?: IMediaSessionId) {
             if(shouldOverride) {
                 // 根据应用的要求进行自定义处理
             } else {
                 // 调用默认处理程序
                 super.handlePlay(mediaSessionId);
             }
         }
     };
    
  2. 将应用的媒体控制处理程序作为第二个参数传递给setMediaControlFocus方法。

    已复制到剪贴板。

     playerClient.current.setMediaControlFocus(componentInstance, new AppOverrideMediaControlHandler());
    

安装其他依赖项

您需要安装以下程序包才能使用无头服务:

  • @amazon-devices/kepler-player-server
  • @amazon-devices/kepler-player-client
  • @amazon-devices/react-native-w3cmedia

将这些依赖项添加到您的应用的package.json中,如以下示例所示。

已复制到剪贴板。

"dependencies": {
    "@amazon-devices/headless-task-manager": "~1.0.0",
    "@amazon-devices/kepler-player-server": "^2.0.4",
    "@amazon-devices/kepler-player-client": "^2.0.4",
    "@amazon-devices/keplerscript-turbomodule-api": "^1.2.1",
    "@amazon-devices/react-native-kepler": "~2.0.0",
    "@amazon-devices/react-native-w3cmedia": "^2.1.66",
    "base-64": "*",
    "react": "18.2.0",
    "react-native": "0.72.0",
    "xmldom": "*"
  },

最佳实践

背景模式

当应用进入后台时,建议用户界面调用IPlayerClient::unloadSync来卸载媒体播放器。同样,无头JS服务应卸载媒体播放器,并在其onStopService回调中进行必要的清理。


Last updated: 2025年10月1日