API_Reference.md

API reference

Overview

This is the API reference which presents every RxPlayer API in a single page.

The point of this page is to provide an easier-to-navigate page than the API documentation for when you're already familiar with it.

API are splitted here in multiple categories depending on if they are properties, methods, events and so on.

Constructor

• new RxPlayer(): Create a new RxPlayer.

Constructor options

• videoElement: specifies the media element on which the content will play.

• initialVideoBitrate: Ceil value for the initial video bitrate wanted.

• initialAudioBitrate: Ceil value for the initial audio bitrate wanted.

• minVideoBitrate: Minimum video bitrate reachable through adaptive streaming.

• minAudioBitrate: Minimum audio bitrate reachable through adaptive streaming.

• maxVideoBitrate: Maximum video bitrate reachable through adaptive streaming.

• maxAudioBitrate: Maximum audio bitrate reachable through adaptive streaming.

• wantedBufferAhead: Set the default buffering goal.

• preferredAudioTracks: Set default audio tracks preferences based on tracks characteristics.

• preferredTextTracks: Set default text tracks preferences based on tracks characteristics.

• preferredVideoTracks: Set default video tracks preferences based on tracks characteristics.

• maxBufferAhead: Set the default maximum kept buffer ahead of the current position, in seconds.

• maxBufferBehind: Set the default maximum kept buffer before the current position, in seconds.

• maxVideoBufferSize: Set the default maximum size the video buffer can take in the memory, in kilobytes (kb).

• limitVideoWidth: Limit the maximum video width according to the video element's current width.

• throttleVideoBitrateWhenHidden: Limit the maximum video bitrate when the current video is hidden to the user.

• stopAtEnd: Stop automatically when the end of a content is reached.

• throttleWhenHidden: [Deprecated] Limit the maximum video bitrate when the current video is hidden to the user.

loadVideo options

• transport: The adaptive streaming technology (e.g. "dash", "smooth" etc.) used.

• url: URL to the content (e.g. DASH's MPD, Smooth's Manifest etc.)

• keySystems: DRM configuration for the content.

  • keySystems[].type: Name of the DRM technology wanted.

  • keySystems[].getLicense: Logic to fetch the license.

  • keySystems[].getLicenseConfig: Supplementary configuration linked to the getLicense function.

  • keySystems[].serverCertificate: Eventual certificate encrypting exchanges between the CDM and license server.

  • keySystems[].persistentLicense: Allows to ask for the DRM session to persist the license.

  • keySystems[].licenseStorage: Allows to ask for the DRM session to persist the license.

  • keySystems[].fallbackOn: Allows to fallback to another quality when a key is refused.

  • keySystems[].maxSessionCacheSize: Maximum number of DRM sessions cached by the RxPlayer.

  • keySystems[].closeSessionsOnStop: Closes DRM sessions when the content stops.

  • keySystems[].singleLicensePer: Allows to use a single getLicense call for keys linked to multiple qualities.

  • keySystems[].disableMediaKeysAttachmentLock: Disable a lock that may cause the RxPlayer to deadlock on encrypted contents on some peculiar devices.

  • keySystems[].distinctiveIdentifierRequired: Allows the configuration of the Distinctive Indentifier(s) property.

  • keySystems[].persistentStateRequired: Allows the configuration of the persistentState property.

  • keySystems[].throwOnLicenseExpiration: Allows to stop or not when the current license has expired.

  • keySystems[].onKeyStatusesChange: Callback triggered when on of the key's status is updated.

• autoPlay: Allows to automatically play after a content is loaded.

• startAt: Define the position at which the RxPlayer should start.

• transportOptions: Options relative to the current "transport".

  • transportOptions.minimumManifestUpdateInterval: Allows to limit the frequency of Manifest updates.

  • transportOptions.initialManifest: Allows to provide an initial Manifest to speed-up the content loading

  • transportOptions.manifestUpdateUrl: Provide another URL, potentially to a shorter Manifest, used only for Manifest updates

  • transportOptions.representationFilter: Filter out qualities from the Manifest based on its characteristics.

  • transportOptions.segmentLoader: Provide a custom logic to fetch segments.

  • transportOptions.manifestLoader: Provide a custom logic to fetch the Manifest.

  • transportOptions.checkMediaSegmentIntegrity: Enable supplementary checks to retry a request if a segment appears corrupted.

  • transportOptions.serverSyncInfos: Provide time synchronization mechanism between the client and server.

  • transportOptions.aggressiveMode: Allows to ask to download the segments early.

  • transportOptions.referenceDateTime: Default offset to add to the segment's time to obtain a live time. This is in most cases not needed.

• textTrackMode: The way in which the text tracks should be displayed.

• textTrackElement: HTMLElement in which text tracks should be displayed.

• audioTrackSwitchingMode: Behavior when switching the audio track.

• manualBitrateSwitchingMode: Behavior when switching manually the video or audio quality.

• onCodecSwitch: Behavior when the codec changes between incompatible ones.

• lowLatencyMode: Allows to play low-latency contents efficiently.

• networkConfig: Configuration linked to the Manifest and segment requests.

  • networkConfig.segmentRetry: Maximum number of retries when a segment request fails.

  • networkConfig.manifestRetry: Maximum number of retries when a Manifest request fails.

  • networkConfig.offlineRetry: Maximum number of retries when a Manifest or segment request fails due to the user being offline.

  • networkConfig.manifestRequestTimeout: Timeout after which manifest requests are aborted.

  • networkConfig.segmentRequestTimeout: Timeout after which segment requests are aborted.

• enableFastSwitching: Enable or disable an optimization replacing segments of poor quality with segments of a better quality.

• hideNativeSubtitle: [Deprecated] hide subtitles in <track> elements.

• supplementaryImageTracks: [Deprecated] Add supplementary tracks in the content for thumbnails.

• supplementaryTextTracks: [Deprecated] Add supplementary tracks in the content for text.

• defaultAudioTrack: [Deprecated] Default characteristics wanted for the audio track.

• defaultTextTrack: [Deprecated] Default characteristics wanted for the text track.

Methods

• loadVideo: Load a content.

• getPlayerState: Get the current player's state.

• addEventListener: Add a listener to one of the RxPlayer's event.

• removeEventListener: Remove a listener to one of the RxPlayer's event.

• play: Resume paused content.

• pause: Pause the current content.

• stop: Stop playing the current content.

• getPosition: Get the current playback condition.

• getWallClockTime: Get the current playback condition offseted to be relative to the the current date.

• seekTo: Seek in the current content.

• getMinimumPosition: Get the minimum seekable position.

• getMaximumPosition: Get the maximum seekable position.

• getVideoDuration: Get the duration linked to the media element.

• getError: Returns the current "fatal" error.

• getVideoElement: Returns the media element linked to the RxPlayer.

• dispose: Dispose of most resources taken by the RxPlayer.

• reload: Reload the last loade content as fast as possible.

• getAudioTrack: Get information on the current audio track.

• getTextTrack: Get information on the current text track.

• getVideoTrack: Get information on the current video track.

• getAvailableAudioTracks: Get information on all the available audio tracks.

• getAvailableTextTracks: Get information on all the available text tracks.

• getAvailableVideoTracks: Get information on all the available video tracks.

• setAudioTrack: Set the current audio track.

• setTextTrack: Set the current text track.

• setVideoTrack: Set the current video track.

• disableTextTrack: Disable the current text track.

• disableVideoTrack: Disable the current video track.

• setPreferredAudioTracks: Update the current audio tracks preferences.

• setPreferredTextTracks: Update the current text tracks preferences.

• setPreferredVideoTracks: Update the current video tracks preferences.

• getPreferredAudioTracks: Return the current audio tracks preferences.

• getPreferredTextTracks: Return the current text tracks preferences.

• getPreferredVideoTracks: Return the current video tracks preferences.

• isTrickModeEnabled: Returns true if trick mode tracks are currently enabled by default.

• getVideoBitrate: Returns the bitrate of the current video quality.

• getAudioBitrate: Returns the bitrate of the current audio quality.

• getAvailableVideoBitrates: Returns all available bitrates for the current video track.

• getAvailableAudioBitrates: Returns all available bitrates for the current audio track.

• setVideoBitrate: Set the bitrate for the current video track.

• setAudioBitrate: Set the bitrate for the current audio track.

• getManualVideoBitrate: Returns the last video bitrate manually set.

• getManualAudioBitrate: Returns the last audio bitrate manually set.

• setMinVideoBitrate: Set the minimum video bitrate reachable through adaptive streaming.

• setMinAudioBitrate: Set the minimum audio bitrate reachable through adaptive streaming.

• setMaxVideoBitrate: Set the maximum video bitrate reachable through adaptive streaming.

• setMaxAudioBitrate: Set the maximum audio bitrate reachable through adaptive streaming.

• getMinVideoBitrate: Returns the minimum video bitrate reachable through adaptive streaming.

• getMinAudioBitrate: Returns the minimum audio bitrate reachable through adaptive streaming.

