Console

Settings

Sign out

Notifications

Alexa

亚马逊应用商店

AWS

文档

Support

My Cases

Console

Vega开发者文档

主页

新手入门

设计和开发

应用发布

参考

支持

@amazon-devices/react-native-w3cmedia

开放Beta测试文档 作为预发布开放Beta测试的一项内容，亚马逊提供了此技术文档。随着亚马逊收到反馈并对功能进行迭代，所描述的这些功能可能会发生变化。有关最新功能的信息，请参阅发布说明。

Kepler WC3媒体API提供符合W3C标准的React Native和JavaScript类组件、JavaScript方法和JavaScript接口。使用此API构建播放体验，例如无间隙的剧集播放和主内容播放期间的无缝广告插入。

API实现 (polyfill) HTMLMediaElement、媒体源扩展和加密媒体扩展方法。

开始使用

设置

将以下库依赖项添加到package.json文件的dependencies部分。
已复制到剪贴板。
```
 "@amazon-devices/react-native-w3cmedia": "~2.1.0 "
```
打开终端窗口并导航到您的应用文件夹。运行npm以将程序包安装到您的应用中。
已复制到剪贴板。
```
 npm install
```

更新您的babel.config.js文件，否则运行时应用会引发“ReferenceError: Property 'React' doesn't exist”（ReferenceError：属性“React”不存在）的异常。

已复制到剪贴板。

 module.exports = {
     presets: [ ['module:metro-react-native-babel-preset', { useTransformReactJSXExperimental: true }] ],
     plugins: [
         [
         '@babel/plugin-transform-react-jsx',
         {
             runtime: 'automatic',
         },
         ],
     ]
     };

在您的manifest.toml中，添加以下权限。

已复制到剪贴板。

 [wants]
 [[wants.service]]
 id = "com.amazon.mediametrics.service" # 对于指标服务为必需

 [[wants.service]]
 id = "com.amazon.media.server"

 [[wants.service]]
 id = "com.amazon.gipc.uuid.*"

 [[wants.service]]
 id = "com.amazon.media.playersession.service"

 [[wants.privilege]]
 id = "com.amazon.devconf.privilege.accessibility" # 对于隐藏式字幕必需

 [[wants.service]]
 id = "com.amazon.mediabuffer.service"

 [[wants.service]]
 id = "com.amazon.mediatransform.service"

 [[wants.service]]
 id = "com.amazon.audio.stream"

 [[wants.service]]
 id = "com.amazon.audio.control"

 [offers]
 [[offers.service]]
 id = "com.amazon.gipc.uuid.*"

用法

Video React Native组件

Video是实现HTMLVideoElement接口的组件，该接口可扩展HTMLMediaElement接口。

使用该组件以播放各种格式的包含音频和视频的视频内容，这些格式包括MP4、MPEG DASH和HLS等。

该组件支持默认媒体控件图形用户界面。

将该组件添加到呈现树中并存储其引用。然后在该引用上调用HTMLMediaElement和HTMLVideoElement方法。该组件不允许应用在屏幕上显示视频之前预缓冲内容。要进行预缓冲，您可以使用VideoPlayer JavaScript类组件。

已复制到剪贴板。

let video: HTMLVideoElement;
<Video
    ref={(ref) => {
        video = ref as HTMLVideoElement; // 存储该组件的引用
    }}
/>

VideoPlayer组件

VideoPlayer组件实现HTMLVideoElement接口，该接口可扩展HTMLMediaElement接口。

HTMLVideoElement是一个typescript类，而非React Native组件。

默认情况下，它不会将视频呈现到屏幕上，也不会呈现媒体控件图形用户界面。

应用必须构建自身的媒体控件用户界面并控制播放体验。

应用必须创建一个VideoPlayer实例，并使用它来开始缓冲内容，而无需在屏幕上呈现视频。

要在屏幕上显示视频，应用必须执行以下操作：

将KeplerVideoSurfaceView React Native组件添加到渲染树中
接收onSurfaceViewCreated事件
通过setSurfaceHandle方法将事件回调中获得的表面句柄传递给VideoPlayer

已复制到剪贴板。

// 创建视频播放器的实例
let videoPlayer = new VideoPlayer();
videoPlayer.initialize().then(() => {
    // 等待Promise解析
});

// 使用它来开始通过MSE API进行预缓冲。
let mediaSource = new MediaSource();
let mediaSourceUrl = URL.createObjectURL(mediaSource);
videoPlayer.src = mediaSourceUrl;
// 等待来自mediasource的打开状态更改
.
.
// 创建源缓冲区
let videoSourceBuffer = mediaSource.addSourceBuffer("video/mp4");
// 现在附加从HLS或DASH清单下载的媒体块。
mediaSource.append(byteArray);
.
.
.
//稍后，当应用想要呈现视频并开始播放时，将KeplerVideoSurface添加到
// 呈现树

//onSurfaceViewCreated事件句柄传递表面句柄。
const onSurfaceViewCreated = (_surfaceHandle: string) : void => {
    videoPlayer.setSurfaceHandle(_surfaceHandle);
    videoPlayer.play();
}

// 当应用进入后台时，会将表面销毁。
const onSurfaceViewDestroyed = (_surfaceHandle: string) : void => {
    videoPlayer.clearSurfaceHandle(null);
}

// 将KeplerVideoSurfaceView React Native组件添加到渲染树中。
<View style={{ backgroundColor: "white", alignItems: "stretch",
    width: deviceWidth, height: deviceHeight}}>
        <KeplerVideoSurfaceView  style={{zIndex: 0}}
            onSurfaceViewCreated={onSurfaceViewCreated}
            onSurfaceViewDestroyed={onSurfaceViewDestroyed}
        />
</View>

Audio React Native组件

Audio是实现HTMLAudioElement接口的组件，该接口可扩展HTMLMediaElement接口。

使用该组件播放仅包含音频的MP3或MPEG DASH/HLS等音频。

该组件支持默认媒体控件图形用户界面。

将该组件添加到呈现树中并存储其引用。

然后在该引用上调用HTMLMediaElement和HTMLAudioElement API。

该组件不允许应用在设备上播放音频之前预缓冲内容。要进行预缓冲，可使用AudioPlayer JavaScript类组件。

已复制到剪贴板。

<Audio
  ref={ref => {
    audio = ref; //存储该组件的参考
  }}
/>

AudioPlayer组件

AudioPlayer组件实现HTMLAudioElement接口，该接口可扩展HTMLMediaElement接口。

AudioPlayer是一个typescript类，而非React Native组件。

使用该组件播放仅包含音频的MP3或MPEG DASH/HLS等格式。

应用需要创建一个AudioPlayer实例，并使用它来开始缓冲内容，而无需开始播放。

它不呈现媒体控件图形用户界面。应用需要构建自身的媒体控件用户界面并控制播放体验。

已复制到剪贴板。

// 创建音频播放器的实例。
let audioPlayer = new AudioPlayer();
audioPlayer.initialize().then(() => {
    // 等待Promise解析
});
.
.
// 使用它来开始通过MSE API进行预缓冲。
let mediaSource = new MediaSource();
let mediaSourceUrl = URL.createObjectURL(mediaSource);
audioPlayer.src = mediaSourceUrl;
// 等待来自mediasource的打开状态更改
.
.
// 创建源缓冲区
let audioSourceBuffer = mediaSource.addSourceBuffer("audio/mpeg");
// 现在附加从HLS或DASH清单下载的媒体块。
mediaSource.append(byteArray);
.
.
.
//稍后当应用希望开始播放时
audioPlayer.play();

KeplerVideoSurfaceView

KeplerVideoSurfaceView是一个React Native组件，用于在屏幕上呈现视频帧。

只有在预缓冲模式下使用VideoPlayer且多个播放器同时预缓冲不同的内容时，才使用KeplerVideoSurfaceView。

然后，应用将由onSurfaceViewCreated事件回调传递的表面句柄附加到需要在屏幕上呈现的视频播放器实例。

已复制到剪贴板。

// 创建视频播放器的实例
let videoPlayer = new VideoPlayer();

// 使用它来开始通过MSE API进行预缓冲。
let mediaSource = new MediaSource();
let mediaSourceUrl = URL.createObjectURL(mediaSource);
videoPlayer.src = mediaSourceUrl;
// 等待来自mediasource的打开状态更改
.
.
// 创建源缓冲区
let videoSourceBuffer = mediaSource.addSourceBuffer("video/mp4");
// 现在附加从HLS或DASH清单下载的媒体块。
mediaSource.append(byteArray);
.
.
.
//稍后，当应用想要呈现视频并开始播放时，将KeplerVideoSurface添加到
//呈现树

//onSurfaceViewCreated事件句柄传递表面句柄。
const onSurfaceViewCreated = (_surfaceHandle: string) : void => {
    videoPlayer.setSurfaceHandle(_surfaceHandle);
    videoPlayer.play();
}

