Class: RecorderEndpoint

elements.RecorderEndpoint()

Provides functionality to store media contents.

RecorderEndpoint can store media into local files or send it to a remote network storage. When another MediaElement is connected to a RecorderEndpoint, the media coming from the former will be muxed into the selected recording format and stored in the designated location.

These parameters must be provided to create a RecorderEndpoint, and they cannot be changed afterwards:

  • Destination URI, where media will be stored. These formats are supported:
    • File: A file path that will be written into the local file system. Example:
      • file:///path/to/file
    • HTTP: A POST request will be used against a remote server. The server must support using the chunked encoding mode (HTTP header Transfer-Encoding: chunked). Examples:
      • http(s)://host/path/to/file
      • http(s)://username:password@host:port/path/to/file
    • Relative URIs (with no schema) are supported. They are completed by prepending a default URI defined by property defaultPath. This property is defined in the configuration file /etc/kurento/modules/kurento/UriEndpoint.conf.ini, and the default value is file:///var/lib/kurento/
    • NOTE: Special characters must be URL-encoded in username and password fields.
  • Media Profile (MediaProfileSpecType), which determines the video and audio encoding. See below for more details.
  • EndOfStream (optional), a parameter that dictates if the recording should be automatically stopped once the EOS event is detected.

Note that RecorderEndpoint requires write permissions to the destination ; otherwise, the media server won't be able to store any information, and an ErrorEvent will be fired. Make sure your application subscribes to event, otherwise troubleshooting issues will be difficult.

  • To write local files (if you use file://), the system user that is owner of the media server process needs to have write permissions for requested path. By default, this user is named 'kurento'.
  • To record through HTTP, the remote server must be accessible through the network, and also have the correct write permissions for the destination path.

Recording will start as soon as the user invokes the record() method. The recorder will then store, in the location indicated, the media that the source is sending to the endpoint. If no media is being received, or no endpoint has been connected, then the destination will be empty. The recorder starts storing information into the file as soon as it gets it.

Recording must be stopped when no more data should be stored. This is done with the stopAndWait() method, which blocks and returns only after all the information was stored correctly.

The source endpoint can be hot-swapped while the recording is taking place. The recorded file will then contain different feeds. When switching video sources, if the new video has different size, the recorder will retain the size of the previous source. If the source is disconnected, the last frame recorded will be shown for the duration of the disconnection, or until the recording is stopped.

NOTE: It is recommended to start recording only after media arrives. For this, you may use the MediaFlowInStateChanged and MediaFlowOutStateChanged events of your endpoints, and synchronize the recording with the moment media comes into the Recorder.

WARNING: All connected media types must be flowing to the RecorderEndpoint. If you used the default connect() method, it will assume both AUDIO and VIDEO. Failing to provide both kinds of media will result in the RecorderEndpoint creating an empty file and buffering indefinitely; the recorder waits until all kinds of media start arriving, in order to synchronize them appropriately.
For audio-only or video-only recordings, make sure to use the correct, media-specific variant of the connect() method.

For example:

  1. When a web browser's video arrives to Kurento via WebRTC, your WebRtcEndpoint will emit a MediaFlowOutStateChanged event.
  2. When video starts flowing from the WebRtcEndpoint to the RecorderEndpoint, the RecorderEndpoint will emit a MediaFlowInStateChanged event. You should start recording at this point.
  3. You should only start recording when RecorderEndpoint has notified a MediaFlowInStateChanged for ALL streams. So, if you record AUDIO+VIDEO, your application must receive a MediaFlowInStateChanged event for audio, and another MediaFlowInStateChanged event for video.

Constructor

new RecorderEndpoint()

Builder for the RecorderEndpoint
Source:
Fires:

Extends

Members

(static) constructorParams

Properties:
Name Type Attributes Description
mediaPipeline module:core.MediaPipeline the MediaPipeline to which the endpoint belongs
mediaProfile module:elements/complexTypes.MediaProfileSpecType <optional>
 Selects the media format used for recording.

The media profile allows you to specify which codecs and media container will be used for the recordings. This is currently the only way available to tell Kurento about which codecs should be used.

Watch out for these important remarks:

  • If the format of incoming media differs from the recording profile, media will need to be transcoded. Transcoding always incurs in noticeable CPU load, so it is always good trying to avoid it. For instance, if a VP8-encoded video (from WebRTC) is recorded with an MP4 recording profile (which means H.264 encoding), the video needs to be transcoded from VP8 to H.264. On the other hand, recording with the WEBM profile would allow to store the video as-is with its VP8 encoding.
  • If you intend to record audio-only or video-only media, select the appropriate _AUDIO_ONLY or _VIDEO_ONLY profile. For example, to record a WebRTC screen capture (as obtained from a web browser's call to MediaDevices.getDisplayMedia()), choose WEBM_VIDEO_ONLY instead of just WEBM.
stopOnEndOfStream external:Boolean <optional>
 Forces the recorder endpoint to finish processing data when an End Of Stream
uri external:String URI where the recording will be stored. It must be accessible from the media
  • Local server resources: The user running the Kurento Media Server must have write permission over the file.
  • Network resources: Must be accessible from the network where the media server is running.
Source:

(static) events

Source:

Methods

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

Starts storing media received through the sink pad.
Parameters:
Name Type Attributes Description
callback module:elements.RecorderEndpoint~recordCallback <optional>
Source:
Returns:
Type
external:Promise

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

Stops recording and does not return until all the content has been written to
Parameters:
Name Type Attributes Description
callback module:elements.RecorderEndpoint~stopAndWaitCallback <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

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

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

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

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

recordCallback(error)

Parameters:
Name Type Description
error external:Error
Source:

stopAndWaitCallback(error)

Parameters:
Name Type Description
error external:Error
Source: