Options

The Ravnur Media Player provides a set of options to customize the behavior and appearance of the player. Below is a list of available options, including default values and descriptions.

Property	Default Value	Type	Description
`aesToken`	`undefined`	`string`	AES Token value. This property specifies the AES Token used for decryption.
`logger`	`undefined`	`PlayerLogger`	Custom logger implementation for the player.
`loggerLevel`	`2`	`number`	Sets the severity level of logs (0-4: error, warn, info, debug, trace).
`i18n`	`null`	`PlayerTranslation`	Custom translations object for internationalization.
`showPlay`	`true`	`boolean`	Shows play/pause button in the player controls.
`showProgress`	`true`	`boolean`	Shows the progress bar and time indicators.
`showVolume`	`true (false on mobile)`	`boolean`	Shows volume control slider and mute button.
`showFullScreen`	`true (false for audio)`	`boolean`	Shows fullscreen toggle button.
`showTheaterMode`	`false`	`boolean`	Shows theater mode button for wide screen viewing.
`showClosedCaptions`	`true`	`boolean`	Shows closed captions/subtitles toggle and menu.
`showCaptionSearch`	`false`	`boolean`	Shows caption search functionality in the menu.
`showTOC`	`true (false for audio)`	`boolean`	Shows table of contents/chapters menu.
`showAnnotations`	`true (false for audio)`	`boolean`	Shows annotations overlay on the video.
`showQuality`	`true (false on mobile/audio)`	`boolean`	Shows quality level selector in settings.
`showAudioTracks`	`false`	`boolean`	Shows audio track selector for multi-audio content.
`showPoster`	`true`	`boolean`	Shows poster image before playback starts.
`showPlaceholder`	`true`	`boolean`	Adds play button overlay on the poster/video.
`showPlaybackRate`	`true (false on Android)`	`boolean`	Shows playback speed control in settings.
`showForward`	`true`	`boolean`	Shows skip forward button (default: 10 seconds).
`showBackward`	`true`	`boolean`	Shows skip backward button (default: 10 seconds).
`showSettings`	`true`	`boolean`	Shows settings menu button.
`showDownload`	`true`	`boolean`	Shows download button for media content. Depends on showDownloadVideo and showDownloadCC properties.
`showDownloadVideo`	`true`	`boolean`	Shows video download option in the download menu. Requires downloadVideoURL property to be set.
`showDownloadCC`	`false`	`boolean`	Shows closed captions download option in the download menu.
`showTitle`	`true (false on mobile)`	`boolean`	Shows media title in the player.
`showNextFrame`	`false`	`boolean`	Shows next frame button for frame-by-frame navigation.
`showPrevFrame`	`false`	`boolean`	Shows previous frame button for frame-by-frame navigation.
`showCCLayout`	`true (false on mobile)`	`boolean`	Enables caption layout customization in CC settings.
`showPrev`	`false`	`boolean`	Shows previous track button in fullscreen mode.
`showNext`	`false`	`boolean`	Shows next track button in fullscreen mode.
`showBottomNext`	`false`	`boolean`	Shows next track button at the bottom of the player.
`showBottomPrev`	`false`	`boolean`	Shows previous track button at the bottom of the player.
`showCrawl`	`false`	`boolean`	Shows scrolling text crawl overlay.
`crawl`	`null`	`PlayerCrawlOptions`	Configuration object for crawl text (text, speed, colors).
`downloadVideoURL`	`null`	`string`	Specific URL for video download option.
`downloadCCLanguages`	`null`	`Array<{code, label}>`	Array of available caption languages for download with language codes and labels.
`isLive`	`false`	`boolean`	Enables live-stream mode, jumping to live edge on start.
`isProgressLiveStream`	`false`	`boolean`	Disables progress bar seeking and current time indicator for live streams.
`showSubtitles`	`false`	`boolean`	Disables captions built into the manifest.
`showError`	`false`	`boolean`	Shows default error message. Set to false to provide custom error handling.
`isAudio`	`false (auto-detected)`	`boolean`	Enables audio-only mode with simplified UI.
`timecode`	`0`	`number`	Sets the timecode offset value in seconds.
`frameRate`	`23.976`	`number`	Sets the frame rate for frame-accurate navigation.
`clip`	`undefined`	`[number, number]`	Plays a specific segment of media [startTime, endTime] in seconds.
`autoStart`	`false`	`boolean`	Automatically starts playback when the player is ready.
`startTime`	`null`	`number`	Sets the initial playback position in seconds.
`endTime`	`null`	`number`	Sets the end time for playback in seconds.
`useOriginTimeForPreview`	`true`	`boolean`	Uses original timeline for thumbnail previews.
`accessibility`	`false`	`boolean`	Enables accessibility features for screen readers and keyboard navigation.
`playlistmode`	`auto`	`PlayerPlaylistMode`	Controls playlist position: "auto", "right", "bottom", "hidden".
`playlistAutoGoNext`	`true`	`boolean`	Automatically plays next media item when current ends.
`playlistitle`	`""`	`string`	Title displayed above the playlist.
`playlistforcepoint`	`0`	`number`	Minimum width (px) before forcing playlist to bottom position.
`playLoop`	`false`	`boolean`	Automatically restarts playback from beginning when media ends.
`hideplaylist`	`false`	`boolean`	Hides playlist item thumbnails and previews.
`alwaysShowExtensions`	`false`	`boolean`	Keeps controls visible even during playback.
`extensionsVisibilityTimeout`	`2000 (4000 on mobile)`	`number`	Time in milliseconds before hiding controls during playback.
`skipDelta`	`10`	`number`	Number of seconds for skip forward/backward buttons.
`keyboardListeners`	`{}`	`{ [key]: function }`	Custom keyboard shortcuts mapping key codes to handler functions.
`globalKeyboardListeners`	`false`	`boolean`	When true, keyboard shortcuts work globally; when false, only in player area.
`isHandlingKeyboardEvents`	`true`	`boolean`	Enables or disables keyboard event handling.
`bufferingTimeout`	`200`	`number`	Delay in milliseconds before showing buffering spinner.
`isMobile`	`auto-detected`	`boolean`	Forces mobile mode UI. Auto-detected by default.
`nextTrackThumbnails`	`null`	`string`	Thumbnail image URL for the next track in playlist.
`nextTrackTitle`	`null`	`string`	Title text for the next track in playlist.
`prevTrackThumbnails`	`null`	`string`	Thumbnail image URL for the previous track in playlist.
`prevTrackTitle`	`null`	`string`	Title text for the previous track in playlist.
`hlsjsURL`	`CDN latest`	`string`	URL to specific hls.js library version.
`shakaURL`	`CDN latest`	`string`	URL to specific Shaka Player library version.
`flashPath`	`"/"`	`string`	Path to Flash fallback SWF files.
`hls`	See defaults	`Hls.js options`	HLS.js configuration object for HTTP Live Streaming playback settings.
`shaka`	See defaults	`Shaka Player options`	Shaka Player configuration object for DASH and advanced streaming features.
`savePlayTime`	`false`	`boolean`	Saves last playback position to localStorage for resume functionality.
`widevineURL`	`undefined`	`string`	Widevine DRM license server URL. See example below.
`playreadyURL`	`undefined`	`string`	PlayReady DRM license server URL. See example below.
`fairplayURL`	`undefined`	`string`	FairPlay DRM license server URL. See example below.
`fairplayCertificateUrl`	`undefined`	`string`	FairPlay DRM certificate URL for authentication.
`playbackRates`	`[0.5, 0.8, 1, 1.5, 2, 3, 5]`	`number[]`	Custom playback speed options. Value 1 always present as "Standard". Range: 0.01-5.
`qualityLevel`	`"Auto"`	`string`	Initial video quality (e.g., "720", "1080"). "Auto" adjusts based on connection speed.
`startLevel`	`"Auto"`	`string`	Initial HLS quality level index. Similar to qualityLevel but uses level index instead of resolution.
`maxQualityLevel`	`undefined`	`number`	Maximum quality level index allowed. Useful for limiting bandwidth usage.
`disableAutoFullScreenOnIOS`	`false`	`boolean`	Prevents automatic fullscreen mode on iOS devices during video playback.
`disableAutoUrlRewrite`	`false`	`boolean`	Disables automatic URL rewriting for media sources.
`useHTMLPlayer`	`false`	`boolean`	Forces the use of native HTML5 video player instead of advanced players.
`useHLSJSPlayer`	`false`	`boolean`	Forces the use of HLS.js player for HLS streams instead of native playback.

Advanced Configuration Objects

HLS Configuration

Ravnur Player has set of default options for hls.js configuration. You can override them by passing your own options to the player. For full list of options, see hls.js API documentation.

// Default HLS.js configuration
{
  maxFragLookUpTolerance: 0.5,
  maxMaxBufferLength: 600,
  highBufferWatchdogPeriod: 3,
  playlistLoadPolicy: {
    default: {
      maxTimeToFirstByteMs: 10000,
      maxLoadTimeMs: 120000,
      timeoutRetry: {
        maxNumRetry: 10,
        retryDelayMs: 0,
        maxRetryDelayMs: 0
      },
      errorRetry: {
        maxNumRetry: 10,
        retryDelayMs: 3000,
        maxRetryDelayMs: 8000
      }
    }
  }
}

Shaka Configuration

We do not set any default options for Shaka Player. You can set them by passing your own options to the player. Refer to the Shaka Player documentation for available options.

Internationalization (i18n)

The player supports custom translations through the i18n option. Below is a list of all available translation keys and their usage.

Key	Default Value	Usage
`fullscreen`	Fullscreen	Fullscreen button tooltip
`exit-fullscreen`	Exit full screen	Exit fullscreen button tooltip
`theater`	Theater mode	Theater mode button tooltip
`exit-theater`	Standard mode	Exit theater mode button tooltip
`play`	Play	Play button tooltip
`pause`	Pause	Pause button tooltip
`replay`	Replay	Replay button tooltip when video ends
`standard-playbackrate`	Standard	Standard playback rate label (1x)
`forward`	Forward 10 sec	Skip forward button tooltip
`backward`	Back 10 sec	Skip backward button tooltip