Class: RecorderEndpoint

elements.RecorderEndpoint()

Provides functionality to store media contents.

The RecorderEndpoint can store media in local files or in a network resource. It receives a media stream from another MediaElement (i.e. the source), and stores it in the designated location.

The following information has to be provided in order to create a RecorderEndpoint, and cannot be changed afterwards:

  • Destination URI, where media will be stored. These formats are supported:
    • File: A file path that exists in the local file system.
      • 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).
      • http(s)://{server-ip}/path/to/file
      • http(s)://{username}:{password}@{server-ip}/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/
  • The Media Profile (module:elements.RecorderEndpoint#MediaProfileSpecType) used for storage. This will determine the video and audio encoding. See below for more details about Media Profile.
  • Optionally, the user can select if the endpoint will stop processing once the EndOfStream event is detected.

RecorderEndpoint requires access to the resource where stream is going to be recorded . Otherwise, the media server won't be able to store any information, and an ErrorEvent will be fired. Please note that if you haven't subscribed to that type of event, you can be left wondering why your media is not being saved, while the error message was ignored.

  • To write local files (if you use file://), the user running media server (by default, user kurento) needs to have write permissions for the requested path.
  • To save into an HTTP server, the server must be accessible through the network, and also have the correct access rights to the destination path.

The media profile is quite an important parameter, as it will determine whether the server needs to perform on-the-fly transcoding of the media. If the input stream codec if not compatible with the selected media profile, the media will be transcoded into a suitable format. This will result in a higher CPU load and will impact overall performance of the media server.

For example: Say that your pipeline will receive VP8-encoded video from WebRTC, and sends it to a RecorderEndpoint; depending on the format selected...

  • WEBM: The input codec is the same as the recording format, so no transcoding will take place.
  • MP4: The media server will have to transcode from VP8 to H264. This will raise the CPU load in the system.
  • MKV: Again, video must be transcoded from VP8 to H264, which means more CPU load.

From this you can see how selecting the correct format for your application is a very important decision.

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.

Stopping the recording process is done through the stopAndWait method, which will return only after all the information was stored correctly. If the file is empty, this means that no media arrived at the recorder.

When another endpoint is connected to the recorder, by default both AUDIO and VIDEO media types are expected, unless specified otherwise when invoking the connect method. Failing to provide both types, will result in teh recording buffering the received media: it won't be written to the file until the recording is stopped. This is due to the recorder waiting for the other type of media to arrive, so they are synchronized.

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.

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

  1. When the remote video arrives to KMS, your WebRtcEndpoint will start generating packets into the Kurento Pipeline, and it will trigger a MediaFlowOutStateChange event.
  2. When video packets arrive from the WebRtcEndpoint to the RecorderEndpoint, the RecorderEndpoint will raise a MediaFlowInStateChange event.
  3. You should only start recording when RecorderEndpoint has notified a MediaFlowInStateChange for ALL streams (so, if you record AUDIO+VIDEO, your application must receive a MediaFlowInStateChange event for audio, and another MediaFlowInStateChange event for video).

Constructor

new 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>
 Sets the media profile used for recording. If the profile is different than the one being recieved at the sink pad, media will be trnascoded, resulting in a higher CPU load. For instance, when recording a VP8 encoded video from a WebRTC endpoint in MP4, the load is higher that when recording in WEBM.
stopOnEndOfStream external:Boolean <optional>
 Forces the recorder endpoint to finish processing data when an EOS is
uri external:String URI where the recording will be stored. It has to be accessible to the KMS process.
  • Local server resources: The user running the Kurento Media Server must have write permission over the file.
  • Network resources: Must be accessible from the server 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 module:core/abstracts.MediaElement#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 module:core/abstracts.MediaElement#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 module:core/abstracts.MediaElement#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 module:core/abstracts.MediaElement#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: