react-native-qencode-sdk

React Native SDK Qencode video player.

Installation

npm install react-native-qencode-sdk

Usage

import QencodePlayer from 'react-native-qencode-sdk';

  var video = [
    { src: 'https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8' },
  ];
  var license = 'f7e3f067-caf5-8a30-c751-b21072c7025b';
  var withCredentials = false;
  var size = {
    aspectRatio: '16:9',
    fluid: false,
    fill: true,
  };
  var titleBar = { text: 'Hello Qencode Player' };
  var social = {
    shareUrl: 'https://www.youtube.com/watch?v=DjTlVloHXCg',
    twitter: 'https://twitter.com',
    facebook: 'https://facebook.com',
  };
  var 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)',
  };
  var thumbnails = {
    src: 'https://nyc3.digitaloceanspaces.com/qencode3/regression_tests/thumb/vtt/thumbnails.vtt',
    width: 120,
    height: 68,
  };
   var textTracks = [
     { src: 'example.vtt', label: 'English', language: 'en' },
     { src: 'esperanto.vtt', label: 'Esperanto', language: 'eo' },
  ];
  var playback = {
    loop: true,
    muted: false,
    autoplay: false, // autoplay will work only if muted is true
    controls: true,
    pauseWhenNotVisible: true,
    autoLoadingVideoQuality: true, // show quality of loading video
  };

// ...
    <View style={styles.container}>
      <View style={styles.header} />
      <QencodePlayer
        playback={playback}
        textTracks={textTracks}
        thumbnails={thumbnails}
        colors={colors}
        social={social}
        titleBar={titleBar}
        size={size}
        withCredentials={withCredentials}
        licenseKey={license}
        videoSources={video}
        style={styles.player}
      />
    </View>
// ...

    const styles = StyleSheet.create({
    // ...
        player: {
            alignItems: 'center',
            justifyContent: 'center',
            alignSelf: 'stretch',
            flex: 1,
        },
    // ...
    });

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;

    var 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

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

social

Adds share button to control panel

var 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

var 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.

var 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

var 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;

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

Parameters that control player's playback

  var 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.

  var 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.

Copyright

Copyright 2024 Qencode, Inc.