// 当应用进入后台时，会将表面销毁。
const onSurfaceViewDestroyed = (_surfaceHandle: string) : void => {
    videoPlayer.clearSurfaceHandle(null);
}

// 将KeplerVideoSurfaceView React Native组件添加到渲染树中。
<View style={{ backgroundColor: "white", alignItems: "stretch",
    width: deviceWidth, height: deviceHeight}}>
        <KeplerVideoSurfaceView  style={{zIndex: 0}}
            onSurfaceViewCreated={onSurfaceViewCreated}
            onSurfaceViewDestroyed={onSurfaceViewDestroyed}
        />
</View>

KeplerCaptionsView

KeplerCaptionsView是一个React Native组件，该组件可在屏幕上呈现隐藏式字幕和字幕。仅在使用VideoPlayer和AudioPlayer组件在预缓冲模式下运行时才使用该组件。

应用通过setCaptionViewHandle方法将onCaptionViewCreated事件回调传递的隐藏式字幕句柄附加到VideoPlayer和AudioPlayer，以便播放器能够在屏幕上呈现隐藏式字幕或字幕。

当前，默认情况下不呈现隐藏式字幕。

要启用字幕呈现，可运行以下命令：

已复制到剪贴板。

vdcm set com.amazon.devconf/system/accessibility/ClosedCaptioningEnabled 1

以下示例展示了该组件的用法。

已复制到剪贴板。

// onCaptionViewCreated事件回调句柄传递隐藏式字幕句柄。
const onCaptionViewCreated = (captionsHandle: string) : void => {
    videoPlayer.setCaptionViewHandle(captionsHandle);
}

// 将KeplerCaptionsView React Native组件添加到渲染树中。
<View style={{ backgroundColor: "white", alignItems: "stretch",
    width: deviceWidth, height: deviceHeight}}>
        <KeplerCaptionsView
            onCaptionViewCreated={onCaptionViewCreated}
            style={{ width: '100%',
            height: '100%',
            top: 0,
            left: 0,
            position: 'absolute',
            backgroundColor: 'transparent',
            flexDirection: 'column',
            alignItems: 'center',zIndex: 2}}
        />
</View>

HTMLMediaElement

HTMLMediaElement代表您的KeplerScript应用用来控制播放的主播放器界面。该接口由Video和Audio React Native组件以及VideoPlayer和AudioPlayer typescript组件实现。

如需了解更多详情，请参阅https://html.spec.whatwg.org/multipage/media.html（仅提供英文版）。

应用可以在两种模式下启动播放，具体取决于内容类型（自适应或非自适应），如下所述。

URL模式播放适用于非自适应流媒体格式，例如MP4、MP3、MKV等媒体文件。Audio和Video组件支持通过“src”属性播放MP4、MP3、MKV等非自适应流媒体格式。
```
 - 将src属性设置为媒体URL。

      应用将内容URL设置为“src”属性。

      `video.src = [某个url] or audio.src = [某个url]`
```

