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-cdn.platformcraft.com/app/recorder-cloud/v1/testaccount/record'

Error response example

Invalid token

Get all settings of all recordings

URL: https://api-cdn.platformcraft.com/app/recorder-cloud/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-cdn.platformcraft.com/app/recorder-cloud/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-cdn.platformcraft.com/app/recorder-cloud/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	-1 (do not delete)	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-cdn.platformcraft.com/app/recorder-cloud/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-cdn.platformcraft.com/app/recorder-cloud/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-cdn.platformcraft.com/app/recorder-cloud/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-cdn.platformcraft.com/app/recorder-cloud/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
path	No	-	Storage path	Storage path where to save recording files
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

Change settings during active record

During an active record, it is possible to change only dvr_enabled parameter.

Request example

curl "https://api-cdn.platformcraft.com/app/recorder-cloud/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-cdn.platformcraft.com/app/recorder-cloud/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-cdn.platformcraft.com/app/recorder-cloud/v1/testaccount/record/$RECORD_ID" -H "cdn-auth-token: $TOKEN" -X PATCH --data '{"action": "stop"}' -H 'Content-Type: application/json'

Reset DVR

action: restart

Request example

curl "https://api-cdn.platformcraft.com/app/recorder-cloud/v1/testaccount/record/$RECORD_ID" -H "cdn-auth-token: $TOKEN" -X PATCH --data '{"action": "restart"}' -H 'Content-Type: application/json'

Deactivate settings

action: deactivate

Request example

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

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

Value	Description
short	Short-term broadcast (up to 12 hours)
long	Continuous broadcast

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

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

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