Apple TV

CLAppleTVPlayer

On Apple tvOS, you can develop a native UI player using the CLAppleTVPlayer class. Refer to the example/src/screens/AppleTVDemosScreen.tsx for an example of how to use this class. The class is supported on tvOS 15.0 and above.

Methods

• openPlayer() Open a new player with player options and action information.

  import { CLAppleTVPlayer } from '@castlabs/react-native-prestoplay';
  
  public static openPlayer(stream: TVStream,
                    options?: PlayerOptions,
                    transportBarActions?: any[],
                    infoTabActions?: Action[],
                    contextualActions?: Action[],
                    error?: (error: any) => void,
                    success?: () => void)
  • stream: Stream configuration, metadata, and the next channel information. Refer to the TVStream section.
  • options: Options to control the player. Refer to the PlayerOptions section.
  • transportBarActions: Array of transport bar actions - Action or PopupMenu.
  • infoTabActions: Array of info tab actions - Action.
  • contextualActions: Array of contextual actions - Action.
  • error: Error callback
  • success: Success callback

• replaceStreamAndActions(), replaceStream() Replace the playback stream, player options, and actions.

  public static replaceStreamAndActions(stream: TVStream,
                                      options?: PlayerOptions,
                                      transportBarActions?: any[],
                                      infoTabActions?: Action[],
                                      contextualActions?: Action[],
                                      error?: (error: any) => void,
                                      success?: () => void)
  
  public static replaceStream(stream: TVStream,
                            error?: (error: any) => void,
                            success?: () => void)

  The parameters are the same as the openPlayer().

• play() Begins playback of the current stream.

• pause() Pauses playback of the current stream.

• closePlayer() Close a player

• setMetadata(metadata: string) Set the metadata to be displayed in the title view and info tab.

  let metadata = JSON.stringify({
      mainTitle: "Main Title",
      subTitle: "Subtitle",
      artworkImage: "https://url.of.artwork/image.jpg",
      description: "Description of the channel"
  });

• setOptions(options: PlayerOptions) Set player options. Refer to the PlayerOptions section for details.

• setTransportBarActions(transportBarActions: any[]) Set transport bar action controls.

  • transportBarActions: Array of Action or PopupMenu.

• setInfoTabActions(infoTabActions: Action[]) Set info tab action controls.

  • infoTabActions: Array of Action.

• setContextualActions(contextualActions: Action[]) Set contextual action controls.

  • contextualActions: Array of Action.

• addActionListener() To handle action events, you can add a handler using the CLAppleTVPlayer.addActionListener() method.

  const onActionEvent = (event: any) => {
      switch (event.id) {
          case ActionId.Speed:
              CLAppleTVPlayer.setRate(Number(event.data));
              break;
          case ActionId.Skip00:
              CLAppleTVPlayer.seekToSecond(15);
              break;
          // ...
      }
  }
  this.actionSubscription = CLAppleTVPlayer.addActionListener(onActionEvent);

• removeActionListener() Remove the action handler using the following function.

  clappletvplayer.removeactionlistener(this.actionsubscription);

• setActionStateAndUi(id: string, state: boolean, uiProp: ActionUiProperty) Change action state and UI appearance.

  • id: Action idenfitier.
  • state: Action state - true or false.
  • uiProp: Action title and image resource name in the Xcode app project.

• setRate(rate: Number) Set playback rate.

  • rate: Playback rate.

• seekToSecond(second: Number) Move playback position.

  • second: Time to move in seconds.

• getLiveStartTime(): Promise<Number> Returns the live start time since the epoch in seconds; -1 if it is unknown or not applicable. A live HLS stream has to have the EXT-X-PROGRAM-DATE-TIME defined.

• getPosition(): Promise<Number> Get the current playback position in seconds.

• getAudioTrack(): Promise<AudioTrack> Returns the current audio track as an object.

• getSubtitleTrack(): Promise<SubtitleTrack> Returns the current subtitle track as an object.

Player events

• CLAppleTVPlayer.didPlayToEnd: Called when the playback is ended. You can close the player or change the stream within this event.

• CLAppleTVPlayer.playerIsClosed: Called when a player is closed.

• CLAppleTVPlayer.willSeek: Called before the playback position is moved.

  • oldSeconds: The current playback position.
  • targetSeconds: The position to move.
  • beyondSeekableRange: The targetSeconds is greater than the seekable range. For live streams, this can indicate an attempt to seek to the current live position.

• CLAppleTVPlayer.didSeek: Called after the playback position is moved.

  • oldSeconds: The position before moving.
  • targetSeconds: The position where playback resumes.

• CLAppleTVPlayer.timeControlStatus: Called when playback status is updated. Refer to AVPlayer.timeControlStatus

  • status: 0(paused), 1(waiting), 2(playing)
  • description: description of the status value

• CLAppleTVPlayer.skipToPreviousChannel: Called when a user tries to skip to the previous channel in a live stream. In this event, you should call replaceStream() or replaceStreamAndActions() with the previous TVStream value.

• CLAppleTVPlayer.skipToNextChannel: Called when a user tries to skip to the next channel in a live stream. In this event, you should call replaceStream() or replaceStreamAndActions() with the next TVStream value.

• CLAppleTVPlayer.onError: Triggered on player error. The error object contains the same values as onError(error) of CLVideo.

• CLAppleTVPlayer.audioTrackChanged: Called when the audio track changed. The track object contains the same values as getAudioTrack().

• CLAppleTVPlayer.subtitleTrackChanged: Called when the sutitle track changed. The track object contains the same values as getSubtitleTrack().

Types

TVStream

export type TVStream = {
    playerConfig: string,
    channelMetadata: string,
    nextChannelInfo?: string,
}

• playerConfig: A JSON string of the PlayerConfig. Refer to the PlayerConfig.md file for details.

• channelMetadata: Metadata that is displayed in a title view and an info tab.

  channelMetadata: JSON.stringify({
      mainTitle: "Main Title",
      subTitle: "Subtitle",
      artworkImage: "https://artwork.url.com/image.png",
      description: "Description of the channel."
  })
  • mainTitle: The stream title.
  • subTitle: The stream subtitle.
  • artworkImage: One of the two options can be used for artwork image.
    1. Image resource name in Xcode app project
    2. URL of local or remote image file
  • description: Description of the channel.

• nextChannelInfo: The next/previous channel information.

  nextChannelInfo: JSON.stringify({
      previousChannelInterstitialView: {
          xibName: "ChannelInterstitialView",
          labels: [
              {1000: "Previous channel number"},
              {1001: "Previous channel title"}
          ],
          images: [
              {2000: previousLogoUri},
              {2001: "image00"},
          ]
      },
      nextChannelInterstitialView: {
          xibName: "ChannelInterstitialView",
          labels: [
              {1000: "Next channel number"},
              {1001: "Next channel title"}
          ],
          images: [
              {2000: nextLogoUri},
              {2001: "image01"},
          ]
      }
  })
  • previousChannelInterstitialView, nextChannelInterstitialView: The view shown when the LIVE channel changes.
    • xibName: Your XIB file name for the view in the Xcode app project. The file is first searched in the bundle's language-specific project directories, then in the Resources directory. Refer to the Apple document.
    • labels: Array of text components in the view. The texts are displayed by UILabel. The key is UILabel's tag number. You can set the tag number in the Xcode Interface Builder.
    • images: Array of image components in the view. The images are displayed by UIImageView. The key is UIImageView's tag number. One of the two options can be used for images.
      1. Image resource name in Xcode app project
      2. URL of local or remote image file

PopupMenu

export type PopupMenu = {
    title: string,
    imageName: string,
    actions: Action[]
}

• title: Popup menu title
• imageName: Image asset name in the Xcode project.
• actions: Array of actions

Action

export type Action = {
    id: string,
    title: string,
    imageName?: string,
    subMenu?: SubMenu,     // for menu action
    startSecond?: number,  // for contextual action
    endSecond?: number,    // for contextual action
}

• id: Action identifier
• title: Action title
• imageName: One of the two options can be used for image.
  1. Image resource name in Xcode app project
  2. System image name, SF Symbols
• subMenu: Submenu info. It includes the default value and submenu items.
• startSecond: Contextual action is displayed at this time.
• endSecond: Contextual action is removed at this time.

SubMenu

export type SubMenu= {
    defaultValue: string,
    menuItems: SubMenuItem[]
}

• defaultValue: Default value of the submenu
• menuItems: Array of the SubMenuItem

SubMenuItem

export type SubMenuItem = {
    title: string,
    value: string,
}

• title: Title of the submenu
• value: Value of the submenu

ActionUiProperty

export type ActionUiProperty = {
    title?: string,
    imageName?: string,
}

• title: Action title
• imageName: Image asset name in the Xcode project.

PlayerOptions

export type PlayerOptions = {
    allowsPictureInPicturePlayback?: boolean;
    closeWhenPlaybackEnd?: boolean;
    requiresLinearPlayback?: boolean;
    disableChannelSkipInLiveStream: boolean;
}

• allowsPictureInPicturePlayback: Enable the Picture in Picture feature. The PiP button appears in the bottom right area. Refer to the Apple document. The default value is true.
• closeWhenPlaybackEnd: If set to true, the player will automatically close when playback ends. The default value is true.
• requiresLinearPlayback: If set to true, user can not skip the content. Refer to the Apple document. The default value is false.
• **disableChannelSkipInLiveStream: If set to true, user can not skip to the next or previous channels in live stream. The default value is false.