Records any inbound stream. The record command allows users to record a stream that may not yet exist. When a new stream is brought into the server, it is checked against a list of streams to be recorded.

Streams can be recorded as FLV files, MPEG-TS files or as MP4 files.

Parameter Name Mandatory Default Value Description
localStreamName true null The name of the stream to be used as input for recording
pathToFile true null Specify path and file name to write to
type false mp4 “ts”, “mp4” or “flv”
overwrite false 0 false If false, when a file already exists for the stream name, a new file will be created with the next appropriate number appended. If 1 (true), files with the same name will be overwritten
keepAlive false 1 true If 1 (true), the server will restart recording every time the stream becomes available again
chunkLength false 0 disabled If non-zero the record command will start a new recording file after ChunkLength seconds have elapsed
waitForIDR false 1 true This is used if the recording is being chunked. When true, new files will only be created on IDR boundaries
winQtCompat false 0 false Mandates 32bit header fields to ensure compatibility with Windows QuickTime
dateFolderStructure false 0 false If set to 1 (true), folders will be created with names in YYYYMMDD format. Recorded files will be placed inside these folders based on the date they were created

An example of the record interface is:

record localStreamName=video1 pathtofile=/recording/path/fileName type=mp4 overwrite=1

This records the local stream named video1 to directory /recording/path in mp4 format with fileName and overwrite enabled.

Example:

API Call:

record localStreamName=testpullstream pathtofile=../media/testRecord type=mp4 overwrite=1

JSON Response:

{
"data":{
    "chunkLength":0,
    "computedPathToFile":"..\/media\/testRecord.mp4",
    "configId":12,
    "dateFolderStructure":false,
    "hasAudio":true,
    "keepAlive":true,
    "localStreamName":"testpullstream",
    "mp4BinPath":"..\\evo-mp4writer.exe",
    "operationType":7,
    "overwrite":true,
    "pathToFile":"..\/media\/testRecord ",
    "preset":0,
    "type":"mp4",
    "waitForIDR":false,
    "winQtCompat":true
},
"description":"Recording Stream",
"status":"SUCCESS"
}

The JSON response contains the following details about recording a stream:

  • data – The data to parse

    • chunkLength - The length (in seconds) of each playlist element
    • computedPathToFile – The path and file name of the recorded stream
    • configID – The configuration ID for this command
    • dateFolderStructure – If true, will organize record chunks by date
    • hasAudio – Indicates if the recorded stream has audio, false if none
    • keepAlive – If true, the stream will attempt to reconnect if the connection is severed
    • localStreamName – The local name for the stream
    • mp4BinPath-??
    • operationType – The type of operation
    • overwrite – If true, files with the same name will be overwritten
    • pathToFile – Path to the folder where recorded files will be written
    • preset - ??
    • type – Type of file for recording. Either `flv`,`ts`, or ‘mp4’
    • waitForIDR – If true, new files will only be created on IDR boundaries
    • winQtCompat – If true, andates 32bit header fields to ensure compatibility with Windows QuickTime

  • description – Describes the result of parsing/executing the command

  • status – SUCCESS if the command was parsed and executed successfully, FAIL if not

    ​

MP4 File Creation

​When recording to an MP4 file format the EMS will create three (if video or audio only stream) or four (if sream has audio and video) different files:

  • filename.info
  • filename.mdat
  • filename.track1

  • filename.track2 (only if audio and video)

    These files will all exist within the destination folder specified in the Record command issued.

    At the end of recording, or when the recording file is closed by the EMS to start a new chunk, the EMS will automatically combine these files into the final .mp4 file. This is done to ensure optimal MP4 file formatting with the header “atoms” at the beginning of the file.

    The EMS uses the evo-mp4writer binary to perform the combination of files into the final MP4 file.

    If for any reason an MP4 file fails to be combined you can manually use the evo-mp4writer binary to create the MP4 file. Typically this failure to combine will only occur if the EMS or the server itself is shutdown mid-record and so the evo-mp4writer is not given a chance to run.

    The syntax for the evo-mp4writer is as follows:

    evo-mp4writer -path=/path/to/file.mp4

    The -path parameter here should be the same as was used in the record pathtofile parameter.

    ​

    *--recovery option is going to be deprecated in the upcoming 1.7.0 revision or in 1.7.1. Previously this option is useful in saving time as it only needs to re write the ftyp and moov atom without changing the mdat. Since both moov and mdat are reordered in our internal codebase, both of them needs to be re-written always in the event that evo-mp4writer is invoked manually.

    If the above command fails, you can add a --recovery parameter to the end to provide some additional resiliency:

    evo-mp4writer -path=/path/to/file.mp4 --recovery