Developer Portal

Video

You.i TV's implementation of a video player. Provides an interface to the native platform video player. By default, it uses the You.i Engine One video player (CYIAbstractVideoPlayer).

See also Using a Custom Video Player.

Example usage


import { Video } from '@youi/react-native-youi';
...
<Video
	paused={this.state.paused}
	source={this.state.videoSource}
	muted={this.state.muted}
	selectedAudioTrack={Video.getAudioTrackId(this.state.audioTracks.map(track => track.id), this.state.selectedAudioTrack)}
	selectedClosedCaptionsTrack={Video.getClosedCaptionsTrackId(this.state.closedCaptionTracks.map(track => track.id), this.state.selectedClosedCaptionsTrack)}
	maxBitrate={this.state.maxBitrate}
	bufferLength={{
				min:5000,
				max:15000,
				}}
	onBufferingStarted={() => console.log("onBufferingStarted called.")}
	onBufferingEnded={() => console.log("onBufferingEnded called.")}
	onErrorOccurred={(error) => {
		this.setState({
			videoSource: {
				uri: '',
				type: ''
			},
			errorCode: error.nativeEvent.errorCode,
			nativePlayerErrorCode: error.nativeEvent.nativePlayerErrorCode,
			errorMessage: error.nativeEvent.message
		})}
	}
	onPreparing={() => console.log("onPreparing called.") }
	onReady={() => console.log("onReady called.")}
	onPlaying={() => console.log("onPlaying called.")}
	onPaused={() => console.log("onPaused called.")}
	onPlaybackComplete={() => console.log("onPlaybackComplete called.")}
	onFinalized={() => console.log("onFinalized called.")}
	onCurrentTimeUpdated={(currentTime) => {
		this.setState({
			currentTime: currentTime
		})}
	}
	onDurationChanged={(duration) => {
		this.setState({
			duration: duration
		})}
	}
	onStateChanged={(playerState) => {
		this.setState({
			playbackState: playerState.nativeEvent.playbackState,
			mediaState: playerState.nativeEvent.mediaState
		})}
	}
	onAvailableAudioTracksChanged={(audioTracks) => {
		tempAudioTracksArray = []
		audioTracks.nativeEvent.forEach(element => {
			tempAudioTracksArray.push({
				id: element.id,
				name: element.name,
				language: element.language,
				valid: element.valid
			})
		});
		this.setState({
			audioTracks: tempAudioTracksArray
		})
		// If there are not enough audio tracks for the selected track, set to the default first track.
		if(this.state.selectedAudioTrack >= audioTracks.nativeEvent.length)
			{
				this.setState({
					>selectedAudioTrack: 0
				})
			}}
		}
		onAvailableClosedCaptionsTracksChanged={(closedCaptionTracks) => {
			tempClosedCaptionTracksArray = []
			closedCaptionTracks.nativeEvent.forEach(element => {
				tempClosedCaptionTracksArray.push({
					id: element.id,
					name: element.id == Video.getClosedCaptionsOffId() && element.name == "" ? OFF_TRACK_NAME : element.name,
					language: element.language
				})
			});
			this.setState({
				closedCaptionTracks: tempClosedCaptionTracksArray
			})
			// If there are not enough closed captions tracks for the selected track, disable closed captions.
			if(this.state.selectedClosedCaptionsTrack >= closedCaptionTracks.nativeEvent.length)
			{
				this.setState({
				  selectedClosedCaptionsTrack: -1
				})
			}
			// If at this point, closed captions are indicated to be disabled with 'selectedClosedCaptionsTrack = -1', set it to the position of the disabled track in the array, for simpler tracking of the selected track position.
			if(this.state.selectedClosedCaptionsTrack < 0)
			{
				this.setState({
					selectedClosedCaptionsTrack: tempClosedCaptionTracksArray.map(track => track.id).indexOf(Video.getClosedCaptionsOffId())
				})
			}}
		}
		this.videoPlayer.getStatistics().then((statistics) => {
			this.props.getStatistics(statistics);
		});
		}
		getPlayerInformationCallback={(playerInformation) => {
		   this.setState({
			 playerInformation: {
			 	name: playerInformation.name,
				version: playerInformation.version
			 }
		   })}
		}
/>

Props

Methods

Helper functions

  • static getAudioTrackId(audioTrackIds, selectedAudioTrack)

    Gets an audio track ID based on an array of audio track objects, and the selected index among those tracks.

  • static getClosedCaptionsTrackId(closedCaptionsTrackIds, selectedClosedCaptionsTrack)

    Gets a closed captions track ID based on an array of closed caption track objects, and the selected index among those tracks.

  • static getClosedCaptionsOffId()

    Returns the constant ID corresponding to closed captions disabled.

Supported Streaming Protocols

The default You.i Engine One video player supports the following protocols.

Platform

Video Player

Video Streaming Format

MP4

HLS

Smooth

DASH

Mobile

iOS

Native (AVPlayer)

Yes

Yes

No

No

Android

Native (ExoPlayer 2)

Yes

Yes

No

Yes

10-Foot

Apple tvOS

Native (AVPlayer)

Yes

Yes

No

No

Android TV

Native (ExoPlayer 2)

Yes

Yes

No

Yes

Amazon Fire TV (Android)

Native (ExoPlayer 2)

Yes

Yes

No

Yes

Samsung Tizen

Native (JavaScript AVPlay)

Yes

Yes

Yes

Yes

PlayStation 4

Non-Native (Custom)

Yes

Yes

No

No

Xbox One

Native (UWP)

Yes

Yes

No

Yes

Roku

Native

Yes

Yes

Yes

Yes

Development/Desktop

Windows

Native (UWP)

Yes

Yes

No

Yes

Windows

Non-Native (VLC)

No

No

No

No

macOS

Native (AV Player)

Yes

Yes

No

No

Linux

Non-Native (VLC)

Yes

No

No

No

Supported DRM

The default You.i Engine One video player supports the following types of DRM with encryption.

Platform

Video Player

PlayReady

WideVine
(Modular)

Fairplay

AES-128/256

Mobile

iOS

Native (AV Player)

No

No

Yes (HLS)

Yes

Android

Native (ExoPlayer 2)

No

Yes (DASH)

No

Yes

10-Foot

Apple tvOS

Native (AV Player)

No

No

Yes (HLS)

Yes

Android TV

Native (ExoPlayer 2)

No

Yes (DASH)

No

Yes

Amazon Fire TV (Android)

Native (ExoPlayer 2)

No

Yes (DASH)

No

Yes

Roku

Native

Yes (DASH)

Yes (DASH)

No

Yes (HLS)

Samsung Tizen

Native (JavaScript)

Yes (DASH)

Yes (DASH)

No

Yes

PlayStation 4

Non-Native (Custom)

No

No

No

Yes

Xbox One

Native (UWP)

Yes (DASH)

No

No

Yes

Development/Desktop

Windows

Native (UWP)

Yes (DASH)

No

No

Yes

Windows

Non-Native (VLC)

No

No

No

No

macOS

Native (AV Player)

No

No

No

Yes

Linux

Non-Native (VLC)

No

No

No

No

Supported Closed Caption and Subtitle Features

The default You.i Engine One video player supports the following types of Subtitle and Closed Caption decoder.

Platform

Video Player

Subtitle

Closed Caption

WebVTT

CEA/EIA 608/708

Mobile

iOS

Native (AV Player)

Yes

Yes

Android

Native (ExoPlayer 2)

Yes

Yes

10-Foot

Apple tvOS

Native (AV Player)

Yes

Yes

Android TV

Native (ExoPlayer 2)

Yes

Yes

Amazon Fire TV (Android)

Native (ExoPlayer 2)

Yes

Yes

Roku

Native

Yes (HLS/DASH).
See the note below.

Yes.
See the note below.

Samsung Tizen

Native (JavaScript AVPlay)

Yes

Yes

PlayStation 4

Non-Native (Custom)

Yes

Yes

Xbox One

Native (UWP)

Yes

Yes

Development/Desktop

Windows

Native (UWP)

Yes

Yes

Windows

Non-Native (VLC)

No

No

macOS

Native (AV Player)

Yes

Yes

Linux

Non-Native (VLC)

No

No

Note

Read the following points for the Roku platform:

Supported Closed Caption Styles

The default You.i Engine One video player supports the following user styling for the Closed Caption feature.

Mobile Platform

Video Player

Closed Caption Features

Text Attribution

Positioning and Special Characters

Modes

Audio Track

 

 

Italics

Line (Vertical Alignment)

Align

Special Characters

Paint On

Roll Up

Pop On

Embedded

Sidecar

iOS

Native (AV Player)

No

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Android

Native (ExoPlayer 2)

No

No

No

No

Yes

Yes

Yes

Yes

Yes

 

10-Foot Platform

Video Player

Closed Caption Features

Text Attribution

Positioning and Special Characters

Modes

Audio Track

 

 

Italics

Line (Vertical Alignment)

Align

Special Characters

Paint On

Roll Up

Pop On

Embedded

Sidecar

Apple tvOS

Native (AV Player)

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Android TV

Native (ExoPlayer 2)

No

No

No

No

Yes

Yes

Yes

No

No

Amazon Fire TV (Android)

Native (ExoPlayer 2)

No

No

No

No

Yes

Yes

Yes

No

No

Roku

Native

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Samsung Tizen

Native (JavaScript AVPlay)

No

No

No

No

No

No

No

YesHLS+WebVTT and MP4 embedded

Yes

PlayStation 4

Non-Native (Custom)Custom streamer does not support embedded audio playback

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Xbox One

Native (UWP)

No

Yes

Yes

Yes

No

No

No

Yes

Yes

 

Development/Desktop Platform

Video Player

Closed Caption Features

Text Attribution

Positioning and Special Characters

Modes

Audio Track

 

 

Italics

Line (Vertical Alignment)

Align

Special Characters

Paint On

Roll Up

Pop On

Embedded

Sidecar

Windows

Native (UWP)

No

No

No

YesThe Windows font must support the character being rendered, otherwise a default glyph is shown.

Yes

Yes

Yes

Yes

Yes

Windows

Non-Native (VLC)Not supported

No

No

No

No

No

No

No

No

No

macOS

Native (AV Player)

Yes

No

No

No

No

No

No

Yes

Yes

Linux

Non-Native (VLC)

No

No

No

No

No

No

No

Yes

NoHLS 4 supports audio tracks as side car but current version of VLC does not support it; embedded audio playback does work.

Supported Subtitle Styles

The default You.i Engine One video player supports the following user styling for the Subtitle feature.

Mobile Platform

Video Player

Subtitle Features

Text Attribution

Positioning and Special Characters

Modes

 

 

Italics

Bold

Underline

Line (Vertical Alignment)

Align

Size

Special Characters

Paint On

Roll Up

Pop On

iOS

Native (AV Player)

Yes

Yes

Yes

Yes

PartialThe implementation of the align property in iOS/OSx/tvOS differs from other platforms. In the Apple-based target platforms, align applies from the middle point of the window instead from the left or right most edges.

Yes

Yes

Yes

Yes

Yes

Android

Native (ExoPlayer 2)

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

 

10-Foot Platform

Video Player

Subtitle Features

Text Attribution

Positioning and Special Characters

Modes

 

 

Italics

Bold

Underline

Line (Vertical Alignment)

Align

Size

Special Characters

Paint On

Roll Up

Pop On

Apple tvOS

Native (AV Player)

Yes

Yes

Yes

Yes

PartialThe implementation of the align property in iOS/OSx/tvOS differs from other platforms. In the Apple-based target platforms, align applies from the middle point of the window instead from the left or right most edges.

Yes

Yes

Yes

Yes

Yes

Android TV

Native (ExoPlayer 2)

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Amazon Fire TV (Android)

Native (ExoPlayer 2)

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Roku

Native

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Samsung Tizen

Native (JavaScript AVPlay)

No

No

No

No

No

No

No

No

No

No

PlayStation 4

Non-Native (Custom)

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Yes

Xbox One

Native (UWP)

No

No

No

No

No

No

Yes

Yes

Yes

Yes

 

Development/Desktop Platform

Video Player

Subtitle Features

Text Attribution

Positioning and Special Characters

Modes

 

 

Italics

Bold

Underline

Line (Vertical Alignment)

Align

Size

Special Characters

Paint On

Roll Up

Pop On

Windows

Native (UWP)

No

No

No

No

No

No

YesThe Windows font must support the character being rendered, otherwise a default glyph is shown.

Yes

Yes

Yes

Windows

Non-Native (VLC)

No

No

No

No

No

No

No

No

No

No

macOS

Native (AV Player)

Yes

Yes

Yes

Yes

Partial

Yes

Yes

Yes

Yes

Yes

Linux

Non-Native (VLC)

No

No

No

No

No

No

No

No

No

No

Cloud Solution Considerations

Additional video restrictions apply when implementing a You.i Engine React Native app for deployment on a Roku app. In a Roku app:

  • Video is streamed directly from the local Roku player.
  • All playback and associated controls are handled by the local Roku player.
  • Cloud Solution playback currently supports only full screen video mode.

Because of these circumstances, additional restrictions exist when implementing functionality based on video player state and events. For details, contact your You.i TV representative.

Roku may have particular requirements for implementing bookmarking, ads, and other such functionality. Ensure you meet all applicable Roku requirements if you are implementing a You.i Engine React Native for deployment on a Roku app.


Reference

Prop: source

The video source; either a remote URL or a local file resource.

Type

Required

object

Yes

  • type: string
  • uri: object
  • drmScheme: string
  • startTimeMs: number. The time, in milliseconds, from where the video asset should start playing. If excluded, the video asset starts from the beginning. It is also supported for Roku.
  • drmInfo: object

    The following is required for each supported DRM scheme:

    • none: null
    • fairplay: null
    • widevine_modular: object

      Example:

      {

         licenseAcquisitionUrl: string,

         headers: array,

         {

            key: string

            value: string

         }

      }

    • playready: string

Prop: muted

Determines whether the video plays audio or not. Default is false, which always plays audio.

Type

Required

bool

No


Prop: visible

Determines whether the component should be visible or not. Default is true. Note the following:

  • Component visibility is different from component opacity.
  • Components that are not visible are not focusable.

Type

Required

bool

No


Prop: bufferLength

Customize the video playback buffer length.

Type

Required

object

no

  • min: number. The value, in milliseconds, that the video player should not to allow the buffer length to fall below.
  • max: number. The value, in milliseconds, that the video player should not let the buffer length exceed.

Prop: selectedAudioTrack

Switches the video player's audio to the track indicated by the given index. If the video is playing, playback isn't stopped during the switch.

Type

Required

number

No


Prop: selectedClosedCaptionsTrack

Switches the video player's closed captions track to the track indicated by the given index. If the video is playing, playback isn't stopped during the switch.

Type

Required

number

No


Prop: userAgent

Sets the user agent to be used by the player for requests on manifests and video segments.

The following applies:

  • Setting the user agent should be done before a call to Prepare(). Otherwise it might have no effect on current playback.
  • The default user agent varies depending on the platform.
  • Setting the user agent to empty string ("") resets it to the default.
  • Only implemented on PS4 and XBoxOne currently.

Type

Required

string

No


Prop: maxBitrate

Sets the maximum bitrate to the number specified, in bits per second. The player then uses it when streaming from an adaptive media source. By default, no bitrate restriction is applied.

The following applies:

  • Setting the maxBitrate during playback may take time to take effect due to content that has already been buffered.
  • For Tizen, maxBitrate must be set before preparing the media.
  • Setting maxBitrate to 0 removes any bitrate restrictions.
  • For Roku, maxBitrate can be set using metadata with the MaxBandwidth key before preparing and starting playback.

Type

Required

number

No


Prop: metadata

Sets the video player metadata. For Roku, this prop must be used if your application uses custom DRM attributes. See Video DRM for Roku.

Type

Required

object

No


Prop: onBufferingStarted

Invoked when player buffering started. An application can display a buffering indicator when this signal is emitted. Currently, it is not supported for the Roku target platform.

Type

Required

function

No


Prop: onBufferingEnded

Invoked when player buffering ended. An application can clear a buffering indicator, if one has been displayed, when this signal is emitted. The video either is in a play or paused state depending on the state the player was in prior to buffering. Currently, it is not supported for the Roku target platform.

Type

Required

function

No


Prop: onErrorOccurred

Invoked when the player reports an error with:

{nativeEvent: { errorCode, nativePlayerErrorCode, message }}

Your application can display an error notification when this signal is emitted. You can also use the resulting error code for application logic. When using ExoPlayer with Android, the value for nativePlayerErrorCode will always be empty; all errors are returned via message.

Type

Required

function

No


Prop: onPreparing

Invoked when the player has started preparing a video for playback. Occurs only when the target platform supports the provided video format. Currently, it is not supported for the Roku target platform.

Type

Required

function

No


Prop: onReady

Invoked when the video is ready to be interacted with and information about the video can be queried. Currently, it is not supported for the Roku target platform.

Type

Required

function

No


Prop: onCompositionDidLoad

Invoked when the parent composition is loaded successfully and the Ref component gets attached to it.


Prop: onPlaying

Invoked when playback has begun. This can either be the initial playback or playback resuming after paused or buffering states.

Type

Required

function

No


Prop: onPaused

Invoked when playback has paused.

Type

Required

function

No


Prop: onPlaybackComplete

Invoked when the playback of the currently loaded video media has completed. After this signal is emitted the player is in the paused state.

Note

You can transition back into the playing state by using a Seek() operation after this signal is emitted. This is invoked each time the video media reaches the end of stream.

Type

Required

function

No


Prop: onFinalized

Invoked when the player has shutdown and cleaned up:

  • On PlayStation 4, the player stalls if deleted or prepared while already being stopped. You.i TV recommends that you listen for this signal before doing so.
  • On other platforms this signal is sent immediately on Stop().
  • Currently, it is not supported for the Roku target platform, but onPlaybackComplete can be used instead for Roku.

Type

Required

function

No


Prop: onCurrentTimeUpdated

Invoked when the current time in the video playback has updated. The callback returns a number; the current time of the video playback in ms.

Type

Required

function

No


Prop: onCurrentTimeUpdatedThresholdMs

Returns how often the current time in the video playback should be updated. The callback returns a number; the threshold time in ms.

Type

Required

function

No

Note

For Roku, you can set it using a metadata with the BookmarkInterval key before preparing and starting the playback.


Prop: onDurationChanged

Invoked when the duration of the loaded video media has changed. This typically occurs after loading new video media. You.i TV recommends that you update the duration visible to the application user when this is invoked. The callback returns a number; the duration of the video in ms.

Type

Required

function

No


Prop: onStateChanged

Invoked when the player state has changed.

Type

Required

function

No


Prop: onAvailableAudioTracksChanged

Invoked when the available audio tracks for the current media have changed. This may be emitted at any point.

Type

Required

function

No


Prop: onAvailableClosedCaptionsTracksChanged

Invoked when the available closed captions tracks for the current media have changed. This may be emitted at any point.

Type

Required

function

No

Prop: onTimedMetaData

Invoked when timed metadata is available.

Note

Platforms supported under this prop include Apple, Android, PS4 and Roku Cloud Solution.

Type

Required

dictionary

No

The above dictionary will have the following content:

Name

Type

Required Description

Identifier

string

Yes

Identifies the meta data content values.

Value

string

Yes

The meta data value. The value contents matches the one described by the identifier.

Time stamp

number (micro seconds)

Yes

The time at which the meta data is located with in the media being played.

Duration

number (micro seconds)

Yes

The time duration for which the meta data is relevant with in the media being played. If the duration is not specified, it will be set to a value larger than the complete duration of the media.

 


Prop: onAudioBitrateChanged

Invoked when the audio bitrate has changed. This may be emitted at any time. The callback passes a new bitrate in kbps.

Type

Required

function

No


Prop: onVideoBitrateChanged

Invoked when the video bitrate has changed. This may be emitted at any time. The callback passes a new bitrate in kbps.

Type

Required

function

No


Prop: onTotalBitrateChanged

Invoked when the combined video and audio bitrate has changed. This may be emitted at any time. The callback passes a new bitrate in kbps.

Type

Required

function

No


Prop: testID

A unique identifier for this element to be used in UI automation testing scripts. Currently, it is not supported for the Roku target platform.

Type

Required

string

No


Method: seek()

seek(positionInMS : number)

Seek the video to a specific position in the video media. When seeking backwards from playback complete, the player must remain paused.

Parameters:

Name

Type

Required

Description

positionInMS

number

Yes

Video position to seek to


Method: play()

play()

Starts the playback of the prepared video asset, or resumes playback if the player is paused.

Note

If you are using a customized Android manifest file for the Android target platform, you need to add the FOREGROUND_SERVICE to the manifest file as shown below:
<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>

For those apps using the template from You.i Engine One, it will be automatically taken care of.


Method: pause()

pause()

Pauses video playback.


Method: stop()

stop()

Stops video playback. Allows users to switch between multiple videos and unload media.


Method: getStatistics()

getStatistics()

Returns a promise for the latest statistics from the player:

  • isLive: boolean
  • totalBitrateKbps: number
  • videoBitrateKbps: number
  • audioBitrateKbps: number
  • defaultTotalBitrateKbps: number
  • defaultVideoBitrateKbps: number
  • defaultAudioBitrateKbps: number
  • bufferLengthMs: number
  • minimumBufferLengthMs: number
  • framesPerSecond: number

Currently, it is not supported for the Roku target platform.


Method: getPlayerInformation()

getPlayerInformation()

Returns a promise for the following data about the player:

  • name: string
  • version: string

Method: getLiveSeekableRanges()

getLiveSeekableRanges()

Returns an array of objects that consists the valid time ranges, start time(ms) and end time(ms), within the current stream that are valid to seek to. Each element in the array has the following fields:

  • startTimeMs: number
  • endTimeMs: number

Depending on the stream, there is no guarantee that the time ranges are continuous. If the seekable time ranges of a live stream are unknown, an empty array is returned.

Note

Only available for live streaming on all supported target platforms, except Roku.