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)://{server-ip}/path/to/file
      • http(s)://{username}:{password}@{server-ip}:{server-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 (for current versions of Kurento 6.x): special characters are supported in {username} or {password}. This means that {username} cannot contain colons (:), and {password} cannot contain 'at' signs (@). This is a limitation of GStreamer 1.8 (the underlying media framework behind Kurento), and is already fixed in newer versions (which the upcoming Kurento 7.x will use).
    • NOTE (for upcoming Kurento 7.x): special characters in {username} or {password} must be url-encoded. This means that colons (:) should be replaced with '%3A', and 'at' signs (@) should be replaced with '%40'.
  • 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

getChilds(callbackopt) → {external:Promise}

Children of this MediaObject.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaObject~getChildsCallback <optional>
Inherited From:
Deprecated:
  • Use children instead.
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

getMaxOuputBitrate(callbackopt) → {external:Promise}

Maximum video bandwidth for transcoding.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaElement~getMaxOuputBitrateCallback <optional>
Inherited From:
Deprecated:
  • Deprecated due to a typo. Use :rom:meth:`maxOutputBitrate` instead of this function.
Source:
Returns:
Type
external:Promise

getMaxOutputBitrate(callbackopt) → {external:Promise}

Maximum video bitrate for transcoding.
  • Unit: bps (bits per second).
  • Default: MAXINT.
  • 0 = unlimited.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaElement~getMaxOutputBitrateCallback <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

getMinOuputBitrate(callbackopt) → {external:Promise}

Minimum video bandwidth for transcoding.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaElement~getMinOuputBitrateCallback <optional>
Inherited From:
Deprecated:
  • Deprecated due to a typo. Use :rom:meth:`minOutputBitrate` instead of this function.
Source:
Returns:
Type
external:Promise

getMinOutputBitrate(callbackopt) → {external:Promise}

Minimum video bitrate for transcoding.
  • Unit: bps (bits per second).
  • Default: 0.
Parameters:
Name Type Attributes Description
callback module:core/abstracts.MediaElement~getMinOutputBitrateCallback <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

setMaxOuputBitrate(maxOuputBitrate, callbackopt) → {external:Promise}

Maximum video bandwidth for transcoding.
Parameters:
Name Type Attributes Description
maxOuputBitrate external:Integer
callback module:core/abstracts.MediaElement~setMaxOuputBitrateCallback <optional>
Inherited From:
Deprecated:
  • Deprecated due to a typo. Use :rom:meth:`maxOutputBitrate` instead of this function.
Source:
Returns:
Type
external:Promise

setMaxOutputBitrate(maxOutputBitrate, callbackopt) → {external:Promise}

Maximum video bitrate for transcoding.
  • Unit: bps (bits per second).
  • Default: MAXINT.
  • 0 = unlimited.
Parameters:
Name Type Attributes Description
maxOutputBitrate external:Integer
callback module:core/abstracts.MediaElement~setMaxOutputBitrateCallback <optional>
Inherited From:
Source:
Returns:
Type
external:Promise

setMinOuputBitrate(minOuputBitrate, callbackopt) → {external:Promise}

Minimum video bandwidth for transcoding.
Parameters:
Name Type Attributes Description
minOuputBitrate external:Integer
callback module:core/abstracts.MediaElement~setMinOuputBitrateCallback <optional>
Inherited From:
Deprecated:
  • Deprecated due to a typo. Use :rom:meth:`minOutputBitrate` instead of this function.
Source:
Returns:
Type
external:Promise

setMinOutputBitrate(minOutputBitrate, callbackopt) → {external:Promise}

Minimum video bitrate for transcoding.
  • Unit: bps (bits per second).
  • Default: 0.
Parameters:
Name Type Attributes Description
minOutputBitrate external:Integer
callback module:core/abstracts.MediaElement~setMinOutputBitrateCallback <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: