Player Reference

Mandatory parameters

licenseKey

LicenseKey is used to identify the Player, it defines a list of allowed domain names where player can be initiated

videoSources

• String - URL for a video file or playlist/manifest;

• Object:

  • src (mandatory String) - URL for the desired video or playlist/manifest;
  • type (optional String) - MIME type for the informed video. In case it is not informed, the player will try to use sensible defaults;

• Array form - an array containing objects in the same form as above. The player will try to run the first item and the followings will be used as fallbacks, whose priorities will respect the informed order;

    videoSources: [
        { src: 'https://example.com/dash/video.mpd', type: 'application/dash+xml' },
        { src: 'https://example.com/hls/master.m3u8' },
        { src: 'https://example.com/fallback/video.mp4' },
    ],

Optional parameters

Use optional parameters to adjust player functionality

titleBar

If it is specified, it adds title aligned to top left corner of the video player

    titleBar: {
        text: 'Hello Qencode Player'
    },  

social

Adds share button to control panel

    social: {
        shareUrl: 'https://www.youtube.com/watch?v=DjTlVloHXCg',
        twitter: 'https://twitter.com',
        facebook: 'https://facebook.com',
    },

colors

Use custom colors for player's UI

    colors{
        controlBarText: "#ffffff",
        controlBarIcons: "#ffffff",

        timeSliderRail: "#366fe0",
        timeSliderProgress: "#366fe0",
        timeSliderLoaded: "#9a9a9a",

        interfaceBackground: 'rgba(0, 0, 0, 0.76)',

        menuText: 'rgba(255, 255, 255, 0.85)',
        menuBackground: 'rgba(38, 38, 38, 0.85)',
        menuOptionHovered: 'rgba(56, 56, 56, 0.5)',
        menuOptionSelected: 'rgba(75, 75, 75, 0.74)',
        menuOptionSelectedMarker: 'rgba(9, 170, 222, 0.85)'         
    }

Thumbnails

Usecase when each thumbnail has 1 image file

width and height parameters are optional, if not specified the default thumbnail size is 120x68 pixels.

    thumbnails:{
        src:'https://nyc3.digitaloceanspaces.com/qencode3/regression_tests/thumb/vtt/thumbnails.vtt',
        width: 120,
        height: 68
    },

Using sprites for thumbnails

In this case you just need to specifie url for VTT file, thumbnail size is based on the dimensions in VTT file. For fastest download we recomend to use sprite image files in JPEG format with 5 rows and 5 columns (5x5) or 10x10 and each image size of 160x90

    thumbnails:{
        src: 'https://nyc3.digitaloceanspaces.com/qencode3/regression_tests/thumb/vtt_sprite/thumbnails.vtt'
    },   

textTracks

Type: Object Array
Mandatory: no
Default: undefined

• When left undefined - no WebVTT tracks will be available

• Object:

  • src (mandatory String) - URL for a valid WebVTT file containing a text track;
  • label (mandatory String) - text to label the text track in the player's list;
  • language (mandatory String) - a valid BCP 47 language tag describing the text track's language;

• Array: an array of objects following the interface described above;

    textTracks: [{
        src: 'example.vtt',
        label: 'English',
        language: 'en'
    }, {
        src: 'esperanto.vtt',
        label: 'Esperanto',
        language: 'eo'
    }]

Parameters that control player's playback

      playback: {
        loop: true,
        muted: true,
        autoplay: true, // autoplay will work only if muted is true
        controls: false,        
        pauseWhenNotVisible: true,
        autoLoadingVideoQuality: true // show quality of loading video
      },      

Layout parameters

By default the player size is set to fluid mode, that means that after player is initiated it will attempt to calculate aspect ratio based on the video dimentions after player loads metadata and player will fit video. If aspectRatio is defined, player will be initiated according to that and player size will not change after video is loaded. In fill mode player will take all available space of its container.

      size:{
        aspectRatio: '16:9',
        fluid: false, // if fluid set to true it will override aspectRatio
        fill: true,      
      }

Passing Credentials

The withCredentials property is a setting used within the HTML video player API to control the behavior of XMLHttpRequests (XHR) when fetching video manifests and segments. When this property is set to true, it configures all XHR requests to include credentials such as cookies, authorization headers, or TLS client certificates in the requests sent to the server hosting the video content.

withCredentials: true

Implications on Cross-Origin Resource Sharing (CORS):

The Access-Control-Allow-Origin HTTP header in the server's response cannot be set to the wildcard '*'. Instead, it must specify the exact origin from which the video player is making the requests.

The server must also include an Access-Control-Allow-Credentials header with a value of true to indicate that it allows credentials to be shared across origins.

Security Considerations:

Setting withCredentials to true can have security implications. Developers should ensure that the server is configured to handle such requests securely to prevent exposure to cross-site request forgery (CSRF) or other web-based attacks.

It is recommended to use this setting only when necessary and with a clear understanding of the associated security policies.

This property is typically used when the video content requires user authentication and the server needs to validate user sessions through cookies or auth tokens. By enabling withCredentials, developers can ensure that authenticated sessions are maintained without interrupting the video streaming experience.