SAMSUNG DEVELOPERS

Smart TV

top

AVPlay API

To use Samsung Product API, 

<script type="text/javascript" src="$WEBAPIS/webapis/webapis.js"></script>

Should be loaded in index.html

This module defines the multimedia player functionalities provided by the Tizen Samsung TV Product API.

Since : 2.3

Product : TV, AV_BD

Table of Contents

  1. 1. Type Definitions
    1. 1.1. AVPlayPlayerState
    2. 1.2. AVPlayDisplayMode
    3. 1.3. AVPlayBufferOption
    4. 1.4. AVPlayBufferSizeUnit
    5. 1.5. AVPlayStreamingPropertyType
    6. 1.6. AVPlayDrmType
    7. 1.7. AVPlayDrmOperation
    8. 1.8. AVPlayStreamType
    9. 1.9. AVPlayError
    10. 1.10. AVPlayEvent
    11. 1.11. AVPlayStreamInfo
    12. 1.12. AVPlaySubtitleAttribute
    13. 1.13. AVPlay360Info
  2. 2. Interfaces
    1. 2.1. AVPlayManagerObject
    2. 2.2. AVPlayManager
    3. 2.3. AVPlayPlaybackCallback
  3. 3. Full WebIDL

Summary of Interfaces and Methods

Interface Method
AVPlayManagerObject  
AVPlayManager void open();
void close();
void prepare();
void prepareAsync(opitional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
void setDisplayRect(unsigned long x, unsigned long y, unsigned long width, unsigned long height);
void set360Rotation(float Horizontal_angle_value, float Vertical_angle_value);
void set360Zoom(long Zoom_level);
AVPlay360Info get360Info();
void play();
void seekTo(long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
void stop();
AVPlayPlayerState getState();
void pause();
void jumpForward(long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
void jumpBackward( long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback );
unsigned long getDuration();
unsigned long getCurrentTime();
void setTimeoutForBuffering(unsigned long seconds);
void setBufferingParam(AVPlayBufferOption option, AVPlayBufferSizeUnit unit, unsigned long amount);
void setSpeed(long playbackSpeed);
void setListener(AVPlayPlaybackCallback playbackCallback);
DOMString setDrm(AVPlayDrmType drmType, AVPlayDrmOperation drmOperation, DOMString jsonParam);
void setSoundAnalysisListener(AVPlaySoundAnalysisCallback soundAnalysisCallback);
void unsetSoundAnalysisListener();
void setSilentSubtitle(boolean onoff);
void setExternalSubtitlePath(DOMString filePath);
void setSubtitlePosition(long position);
void setDisplayMethod(AVPlayDisplayMode displayMode);
void setSelectTrack(AVPlayStreamType trackType, long trackIndex);
AVPlayCurrentStreamInfo getCurrentStreamInfo();
AVPlayStreamInfo[] getTotalTrackInfo();
void setStreamingProperty(AVPlayStreamingPropertyType propertyType, Any propparam);
Any getStreamingProperty(AVPlayStreamingPropertyType propertyType);
DOMString getVersion();
void suspend();
void restore(DOMString URL, long resumeTime, boolean bPrepare);
AVPlayPlaybackCallback void onbufferingstart();
void onbufferingprogress(unsigned long percent);
void onbufferingcomplete();
void oncurrentplaytime(unsigned long currentTime );
void onstreamcompleted();
void onevent(long eventid, DOMString data );
void onerror(long eventid);
void ondrmevent(AVPlayDrmType type, long eventid);
void onsubtitlechange(unsigned long duration, DOMString subtitles, unsigned long type, unsigned long attriCount, AVPlaySubtitleAttribute attributes);

1. Type Definitions

1.1. AVPlayPlayerState

Specifies the player state.

enum AVPlayPlayerState {
  "NONE",
  "IDLE",
  "READY",
  "PLAYING",
  "PAUSED"
};

The following values are supported

  • NONE : Player is not created
  • IDLE : Player is created but not prepared
  • READY : Player is ready to play media
  • PLAYING : Player is playing media
  • PAUSED : Player is paused

1.2. AVPlayDisplayMode

Specifies display modes.

enum AVPlayDisplayMode { 
  "PLAYER_DISPLAY_MODE_LETTER_BOX", 
  "PLAYER_DISPLAY_MODE_FULL_SCREEN",
  "PLAYER_DISPLAY_MODE_AUTO_ASPECT_RATIO" 
};

The following values are supported

  • PLAYER_DISPLAY_MODE_LETTER_BOX : Letterbox mode
  • PLAYER_DISPLAY_MODE_FULL_SCREEN : Full-screen mode
  • PLAYER_DISPLAY_MODE_AUTO_ASPECT_RATIO : Screen mode based on video dar/par info
    LIMITATION : PLAYER_DISPLAY_MODE_LETTER_BOX and PLAYER_DISPLAY_MODE_AUTO_ASPECT_RATIO work only when setDisplayRect set as setDisplayRect(0,0,1920,1080)

1.3. AVPlayBufferOption

Specifies buffering scenarios.

enum AVPlayBufferOption { 
  "PLAYER_BUFFER_FOR_PLAY", 
  "PLAYER_BUFFER_FOR_RESUME" 
};

The following values are supported

  • PLAYER_BUFFER_FOR_PLAY : Normal playback scenario
  • PLAYER_BUFFER_FOR_RESUME : Playback re-buffering scenario

1.4. AVPlayBufferSizeUnit

This enumeration defines the Buffering param's Unit defined by the player.

enum AVPlayBufferSizeUnit {
  "PLAYER_BUFFER_SIZE_IN_BYTE", 
  "PLAYER_BUFFER_SIZE_IN_SECOND" 
};

The following values are supported

  • PLAYER_BUFFER_SIZE_IN_BYTE : Buffer size in bytes
  • PLAYER_BUFFER_SIZE_IN_SECOND : Buffer size in seconds

1.5. AVPlayStreamingPropertyType

Specifies parameters for various streaming protocols, such as HTTP, MMS, and adaptive streaming (Smooth Streaming, HLS, and MPEG-DASH).

enum AVPlayStreamingPropertyType { 
  "COOKIE", 
  "USER_AGENT", 
  "PREBUFFER_MODE", 
  "ADAPTIVE_INFO",  
  "SET_MODE_4K", 
  "PROPERTY_HD_AUDIO", 
  "LISTEN_SPARSE_TRACK", 
  "IS_LIVE", 
  "AVAILABLE_BITRATE", 
  "GET_LIVE_DURATION", 
  "CURRENT_BANDWIDTH", 
  "WIDEVINE", 
  "SET_VR360_MODE"
};

The following values are supported

  • COOKIE : HTTP request cookie used to establish the session with the HTTP server. (for setStreamingProperty)
  • USER_AGENT : HTTP user agent, used in the HTTP request header. (for setStreamingProperty)
  • PREBUFFER_MODE : Property defining the start time from where pre-buffered content resumes playback, in milliseconds. (for setStreamingProperty)
  • ADAPTIVE_INFO : Sets a custom streaming URL with various streaming parameters, such as "BITRATES", "STARTBITRATE", or "SKIPBITRATE" (for setStreamingProperty)
    String containing custom attributes for adaptive streaming playback.
    • "STARTBITRATE=" Valid values are "LOWEST", "HIGHEST", and "AVERAGE". You can also define a specific bandwidth for the start of playback.
    • "BITRATES=" Use '~' to define a bandwidth range (5000 ~ 20000). You can also define a specific bandwidth for playback.
    • "SKIPBITRATE=" Defines the bandwidth to use after a skip operation.
    • "STARTFRAGMENT=" For live content playback, defines the start fragment number.
  • WIDEVINE : Custom URL and parameters for Widevine Classic streaming, including license and device ID information. (for setStreamingProperty). It can contain the following parameters:
    • "DEVICE_ID" Unique player device ID [mandatory]
    • "DEVICE_TYPE_ID" Device type ID. [mandatory]
    • "DRM_URL" DRM server URL [mandatory]
    • "HEARTBEAT_URL" Client heartbeat URL [optional]
    • "PORTAL" Operator identification [optional]
    • "ACK_URL" Entitlement confirmation server URL [mandatory]
    • "STREAM_ID" Unique stream ID [mandatory]
    • "IP_ADDR" Client IP address [optional]
    • "HEARTBEAT_PERIOD" Time between heartbeats, in seconds. 0 for no heartbeats. [optional]
    • "CUR_TIME" same as "PTS" value. [mandatory]
    • "I_SEEK" same as "TIME" value [mandatory]
    • Parameters are combined using the "|" pipe operation.
  • SET_MODE_4K : Forces the player to use the UHD decoder. Its parameter can be the string "TRUE" or "FALSE". (for setStreamingProperty)
  • PROPERTY_HD_AUDIO : Forces the player to use the HD audio mode. (for setStreamingProperty)
  • LISTEN_SPARSE_TRACK : Configures the player to listen for a "Sparse name" configured through "propertyParam" . The sparse track name is a string. (for setStreamingProperty)
  • IS_LIVE : Whether the stream is LIVE or VOD. Applicable to all streaming types. (for getStreamingProperty)
  • AVAILABLE_BITRATE : String listing the available bit-rates for the currently-playing stream. (for getStreamingProperty)
  • GET_LIVE_DURATION : String describing the duration of live content. (for getStreamingProperty)
  • CURRENT_BANDWIDTH : String describing the current streaming bandwidth. (for getStreamingProperty)
  • SET_VR360_MODE : Forces the player to use the VR360 mode. Its parameter can be the string "TRUE" or "FALSE". (for setStreamingProperty)

1.6. AVPlayDrmType

Specifies DRM systems supported by the player.

enum AVPlayDrmType {
  "PLAYREADY", 
  "VERIMATRIX", 
  "WIDEVINE_CDM"
};

The following values are supported

  • PLAYREADY : PlayReady
  • VERIMATRIX : Verimatrix
  • WIDEVINE_CDM : Widevine CDM

1.7. AVPlayDrmOperation

Specifies various DRM operations.

enum AVPlayDrmOperation { 
  "SetProperties", 
  "InstallLicense", 
  "ProcessInitiator", 
  "GetUID", 
  "Initialize", 
  "Finalize", 
  "widevine_license_data", 
  "widevine_app_session", 
  "widevine_data_type" 
};

The following values are supported

  • SetProperties : Sets PlayReady DRM instance properties
  • InstallLicense : Installs a PlayReady license
  • GetUID : Get a Verimatrix unique identifier. This must be called before calling the open method.
  • Initialize : Initialize the DRM instance
  • ProcessInitiator : initialize the PlayReady DRM instance
  • Finalize : Finalize the DRM instance. This must be called before closing the player instance.
  • widevine_license_data : Base64-encoded license data. This must be preceeded by the session ID received with challenge data during the onevent method.
  • widevine_app_session : Session ID string for the session established between the application and the server
  • widevine_data_type : Data type, such as "matroska_webm" or "MPEG-DASH"

1.8. AVPlayStreamType

Specifies stream types supported by the player.

enum AVPlayStreamType { 
  "VIDEO", 
  "AUDIO", 
  "TEXT" 
};

The following values are supported

  • VIDEO : Video track
  • AUDIO : Audio track
  • TEXT : Subtitle track

1.9. AVPlayError

Specifies the player error messages.

enum AVPlayError{
  "PLAYER_ERROR_NONE",
  "PLAYER_ERROR_INVALID_PARAMETER",
  "PLAYER_ERROR_NO_SUCH_FILE",
  "PLAYER_ERROR_INVALID_OPERATION",
  "PLAYER_ERROR_SEEK_FAILED",
  "PLAYER_ERROR_INVALID_STATE",
  "PLAYER_ERROR_NOT_SUPPORTED_FILE",
  "PLAYER_ERROR_INVALID_URI",
  "PLAYER_ERROR_CONNECTION_FAILED",
  "PLAYER_ERROR_GENEREIC"
};

The following values are supported

  • PLAYER_ERROR_NONE : Operation has successfully completed; no error.
  • PLAYER_ERROR_INVALID_PARAMETER : Unable to find the parameter
  • PLAYER_ERROR_NO_SUCH_FILE : Unable to find the specified media content
  • PLAYER_ERROR_INVALID_OPERATION : Failed to create the player
  • PLAYER_ERROR_SEEK_FAILED : Failed to perform seek operation, or seek operation called during an invalid state
  • PLAYER_ERROR_INVALID_STATE : AVPlay API method was called during an invalid state
  • PLAYER_ERROR_NOT_SUPPORTED_FILE : Multimedia file format not supported
  • PLAYER_ERROR_INVALID_URI : Input URI is in an invalid format
  • PLAYER_ERROR_CONNECTION_FAILED : Failed multiple attempts to connect to the specified content server
  • PLAYER_ERROR_GENEREIC : Failed to create the display window

1.10. AVPlayEvent

Specifies player events.

enum AVPlayEvent {
  "PLAYER_MSG_NONE",
  "PLAYER_MSG_RESOLUTION_CHANGED",
  "PLAYER_MSG_BITRATE_CHANGE",
  "PLAYER_MSG_FRAGMENT_INFO",
  "PLAYER_SPARSE_TRACK_DETECT",
  "PLAYER_STREAMING_EVENT",
  "PLAYER_MSG_HTTP_ERROR_CODE",
  "PLAYER_MSG_DRM_CHALLENGE_DATA"
};

The following values are supported

  • PLAYER_MSG_NONE : Notifies that a multimedia component message was not recognized by the player
  • PLAYER_MSG_RESOLUTION_CHANGED : During adaptive streaming playback, notifies that the video resolution has changed
  • PLAYER_MSG_BITRATE_CHANGE : During adaptive streaming playback, notifies of a change, based on network heuristics, in the bandwidth-specific URL. The current bandwidth value is also sent.
  • PLAYER_MSG_FRAGMENT_INFO : Posts the downloaded fragment details. The following information is posted:
    fragment number, stream-type, current bitrate, and download time for this fragment
  • PLAYER_SPARSE_TRACK_DETECT : During adaptive streaming playback, notifies that a sparse track was encountered
  • PLAYER_STREAMING_EVENT : Posts required streaming data
  • PLAYER_MSG_HTTP_ERROR_CODE : Describes the detailed HTTP network situation information
  • PLAYER_MSG_DRM_CHALLENGE_DATA : For encrypted content playback, posts the DRM challenge data

1.11. AVPlayStreamInfo

Defines a dictionary for streaming video, audio and subtitle information for various streaming scenarios.

dictionary AVPlayStreamInfo {
  unsigned long index;
  unsigned long adaption_index;
  unsigned long alternate_index;
  AVPlayStreamType type;
  DOMString extra_info;
};

The following values are supported

  • index : unsigned long Index
  • adaption_index : Stream track index. For DASH playback, the adaptationset index.
  • alternate_index : For DASH playback, the representation index. For other streaming URL types, the value is 0.
  • type : Track type (audio, video, or text)
  • extra_info : DOMString JSON string containing all media-related info (such as height, width, and fourCC for a video stream, and bitrate, fourCC, language, and codec type for an audio stream)

1.12. AVPlaySubtitleAttribute

Defines a dictionary for subtitle attributes.

dictionary AVPlaySubtitleAttribute {
  DOMString type;
  long start;
  long stop;
};

The following values are supported

  • type : DOMString (json)
  • start : Start position
  • stop : Stop position

1.13. AVPlay360Info

Defines a dictionary for 360-degree video playback information.

dictionary AVPlay360Info {
  long horizontal_angle;
  long vertical_angle;
  long zoom_level;
};

The following values are supported

  • horizontal_angle : Horizontal angle (range: 0 ~ 360)
  • vertical_angle : Vertical angle (range: 0 ~ 360)
  • zoom_level : Zoom leve (range: 0 ~ 100)

2. Interfaces

2.1. AVPlayManagerObject

Defines a WebApi object instance of the Tizen Samsung TV Product API.
The webapis.AVPlay object enables access to AVPlay API functionality.

[NoInterfaceObject] interface AVPlayManagerObject {
  readonly attribute AVPlayManager avplay;
};

WebApi implements AVPlayManagerObject;

Attributes

2.2. AVPlayManager

Provides methods for the AVPlay functionalities.

[NoInterfaceObject] interface AVPlayManager {
  void open(DOMString url) ;
  void close() ;
  void prepare() ;
  void prepareAsync(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) ;
  void setDisplayRect( unsigned long x, unsigned long y, unsigned long width, unsigned long height ) ;
  void set360Rotation( float Horizontal_angle_value, float Vertical_angle_value ) ;
  void set360Zoom(long Zoom_level);
  AVPlay360Info get360Info()  ;
  void play() ;
  void seekTo(long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
  void stop() ;
  AVPlayPlayerState getState() ;
  void pause() ;
  void jumpForward(long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) ;
  void jumpBackward( long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback ) ;
  unsigned long getDuration() ;
  unsigned long getCurrentTime() ;
  void setTimeoutForBuffering(unsigned long seconds);
  void setBufferingParam(AVPlayBufferOption option, AVPlayBufferSizeUnit unit, unsigned long amount);
  void setSpeed(long playbackSpeed)  ;
  void setListener(AVPlayPlaybackCallback playbackCallback)  ;
  DOMString setDrm(AVPlayDrmType drmType, AVPlayDrmOperation drmOperation, DOMString jsonParam)  ;
  void setSoundAnalysisListener(AVPlaySoundAnalysisCallback soundAnalysisCallback)  ;
  void unsetSoundAnalysisListener()  ;
  void setSilentSubtitle(boolean onoff)  ;
  void setExternalSubtitlePath(DOMString filePath)  ;
  void setSubtitlePosition(long position)  ;
  void setDisplayMethod(AVPlayDisplayMode displayMode)  ;
  void setSelectTrack(AVPlayStreamType trackType, long trackIndex)  ;
  AVPlayStreamInfo getCurrentStreamInfo()  ;
  AVPlayStreamInfo[] getTotalTrackInfo()  ;
  void setStreamingProperty(AVPlayStreamingPropertyType propertyType, Any propparam)  ;
  DOMString getStreamingProperty(AVPlayStreamingPropertyType propertyType)  ;
  DOMString getVersion()  ;
  void suspend() ;
  void restore(DOMString URL, unsigned long resumeTime, boolean bPrepare) ;
};

Methods

open
Instantiates the player object with a content URL as the input parameter.

void open(DOMString url);

Product : TV, AV_BD

Parameters:

  • url: Content URL for playback. It can be an absolute local path or a remote URL from a network-based stream server.

Constraint

  • Can be called in the following states: "NONE", "IDLE"

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


try {
  webapis.avplay.open(url);
} catch (e) {
  console.log(e);
}
close
Destroys the player object.

        void close();

Product : TV, AV_BD

Constraint

  • Can be called in the following states: "NONE", "IDLE", "READY", "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError, for any other error.

Code example:


try {
  webapis.avplay.close();
} catch (e) {
  console.log(e);
}
prepare
Prepares the media player for playback synchronously. The player must already be created with a valid URI.

void prepare();

Product : TV, AV_BD

Constraint

  • Can be called in the following states: "IDLE", "READY"

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


try {
  webapis.avplay.prepare();
} catch (e) {
  console.log(e);
}
prepareAsync
Prepares the media player for playback asynchronously. This method is preferred over prepare because it returns immediately and does not block the application thread during preparation.
When preparation is successful, the success callback is returned and the player is in READY state. If preparation fails, the error callback returns the error value.
When prepareAsync is used with "PREBUFFER_MODE", successCallback is invoked when prebuffering is complete, instead of when preparation is complete.

void prepareAsync(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

Product : TV, AV_BD

Parameters:

  • successCallback [optional]: Callback method to invoke when the call is successful
  • errorCallback [optional]: Callback method to invoke when an error occurs

Constraint

  • Can be called in the following states: "IDLE", "READY"

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


webapis.avplay.prepareAsync(successCallback, errorCallback);
setDisplayRect
Sets the display area for video content playback.

void setDisplayRect( unsigned long x, unsigned long y, unsigned long width, unsigned long height );

Product : TV, AV_BD

Parameters:

  • x: Display area top-left X-coordinate. Must be less than the TV screen width.
  • y: Display area top-left Y-coordinate. Must be less than the TV screen height.
  • width: Display area width. Must be less than the TV screen width.
  • height: Display area height from source image. Must be less than the source image height.

Constraint

  • Can be called in the following states: "IDLE", "READY", "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


try {
  webapis.avplay.setDisplayRect(0, 0, 1920, 1080);
} catch (e) {
  console.log(e);
}
set360Rotation
Sets the video content playback display angle. Call this method after the open method. The default angle is (0,0).
To create smooth movement, use the minimum increment and call this method at 20 ms intervals.

void set360Rotation( float Horizontal_angle_value, float Vertical_angle_value );

Product : TV

Parameters:

  • Horizontal_angle_value: Horizontal angle as float. The minimum increment is 0.1 (range: 0.0 to 360.0)
  • Vertical_angle_value: Vertical angle as float. The minimum increment is 0.1 (range: 0.0 to 360.0)

Constraint

  • Can be called in the following states: "READY", "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


// Left and right rotation using the left and right keys
// For up and down rotation, change the VerticalAngle value

var HorizontalAngle = 0;
var VerticalAngle = 0;
var IntervalTimer = null;
var Interval_time = 20; // Recommended interval

document.addEventListener('keydown', handleKeydown);
document.addEventListener('keyup', handleKeyup);

function handleKeydown(event) {
  switch(event.keyCode) {
    case 37 : // Use left keydown for left rotation
      if(IntervalTimer == null) {
        intervalTimer = setInterval(function() {
          HorizontalAngle--;
          if(HorizontalAngle <= 0) {
            HorizontalAngle = 360;
          }
          webapis.avplay.set360Rotation(HorizontalAngle, VerticalAngle);
        }, Interval_time);
      }
      break;
    case 39 : // Use right keydown for right rotation
      if(IntervalTimer == null) {
        IntervalTimer = setInterval(function() {
          HorizontalAngle++;
          if(HorizontalAngle >= 360) {
            HorizontalAngle = 0;
          }
          webapis.avplay.set360Rotation(HorizontalAngle, VerticalAngle);
        }, Interval_time);
      }
      break;
  }
}

function handleKeyup(event) {
  switch(event.keyCode) {
    case 37: // Use left and right keyup to stop rotation
    case 39:
      if(IntervalTimer) {
        clearInterval(IntervalTimer);
        IntervalTimer = null;
      }
      break;
  }
}
set360Zoom
Sets the video content playback display zoom. Call this method after the open method. The default zoom is 0. If the input parameter is out of range, an exception object is returned.

void set360Zoom(long Zoom_level);

Product : TV

Parameters:

  • Zoom_level: Zoom level as long (range: 0 to 100)

Constraint

  • Can be called in the following states: "READY", "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


// Zoom in and out using the up and down keys
var ZoomLevel = 0;
document.addEventListener('keydown', handleKeydown);
function handleKeydown(event) {
  switch(event.keyCode) {
    case 38 : // Use up keydown to zoom-in
      ZoomLevel = ZoomLevel + 10;
      if(ZoomLevel >= 100) {
        ZoomLevel = 100;
      }
      break;
    case 40 : // Use down keydown to zoom-out
      ZoomLevel = ZoomLevel - 10;
      if(ZoomLevel <= 0) {
        ZoomLevel = 0;
      }
      break;
  }
  webapis.avplay.set360Zoom(ZoomLevel);
}
get360Info
Retrieves the current 360 video playback angle and zoom level.

AVPlay360Info get360Info();

Product : TV

Return value:

AVPlay360Info current version

Constraint

  • Can be called in the following states: "READY", "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


var AVPlay360Info = webapis.avplay.get360Info();
var Horizontalangle = AVPlay360Info.horizontal_angle;
var Verticalangle = AVPlay360Info.vertical_angle;
var Zoomlevel = AVPlay360Info.zoom_level;
play
Starts stream playback, or resumes stream playback after pause.

void play();

Product : TV, AV_BD

Constraint

  • Can be called in the following states: "READY", "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


try {
  webapis.avplay.play();
} catch (e) {
  console.log(e);
}
seekTo
Skips playback to a specific timestamp.
For HTTP streaming, this method is successful even when the specified timestamp is invalid. The internal player automatically resets an out-of-range value to an in-range one.

void seekTo(long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

Product : TV, AV_BD

Parameters:

  • milliseconds: Timestamp to skip to
  • successCallback [optional]: Callback method to invoke when the call is successful
  • errorCallback [optional]: Callback method to invoke when an error occurs

Constraint

  • Can be called in the following states: "IDLE","READY", "PLAYING" (buffered data is flushed and buffering starts over), "PAUSED"

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


try {
  webapis.avplay.seekTo(10000,successCallback, errorCallback);
} catch (e) {
  console.log(e);
}
stop
Stops the player. Call this function after the video finishes playing.

void stop();

Product : TV, AV_BD

Constraint

  • Can be called in the following states: "NONE", "IDLE", "READY", "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError, for any other error.

Code example:


try {
    webapis.avplay.stop();
} catch (e) {
    console.log(e);
}
getState
Retrieves the current player state.

  AVPlayPlayerState getState();

Product : TV, AV_BD

Return value:

AVPlayPlayerState "NONE", "IDLE", "READY", "PLAYING", "PAUSED".

Constraint

  • Can be called in the following states: "NONE", "IDLE", "READY", "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError, for any other error.

Code example:


var BRet = webapis.avplay.getState();
pause
Pauses playback. If this method is called successfully, current time updates are stopped.

 void pause();

Product : TV, AV_BD

Constraint

  • Can be called in the following states: "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


try {
    webapis.avplay.pause();
} catch (e) {
    console.log(e);
}
jumpForward
Skips playback forward by a specific amount of time. The player state is unchanged.
Passing the optional callbacks is recommended. For best performance, ensure that the previous call to this API was successful.
For HTTP streaming, this method is successful even when the resulting timestamp is invalid. The internal player automatically resets an out-of-range value to an in-range one.

 void jumpForward(long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

Product : TV, AV_BD

Parameters:

  • milliseconds: Time to skip forward, in milliseconds
  • successCallback [optional]: Callback method to invoke when the call is successful
  • errorCallback [optional]: Callback method to invoke when an error occurs

Constraint

  • Can be called in the following states: "READY" (when using the synchronous prepare method), "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


webapis.avplay.jumpForward(5000,  successCallback, errorCallback);
jumpBackward
Skips playback backward by a specific amount of time. The player state is unchanged.
For HTTP streaming, this method is successful even when the resulting timestamp is invalid. The internal player automatically resets an out-of-range value to an in-range one.

void jumpBackward( long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback );

Product : TV, AV_BD

Parameters:

  • milliseconds: Time to skip backward, in milliseconds
  • successCallback [optional]: Callback method to invoke when the call is successful
  • errorCallback [optional]: Callback method to invoke when an error occurs

Constraint

  • Can be called in the following states: "READY" (when using the synchronous prepare method), "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


webapis.avplay.jumpBackward(5000,  successCallback, errorCallback);
getDuration
Retrieves the total media duration.

unsigned long getDuration();

Product : TV, AV_BD

Return value:

unsigned long number Duration, in milliseconds

Constraint

  • Can be called in the following states:"NONE", "IDLE", "READY", "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError, for any other error.

Code example:


duration = calcPlaytime(webapis.avplay.getDuration());

function calcPlaytime(totalMilisec) {
  var Hours = Math.floor(totalMilisec/3600000);
  var Minutes = Math.floor((totalMilisec - (Hours * 3600000)) / 60000);
  var Seconds = Math.floor((totalMilisec - (Hours * 3600000) - (Minutes * 60000)) / 1000);
  var Milisec = totalMilisec - (Hours * 3600000) - (Minutes * 60000) - (Seconds * 1000);
  return {
    Hours: Hours,
    Minutes: Minutes,
    Seconds: Seconds,
    milisec: Milisec,
    totalMilisec: totalMilisec
  }
}
getCurrentTime
Retrieves the current playback time.

unsigned long getCurrentTime();

Product : TV, AV_BD

Return value:

unsigned long number Current playback time, in milliseconds.

Constraint

  • Can be called in the following states: "NONE", "IDLE", "READY", "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError, for any other error.

Code example:


var CurrentPlayTime = webapis.avplay.getCurrentTime();
setTimeoutForBuffering
Sets the stream buffering timeout. When the specified amount of time has passed, the onbufferingcomplete callback is invoked, irrespective of buffering progress.
If not set using this method, the default buffer size is 32MB or 10 seconds of playable data, and 20 seconds time-out.

void setTimeoutForBuffering(unsigned long seconds);

Product : TV, AV_BD

Parameters

  • seconds: Buffering timeout duration, in seconds. Depending on network conditions, 3 to 10 seconds is recommended.

Constraint

  • Can be called in the following states: "IDLE", "READY", "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


webapis.avplay.setTimeoutForBuffering(10);
setBufferingParam
Sets the buffer size for the play and resume scenarios. The default values are 10 seconds or 15 MB. The time buffer size must be at least 4 seconds.
For example, if a 20 MB buffer size is set, playback can only start or resume after 20 MB of data has accumulated in the buffer. If a 10 second buffer size is set, playback can only start or resume after 10 seconds of media has accumulated in the buffer.
Play scenarios include user-initiated streaming playback and whenever media playback is starting for the first time.
Resume scenarios include resuming playback after pause or seek operations, or when lack of data causes playback rebuffering. 

void setBufferingParam(AVPlayBufferOption option, AVPlayBufferSizeUnit unit, unsigned long amount);

Product : TV, AV_BD

Parameters

  • option: "PLAYER_BUFFER_FOR_PLAY" or "PLAYER_BUFFER_FOR_RESUME"
  • unit: "PLAYER_BUFFER_SIZE_IN_BYTE" or "PLAYER_BUFFER_SIZE_IN_SECOND"
  • amount: Data amount to be buffered, in bytes or seconds as specified by the unit parameter

Constraint

  • Can be called in the following states: "IDLE"

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


// For play scenario
webapis.setBufferingParam("PLAYER_BUFFER_FOR_PLAY","PLAYER_BUFFER_SIZE_IN_BYTE", 32*1024*1024);  // 32 is in MBs
webapis.avplay. setBufferingParam("PLAYER_BUFFER_FOR_PLAY","PLAYER_BUFFER_SIZE_IN_SECOND", 10);  // 10 is in seconds


// For resume scenario
webapis.avplay. setBufferingParam("PLAYER_BUFFER_FOR_RESUME","PLAYER_BUFFER_SIZE_IN_BYTE", 32*1024*1024);  // 32 is in MBs
webapis.avplay. setBufferingParam("PLAYER_BUFFER_FOR_RESUME","PLAYER_BUFFER_SIZE_IN_SECOND", 10);  // 10 is in seconds
setSpeed
Sets the current playback rate. Positive parameter values play the media forwards, while negative values cause the media to play in reverse.
The range of valid playback rates depends on the streaming protocol. If the input parameter is out of range, the player returns the PLAYER_ERROR_INVALID_PARAMETER flag.

 void setSpeed(long playbackSpeed);

Product : TV, AV_BD

Parameters:

  • playbackSpeed: -32x, -16x, -8x, -4x, -2x, 1x, 2x, 4x, 8x, 16x, 32x

Constraint

  • Can be called in the following states: "READY, "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

    • limitation

      • Widevine : -32x ~ 32x

      • Smooth Streaming : -16x ~ 16x

      • HLS : Supported only if the master M3U8 has the #EXT-X-I-FRAME-STREAM-INF tag

      • HTTP and HTTPS: -8x ~ 8x (Repeated seek)

      • MPEG-DASH: -8x ~ 8x (Trick play (forward on fast network connection (HbbTV), otherwise repeated backward and forward seek (WebApp))

Code example:


try {
  webapis.avplay.setSpeed(2)
} catch (e) {
  console.log(e);
}
setListener
Sets asynchronous callback methods for player information notifications, such as buffering progress, player information, playback mode, and DRM mode information.

void setListener(AVPlayPlaybackCallback playbackCallback);

Product : TV, AV_BD

Parameters:

  • playbackCallback: AVPlayPlaybackCallback

Constraint

  • Can be called in the following states: "NONE", "IDLE" (recommended), "READY", "PLAYING", "PAUSED"
    To avoid missing necessary information, the onbufferingstart, onbufferingprogress, onbufferingcomplete, onerror, onevent, and ondrmevent listeners must be set during the "IDLE" state.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type UnknownError, for any other error.

Code example:


var Listener = {
  onbufferingstart: function() {
    console.log("Buffering start.");
  },
  onbufferingprogress: function(percent) {
    console.log("Buffering progress data : " + data1);
  },
  onbufferingcomplete: function() {
    console.log("Buffering complete.");
  },
  oncurrentplaytime: function(currentTime) {
    console.log("Current Playtime : " + data1);
  },
  onbufferingcomplete: function() {
    console.log("Buffering complete.");
  },
  onevent: function(eventType, eventData) {
    console.log("event type error : " + eventType + ", data: " + eventData);
  },
  onerror: function(eventType) {
    console.log("event type error : " + eventType);
  },
  onsubtitlechange: function(duration, text, data3, data4) {
    console.log("Subtitle Changed.");
  },
  ondrmevent: function(drmEvent, drmData) {
    console.log("DRM callback: " + drmEvent + ", data: " + drmData);
  },
  onstreamcompleted: function() {
    console.log("Stream Completed");
  }
}

webapis.avplay.setListener(Listener);
setDrm
Updates the DRM information, such as SetProperties. You can change the DRM mode and run the control feature. The AVPlayDrmOperation and jsonParam parameters depend on the DRM type. Widevine CDM is not supported on the 15_Hawk-P and 15_Hawk-M chipsets.

DOMString setDrm(AVPlayDrmType drmType, AVPlayDrmOperation drmOperation, DOMString jsonParam);

Product : TV, AV_BD

Privilege level: Public

Privilege: http://developer.samsung.com/privilege/drmplay

Parameters

  • drmType: AVPlayDrmType {"PLAYREADY", "VERIMATRIX", "WIDEVINE_CDM"}
  • drmOperation: AVPlayDrmOperation : String specifying the DRM operation to be performed. The valid values are "SetProperties", "InstallLicense", "ProcessInitiator", "GetUID", "Initialize", and "Finalize", depending on the DRM type.
    "SetProperties" : Used when DRM-related information is stringified in "json_string" format and passed along in this operation.
    This is mainly used for setting DRM information, such as the license server, application-specific custom data, SOAP or HTTP header, the genChallenge mode, and license usage.
  • jsonParam: DOMString DRM parameter represented by JSON string. You can use the JSON.stringify method to generate the JSON string.

Return value:

any

Constraint

  • Can be called in the following states: "NONE" (only for the Verimatrix GetUID operation), "IDLE", "READY"

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.
      Examples of exception scenarios include an invalid DRM session, or failure to create the underlying DRM module or configuration. In these scenarios, an exception is thrown and the method call returns FALSE.

Code example:


//Implementing DRM support
//PlayReady example: Setting license server and custom data
var DrmParam = {};
DrmParam.LicenseServer = "http://license.company.com";
DrmParam.CustomData    = "mycustom";
webapis.avplay.setDrm("PLAYREADY", "SetProperties", JSON.stringify(DrmParam));

//Verimatrix example: Initializing Verimatrix DRM
var DrmParam = {};
DrmParam.CompanyName ="MyCompany";
DrmParam.IPTV="public2.verimatrix.com";
DrmParam.Web="public-ott-nodrm.verimatrix.com:80";
webapis.avplay.setDrm( "VERIMATRIX", "Initialize", JSON.stringify(DrmParam));

//Verimatrix example: Retrieving the Verimatrix UID
DOMString Verimatrix_UID = webapis.avplay.setDrm( "VERIMATRIX", "GetUID", ""); // Note: For GetUID, the 3rd parameter is not needed

//Widevine CDM example:
var DrmParam = {};
// Sample session value; you must set your own
DrmParam.widevine_data_session = "AXA20a132bsd-1234-1234-1a2b-f0a12a5789";
DrmParam.widevine_data_type = "MPEG-DASH";
webapis.avplay.setDRM("WIDEVINE_CDM", "Initialize", "");
webapis.avplay.setDRM("WIDEVINE_CDM", "widevine_app_session", DrmParam.widevine_app_session);
webapis.avplay.setDRM("WIDEVINE_CDM", "widevine_data_type", DrmParam.widevine_data_type);
// After receiving challenge data through the onDrmEvent callback, the application parses and saves the "session_id", challenge, and server URL
// The challenge data is posted to the server URL and the license data is received
// Application encodes the received license data in database64 format and sends it to AVPlay
var LicenseParam = sessionId + "PARAM_START_POSITION" + dataBase64 + "PARAM_START_POSITION"; //param1 for setDrm
var LicenseDataLen = dataBase64Len; //param2 for setDrm
webapis.avplay.setDRM("WIDEVINE_CDM", "widevine_license_data", LicenseParam, LicenseDataLen);
setSoundAnalysisListener
Retrieves the audio spectrum analysis result every 30 ms. You can use it for an equalizer effect video or in a PartyTV application. The spectrum is analyzed across an array of 31 bands, of which Bands[14] ~ Bands[18] generally have the largest values.

void setSoundAnalysisListener(AVPlaySoundAnalysisCallback soundAnalysisCallback);

Product : TV, AV_BD

Parameters:

  • soundAnalysisCallback: AVPlaySoundAnalysisCallback

Constraint

  • Can be called in the following states: "IDLE"

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


webapis.avplay.setSoundAnalysisListener(soundAnalysisListener);

function soundAnalysisListener(dataArray) {           // Listener registered to and receiving data from AVPlay
  var BarHeight = 0;
  var AbsValue = 0;
  var Threshold = 70;
  for (var I = 0; I < dataarray.length;="" i++)="" {="" absvalue="Math.abs(dataArray[I]);" if="" (absvalue=""> Threshold) {
      BarHeight = Main.barContainerHeight;
    }
    else {
      BarHeight = Math.round((AbsValue/Threshold) * Main.barContainerHeight);
    }
    if (BarHeight == 0) BarHeight = 1;
      document.getElementById('frequencyBar' + I).style.height = BarHeight + 'px';
    }
    console.log("Sound analysis: " + dataArray.toString());
  }
}
unsetSoundAnalysisListener
Unregisters the sound analysis listener.

void unsetSoundAnalysisListener();

Product : TV, AV_BD

Constraint

  • Can be called in the following states: "IDLE", "READY", "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


webapis.avplay.unsetSoundAnalysisListener();
setSilentSubtitle
Enables or disables external subtitles.

void setSilentSubtitle(boolean onoff);

Product : TV, AV_BD

Parameters:

  • onoff: Boolean value:
    • true: Subtitles are hidden
    • false: Subtitles are shown. The application does not receive any subtitle-related events.

Constraint

  • Can be called in the following states: "IDLE", "READY" (when using the synchronous prepare method), "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


webapis.avplay.setSilentSubtitle(true);
setExternalSubtitlePath
Sets the local path for the external subtitle file. Only absolute local paths are supported. If the subtitle file is stored remotely, you must first download the file to local storage, and pass the absolute local path.

void setExternalSubtitlePath(DOMString filePath);

Product : TV, AV_BD

Parameters:

  • filePath: Absolute local path

Constraint

  • Can be called in the following states: "IDLE", "READY", "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


webapis.avplay.setExternalSubtitlePath(uri);
setSubtitlePosition
Adjusts external subtitle synchronization with the audio and video.

void setSubtitlePosition(long position);

Product : TV, AV_BD

Parameters:

  • position: Time delay in milliseconds. The duration can be a positive or negative number; a positive delay displays the subtitles later, while a negative delay displays the subtitles sooner.

Constraint

  • Can be called in the following states: "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


webapis.avplay.setSubtitlePosition(position_millisec);
setDisplayMethod
Sets the video screen mode in the specified display area. Works only when setDisplayRect(0,0,1920,1080) is set.

void setDisplayMethod(AVPlayDisplayMode displayMode);

Product : TV, AV_BD

Parameters:

  • displayMode: "PLAYER_DISPLAY_MODE_LETTER_BOX", "PLAYER_DISPLAY_MODE_FULL_SCREEN", or "PLAYER_DISPLAY_MODE_AUTO_ASPECT_RATIO"

Constraint

  • Can be called in the following states: "IDLE", "READY", "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type UnknownError, for any other error.

Code example:


webapis.avplay.setDisplayMethod("PLAYER_DISPLAY_MODE_FULL_SCREEN");
setSelectTrack
Switches audio or subtitle tracks during playback.

void setSelectTrack(AVPlayStreamType trackType, long trackIndex);

Product : TV, AV_BD

Parameters:

  • trackType: "AUDIO" or "TEXT"
  • trackIndex: AVPlayStreamInfo index

Constraint

  • Can be called in the following states: "READY" (for Smooth Streaming only), "PLAYING", "PAUSED" (for TEXT tracks only)
    If buffering is not complete, calling this method for an AUDIO track returns an error.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


var totalTrackInfo = webapis.avplay.getTotalTrackInfo();
for (var i=0; i < totalTrackInfo.length; i++) {
  if(totalTrackInfo.type == 'TEXT') {
    console.log('Find subtitle track.');
    console.log('subtitle track index is ' + totalTrackInfo.index);
    console.log('subtitle track language is ' + totalTrackInfo.extra_info.track_lang);
  }
}
// Choose subtitle track index 2
webapis.avplay.setSelectTrack('TEXT',2);
getCurrentStreamInfo
Retrieves the currently-playing video, audio, or subtitle stream information, and notifies that a stream is playing.

AVPlayCurrentStreamInfo getCurrentStreamInfo();

Product : TV, AV_BD

Return value:

AVPlayStreamInfo structure containing tracktype, extraInfo and index for the current stream

Constraint

  • Can be called in the following states: "READY", "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


var StreamInfo = webapis.avplay.getCurrentStreamInfo();
var Text = '';
for (var I = 0; I < streaminfo.length;="" i++)="" {="" text="" +='index: ' +="" streaminfo[i].index="" +="" '';="" text="" +='type: ' +="" streaminfo[i].type="" +="" '';="" text="" +='extra_info: ' +="" streaminfo[i].extra_info="" +="" '';="" }="" all="" streams="" have="" extra_info="" as="" a="" jsonstring.="" video="" extra_info="" example="" :="" "{fourcc:"h264","width":"1920","height":"1080","bit_rate":"="" 477000"}"="" audio="" extra_info="" example="" :="" "{"language":"eng","channels":"2","sample_rate":"44100","bit_rate":"96000","fourcc":"aacl"}"="" text(subtitle)="" extra_info="" example="" :="" "{"track_num":"0","track_lang":"eng","subtitle_type":"-1","fourcc":"ttml"}"="" if="" the="" stream="" is="" invalid,="" the="" domstring="" is="" null="" and="" the="" index="" value="" is="" -1.="">
getTotalTrackInfo
Retrieves the currently-playing stream information.

AVPlayStreamInfo[] getTotalTrackInfo();

Product : TV, AV_BD

Return value:

AVPlayStreamInfo[] structure containing tracktype, extraInfo and Index of current stream
Returns information for the all available tracks in the stream. The information is returned in the following structure:
For video tracks: "{"fourCC":"%s","Width":"%u","Height":"%u","Bit_rate":"%u"}"
For audio track: "{"language":"%s","channels":"%d","sample_rate":"%d","bit_rate":"%d","fourCC":"%s"}"
* For subtitle tracks: "{"track_num":"%d","track_lang":"%s","subtitle_type":"%d","fourCC":"%s"}"

Constraint

  • Can be called in the following states: "READY" (when using the synchronous prepare method), "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


var TrackInfo = webapis.avplay.getTotalTrackInfo();
var Text = 'type of track info: ' + typeof TrackInfo + '';
Text += 'length: ' + TrackInfo.length + '';
for (var I = 0; I < trackinfo.length;="" i++)="" {="" text="" +='index: ' +="" trackinfo[i].index="" +="" '';="" text="" +='type: ' +="" trackinfo[i].type="" +="" '';="" text="" +='extra_info: ' +="" trackinfo[i].extra_info="" +="" '';="" }="">
setStreamingProperty
Sets specific feature values for HTTP, MMS, or specific streaming engine (Smooth Streaming, HLS, DASH, DivX Plus Streaming, or Widevine). The available streaming properties depend on the streaming protocol or engine.
Use the CUSTOM_MESSAGE property for streaming engine or CP-specific settings.

void setStreamingProperty(AVPlayStreamingPropertyType propertyType, Any propparam);

Product : TV, AV_BD

Parameters:

  • propertyType: { "COOKIE", "USER_AGENT", "PREBUFFER_MODE" , "ADAPTIVE_INFO", "SET_MODE_4K", "PROPERTY_HD_AUDIO", "LISTEN_SPARSE_TRACK","WIDEVINE" };
  • propparam: Value according to the propertyType. e.g. "ADAPTIVE_INFO" PropetyTypes are "BITRATES", "STARTBITRATE", "SKIPBITRATE".

Constraint

  • Can be called in the following states: "IDLE"

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


//Smooth Streaming example:
var BitRateString = "BITRATES=5000~10000|STARTBITRATE=HIGHEST|SKIPBITRATE=LOWEST"; webapis.avplay.setStreamingProperty("ADAPTIVE_INFO", BitRateString);

//Prebuffer mode example:
webapis.avplay.setStreamingProperty("PREBUFFER_MODE", time_in_miliseconds);

Player1 => Playback of Main Content
Player2 => Playback of advertisement (Buffered   the ad content before playback).
Player1 = webapis.avplaystore.getPlayer();
Player2 = webapis.avplaystore.getPlayer();
Player1.open('http://www.example.com/example_1.mp4');
Player1.setDisplayRect(x, y, width, height);
Player1.prepare();
Player1.play();
Player2.open('http://www.example.com/example_2.mp4');
Player2.setStreamingProperty("PREBUFFER_MODE", "5000");
Player2.setDisplayRect(x, y, width, height);
Player2.prepare();
Player1.stop();
Player2.play();

//User-agent example:
webapis.avplay.setStreamingProperty("USERAGENT", "samsungsmooth-agent/1.1");
 
//Widevine example:
webapis.avplay.setStreamingProperty ("WIDEVINE","DEVICE_ID=null|DEVICET_TYPE_ID=60|DRM_URL=https://~~~|I_SEEK=TIME|CUR_TIME=PTS|PORTAL=~~");
getStreamingProperty
Retrieves a specific property value obtained by the streaming engine (Smooth Streaming, HLS, DASH, or Widevine).

DOMString getStreamingProperty(AVPlayStreamingPropertyType propertyType);

Product : TV, AV_BD

Parameters:

Return value:

DOMString Property value

Constraint

  • Can be called in the following states: "READY", "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


var Text = 'AVAILABLE_BITRATE: ' + webapis.avplay.getStreamingProperty ("AVAILABLE_BITRATE") ;
Text += 'CURRENT_BANDWIDTH: ' + webapis.avplay.getStreamingProperty ("CURRENT_BANDWIDTH") + '';
Text += 'IS_LIVE: ' + webapis.avplay.getStreamingProperty ("IS_LIVE") +'';
Text += 'AVAILABLE_BITRATE': ' + webapis.avplay.getStreamingProperty ("AVAILABLE_BITRATE") +'';
Text += 'LISTEN_SPARSE_TRACK' + webapis.avplay.getStreamingProperty ("LISTEN_SPARSE_TRACK") +'';

Code example:


var StartTime = webapis.avplay.getStreamingProperty("GET_LIVE_DURATION").split('|')[0];
var EndTime = webapis.avplay.getStreamingProperty("GET_LIVE_DURATION").split('|')[1];

if (StartTime > targetSeekTime)
{
  if (EndTime < targetseektime)="" {="" webapis.avplay.seekto(targetseektime);="" ms="" }="" }="" get_live_duration="" is="" available="" since="" 2016="" tv="" models.="" is_live,="" available_bitrate,="" get_live_duration="" and="" current_bandwith:="" supported="" for="" smooth="" streaming,="" hls,="" and="" dash.="" get_server_time_scale="" and="" get_absolute_server_time:="" supported="" for="" smooth="" streaming="">
getVersion
Retrieves the AVPlay version.

DOMString getVersion();

Product : TV, AV_BD

Return value:

DOMString string current version

Constraint

  • Can be called in the following states: "NONE", "IDLE", "READY", "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError, for any other error.

Code example:


var Version = webapis.avplay.getVersion();
suspend
Pauses the player state when the application is sent to the background. Saves the current statistics for the ongoing playback session.

void suspend();

Product : TV, AV_BD

Constraint

  • Can be called in the following states: "READY, "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


document.addEventListener("visibilitychange", function() {
  if(document.hidden){
    // Something you want to do when application is paused.
    console.log("lifecycle [pause]");
    webapis.avplay.suspend();
  } else {
    // Something you want to do when application is resumed.
    console.log("lifecycle [resume]");
    webapis.avplay.restore();
  }
});
restore
During multitasking, restores the player state when the application is resumed. For live streaming or DRM-encrypted content playback, you must check whether the streaming URL has changed or the DRM session or license has expired, and specify the new URL and DRM information as needed.

void restore(DOMString URL, long resumeTime, boolean bPrepare);

Product : TV, AV_BD

Parameters

  • URL: updated URL after suspend. If null, the stored URL is used.
    For live streaming or DRM-encrypted content playback, in case the URL has changed or the DRM license or session has expired, checking for and passing the newest URL is recommended.
  • resumeTime: (milliseconds) Optional. Timestamp from which to resume playback. If 0, the stored position is used.
    For live streaming, this parameter is not meaningful. Do not pass 0 for this parameter.
    For DRM-encrypted content playback, if the DRM session has expired, to recreate the playback pipeline, pass 0 for this parameter.
  • bPrepare: Optional boolean. false (default): Player sets the resume behavior automatically. true: Player does not resume automatically. The application must invoke the prepare and play methods.
    For live streaming, this parameter is not meaningful. Do not pass true for this parameter.
    For DRM-encrypted content playback: if the DRM session has expired, pass true for this parameter.

Constraint

  • Can be called in the following states: "NONE" (when the "instant-on" TV feature is enabled), "PLAYING", "PAUSED"

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if an input parameter is not compatible with its expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any input parameter contains an invalid value.

    • with error type InvalidStateError, if it is called in an invalid state.

    • with error type UnknownError, for any other error.

Code example:


document.addEventListener("visibilitychange", function() {
  if(document.hidden){
    // Something you want to do when application is paused
    console.log("lifecycle [pause]");
    webapis.avplay.suspend();
  } else {
    // Something you want to do when application is resumed
    console.log("lifecycle [resume]");
    webapis.avplay.restore(url, 0, false);
  }
});

2.3. AVPlayPlaybackCallback

Defines callbacks for buffering and playback notifications.

[Callback=FunctionOnly, NoInterfaceObject] interface AVPlayPlaybackCallback{
  void onbufferingstart();
  void onbufferingprogress(unsigned long percent);
  void onbufferingcomplete();
  void oncurrentplaytime(unsigned long currentTime );
  void onstreamcompleted();
  void onevent(AVPlayEvent eventid, DOMString data );
  void onerror(AVPlayError eventid);
  void ondrmevent(AVPlayDrmType type, drmData data);
  void onsubtitlechange(unsigned long duration, DOMString subtitles, unsigned long type, unsigned long attriCount, AVPlaySubtitleAttribute attributes);
};

Methods

onbufferingstart
Callback method for asynchronous buffering started notifications.

void onbufferingstart();

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError, for any other error.

Code example:


onbufferingstart: function() {
  console.log("Buffering start.");
}
onbufferingprogress
Callback method for asynchronous buffering progress notifications.

void onbufferingprogress(unsigned long percent);

Parameters:

  • percent: unsigned long

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError, for any other error.

Code example:


onbufferingprogress: function(percent) {
  console.log("Buffering progress data : " + percent);
}
onbufferingcomplete
Callback method for asynchronous buffering complete notifications.

void onbufferingcomplete();

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError, for any other error.

Code example:


onbufferingcomplete: function() {
  console.log("Buffering complete.");
}
oncurrentplaytime
Callback method for the current playback time.

void oncurrentplaytime(unsigned long currentTime );

Parameters:

  • currentTime: unsigned long

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError, for any other error.

Code example:


oncurrentplaytime: function(currentTime) {
  console.log("Current playtime: " + currentTime);
}
onstreamcompleted
Callback method for asynchronous playback finished notifications.

void onstreamcompleted();

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError, for any other error.

Code example:


onstreamcompleted: function(currentTime) {
  console.log("Stream Completed");
}
onevent
Callback method for asynchronous event notifications.

void onevent(AVPlayEvent eventid, DOMString data );

Parameters:

  • eventid: AVPlayEvent object
  • data: DOMString

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError, for any other error.

Code example:


onevent: function(eventType, eventData) {
  console.log("OnEvent Callback with eventType: " + eventType);
}
onerror
Callback method for AVPlay error notifications.

void onerror(AVPlayError eventid);

Parameters:

  • eventid: AVPlayError object

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError, for any other error.

Code example:


onerror: function(eventType) {
  console.log("OnError Event Callback with eventType: " + eventType);
}
ondrmevent
Callback method for DRM information notifications.

void ondrmevent(AVPlayDrmType type, drmData data);

Parameters:

  • type: AVPlayDrmType object
  • data: drmData

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError, for any other error.

Code example:


ondrmevent: function(drmEvent, drmData) {
  console.log("DRM callback: " + drmEvent + ", data: " + drmData);
}

/*
drmData
{
  readonly attribute DOMString name: Message name
                                     If the name is "Challenge", it is challenge data posted from the platform. The application can store the challenge data in the following way:
                                       if (drmData.name == "Challenge") {
                                         var EventDataObj = {
                                           "NAME": drmData.name,
                                           "SESSION_ID": drmData.session_id,
                                           "CHALLENGE": drmData.challenge,
                                           "CHALLENGE_LEN": drmData.challenge_len,
                                           "SERV_URL": drmData.serverurl,
                                           "SERV_URL_LEN": drmData.serverurl_len
                                         };
                                       }
                                     If the name is "DrmError", DRM processing has encountered an error.
  readonly attribute DOMString code     : For "DrmError" message only; the DRM error code
  readonly attribute DOMString message  : For "Challenge", the challenge data string. For "DrmError", the DRM error message.
  readonly attribute DOMString reserved : Currently unused
}
*/
onsubtitlechange
Callback method for asynchronous subtitle change notifications.

void onsubtitlechange(unsigned long duration, DOMString subtitles, unsigned long type, unsigned long attriCount, AVPlaySubtitleAttribute attributes);

Parameters:

  • duration: unsigned long
  • subtitles: DOMString
  • type: unsigned long
  • attriCount: unsigned long
  • attributes: AVPlaySubtitleAttribute "attr_type": "AttributeType:value"; "start_pos": start position as long; "stop_pos": stop position as long

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError, for any other error.

Code example:


onsubtitlechange: function(duration, text, data3, data4) {
  console.log("Subtitle Changed.");
}


module AVPlay {
  enum AVPlayPlayerState {
    "NONE",
    "IDLE",
    "READY",
    "PLAYING",
    "PAUSED"
  };

  enum AVPlayDisplayMode { 
    "PLAYER_DISPLAY_MODE_LETTER_BOX", 
    "PLAYER_DISPLAY_MODE_FULL_SCREEN",
    "PLAYER_DISPLAY_MODE_AUTO_ASPECT_RATIO" 
  };

  enum AVPlayBufferOption { 
    "PLAYER_BUFFER_FOR_PLAY", 
    "PLAYER_BUFFER_FOR_RESUME" 
  };

  enum AVPlayBufferSizeUnit {
    "PLAYER_BUFFER_SIZE_IN_BYTE", 
    "PLAYER_BUFFER_SIZE_IN_SECOND" 
  };

  enum AVPlayStreamingPropertyType { 
    "COOKIE", 
    "USER_AGENT", 
    "PREBUFFER_MODE", 
    "ADAPTIVE_INFO",  
    "SET_MODE_4K", 
    "PROPERTY_HD_AUDIO", 
    "LISTEN_SPARSE_TRACK", 
    "IS_LIVE", 
    "AVAILABLE_BITRATE", 
    "GET_LIVE_DURATION", 
    "CURRENT_BANDWIDTH", 
    "WIDEVINE", 
    "SET_VR360_MODE"
  };

  enum AVPlayDrmType {
    "PLAYREADY", 
    "VERIMATRIX", 
    "WIDEVINE_CDM"
  };

  enum AVPlayDrmOperation { 
    "SetProperties", 
    "InstallLicense", 
    "ProcessInitiator", 
    "GetUID", 
    "Initialize", 
    "Finalize", 
    "widevine_license_data", 
    "widevine_app_session", 
    "widevine_data_type" 
  };

  enum AVPlayStreamType { 
    "VIDEO", 
    "AUDIO", 
    "TEXT" 
  };

  enum AVPlayError{
    "PLAYER_ERROR_NONE",
    "PLAYER_ERROR_INVALID_PARAMETER",
    "PLAYER_ERROR_NO_SUCH_FILE",
    "PLAYER_ERROR_INVALID_OPERATION",
    "PLAYER_ERROR_SEEK_FAILED",
    "PLAYER_ERROR_INVALID_STATE",
    "PLAYER_ERROR_NOT_SUPPORTED_FILE",
    "PLAYER_ERROR_INVALID_URI",
    "PLAYER_ERROR_CONNECTION_FAILED",
    "PLAYER_ERROR_GENEREIC"
  };

  enum AVPlayEvent {
    "PLAYER_MSG_NONE",
    "PLAYER_MSG_RESOLUTION_CHANGED",
    "PLAYER_MSG_BITRATE_CHANGE",
    "PLAYER_MSG_FRAGMENT_INFO",
    "PLAYER_SPARSE_TRACK_DETECT",
    "PLAYER_STREAMING_EVENT",
    "PLAYER_MSG_HTTP_ERROR_CODE",
    "PLAYER_MSG_DRM_CHALLENGE_DATA"
  };

  dictionary AVPlayStreamInfo {
    unsigned long index;
    unsigned long adaption_index;
    unsigned long alternate_index;
    AVPlayStreamType type;
    DOMString extra_info;
  };

  dictionary AVPlaySubtitleAttribute {
    DOMString type;
    long start;
    long stop;
  };

  dictionary AVPlay360Info {
    long horizontal_angle;
    long vertical_angle;
    long zoom_level;
  };

  [NoInterfaceObject] interface AVPlayManagerObject {
    readonly attribute AVPlayManager avplay;
  };

  WebApi implements AVPlayManagerObject;

  [NoInterfaceObject] interface AVPlayManager {
    void open(DOMString url);
    void close();
    void prepare();
    void prepareAsync(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
    void setDisplayRect( unsigned long x, unsigned long y, unsigned long width, unsigned long height );
    void set360Rotation( float Horizontal_angle_value, float Vertical_angle_value );
    void set360Zoom(long Zoom_level);
    AVPlay360Info get360Info();
    void play();
    void seekTo(long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
    void stop();
    AVPlayPlayerState getState();
    void pause();
    void jumpForward(long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
    void jumpBackward( long milliseconds, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback );
    unsigned long getDuration() ;
    unsigned long getCurrentTime() ;
    void setTimeoutForBuffering(unsigned long seconds);
    void setBufferingParam(AVPlayBufferOption option, AVPlayBufferSizeUnit unit, unsigned long amount);
    void setSpeed(long playbackSpeed);
    void setListener(AVPlayPlaybackCallback playbackCallback);
    DOMString setDrm(AVPlayDrmType drmType, AVPlayDrmOperation drmOperation, DOMString jsonParam);
    void setSoundAnalysisListener(AVPlaySoundAnalysisCallback soundAnalysisCallback);
    void unsetSoundAnalysisListener();
    void setSilentSubtitle(boolean onoff);
    void setExternalSubtitlePath(DOMString filePath);
    void setSubtitlePosition(long position);
    void setDisplayMethod(AVPlayDisplayMode displayMode);
    void setSelectTrack(AVPlayStreamType trackType, long trackIndex);
    AVPlayStreamInfo getCurrentStreamInfo();
    AVPlayStreamInfo[] getTotalTrackInfo();
    void setStreamingProperty(AVPlayStreamingPropertyType propertyType, Any propparam);
    DOMString getStreamingProperty(AVPlayStreamingPropertyType propertyType);
    DOMString getVersion();
    void suspend() ;
    void restore(DOMString URL, unsigned long resumeTime, boolean bPrepare);
  };

  [Callback=FunctionOnly, NoInterfaceObject] interface AVPlayPlaybackCallback{
    void onbufferingstart();
    void onbufferingprogress(unsigned long percent);
    void onbufferingcomplete();
    void oncurrentplaytime(unsigned long currentTime );
    void onstreamcompleted();
    void onevent(AVPlayEvent eventid, DOMString data );
    void onerror(AVPlayError eventid);
    void ondrmevent(AVPlayDrmType type, drmData data);
    void onsubtitlechange(unsigned long duration, DOMString subtitles, unsigned long type, unsigned long attriCount, AVPlaySubtitleAttribute attributes);
  };
};

SAMSUNG

Copyright © 2010 - 2018 SAMSUNG All rights reserved.

Portions of this page are reproduced from work created and shared by the Android Open Source Project
and used according to terms described in the Creative Commons 2.5 Attribution License.