Class: PlayerEndpoint

elements.PlayerEndpoint()

Retrieves content from external sources.

PlayerEndpoint will access the given resource, read all available data, and inject it into Kurento. Once this is is done, the injected video or audio will be available for passing through any other Filter or Endpoint to which the PlayerEndpoint gets connected.

The source can provide either seekable or non-seekable media; this will dictate whether the PlayerEndpoint is able (or not) to seek through the file, for example to jump to any given timestamp.

The Source URI supports these formats:

  • File: A file path that will be read from the local file system. Example:
    • file:///path/to/file
  • HTTP: Any file available in an HTTP server. Examples:
    • http(s)://host/path/to/file
    • http(s)://username:password@host:port/path/to/file
  • RTSP: Typically used to capture a feed from an IP Camera. Examples:
    • rtsp://host
    • rtsp://username:password@host:port/path/to/file?key=value&key=value
  • NOTE: Special characters must be URL-encoded in username and password fields.

Note that PlayerEndpoint requires read permissions to the source ; otherwise, the media server won't be able to retrieve any data, and an ErrorEvent will be fired. Make sure your application subscribes to event, otherwise troubleshooting issues will be difficult.

The list of valid operations is:

  • play : Starts streaming media. If invoked after pause, it will resume playback.
  • stop : Stops streaming media. If play is invoked afterwards, the file will be streamed from the beginning.
  • pause : Pauses media streaming. Play must be invoked in order to resume playback.
  • seek : If the source supports seeking to a different time position, then the PlayerEndpoint can:
    • setPosition : Allows to set the position in the file.
    • getPosition : Returns the current position being streamed.

Events fired

  • EndOfStreamEvent: If the file is streamed completely.

Constructor

new PlayerEndpoint()

Create a PlayerEndpoint
Source:
Fires:

Extends

Members

(static) constructorParams

Properties:
Name Type Attributes Description
mediaPipeline module:core.MediaPipeline The MediaPipeline this PlayerEndpoint belongs to.
networkCache external:Integer <optional>
RTSP buffer length.

When receiving media from an RTSP source, the streamed video can suffer spikes or stuttering, caused by hardware or network issues. Having a reception buffer helps alleviate these problems, because it smoothes the stream of incoming data to the receiving endpoint.

Finding a buffer length that works best for your connection might take some tweaking, which can be done with this optional property. Note that a longer buffer will be able to fix bigger network spikes, but at the cost of introducing more latency to the media playback.

  • Unit: milliseconds.
  • Default: 2000.
uri external:String URI pointing to the video. It has to be accessible to the KMS process.
  • Local resources: The user running the Kurento Media Server must have read permission over the file.
  • Remote resources: Must be accessible from the server where the media server is running.
useEncodedMedia external:Boolean <optional>
Feed an encoded media as-is to the Media Pipeline, instead of first decoding

This property is disabled by default. The input media gets always decoded into a raw format upon receiving it, before being processed by the rest of the Media Pipeline. This is done to ensure that Kurento is able to keep track of lost keyframes among other quality-control measurements. Of course, having to decode the media has a cost in terms of CPU usage, but ensures that the output streaming will be more robust and reliable.

When this property is enabled, Kurento simply passes the encoded media as-is to the rest of the Media Pipeline, without decoding. Enabling this mode of operation could have a severe effect on stability, because lost video keyframes will not be regenerated; however, not having to encode the video greatly reduces the CPU load.

Keep in mind that if this property is enabled, the original source media MUST already be in a format that is compatible with the destination target. For example: Given a Pipeline that reads a file and then streams browser such as Chrome, the file must already be encoded with a VP8 or H.264 codec profile, which Chrome is able to decode.

Of special note is that you cannot feed any random combination of H.264 encoding options to a web browser; instead, they tend to support only a very specific subset of the codec features (also known as 'profiles'). The most compatible config for H.264 is Constrained Baseline profile, level 3.1.

Code examples:


                 # Java
                 PlayerEndpoint player = new PlayerEndpoint
                   .Builder(pipeline, 'rtsp://localhost:5000/video')
                   .useEncodedMedia()
                   .build();
               

                 # JavaScript
                 let player = await pipeline.create('PlayerEndpoint', {
                   uri: 'rtsp://localhost:5000/video',
                   useEncodedMedia: true,
                 });
               
Source:

(static) events

Source:

Methods

(static) play(callbackopt) → {external:Promise}

Starts reproducing the media, sending it to the :rom:cls:`MediaSource`. If the endpoint has been connected to other endpoints, those will start receiving media.
Parameters:
Name Type Attributes Description
callback module:elements.PlayerEndpoint~playCallback <optional>
Source:
Returns:
Type
external:Promise

getChildren(callbackopt) → {external:Promise}

Children of this MediaObject.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaObject~getChildrenCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getCreationTime(callbackopt) → {external:Promise}

MediaObject creation time in seconds since Epoch.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaObject~getCreationTimeCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getElementGstreamerDot(callbackopt) → {external:Promise}

Returns the GStreamer DOT string for this element's private pipeline
Parameters:
Name Type Attributes Description
callback module:elements.PlayerEndpoint~getElementGstreamerDotCallback <optional>
Source:
Returns:
Type
external:Promise

getEncoderBitrate(callbackopt) → {external:Promise}

Target video bitrate for media transcoding.

The bitrate of a video has a direct impact on its perceived image quality. Higher bitrate means higher quality, but also a larger amount of bytes to transmit or store. Use this parameter to set the desired average bitrate in videos that are transcoded by the media server.

This parameter is most useful for :rom:cls:`RecorderEndpoint` and :rom:cls:`RtpEndpoint`: when media is being transcoded (either for streaming or storing on disk), the resulting quality is directly controlled with this value.

For :rom:cls:`WebRtcEndpoint`, this value should be left as default, as remote WebRTC receivers will already send feedback to inform the media server about what is the optimal bitrate to send.

Setting a value will only work if done before the media starts to flow.

  • Unit: bps (bits per second).
  • Default: 300000 (300 kbps).
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaElement~getEncoderBitrateCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getMaxEncoderBitrate(callbackopt) → {external:Promise}

Maximum video bitrate for media transcoding.

This parameter can be used to fine tune the automatic bitrate selection that normally takes place within elements that are able to dynamically change the encoding bitrate according to the conditions of the streaming, such as :rom:cls:`WebRtcEndpoint`.

This should be left as default in most cases, given that remote WebRTC receivers already send feedback to inform the media server about what is the optimal bitrate to send. Otherwise, this parameter could be used for example to limit the total bitrate that is handled by the server, by setting a low maximum output for all endpoints.

This should be left as default in most cases, given that remote WebRTC receivers already send feedback to inform the media server about what is the optimal bitrate to send. Otherwise, this parameter could be used for example to limit the total bitrate that is handled by the server, by setting a low maximum output for all endpoints.

Setting a value will only work if done before the media starts to flow.

  • Unit: bps (bits per second).
  • Default: 0.
  • 0 = unlimited. Encoding performed with bitrate as requested by receivers.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaElement~getMaxEncoderBitrateCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getMediaPipeline(callbackopt) → {external:Promise}

MediaPipeline to which this MediaObject belongs. It returns itself when invoked for a pipeline object.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaObject~getMediaPipelineCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getMinEncoderBitrate(callbackopt) → {external:Promise}

Minimum video bitrate for media transcoding.

This parameter can be used to fine tune the automatic bitrate selection that normally takes place within elements that are able to dynamically change the encoding bitrate according to the conditions of the streaming, such as :rom:cls:`WebRtcEndpoint`.

This should be left as default in most cases, given that remote WebRTC receivers already send feedback to inform the media server about what is the optimal bitrate to send. Otherwise, this parameter could be used for example to force a higher bitrate than what is being requested by receivers.

Setting a value will only work if done before the media starts to flow.

  • Unit: bps (bits per second).
  • Default: 0.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaElement~getMinEncoderBitrateCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getName(callbackopt) → {external:Promise}

This MediaObject's name.

This is just sugar to simplify developers' life debugging, it is not used internally for indexing nor identifying the objects. By default, it's the object's ID.

Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaObject~getNameCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getParent(callbackopt) → {external:Promise}

Parent of this MediaObject.

The parent of a Hub or a MediaElement is its MediaPipeline. A MediaPipeline has no parent, so this property will be null.

Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaObject~getParentCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getPosition(callbackopt) → {external:Promise}

Get or set the actual position of the video in ms.
Note Setting the position only works for seekable videos
Parameters:
Name Type Attributes Description
callback module:elements.PlayerEndpoint~getPositionCallback <optional>
Source:
Returns:
Type
external:Promise

getSendTagsInEvents(callbackopt) → {external:Promise}

Flag activating or deactivating sending the element's tags in fired events.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaObject~getSendTagsInEventsCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getState(callbackopt) → {external:Promise}

State of the endpoint
Parameters:
Name Type Attributes Description
callback module:core/abstracts.UriEndpoint~getStateCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getUri(callbackopt) → {external:Promise}

The uri for this endpoint.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.UriEndpoint~getUriCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

getVideoInfo(callbackopt) → {external:Promise}

Returns info about the source being played
Parameters:
Name Type Attributes Description
callback module:elements.PlayerEndpoint~getVideoInfoCallback <optional>
Source:
Returns:
Type
external:Promise

setEncoderBitrate(encoderBitrate, callbackopt) → {external:Promise}

Target video bitrate for media transcoding.

The bitrate of a video has a direct impact on its perceived image quality. Higher bitrate means higher quality, but also a larger amount of bytes to transmit or store. Use this parameter to set the desired average bitrate in videos that are transcoded by the media server.

This parameter is most useful for :rom:cls:`RecorderEndpoint` and :rom:cls:`RtpEndpoint`: when media is being transcoded (either for streaming or storing on disk), the resulting quality is directly controlled with this value.

For :rom:cls:`WebRtcEndpoint`, this value should be left as default, as remote WebRTC receivers will already send feedback to inform the media server about what is the optimal bitrate to send.

Setting a value will only work if done before the media starts to flow.

  • Unit: bps (bits per second).
  • Default: 300000 (300 kbps).
Parameters:
Name Type Attributes Description
encoderBitrate external:Integer
callback module:core/abstracts.MediaElement~setEncoderBitrateCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

setMaxEncoderBitrate(maxEncoderBitrate, callbackopt) → {external:Promise}

Maximum video bitrate for media transcoding.

This parameter can be used to fine tune the automatic bitrate selection that normally takes place within elements that are able to dynamically change the encoding bitrate according to the conditions of the streaming, such as :rom:cls:`WebRtcEndpoint`.

This should be left as default in most cases, given that remote WebRTC receivers already send feedback to inform the media server about what is the optimal bitrate to send. Otherwise, this parameter could be used for example to limit the total bitrate that is handled by the server, by setting a low maximum output for all endpoints.

This should be left as default in most cases, given that remote WebRTC receivers already send feedback to inform the media server about what is the optimal bitrate to send. Otherwise, this parameter could be used for example to limit the total bitrate that is handled by the server, by setting a low maximum output for all endpoints.

Setting a value will only work if done before the media starts to flow.

  • Unit: bps (bits per second).
  • Default: 0.
  • 0 = unlimited. Encoding performed with bitrate as requested by receivers.
Parameters:
Name Type Attributes Description
maxEncoderBitrate external:Integer
callback module:core/abstracts.MediaElement~setMaxEncoderBitrateCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

setMinEncoderBitrate(minEncoderBitrate, callbackopt) → {external:Promise}

Minimum video bitrate for media transcoding.

This parameter can be used to fine tune the automatic bitrate selection that normally takes place within elements that are able to dynamically change the encoding bitrate according to the conditions of the streaming, such as :rom:cls:`WebRtcEndpoint`.

This should be left as default in most cases, given that remote WebRTC receivers already send feedback to inform the media server about what is the optimal bitrate to send. Otherwise, this parameter could be used for example to force a higher bitrate than what is being requested by receivers.

Setting a value will only work if done before the media starts to flow.

  • Unit: bps (bits per second).
  • Default: 0.
Parameters:
Name Type Attributes Description
minEncoderBitrate external:Integer
callback module:core/abstracts.MediaElement~setMinEncoderBitrateCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

setName(name, callbackopt) → {external:Promise}

This MediaObject's name.

This is just sugar to simplify developers' life debugging, it is not used internally for indexing nor identifying the objects. By default, it's the object's ID.

Parameters:
Name Type Attributes Description
name external:String
callback module:core/abstracts.MediaObject~setNameCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

setPosition(position, callbackopt) → {external:Promise}

Get or set the actual position of the video in ms.
Note Setting the position only works for seekable videos
Parameters:
Name Type Attributes Description
position external:int64
callback module:elements.PlayerEndpoint~setPositionCallback <optional>
Source:
Returns:
Type
external:Promise

setSendTagsInEvents(sendTagsInEvents, callbackopt) → {external:Promise}

Flag activating or deactivating sending the element's tags in fired events.
Parameters:
Name Type Attributes Description
sendTagsInEvents external:Boolean
callback module:core/abstracts.MediaObject~setSendTagsInEventsCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

Type Definitions

getElementGstreamerDotCallback(error, result)

Parameters:
Name Type Description
error external:Error
result external:String
Source:

getPositionCallback(error, result)

Parameters:
Name Type Description
error external:Error
result external:int64
Source:

getVideoInfoCallback(error, result)

Parameters:
Name Type Description
error external:Error
result module:elements/complexTypes.VideoInfo
Source:

playCallback(error)

Parameters:
Name Type Description
error external:Error
Source:

setPositionCallback(error)

Parameters:
Name Type Description
error external:Error
Source: