@amazon-devices/react-native-w3cmedia

​

Get started

​

Setup

1. Add the following library dependency to the dependencies section of your package.json file.
    "@amazon-devices/react-native-w3cmedia": "~2.2.20"
   
2. Open a terminal window and navigate to your app folder. Run npm to install the package in your app,
    npm install
   
3. Update your babel.config.js file, otherwise the app throws a “ReferenceError: Property ‘React’ doesn’t exist” exception during runtime.
    module.exports = {
        presets: [ ['module:metro-react-native-babel-preset', { useTransformReactJSXExperimental: true }] ],
        plugins: [
            [
            '@babel/plugin-transform-react-jsx',
            {
                runtime: 'automatic',
            },
            ],
        ]
        };
   
4. Add the following privileges in your manifest.toml.
    [wants]
    [[wants.service]]
    id = "com.amazon.mediametrics.service" # Required for metrics 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" # Required for captions
   
    [[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.*"
   

​

Usage

​

Video react native component

let video: HTMLVideoElement;
<Video
    ref={(ref) => {
        video = ref as HTMLVideoElement; // store the reference of this component
    }}
/>

​

VideoPlayer component

• Add the KeplerVideoSurfaceView React Native component to the render tree
• Receive onSurfaceViewCreated event
• Pass the surface handle obtained in the event callback to VideoPlayer through setSurfaceHandle method

// create an instance of video player
let videoPlayer = new VideoPlayer();
videoPlayer.initialize().then(() => {
    // wait for the promise resolution
});

// use it to start prebuffering using MSE APIs.
let mediaSource = new MediaSource();
let mediaSourceUrl = URL.createObjectURL(mediaSource);
videoPlayer.src = mediaSourceUrl;
// wait for open state change from mediasource
.
.
// create a source buffer
let videoSourceBuffer = mediaSource.addSourceBuffer("video/mp4");
// now append the media chunks downloaded from HLS or DASH manifests.
mediaSource.append(byteArray);
.
.
.
// Later when the app wants to render video and start playback add KeplerVideoSurface to
// render tree

// onSurfaceViewCreated event handle passes the surface handle.
const onSurfaceViewCreated = (_surfaceHandle: string) : void => {
    videoPlayer.setSurfaceHandle(_surfaceHandle);
    videoPlayer.play();
}

// when the app goes to background, the surface is destroyed.
const onSurfaceViewDestroyed = (_surfaceHandle: string) : void => {
    videoPlayer.clearSurfaceHandle(null);
}

// add the KeplerVideoSurfaceView react native comonent to the render tree.
<View style={{ backgroundColor: "white", alignItems: "stretch",
    width: deviceWidth, height: deviceHeight}}>
        <KeplerVideoSurfaceView  style={{zIndex: 0}}
            onSurfaceViewCreated={onSurfaceViewCreated}
            onSurfaceViewDestroyed={onSurfaceViewDestroyed}
        />
</View>

​

Audio react native component

<Audio
  ref={ref => {
    audio = ref; // store the reference of this component
  }}
/>

​

AudioPlayer component

// create an instance of audio player
let audioPlayer = new AudioPlayer();
audioPlayer.initialize().then(() => {
    // wait for the promise resolution
});
.
.
// use it to start prebuffering using MSE APIs.
let mediaSource = new MediaSource();
let mediaSourceUrl = URL.createObjectURL(mediaSource);
audioPlayer.src = mediaSourceUrl;
// wait for open state change from mediasource
.
.
// create a source buffer
let audioSourceBuffer = mediaSource.addSourceBuffer("audio/mpeg");
// now append the media chunks downloaded from HLS or DASH manifests.
mediaSource.append(byteArray);
.
.
.
// Later when the app wants to start playback
audioPlayer.play();

​

KeplerVideoSurfaceView

// create an instance of video player
let videoPlayer = new VideoPlayer();

// use it to start prebuffering using MSE APIs.
let mediaSource = new MediaSource();
let mediaSourceUrl = URL.createObjectURL(mediaSource);
videoPlayer.src = mediaSourceUrl;
// wait for open state change from mediasource
.
.
// create a source buffer
let videoSourceBuffer = mediaSource.addSourceBuffer("video/mp4");
// now append the media chunks downloaded from HLS or DASH manifests.
mediaSource.append(byteArray);
.
.
.
// Later when the app wants to render video and start playback add KeplerVideoSurface to
// render tree

// onSurfaceViewCreated event handle passes the surface handle.
const onSurfaceViewCreated = (_surfaceHandle: string) : void => {
    videoPlayer.setSurfaceHandle(_surfaceHandle);
    videoPlayer.play();
}

// when the app goes to background, the surface is destroyed.
const onSurfaceViewDestroyed = (_surfaceHandle: string) : void => {
    videoPlayer.clearSurfaceHandle(null);
}

// add the KeplerVideoSurfaceView react native comonent to the render tree.
<View style={{ backgroundColor: "white", alignItems: "stretch",
    width: deviceWidth, height: deviceHeight}}>
        <KeplerVideoSurfaceView  style={{zIndex: 0}}
            onSurfaceViewCreated={onSurfaceViewCreated}
            onSurfaceViewDestroyed={onSurfaceViewDestroyed}
        />
</View>

​

KeplerCaptionsView

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

// onCaptionViewCreated event callback handle passes the captions handle.
const onCaptionViewCreated = (captionsHandle: string) : void => {
    videoPlayer.setCaptionViewHandle(captionsHandle);
}

// add the KeplerCaptionsView react native comonent to the render tree.
<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

• URL Mode playback for non-adaptive streaming formats such as MP4, MP3, MKV etc media files. Audio and Video components support playback of non-adaptive streaming formats like MP4, MP3, MKV etc through “src” attribute.
  • Set the src attribute to a media URL. Apps set the content URL to the “src” attribute. video.src = [some url] or audio.src = [some url]
• Media Source Extension (MSE) mode for playback of adaptive streaming formats such as HLS and MPEG DASH. The MSE APIs support daptive streaming formats such as HLS and MPEG DASH. This API allows apps to inject the media segments of adaptive streaming contents such as HLS and DASH to the player. Apps download the manifest and parse it to determine the different bitrate quality levels and variants that the content supports. The app downloads a media segment of an appropriat quality level based on the available network bandwidth. It then passes it to the player through MediaSource and SourceBuffer methods. For additional information about how to use these APIs, see https://www.w3.org/TR/media-source-2/.
  • Create a MediaSource object.
    let mediaSource = new MediaSource();
  • Create a blob URL for MediaSource:
    let url = URL.createObjectURL(mediaSource)
  • Attach MediaSource to video or audio component.
    video.src = url or audio.src = url
  • Add a SourceBuffer by mime type.
    let sourceBuffer = mediaSource.addSourceBuffer(mimeType)
  • Download and append a media segment to SourceBuffer:
    
    // Download media segment to ArrayBuffer using fetch API
    let response = await fetch(uri);
    let arrayBuffer = await response.arrayBuffer();
    
    // Pass the downloaded media segment buffer to SourceBuffer.
    sourceBuffer.appendBuffer(arrayBuffer);
    

​

Common Media operations

​

Start playback

​

Pause playback

​

Get current time

​

Seek to a position

​

Handling Events

• Use the props on the Audio/Video React Native component. Refer to MediaProps for the list of supported props. For example, you can register an event handler for ended as shown the following example.

    <Video>
    onended = {onEnded}
    />

1. Use the EventTarget addEventListener() method. The Video and Audio component implements two methods of EventTarget interface: addEventListener and removeEventListener. Apps can use these methods to register event handlers on the reference of Audio/Video React Native components. For example, you can register the event handler as shown in the following example. video.addEventListener("ended", onEnded);

​

Unsupported features in HTMLMediaElement

• networkState
• load
• canPlayType - Indicates it supports any type.
• fastSeek - Performs the same seek as setting currentTime.
• getStartDate
• addTextTrack
• preload
• defaultPlaybackRate, playbackRate
• preservesPitch
• loop
• volume, muted

​

Unsupported features in Media Source Extension (MSE)

​

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

• The EventHandler attributes are not supported. Apps can use the addEventListener method of the EventTarget interface that MediaSource implements to register the event handler.

    EventHandler onsourceopen;
    EventHandler onsourceended;
    EventHandler onsourceclose;

• audioTracks, videoTracks and textTracks

​

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

• changeType
• EventHandler - The following attributes. For now apps can use addEventListener method of the EventTarget interface that SourceBuffer implements to register the event handler.

  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)

• The following EventHandler attributes are not supported. For now apps can use addEventListener method of the EventTarget interface that SourceBufferList implements.

  EventHandler  onaddsourcebuffer;
  EventHandler  onremovesourcebuffer;

​

Related topics

• Media Player Setup
• Selecting the Playback Mode

​

Modules

• Audio
• AudioPlayer
• EncryptedMediaInterface
• EventTargetInterface
• HTMLMediaElement
• index
• KeplerCaptionsView
• KeplerMediaControlHandler
• KeplerShareableSurfaceView
• KeplerVideoSurfaceView
• KeplerVideoView
• MediaCapabilities
• MediaCapabilitiesKeySystemConfiguration
• MediaProps
• MediaSource
• MediaSourceInterface
• MediaTypes
• Utils
• Video
• VideoPlayer