Skip to content

API for DVR and stream recording

Description

This section describes API methods for creating, deleting and managing DVR and stream recording settings.

General information

  • Required headers: CDN-AUTH-TOKEN (authorization token, see Authorization)
  • Successful response Content-Type: application/json
  • Resource ID means ID of RTMP/RTSP-publish resource
  • Abbreviations in use:
Abbreviation Full name
SP Source playlist

Common errors

You can get one of the following errors as a result of any request:

Code Content-Type Body Description
400 text/plain Invalid path Wrong path
401 text/plain Invalid token No header with token provided
403 text/plain Invalid account Wrong account provided
404 text/plain Not found Wrong URL
405 text/plain Method is not allowed You are not allowed to perform an action
500 text/html - Internal server error

Request example

curl 'https://api.cdnvideo.ru/app/dvr/v1/testaccount/record'

Error response example

Invalid token

Get all settings of all recordings

URL: https://api.cdnvideo.ru/app/dvr/v1/<your_account_name>/record

  • Request method: GET
  • Available querystring-parameters:

    Parameter Possible values Description
    resource_id Resource ID ID of the resource settings are applied to
    all Presence in the parameters list Return all recording instances, including already finished or started
    extra_fields Comma-separated strings list Return extra fields
  • Available extra_fields parameter values:

    Value Description
    status Recording status (wait/progress/finish/error)
  • Possible response codes:

    Code Data Description
    200 List of settings data -
  • Settings data format:

    Key Description
    id Identifier
    resource_id Resource ID
    account_name Account name
    source_domain SP domain
    source_path SP path
    stream_type Stream type
    launch_type Recording launch type
    stop_timeout Publishing timeout of stream to record (in seconds)
    storage_time Time to store recording files (in days)
    dvr_enabled Whether DVR is enabled in the player
    dvr_window DVR window (in seconds)
    smil Whether source playlist is a SMIL
    qualities Object with qualities URLs and names of SP
    records List of recording instances data
    path Path where to save recording files
  • Recording instances data format:

    Key Description
    start Recording start datetime
    stop Recording stop datetime
    init_path Path where recording files were saved

    Start and stop datetime format

    Datetime values (start, stop) should be passed in YYYY-MM-DDThh:mm:ssZ format in UTC timezone.
    Example: 2021-12-30T12:30:05Z

Request example

curl 'https://api.cdnvideo.ru/app/dvr/v1/testaccount/record' -H "CDN-AUTH-TOKEN: $TOKEN"

Successful response example

[
 {
    "id": "a9bdcf5f-4e9e-42b3-bfсd-35469d66a44f",
    "resource_id": "6434361230573122384_fxqe0wa6vvv",
    "account_name": "test_account",
    "source_domain": "https://prefix.a.trbcdn.net",
    "source_path": "/livemaster/70xs4gn2s0_zv2dm9kt929/playlist.m3u8",
    "stream_type": "short",
    "launch_type": "button",
    "stop_timeout": 1800,
    "storage_time": 3,
    "dvr_enabled": true,
    "dvr_window": 43200,
    "smil": false,
    "qualities": null,
    "records": [
      {
        "start": "2022-01-01T13:26:26Z",
        "stop": "2022-01-01T15:27:34Z",
        "init_path": "/records/20220101T121112.m3u8"
      },
      {
        "start": "2022-01-01T16:13:52Z",
        "stop": "2022-01-01T17:14:48Z",
        "init_path": "/records/20220101T121112.m3u8"
      }
    ],
    "path": "/records/20220101T121112.m3u8"
  }
]

Create stream recording settings

URL: https://api.cdnvideo.ru/app/dvr/v1/<your_account_name>/record

  • Request method: PUT
  • Request body Content-Type: application/json
  • Available parameters:

    Parameter Required Default value Possible values Description
    resource_id No - Resource ID ID of resource settings should be applied to
    stream_name Yes - String Stream name
    stream_type Yes - Stream type Type of stream to record
    source Yes - URL Source playlist URL
    launch_type Yes - Launch type Recording launch type
    schedule No - List of schedule objects List of scheduled recordings objects
    path No /records/{now}.m3u8 Storage path Storage path where to save recording files
    stop_timeout No 1800 Integer (seconds) Duration of stream timeout in seconds
    storage_time No 3 Integer (days) Amount of days to store recording file for
    dvr_enabled No false Boolean Whether DVR in the player should be enabled
    dvr_window No 43200 Integer (seconds) DVR window
    smil No false Boolean Whether source playlist is a SMIL
    qualities No - Object Object with qualities URLs and names
  • Available stream types:

    Value Description
    short Short-term broadcast (up to 12 hours)
    long Continuous broadcast
  • Available recording launch types:

    Value Description
    stream_start Launch on stream publishing
    button Launch on button press (request)
    schedule* Launch on specified datetime

    Attention

    * - this type is only available for short-term broadcasts

  • Possible response codes:

    Code Data Description
    201 record_id Settings have been successfully applied
    409 - Settings for provided source playlist exist and are active
    422 Errors data Errors in parameters values

Request example

curl 'https://api.cdnvideo.ru/app/dvr/v1/testaccount/record' -X PUT --data '{"stream_name": "6t48oq7ts_i12f41tnkfs_smil", "stream_type":"short", "path":"/records/20220101T175729.m3u8", "smil":true, "qualities": {"https://prefix.a.trbcdn.net/livemaster/6t48oq7ts_i12f41tnkfs_tcode360p/playlist.m3u8": "360p", "https://prefix.a.trbcdn.net/livemaster/6t48oq7ts_i12f41tnkfs_tcode480p/playlist.m3u8": "480p", "https://prefix.a.trbcdn.net/livemaster/6t48oq7ts_i12f41tnkfs_tcode720p/playlist.m3u8": "720p"}, "launch_type": "button", "stop_timeout": 1800, "dvr_enabled": false, "schedule": [], "storage_time": 3, "resource_id": "9778349385416447311_hl4ceseblgw", "source": "https://prefix.a.trbcdn.net/livemaster/xlepd_live-5nls7s5gi2.smil/playlist.m3u8"}' -H "Content-Type: application/json" -H "CDN-AUTH-TOKEN: $TOKEN"

Successful response example

{
  "id": "b1795283-c88b-43ad-a28b-0659389e82df"
}

Get settings for specific stream recording

URL: https://api.cdnvideo.ru/app/dvr/v1/<your_account_name>/record/<record_id>

  • Request method: GET
  • Available querystring-parameters:

    Parameter Possible values Description
    resource_id Resource ID ID of the resource settings are applied to
    all Presence in the parameters list Return all recording instances, including already finished or started
    extra_fields Comma-separated string list Return extra fields
  • Available extra_fields parameter values:

    Value Description
    status Recording status (wait/progress/finish/error)
  • Possible response codes:

    Code Data Description
    200 List of settings data -
  • Settings data format:

    Key Description
    id Identifier
    resource_id Resource ID
    account_name Account name
    source_domain SP domain
    source_path SP path
    stream_type Stream type
    launch_type Recording launch type
    stop_timeout Publishing timeout of stream to record (in seconds)
    storage_time Time to store recording files (in days)
    dvr_enabled Whether DVR is enabled in the player
    dvr_window DVR window (in seconds)
    smil Whether source playlist is a SMIL
    qualities Object with qualities URLs and names of SP
    records List of recording instances data
    path Path where to save recording files
  • Recording instances data format:

    Key Description
    start Recording start datetime
    stop Recording stop datetime
    init_path Path where recording files was saved

    Start and stop datetime format

    Datetime values (start, stop) should be passed in YYYY-MM-DDThh:mm:ssZ format in UTC timezone.
    Example: 2021-12-30T12:30:05Z

Request example

curl "https://api.cdnvideo.ru/app/dvr/v1/testaccount/record/$RECORD_ID" -H "CDN-AUTH-TOKEN: $TOKEN"

Successful response example

[
  {
    "id": "089ec628-1e96-482e-a43d-02537b6f8f8e",
    "resource_id": "2415236563435151586_izxvl4r88pc",
    "account_name": "testaccount",
    "source_domain": "https://prefix.a.trbcdn.net",
    "source_path": "/livemaster/dxsbm_live-sj74f3ih5co.smil/playlist.m3u8",
    "stream_type": "short",
    "launch_type": "schedule",
    "stop_timeout": 1800,
    "storage_time": 87,
    "dvr_enabled": false,
    "dvr_window": 43200,
    "smil": true,
    "qualities": {
      "https://prefix.a.trbcdn.net/livemaster/bkxw4xqxna_7vn4752dq4_tcode360p/playlist.m3u8": "360p",
      "https://prefix.a.trbcdn.net/livemaster/bkxw4xqxna_7vn4752dq4_tcode480p/playlist.m3u8": "480p",
      "https://prefix.a.trbcdn.net/livemaster/bkxw4xqxna_7vn4752dq4_tcode720p/playlist.m3u8": "720p"
    },
    "records": [],
    "path": null
  }
]

Actions with recording settings

URL: https://api.cdnvideo.ru/app/dvr/v1/<your_account_name>/record/<record_id>

  • Request method: PATCH
  • Request body Content-Type: application/json
  • Available parameters:

    Parameter Required Default value Possible values Description
    action No change action string Name of the action to perform
  • Possible response codes:

    Code Data Description
    200 - Action has been successfully performed
    400 - No settings for record with provided record_id
    422 Errors data Errors in parameters values

Change settings

  • action: change
  • Available parameters:

    Parameter Required Default value Possible values Description
    stream_type No - Stream type Type of stream to record
    launch_type No - Launch type Recording launch type
    schedule No - List of schedule objects List of scheduled recordings objects
    storage_time No - Integer (days) Amount of days to store recording file for
    dvr_enabled No - Boolean Whether DVR in the player should be enabled

Request example

curl "https://api.cdnvideo.ru/app/dvr/v1/testaccount/record/$RECORD_ID" -H "cdn-auth-token: $TOKEN" -X PATCH --data '{"stream_type": "long", "dvr_enabled": true}' -H 'Content-Type: application/json'

Start recording

  • action: start

Request example

curl "https://api.cdnvideo.ru/app/dvr/v1/testaccount/record/$RECORD_ID" -H "cdn-auth-token: $TOKEN" -X PATCH --data '{"action": "start"}' -H 'Content-Type: application/json'

Stop recording

  • action: stop

Request example

curl "https://api.cdnvideo.ru/app/dvr/v1/testaccount/record/$RECORD_ID" -H "cdn-auth-token: $TOKEN" -X PATCH --data '{"action": "stop"}' -H 'Content-Type: application/json'

Deactivate settings

  • action: deactivate

Request example

curl "https://api.cdnvideo.ru/app/dvr/v1/testaccount/record/$RECORD_ID" -H "cdn-auth-token: $TOKEN" -X PATCH --data '{"action": "deactivate"}' -H 'Content-Type: application/json'