媒体源扩展 (MSE) 模式适合播放自适应流媒体格式，例如HLS和MPEG DASH等。MSE API支持HLS和MPEG DASH等自适应流媒体格式。此API允许应用向播放器注入HLS和DASH等自适应流媒体内容的媒体片段。应用下载清单并对其进行解析，以确定内容支持的不同比特率质量级别和变体。该应用根据可用网络带宽下载具有适当质量级别的媒体片段。然后它通过MediaSource和SourceBuffer方法将其传递给播放器。

 有关如何使用这些API的更多信息，请参阅 [https://www.w3.org/TR/media-source-2/](https://www.w3.org/TR/media-source-2/)（仅提供英文版）。

 - 创建MediaSource对象。<br>
     `let mediaSource = new MediaSource();`

 - 为MediaSource创建blob URL：<br>
     `let url = URL.createObjectURL(mediaSource)`

 - 将MediaSource连接到video或audio组件。<br>
     `video.src = url`或`audio.src = url`

 - 按mime类型添加`SourceBuffer`。<br>
     `let sourceBuffer = mediaSource.addSourceBuffer(mimeType)`

 -5 下载媒体片段并将其附加到`SourceBuffer`中：<br>

     ```javascript
     // 使用Fetch API将媒体片段下载到ArrayBuffer
     let response = await fetch(uri);
     let arrayBuffer = await response.arrayBuffer();

     // 将下载的媒体片段缓冲区传递至SourceBuffer。
     sourceBuffer.appendBuffer(arrayBuffer);
     ```

常见媒体操作

使用Audio或Video React Native组件引用，通过HTMLMediaElement方法控制媒体播放和其他常见操作，如下所示。

开始播放

video.play()或audio.play()

暂停播放

video.pause()或audio.pause()

获取当前时间

读取currentTime属性以获取当前的播放位置。

console.log('${video.currentTime}'); or console.log('${audio.currentTime}');

搜索位置

将currentTime属性设置为搜索所需位置。

video.currentTime = seekPosition;或audio.currentTime = seekPosition;

处理事件

Kepler W3C媒体API支持W3C媒体规范中描述的所有事件。有两种方法可以在Video或Audio上注册事件处理程序。

在React Native的Audio/Video组件上使用属性。有关支持的属性列表，请参阅MediaProps。例如，您可以为ended注册一个事件处理程序，如以下示例所示：
已复制到剪贴板。
```
  <Video>
  onended = {onEnded}
  />
```

使用EventTarget addEventListener() 方法。

Video和Audio组件实现了EventTarget接口的两种方法：addEventListener和removeEventListener。

应用可以使用这些方法在React Native的Audio/Video组件的引用上注册事件处理程序。例如，您可以按以下示例所示注册事件处理程序。

video.addEventListener("ended", onEnded);

除了Audio和Video React Native组件，还有其他非React Native组件，例如AudioTrackList、VideoTrackList、MediaSource、SourceBuffer和SourceBufferList，它们也可以发出事件。这些事件通过EventTarget的addEventListener方法来处理。所有这些方法都支持addEventListener。

注意：不支持这些方法的EventHandler属性。

例如，以下示例显示了如何处理VideoTrackList上的addtrack事件。

video.videoTracks.addEventListener("addtrack", onVideoTrackAdded);

或者要处理MediaSource上的sourceopen事件。

mediasource.addEventListener("sourceopen", onMediaSourceOpen)

加密媒体扩展仅在MSE模式下支持受DRM保护的播放。有关更多信息，请参阅https://w3c.github.io/encrypted-media/。

HTMLMediaElement中不支持的功能

networkState
加载
canPlayType - 指明支持的任何类型。
fastSeek - 执行与设置currentTime相同的搜索。
getStartDate
addTextTrack
预加载
defaultPlaybackRate, playbackRate
preservesPitch
循环
音量、静音

媒体源扩展 (MSE) 中不支持的功能

MediaSource API (https://www.w3.org/TR/media-source-2/#mediasource)

不支持的EventHandler属性。应用可以使用MediaSource实现的EventTarget接口的addEventListener方法来注册事件处理程序。
```
  EventHandler onsourceopen;
  EventHandler onsourceended;
  EventHandler onsourceclose;
```
audioTracks、videoTracks和textTracks

SourceBuffer API (https://www.w3.org/TR/media-source-2/#sourcebuffer)

changeType

EventHandler - 以下属性。目前，应用可以使用SourceBuffer实现的EventTarget接口的addEventListener方法来注册事件处理程序。

double              appendWindowStart;
unrestricted double appendWindowEnd;
EventHandler        onupdatestart;
EventHandler        onupdate;
EventHandler        onupdateend;
EventHandler        onerror;
EventHandler        onabort;

SourceBufferList API (https://www.w3.org/TR/media-source-2/#sourcebufferlist)

不支持以下EventHandler属性。目前，应用可以使用SourceBufferList实现的EventTarget接口的addEventListener方法。
```
EventHandler  onaddsourcebuffer;
EventHandler  onremovesourcebuffer;
```

模块

Last updated: 2025年10月23日

@amazon-devices/react-native-w3cmedia

开始使用

设置

用法

Video React Native组件

VideoPlayer组件

Audio React Native组件

AudioPlayer组件

KeplerVideoSurfaceView

KeplerCaptionsView

HTMLMediaElement

常见媒体操作

开始播放

暂停播放

获取当前时间

搜索位置

处理事件

HTMLMediaElement中不支持的功能

媒体源扩展 (MSE) 中不支持的功能

MediaSource API (https://www.w3.org/TR/media-source-2/#mediasource)

SourceBuffer API (https://www.w3.org/TR/media-source-2/#sourcebuffer)

SourceBufferList API (https://www.w3.org/TR/media-source-2/#sourcebufferlist)

相关主题

模块