Control Panel — API Documentation

Documentation

Stream Status API

The Recording API is separate from the regular ScaleEngine API. You query the origin server where you publish your streams directly via HTTP GET requests. The API allows publishers to request recorded streams to start, stop, and split recording on demand. All streams that match the stream parameter and their transcoders will perform the requested action.

If a request is already in process, additional stop/split actions will skip performing their action and return the result from the first pending request. These additional requests will return as an error to indicate that this request did not execute and is the results of a previous stop/split. After 20 seconds of waiting if the file name is not set all requests will return a timeout error. Responses from the API Module are return in XML format. To connect to the API a GET Request is sent with the necessary parameters, which include:

  • action [string] - start, stop, or split
  • secret [string] - the secret key assigned to either the server or to the application.xml
  • app [string] - the applcation/instance to query.
  • stream [string] - the name of the stream to query
  • size [int] - Splits recorded files when files reach this size in MB
  • duration [int] - Splits recorded files when files reach this duration in minutes
  • schedule [string] - Splits recorded files based on the provided crontab expression
  • default [boolean] - Set a start record request to use default settings
  • delete [boolean] - Recorded files can be flagged to be deleted rather than kept when requesting a stop or split.
  • flushqueue [boolean] - Resets the wait queue and allows the action to proceed as if there were no other requests waiting. (note: this will not make splits happen faster, this is only to reset the queue)
Error messages:
  • Invalid Request: - Request is missing parameters and the message will indicate which
  • Unknown Action Requested: - Action parameter was not set properly
  • You do not have permission to access this application.
  • Stream {stream_str} not found on {application}
  • Another process is running on this stream, try again later
  • Value of Size was not formatted as a number. only 0-9 digits are accepted.
  • Value of Duration was not formatted as a number. only 0-9 digits are accepted
  • Value of Schedule not a valid crontab expression.
  • Recording already in progress.
  • Recording cannot be stopped yet.
  • Recording not ready to be split yet
  • Stream is not being recorded.
  • timed out waiting for filename to be returned.
  • File could not be deleted.

Connection URL Example

https://jb-origin.secdn.net/serecordcontrols?action=start&app=jb-origin/live&stream=my-stream&secret=myapipassword

Commands

Actions Description / Requirements Response
start Starts a recording on the requested stream using the default parameters.
The size, duration, schedule, and default parameters can be added to the query to request behaviour other than the default. Size will indicate that the recording should split when the size in mb is reached. Duration will indicate that the recording should split when the length of the video in minutes is reached. Schedule will define that the recording should split based on a crontab expression. Default does not require a value, but will overwrite the saved parameters back to the default settings. 
Success:
<ScaleEngineRecordControls>
    <streams>
        <stream>
            <name>stream-name</name>
            <error>this will display only if there is an error</error>
            <message>Stream {stream_name}: Default Recording started</message>
        </stream>
    </streams>
</ScaleEngineRecordControls>
Error:
<ScaleEngineRecordControls>
    <error>Stream already in progress</error>
</ScaleEngineRecordControls>
stop Stop will tell the recorder to stop recording the request stream. 
Success:
                <ScaleEngineRecordControls>
    <streams>
        <stream>
            <name>stream-name</name>
            <error>this will display only if there is an error</error>
            <message>Recording has stopped for stream {stream_name}</message>
            <deleted>true or false if delete file was requested</deleted>
            <duration>file duration</duration>
            <file>recorded file name</file>
        </stream>
    </streams>
</ScaleEngineRecordControls>
Error:
<ScaleEngineRecordControls>
    <error>Stream is not recording</error>
</ScaleEngineRecordControls>
split Split will cause the current file to be saved and moved, and a recording to start. 
Success:
                <ScaleEngineRecordControls>
    <streams>
        <stream>
            <name>stream-name</name>
            <error>this will display only if there is an error</error>
            <message>Recording has been split for stream {stream_name}</message>
            <deleted>true or false if delete file was requested</deleted>
            <duration>file duration</duration>
            <file>recorded file name</file>
        </stream>
    </streams>
</ScaleEngineRecordControls>
Error:
<ScaleEngineRecordControls>
    <error>Stream is not recording</error>
</ScaleEngineRecordControls>

Change Log

  • v1.0.25.2015.07.04
    - added a list of all valid actions
    - requested actions will be validated and an unknown action requested error message is sent when failed
    - authentication happens before finding matching streams
    - added flushqueue param that will reset the queue property back to 0
    - requests now only only increments/decrements the queue when waiting for a filename
    - a queue cannot go below 0