• getMaxVideoBitrate: Returns the maximum video bitrate reachable through adaptive streaming.

• getMaxAudioBitrate: Returns the maximum audio bitrate reachable through adaptive streaming.

• setPlaybackRate: Update the speed at which the content is played.

• getPlaybackRate: Read the speed at which the content is played.

• areTrickModeTracksEnabled: Indicates if the tricmode tracks are active by default.

• setVolume: Update the audio volume.

• getVolume: Get the current audio volume.

• mute: Mute the audio volume.

• isMute: Return true if the audio volume is set to 0.

• isMute: Return true if the audio volume is set to 0.

• unMute: Restore the volume as it was before it was muted.

• setWantedBufferAhead: Update the buffering goal, in seconds.

• getWantedBufferAhead: Get the current buffering goal, in seconds

• setMaxBufferBehind: Remove automatically old media data.

• getMaxBufferBehind: Get the current maximum kept buffer behind the current position, in seconds.

• setMaxBufferAhead: Remove automatically media data too far ahead.

• getMaxBufferAhead: Get the current maximum kept buffer ahead of the current position, in seconds.

• setMaxVideoBufferSize: Set the maximum memory the video buffer can take up in the memory, in kilobytes.

• getMaxVideoBufferSize: Get the maximum memory the video buffer can take up in the memory, in kilobytes.

• getVideoBufferGap: Returns in seconds the difference between the current position and the end of the current media time range.

• getVideoLoadedTime: Returns in seconds the difference between the start and the end of the current media time range.

• getVideoPlayedTime: Returns in seconds the difference between the start of the current media time range and the current position.

• getUrl: Get URL of the currently-played content.

• isLive: Returns true if the content is a "live" content.

• getCurrentKeySystem: Returns the name of the current key system.

• getManifest: [Deprecated] Information on the current Manifest.

• getCurrentAdaptations: [Deprecated] Information on the current Adaptations.

• getCurrentRepresentations: [Deprecated] Information on the current Representations.

• setFullscreen: [Deprecated] Switch media element into fullscreen mode.

• isFullscreen: [Deprecated] Returns true if the current media element is in fullscreen mode.

• exitFullscreen: [Deprecated] Exit fullscreen mode.

• getImageTrackData: [Deprecated] Returns the data of the current image track.

• getNativeTextTrack: [Deprecated] Returns the first <track> element attached to the media element.

Static Properties

• version: The current version of the RxPlayer.

• LogLevel: Update the verbosity of the RxPlayer logger.

• ErrorTypes: All Error types that can be encountered.

• ErrorCodes: All Error codes that can be encountered.

Events

• playerStateChange: The current state of the player has changed.

• error: A fatal error happened.

• warning: A non-fatal error happened.

• positionUpdate: Regular event about the current position evolving.

• seeking: A seek operation began.

• seeked: A seek operation ended.

• availableAudioTracksChange: The list of available audio tracks changed.

• availableVideoTracksChange: The list of available video tracks changed.

• availableTextTracksChange: The list of available text tracks changed.

• audioTrackChange: The current audio track changed.

• videoTrackChange: The current video track changed.

• textTrackChange: The current text track changed.

• availableAudioBitratesChange: The list of available audio bitrates changed.

• availableVideoBitratesChange: The list of available video bitrates changed.

• audioBitrateChange: The current audio bitrate changed.

• videoBitrateChange: The current video track changed.

• bitrateEstimationChange: A new bitrate estimate is available.

• periodChange: A new Period begins.

• decipherabilityUpdate: A Representation's decipherability status has been updated.

• inbandEvents: Events in the media have been encountered.

• streamEvent: A "stream event" just started.

• streamEventSkip: A "stream event" was just skipped.

• imageTrackUpdate: [Deprecated] The current image track changed.

• fullscreenChange: [Deprecated] The player went into or exited fullscreen mode.

• nativeTextTracksChange: [Deprecated] A <track> element is added or removed to the media element.

Error types

• NETWORK_ERROR: A network-related error.

• MEDIA_ERROR: A media-related error.

• ENCRYPTED_MEDIA_ERROR: An error related to media decryption.

• OTHER_ERROR: Another non-categorized error.

Tools

• TextTrackRenderer: Render external text tracks on top of the video.

• VideoThumbnailLoader: Display seeking preview thumbnails from trick mode video tracks.

• StringUtils: Various string conversion utils.

• parseBifThumbnails: Parse thumbnails in the "BIF" format.

• MediaCapabilitiesProber: Tool to probe several media-related browser APIs.

• createMetaplaylist: Generate a MetaPlaylist content.