Efficient tools to build your streaming infrastructure

HTML5 player SDK documentation

JavaScript player for Softvelum Low Delay Protocol

SLDP Player HTML5 SDK

Softvelum provides JavaScript SDK packages which you can use on your web sites to enable SLDP low-latency playback. It's a JavaScript-based library that has its API to operate. Here's how you can obtain it:

  1. You subscribe for the SDK using this page.
  2. You send a helpdesk request, specifying the list of domains where you plan using our player. Domain levels 2 and below are supported.
  3. Within 2 business days we generate individual builds for each specified domain and send them to you.
  4. As soon as we make SDK update, we'll send you new builds for each domain.
SDK subscription covers our technical support which is provided as long as you are subscribed.

Subscribe now

Please find the player methods and callbacks described below.

  • SLDP.isMediaSourceSupported()
    Returns whether current browser supports Media Source Extensions API and hence ability to run SLDP player.
    Return value: true if supports, false otherwise.

SLDP Player interfaces

  • destroy( callback )
    Destroys given player instance, including MSE objects (Media Source Extensions), UI and connections.
    Parameters:
    • callback - (optional) callback function that is invoked after given player instance is destroyed
  • play()
    Starts playback for given player instance.
  • pause()
    Pauses playback for given player instance. Current connection to media server is retained during pause_timeout interval if specified.
  • stop()
    Stops playback for given player instance. Current connection to media server is closed immediately.
  • getVolume()
    Retruns player volume.
    Return value: integer from 0 (muted) to 100 (full volume).
  • setVolume( volume )
    Sets player volume. UI controls are updated according to selected value.
    Parameters:
    • volume - integer from 0 (muted) to 100 (full volume)
  • startAbr()
    Starts adaptive bitrate algorithm (ABR), which performs automatic switching to the best available rendition at a time according to network conditions and CPU processing.
  • stopAbr()
    Stops adaptive bitrate algorithm (ABR).
  • isAbr()
    Returns whether adaptive bitrate algorithm (ABR) is turned on.
  • getRenditions()
    Returns list of available stream renditions.
    Return value: array of strings containing available renditions, e.g. ['360p', '720p'].
  • getCurrentRendition()
    Returns currently selected rendition.
    Return value: string with current rendition, e.g. '720p'.
  • changeRendition( rendition )
    Switches playback to the specified rendition.
    Return value: boolean status (true - rendition switching has started, false - another switching is currently in progress).
    Parameters:
    • rendition - string representing desired rendition, e.g. '1080p'
  • getStreams()
    Returns list of streams available for select as renditions.
    Return value: array of objects with the following fields:
    • name - application and stream name, e.g. 'live/stream'
    • width - video width in pixels, if present
    • height - video height in pixels, if present
    • bandwidth - stream bandwidth expressed in bits per second
  • getCurrentStream()
    Returns currently selected stream.
    Return value: object with the following fields:
    • name - application and stream name, e.g. 'live/stream'
    • width - video width in pixels, if present
    • height - video height in pixels, if present
    • bandwidth - stream bandwidth expressed in bits per second
  • getCurrentStreamBandwidth()
    Returns stream's bandwidth in bits per second.
    Return value: integer value of current stream's bandwidth in bits per second.
  • changeStream( name )
    Switches playback to the stream with the name specified.
    Return value: boolean status (true - stream switching has started, false - another switching is currently in progress).
    Parameters:
    • name - target application and stream name, e.g. 'live/stream'
  • setStreamURL( url )
    Sets new SLDP stream URL. Currently playing stream is aborted. If given player instance has "autoplay" parameter set to true, then new stream's playback starts immediately if possible.
    Parameters:
    • url - string representing desired SLDP stream URL, e.g. 'ws://example.com/app/stream'
  • refreshVUMeterUI()
    Re-draws VU meter UI. Should be used in case of VU meter container size has been changed, so the UI will be updated accordingly.
  • unmuteVUMeter()
    Applicable for input type VU meter. Activates VU meter that was automatically suspended by browser in case of muted autoplay. Must be accompanied with user's action like click or tap.
  • setCallbacks( callbacks )
    Sets callback functions for given player instance.
    Parameters:
    • callbacks - object, where keys are callback names and values are references to developer's callback functions. Acceptable callback names are: onConnectionStarted, onConnectionEstablished, onPlay, onPause, onVolumeSet, onConnectionClosed, onChangeRendition, onChangeRenditionComplete, onError, onLatencyAdjustSeek, onLowBuffer, onVUMeterUpdate, onCaptionsArrived, onScreenshotReady
  • setParameters( params )
    Allows to modify a subset of SLDP player parameters dynamically.
    Parameters:
    • params - object of player parameters in the form of {param: value}. Currently supported parameters are: buffering, latency_tolerance, aspect_ratio, splash_screen, pause_timeout, key_frame_alignment, muteable, screenshots
  • getCaptionTracks()
    Returns map of available CEA-608 caption tracks.
    Return value: object, containing ID: CAP_OBJ pairs, where the ID is one of the following: 'CC1', 'CC2', 'CC3', 'CC4'. The CAP_OBJ is and object with the following fields:
    • title - caption track title that is shown in caption selection dialog.
    • name - (optional) caption track name defined in caption settings.
    • lang - (optional) caption track language defined in caption settings.
  • getCurrentCaptionTrack()
    Returns currently selected CEA-608 caption track.
    Return value: object, containing single ID: CAP_OBJ pair, with the ID of currently selected caption track. The CAP_OBJ is an object with the following fields:
    • title - caption track title that is shown in caption selection dialog.
    • name - (optional) caption track name defined in caption settings.
    • lang - (optional) caption track language defined in caption settings
    If no caption track is selected, then an empty object will be returned.
  • setCaptionTrack( ID )
    Sets current CEA-608 caption track with the ID specified. To turn off captions, 'OFF' value should be specified as ID.
    Return value: boolean status (true - track is set successfully, false - specified track can't be set).
    Parameters:
    • ID - either caption track ID value, which can be one of the following: 'CC1', 'CC2', 'CC3', 'CC4' or 'OFF' to turn off captions.
  • seekVod( position )
    Updates current VOD playback position with the specified value. If the player is currently in the live mode, it's switched to the VOD mode.
    Return value: boolean status (`true` - position update is performed successfully, `false` - playback position update failed).
    Parameters:
    • position - playback position in seconds from the start. Possible values are in range [0, duration]
  • seekLive( buffer )
    Updates the current live playback position (buffering) with the specified value. If the player is currently in VOD mode, it will be switched to Live mode. The buffering value in the player's settings is updated with the value of the buffer parameter. If the parameter is omitted, the current buffering setting is used.
    Return value: boolean status (`true` - position update is performed successfully, `false` - playback position update failed).
    Parameters:
    • buffer - (optional) buffer size in seconds that the player pertains during live playback.
  • getStreamEncodedFramerate()
    Returns framerate value calculated from the SPS parameters. Applicable only when the 'timecodes' init parameter is enabled. If there are no relevant parameters in the SPS, the method will return undefined. The method should be run after the player started to receive video frames. E.g. it can be run on the first onTimecodeArrived() callback invocation.
    Return value: integer value of the current stream's framerate, encoded in the SPS.
  • getVodThumbnailUrl( time )
    Returns the URL to the thumbnail of the current VOD stream at the given time in seconds. More specifically, the thumbnail is the keyframe of the HLS segment that covers the given time.
    IMPORTANT: This functionality only works if Nimble Streamer is configured with the dvr_hls_add_program_date_time parameter enabled. If there is no thumbnail at the specified time or if Nimble Streamer isn't configured with the above parameter, the result is undefined.
    Return value: string with the requested thumbnail URL.
    Parameters:
    • time - time of the thumbnail in seconds from 0 to the length of the DVR archive

SLDP player callbacks:

  • onConnectionStarted( url )
    Invoked when player starts connection to media server.
    Parameters:
    • url - SLDP stream URL, which player connects to, e.g. 'ws://example.com/live/stream'
  • onConnectionEstablished( streams )
    Invoked when connection to media server is established and list of available streams is received. List of renditions available for user is composed depending on those streams and browser capabilities.
    Parameters:
    • streams - array of available streams.
      Each stream is an object with the following fields:
      • name - application and stream name, e.g. 'live/stream'
      • width - stream width in pixels if video is present
      • height - stream height in pixels if video is present
      • vcodec - stream video codec if present
      • video - either 'supported' or 'not supported' depending on browser capabilities
      • acodec - stream audio codec if present
      • audio - either 'supported' or 'not supported' depending on browser capabilities
      • bandwidth - stream bandwidth expressed in bits per second
  • onPlay()
    Invoked when user presses play button, or play() method is executed.
  • onPause()
    Invoked when user presses pause button, or pause() method is executed.
  • onVolumeSet( volume )
    Invoked when user changes volume using volume control elements, or setVolume() method is executed.
    Parameters:
    • volume - integer from 0 to 100, representing selected volume level
  • onConnectionClosed()
    Invoked when connection to media server is closed due to whatever reason.
  • onError( error, opts )
    Invoked when player error is encountered.
    Parameters:
    • error - string with error description, e.g. 'MEDIA_SOURCE_NOT_SUPPORTED' or 'NO_PLAYABLE_SOURCE_FOUND'
    • opts - error options object, containing the playback type
  • onChangeRendition( rendition, name )
    Invoked when user changes rendition, or either changeRendition() or changeStream() method is executed.
    Parameters:
    • rendition - string with user selected rendition, e.g. '1080p' or 'Auto'
    • name - selected application and stream name, e.g. 'live/stream'
  • onChangeRenditionComplete( rendition, name )
    Invoked when rendition switch is complete.
    Parameters:
    • rendition - string representing actual rendition, e.g. '1080p'
    • name - actual application and stream name, e.g. 'live/stream'
  • onLatencyAdjustSeek( from, to )
    Invoked when seek is performed for automatic latency adjustment (latency_tolerance parameter must be set).
    Parameters:
    • from - position in seconds that seek is performed from
    • to - position in seconds that seek is performed to
  • onLowBuffer()
    Invoked when player encounters low buffer conditions, e. g. it doesn't have data enough to continue playback.
  • onVUMeterUpdate( magnitudes, decibels )
    Invoked each time audio level is calculated for next 2048 samples. So, for 48KHz audio this callback will be executed about 24 times per second. The execution frequency can be limited by setting 'rate' parameter. Applicable only if VU meter settings are defined. This callback is executed within main browser thread, therefore no heavy processing related to UI rendering should be invoked within it (use window.requestAnimationFrame method instead).
    Parameters:
    • magnitudes - array of audio magnitudes for each channel, calculated according to the mode specified in the VU meter settings. Possible values should be from 0 to 1, but may be greater than 1, if that's set in the audio source.
    • decibels - array of audio levels for each channel in decibels, calculated according to the mode specified in the VU meter settings. Possible values should be from -100 dB to 0 dB, but may be greater than 0, if that's set in the audio source.
  • onCaptionsArrived( captions )
    Invoked each time a new set of captions is ready to be displayed on the player's screen. All previous captions should be replaced by new ones. CEA-608 caption format implies that player's screen is divided into 15 rows and 32 columns. Each cell contains one symbol.
    Parameters:
    • captions - array of caption block objects having the following fields:
      • time - caption display start time related to video element's currentTime
      • x - caption block's horizontal position counted from the left. Can be in range of 0 - 31.
      • y1 - caption block's top line position counted from the top. Can be in range of 0 - 14.
      • y2 - caption block's bottom line position counted from the top. Can be in range of 0 - 14.
      • regions - array of caption region objects containing single field - spans. The value of this field is an array of caption row span elements. Each element contains text string related to specific row and styling parameters:
        • row - row number starting from the top. Can be in range of 0 - 14.
        • content- caption span text string
        • style - caption span style object, having the follwing fields:
          • foreground - text font color
          • background - background color
          • italic - text should be italic if true
          • underline - text should be underlined if true
          • flash - span should be blinking if true
        If the regions array is empty, it means that given caption block is used to clear all previous captions starting from given time.
  • onScreenshotReady( imageData, presentationTimestamp )
    Invoked each time new screenshot is rendered.
    Parameters:
    • imageData - ImageData object of a screenshot
    • presentationTimestamp - presentation timestamp of corresponding frame in milliseconds tied to the video element's currentTime
  • onTimecodeArrived( frameTs, clockTs, stringTs )
    Invoked each time a new SEI picture timing message is parsed by the player.
    Parameters:
    • frameTs - timestamp of a frame to which the given SEI picture timing message is attached. The timestamp is calculated according to the stream's timescale, so it's directly related to the media element's currentTime value.
    • clockTs - clockTimstamp from the SEI message which is calculated according to the Rec. ITU-T H.264 document.
    • stringTs - timecode from the SEI message in the form "hh:mm:ss.n_frames time_offset"
  • onPlaybackProgress( status )
    Invoked when the current live or VOD playback state is changed. The VOD playback status change during live playback is usually related to the VOD duration change.
    Parameters:
    • status - VOD or live playback status object.
      For the VOD playback:
      • type - playback type 'vod'
      • position- VOD playback position in seconds from the start
      • duration- total VOD duration in seconds
      For the live playback:
      • type - playback type 'live'
      • buffer- current buffer size in seconds

Reference implementation

You can go to Reference page and start some stream there to see an example of player implementation with our SDK with all existing controls.

Subscribe now