Interface RecorderEndpoint

All Superinterfaces:
Endpoint, KurentoObject, MediaElement, MediaObject, UriEndpoint
public interface RecorderEndpoint extends UriEndpoint
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 this 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 the 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.