Configuration Reference

Configuration object

Here is the whole spread configuration object for the player and the corresponding default values if any

Player configuration object

{
  playlist: [
    // playlist item
    {
      // free common options
      videoUrl: String,
      videoProviderOptions: Object,
      muted: Boolean,
      volume: 0.7,
      autoplay: true,
      aspect: 'player',

      // premium options
      drm: Object,
      vast: Object,
      metadata: {
        title: String,
        description: String,
        imageUrl: String,
      },
      rights: {
        from: String,
        to: String
      },
      geolocation: {
        country: String,
        region: String
      },
      restrictions: {
        age: Number,
        time: {
          from: Date,
          to: Date
        }
      },
      goToButtons: [{
        title: String,
        visibleFrom: Number,
        visibleUntill: Number,
        targetTime: Number
      }],
      thumbnailsVttUrl: String,
      chaptersVttUrl: String,
    },
    // another playlist item
    {
      ...
    }
  ],
  // general option
  debug: Boolean,
  phrases: Object,
  lang: 'en',
  token: String,
  color: String
}

tip

Setting up all these options is not necessary for the player to work. Only a playlist with a videoUrl is necessary. See below for the playlist item attribute reference 👇🏻

Playlist item attributes reference (free features)

videoUrl

This is the URL of the video to be played. It can be VOD or Live.

Description	Type
videoUrl	String

videoProviderOptions

Use this option to pass a configuration option to the video provider library. As we use an external library to transmux different kinds of streams, it could be interesting for a developer to tweak them.

• See here for our shaka video provider options: https://shaka-player-demo.appspot.com/docs/api/tutorial-config.html

caution

Use this option only if you know exactly what you are doing. A misconfiguration of the provider could lead to bugs or bad performance.

autoplay

If the option is set to false, the player will stay in the preview state, showing the metadata image if any or the first frame of the video when preloading is finished.

Description	Type	Default
autoplay	Boolean	true

true means that the player will try to play, and if that's not possible due to the browser's policies limitation, the sound will be muted and the player will retry playing it (this has a good chance of working).

tip

It's important to understand that every browser has its own strategy regarding autoplay.

muted

Tells the player if the sound is muted or not.

Description	Type
autoplay	Boolean

tip

This option is independent from the following "volume" option. A player can be muted with a volume set to 0.7, and a player can be unmuted with a volume set to 0. Both configurations will lead to "no sound".

volume

Description	Type	Default
volume	Number	0.7

This option will set the player to the desired volume value.

aspect

This option will change the appearance of the player.

• player : will display the player with our style and buttons. This is the only way to have all functionalities accessible to the user. This style can be easily overwritten with a bit of CSS.
• browser : will display the player with the browser browser design, which differs from one to the others. All functionalities may not be available to the user
• chromeless: no controls at all are displayed. Usefull if you want to design your own player from scratch with the help of the API.

Description	Type	Possible values	Default
aspect	String	player | browser | chromeless	player

Native Aspect

Playlist item attributes reference (premium features)

drm (Digital Rights Management) Premium option

Description	Type
drm	Object

This option is used to set DRM parameters to let the player play protected content. The player is compatible with Playready (Microsoft), Widewine, and Fairplay (Apple).

Widevine and Playready

Server only

drm: {
  keySystem: "com.widevine.alpha" | "com.microsoft.playready",
  serverUrl: String
}

With header auth

drm: {
  keySystem: "com.widevine.alpha" | "com.microsoft.playready",
  serverUrl: String
  authType: 'header',
  headerKey: String,
  headerValue: String,
  withCookie: Boolean (optionnal),
}

With parameter auth

drm: {
  keySystem: "com.widevine.alpha" | "com.microsoft.playready",
  serverUrl: String
  authType: 'parameter',
  parameterValue: String,
  withCookie: Boolean (optionnal)
}

With robustness

drm: {
  keySystem: "com.widevine.alpha" | "com.microsoft.playready",
  serverUrl: String
  robustness: {
    videoRobustness: String,
    audioRobustness: String
  }
}

See https://vtb.axinom.com/drminfo.html for a complete values list.

Fairplay

With certificate

drm: {
  keySystem: 'com.apple.fps',
  certificate: String
}

With certificate URL

drm: {
  keySystem: 'com.apple.fps',
  certificateUrl: String
}

vast (Video Ad Serving Template) Premium option

Description	Type
vast	Object

This option allows you to play ads following the VAST specifications (https://www.iab.com/guidelines/vast/)

With VAST

vast: {
  vastUrl: 'https://cdn.oberplayer.com/fixtures/vast/vast_skip.xml'
}

Result

VMAP specifications here: https://www.iab.com/guidelines/vmap/

With VMAP

vast: {
  vmapUrl: 'https://cdn.oberplayer.com/fixtures/vast/vmap.xml'
}

Result

metadata Premium option

Description	Type
metadata	Object

This option displays a preview image and title instead of the first frame before playing.

Complete metadata object

{
  title: 'Sintel',
  description: 'Sintel is a 2010 animated fantasy short film.',
  imageUrl: 'https://cdn.oberplayer.com/fixtures/images/sintel.webp',
}

Result

rights Premium option

This option allows you to handle rights for a given video. For example you might want a livestream to be available from a certain date and hour and want a countdown to be displayed. In some other situations, you might want a video to be available until a specific date.

Description	Type
right	Object

rights: {
  from: Date (ISO 8601 Extended Format for example 2023-08-11T17:08:50+02:00),
  to: Date (ISO 8601 Extended Format for example 2023-09-11T17:08:50+02:00)
}

Now, depending on the date value, three situations can happen:

Past date

This will make the player display a message saying the video is not available anymore

For example

Future date

This will make the player display a message saying that the video will be available later and the date (> 24 hours) or a countdown (< 24 hours)

Date > 24 hours

Date < 24 hours (Countdown)

info

Keep in mind that as all strings are displayed by the player, you can easily change the message displayed with the help of the phrases option.

geolocation Premium option

This option allows you to restrict the video availability with specific country or region.

Description	Type
geolocation	Object

geolocation: {
  country: String,
  region: String
}

info

Valid regions : Europe | North America | Asia | Africa | Oceania | Antarctica

Valid country code : any valid 2 characters ISO 3166-1 code

Geolocation restriction to Kenya

restrictions Premium option

This option allows you to restrict the video availability with specific hours availability or age limitations.

Description	Type
restrictions	Object

restrictions: {
  age: Number,
  time: {
    from: 'hh:mm:ss+hh:mm' (Time with ISO timezone extended)
    to: 'hh:mm:ss+hh:mm' (Time with ISO timezone extended)
  }
}

Age restriction

info

Keep in mind that as all strings displayed by the player, you can easily change the message displayed with the help of the phrases option.

goToButtons Premium option

This option allows you to display timecoded buttons with a "go to timecode" functionality. A typical case is a "Skip credits" button.

Description	Type
goToButtons	Array of Object

This example will display a "Skip credits" button in the player from the beginning to five seconds and will disappear at exactly six seconds.

Skip credits example

goToButtons: [{
  title: 'Skip credits',
  visibleFrom: 0,
  visibleUntill: 5,
  targetTime: 6
}],

Result

thumbnailsVttUrl Premium option

This option allows you to display thumbnails when the user rolls over the progress bar.

Description	Type
thumbnailsVttUrl	String

This example will display a different thumbnail each second.

Thumbnail each second

thumbnailsVttUrl: "https://cdn.oberplayer.com/fixtures/vtt/bbb-thumbs.vtt"

Result

Your VTT thumbnail file should look like this

VTT Thumbnails example

WEBVTT

00:00.000 --> 00:01.000
https://cdn.oberplayer.com/fixtures/vtt/sprites/bbb/160-90-001.jpg#xywh=0,0,160,90

00:01.000 --> 00:02.000
https://cdn.oberplayer.com/fixtures/vtt/sprites/bbb/160-90-001.jpg#xywh=160,0,160,90

00:02.000 --> 00:03.000
https://cdn.oberplayer.com/fixtures/vtt/sprites/bbb/160-90-001.jpg#xywh=320,0,160,90

00:03.000 --> 00:04.000
https://cdn.oberplayer.com/fixtures/vtt/sprites/bbb/160-90-001.jpg#xywh=480,0,160,90

00:04.000 --> 00:05.000
https://cdn.oberplayer.com/fixtures/vtt/sprites/bbb/160-90-001.jpg#xywh=640,0,160,90

tip

You can find documentation about sprite generation with FFmpeg here: https://trac.ffmpeg.org/wiki/Create%20a%20thumbnail%20image%20every%20X%20seconds%20of%20the%20video And an interesting stackoverflow page about this topic: https://stackoverflow.com/questions/31223926/ffmpeg-command-to-create-thumbnail-sprites

chaptersVttUrl Premium option

This option allows you to display the chapters title when the user rolls over the progress bar.

Description	Type
chaptersVttUrl	String

This example will display six chapters at differents times.

Thumbnail each second

chaptersVttUrl: "https://cdn.oberplayer.com/fixtures/vtt/sintel-chapters.vtt",

Result

Your VTT chapter file should look like this

VTT Chapters example

WEBVTT

00:00:00.000 --> 00:00:05.000
This is the first chapter

00:00:05.000 --> 00:00:10.000
This is the second chapter

00:00:10.000 --> 00:00:15.000
A new chapter

00:00:15.000 --> 00:00:24.000
Another one

00:00:24.000 --> 00:00:26.000
This one with an emoji 😅

00:00:26.000 --> 00:00:31.000
And the last one

Of course, you can combine both chaptersVttUrl and thumbnailsVttUrland for a perfect result

aspectRatio

Description	Type	Default
aspectRatio	Number:Number	16:9

Set the player ratio, generally following the video aspect-ratio. For example CinemaScope can be 2.35:1, old TV format is 4:3

General attributes reference

lang

Description	Type	Default
lang	ISO 639-1 language code	en

This option will define the date format and language in which the text will be displayed.

info

A complete code list can be found here : https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes

phrases

Description	Type
phrases	Object

This option allows you to overwrite texts and messages within the player.

debug

Description	Type
debug	Boolean

This option can be helpful to activate debug logging in the Javascript console.

color

Description	Type
color	String

This color value will be applied on the timeline and the volume bar which are #E62175 by default. See possible values here : https://developer.mozilla.org/en-US/docs/Web/CSS/color_value

token

Description	Type
token	String

This option is needed to activate the premium features available with your subscription. Get a premium token with a premium account.