Player Configuration

Android

PlaybackProperties

The following properties are available for configuring Android playback behavior:

Property	Type	Description
preferredInitialBufferDurationMs	number	Duration of media that must be buffered before playback starts or resumes after a user action (e.g. seek), in milliseconds.
preferredMinBufferDurationMs	number	Minimum duration of media the player will attempt to keep buffered at all times, in milliseconds.
preferredMaxBufferDurationMs	number	Maximum duration of media the player will attempt to buffer, in milliseconds.
preferredBufferDurationAfterRebufferMs	number	Duration of media that must be buffered for playback to resume after a rebuffer (caused by buffer depletion, not a user action), in milliseconds.
preferredMinLoadableRetryCountMs	number	Minimum number of times to retry loading data before propagating the error.
autoPlayOnLoad	boolean	Whether playback starts automatically when content is loaded.
initialStartTimeMillis	number	Initial start position for playback, in milliseconds.
preferredConnectTimeoutMs	number	Connection read timeout, in milliseconds.
preferredReadTimeoutMs	number	Minimum number of times to retry a load before a load error may be considered fatal.
asyncCodecProcessing	boolean	Enables synchronization of codec interactions with asynchronous buffer queueing.
preferredInitialNetworkBandwidth	number	Initial network bandwidth estimate (in bits per second) used for optimal track selection on startup.
preferredMinDurationForQualityIncreaseMs	number	Minimum buffered duration required to switch to a higher quality track, in milliseconds. Default: 10000.
preferredMaxDurationForQualityDecreaseMs	number	Maximum buffered duration before switching to a lower quality track, in milliseconds. Default: 25000.
preferredMinDurationToRetainAfterDiscardMs	number	Minimum duration of lower quality media to retain when discarding during a quality upgrade. Default: 25000.
preferredBandwidthFraction	number	Fraction of available bandwidth considered for track selection. Values below 1 account for estimator inaccuracies. Default: 0.7.
preferredMaxPlaybackRecoveryRetryCount	number	Maximum number of recovery attempts before a non-fatal error is propagated via onError.
monitorLiveStream	boolean	Enables live stream monitoring to prevent the player from falling behind the media window.
tunnelingMode	boolean	Enables tunneled video playback for hardware-accelerated decoding on Android TV. Should only be enabled on TV platforms. Default: false.
monitorVFPO	boolean	Enables or disables VFPO (Video Frame Processing Offset Average) monitoring. Default: false.
vfpoMonitoringRange	IntRange	Lower and upper VFPO thresholds used to trigger bitrate switching. Only applicable when monitorVFPO is true. Default: 15000...40000.
mediaSessionPlaybackActions	Array<number>	Playback actions permitted externally via Android's MediaSession API (e.g. Google Assistant).
preferredTargetLiveOffsetMs	number	Target offset from the live edge, in milliseconds. Defaults to the player-calculated value if not set.
preferredMinPlaybackSpeed	number	Minimum playback speed used when catching up to the live edge.
preferredMaxPlaybackSpeed	number	Maximum playback speed used when catching up to the live edge.
preferredBufferedFractionToLiveEdgeForQualityIncrease	number	Fraction of the duration to the live edge that must be buffered before switching to a higher quality track.
preferredMinLiveStartPosition	number	Minimum position from which playback is allowed to start, in milliseconds.
preferredSeekBackIncrementMs	number	Preferred seek-back increment, in milliseconds.
preferredSeekForwardIncrementMs	number	Preferred seek-forward increment, in milliseconds.
remoteStopLivePlaybackOnPause	boolean	When true, stops live playback when a pause is triggered remotely. Default: false.
handleAudioFocus	boolean	Controls audio focus behavior. Set to false to allow simultaneous playback of multiple players. Default: true.
preferredFallbackMinPlaybackSpeed	number	Minimum playback speed when none is defined by the media. Default: 0.97.
preferredFallbackMaxPlaybackSpeed	number	Maximum playback speed when none is defined by the media. Default: 1.03.
preferredTargetLiveOffsetIncrementOnRebufferMs	number	Increment applied to the target live offset each time the player rebuffers, in milliseconds.
preferredBufferTimeoutMs	number	Maximum duration the player attempts to buffer before throwing a timeout error. Prevents indefinite buffering.
preferredBackBufferDurationMs	number	Duration of media retained in the buffer prior to the current playback position, for fast backward seeking.
preferredRetainBackBufferFromKeyframe	boolean	When false, backward seeking is only fast if the back buffer contains a keyframe before the seek position.
preferredMinBitrate	number	Minimum bitrate (in bits per second) considered for adaptive track selection on startup.
preferredMaxBitrate	number	Maximum bitrate (in bits per second) considered for adaptive track selection on startup.
liveStreamMonitorConfiguration	LiveStreamMonitorConfiguration	Configuration for the live stream monitoring logic.
recoverablePlayerErrors	Array<string>	Error codes from which the player will attempt to recover. Send an empty array to disable recovery.

Usage

Basic Buffer Configuration

import { createPlayer, PlayerConfig } from '@quickplay/rn-qp-nxg-player';

const playbackProperties: PlaybackProperties = {
  preferredInitialBufferDurationMs: 1500,
  preferredMinBufferDurationMs: 3000,
  preferredMaxBufferDurationMs: 15000,
  preferredBufferDurationAfterRebufferMs: 3000,
  preferredTargetLiveOffsetIncrementOnRebufferMs: 0,
};

const playerConfig: PlayerConfig = {
  playbackProperties: playbackProperties,
  // ... other configuration
};

const player = await createPlayer(playerConfig);

Thumbnail Preview

The player provides two APIs for retrieving thumbnail previews during seek, depending on the player type being used.

API	Returns	Usage
getThumbnailPreview(position)	Base64 encoded image string	All players except Brightcove
getThumbnailUrl(position)	Remote image URL	Brightcove player only

// For most players — returns a base64 image
const res = await player.getThumbnailPreview(currentPosition);
if (res != null) {
  const base64Icon = `data:image/png;base64,${res}`;
  setThumbnailImage(base64Icon);
}

// For Brightcove — returns a remote URL
const res = await player.getThumbnailUrl(currentPosition);
if (res != null) {
  setThumbnailImage(res);
}

iOS

PlayerPreference

The following properties are available for configuring iOS and tvOS playback behavior:

Property	Type	Description
initialPlaybackTime	number	Initial playback position at which the player begins playback.
preferredPeakBitRate	number	Preferred peak bitrate for adaptive streaming track selection.
preferredInitialForwardBufferDuration	number	Preferred initial forward buffer duration before playback starts, in seconds.
preferredForwardBufferDurationAfterRebuffer	number	Preferred forward buffer duration after a rebuffer event, in seconds.
preferredPeakBitRateForExpensiveNetworks	number	Preferred peak bitrate when on expensive networks (e.g. cellular).
preferredMaximumResolutionForExpensiveNetworks	string	Preferred maximum resolution when on expensive networks.
preferredMaximumResolution	string	Preferred maximum resolution for playback.
startsOnFirstEligibleVariant	boolean	When true, playback starts on the first eligible stream variant.
assignRemoteActions	boolean	When true, automatically updates NowPlayingInfo with playback metadata such as playhead time and duration. Required for Apple TV's "Continue Watching" queue.
remoteStopAction	RemoteStopAction	Defines the behavior of the remote stop action.
addInterstitialMarkers	boolean	Enables interstitial markers in the playback timeline.
shouldAutoResumeAfterInterruption	boolean	When true, the player automatically resumes playback after an interruption. Default: true.
enableAdditionalSubtitle	[AdditionalSubtitleFormat]	Enables additional subtitle formats. Pass ['SMPTE-TT'] to enable SMPTE-TT subtitle rendering on iOS.
shouldHandleAudioInterruption	boolean	When true, the player handles audio interruption actions (pause/play) internally. When false, the application is responsible for handling them. Default: true.
useSharedNowPlayingInfoCenter	boolean	When true, uses MPNowPlayingInfoCenter instead of MPNowPlayingSession on tvOS. Useful for compatibility with older Apple TV HD models. Not applicable to iOS.
audiovisualBackgroundPlaybackPolicy	AudiovisualBackgroundPlaybackPolicy	Controls playback behavior when the app transitions to the background. Accepted values: automatic, continuesIfPossible, pauses.

Usage

Basic Buffer Configuration

import { createPlayer, PlayerConfig } from '@quickplay/rn-qp-nxg-player';

const playerPreference: PlayerPreference = {
  preferredInitialForwardBufferDuration: 3,
  preferredForwardBufferDurationAfterRebuffer: 3,
};

const playerConfig: PlayerConfig = {
  // ... other configuration
};

const player = await createPlayer(playerConfig);
player.setPlayerPreference(playerPreference);

Low Latency Playback

To minimize delay while maintaining smooth playback, set both buffer duration properties to a low value.

const playerPreference: PlayerPreference = {
  preferredInitialForwardBufferDuration: 1,
  preferredForwardBufferDurationAfterRebuffer: 1,
};

player.setPlayerPreference(playerPreference);

Now Playing Info

Use setNowPlayingInfo to display playback metadata on the lock screen and in the Control Center. Set constant metadata such as title and artist after player creation, and update it when ad breaks start and end.

// Set Now Playing info for main content
const playingInfo: PlayingInfo = {
  assetUrl: playerConfig.mediaURL,
  mediaType: playerConfig.mediaType,
  title: 'Interstellar',
  artist: 'Unknown Artist',
  contentIdentifier: '550e8400-e29b-41d4-a716-446655440000',
};
player.setNowPlayingInfo(playingInfo);

// Set artwork on the lock screen
await player.setNowPlayingArtworkImage('artWorkUrl');

// Enable automatic playhead and duration updates in Now Playing info
player.setPlayerPreference({ assignRemoteActions: true });

To update Now Playing metadata during ad breaks, listen for onAdBreakStart and onAdBreakEnd events:

const playerListener = {
  onAdBreakStart(adBreakInfo: AdPlayerAdBreakInfo): void {
    player.setNowPlayingInfo({ title: 'Advertisement' });
  },
  onAdBreakEnd(adBreakInfo: AdPlayerAdBreakInfo): void {
    player.setNowPlayingInfo({
      assetUrl: playerConfig.mediaURL,
      mediaType: playerConfig.mediaType,
      title: 'Interstellar',
      artist: 'Unknown Artist',
    });
  },
};

player.addListener(playerListener);

Manual Reporting Using MPNowPlayingInfoCenter

On tvOS, the player uses MPNowPlayingSession by default to report playback metadata. However, some older Apple TV HD models do not recognize metadata reported through this API. To ensure compatibility with these devices, configure the player to use the shared MPNowPlayingInfoCenter instance instead:

player.setPlayerPreference({ useSharedNowPlayingInfoCenter: true });

Note: useSharedNowPlayingInfoCenter is only applicable to tvOS. On iOS, MPNowPlayingInfoCenter is always used.

Remote command registration is handled automatically by the player — commands are registered on player creation and unregistered when the instance is deinitialized. No additional management is required by the application.

SMPTE-TT Subtitles

SMPTE-TT is a bitmap-based subtitle format where subtitle data is embedded in the stream and delivered as XML via ID3 timed metadata. Since AVPlayer does not natively support this format, the QP Player includes custom rendering support for SMPTE-TT subtitles. Subtitles can also be delivered via a sidecar XML file covering the full media duration.

Note: SMPTE-TT rendering is resource-intensive. Enable it only for content that explicitly supports this subtitle format.

const playerPreference: PlayerPreference = {
  enableAdditionalSubtitle: enableSubtitleMediaTrackType ? ['SMPTE-TT'] : undefined,
};

player.setPlayerPreference(playerPreference);

Thumbnail Preview

The player provides two APIs for retrieving thumbnail previews during seek, depending on the player type being used.

API	Returns	Usage
getThumbnailPreview(position)	Base64 encoded image string	All players except Brightcove
getThumbnailUrl(position)	Remote image URL	Brightcove player only

// For most players — returns a base64 image
const res = await player.getThumbnailPreview(currentPosition);
if (res != null) {
  const base64Icon = `data:image/png;base64,${res}`;
  setThumbnailImage(base64Icon);
}

// For Brightcove — returns a remote URL
const res = await player.getThumbnailUrl(currentPosition);
if (res != null) {
  setThumbnailImage(res);
}