Control Panel — API documentation

Streams

Stream object

The Stream object contains information on how the stream is to be played, recording, DVR, stream protection, and Google Analytics settings.

Recording

Record settings for the stream are configured using record, record_type, segment_type and segment_value. Record determines if a stream should start recording when it is published. Record Type controls how the file name is versioned. Segmenting will split recorded files into chunks by size, duration, or based on a cron value.

DVR

For DVR users you can control how much of a buffer the dvr provides and how long to wait for an encoder to reconnect.

Protection

Stream authentication can be enabled using a username and password that is required for encoders to connect. By default this is disabled, but can be enabled by setting the username and password fields.

Further streams can enable playback protection using SEVU.

Google Analytics

Viewer data can be tracked and sent to Google Analytics when provided with a proper key.

Descriptions

id Integer Autogenerated

Unique identifier for this object.

Sample value:N/A

cdn_id Integer Autogenerated

The CDN ID that owns this object.

Sample value:8123

app String Immutable Required

Application Name

The application name must begin with "username-"

Sample value:username-origin

name String Immutable Required

Stream Name

May only contain alpha numerical characters, dashes (-), and underscores (_)

Sample value:mystreamname

type String Immutable Required

Type of Stream

Enum:live, channel, switchboard, streamfetch

Default:live

Sample value:switchboard

edge_type String Normal Required

Playback type

Enum:vsn, vse, dvr

Default:vse

Sample value:dvr

protection String Normal Required

Playback Protection Type

Enum:none, sevu, hmac, geoip

Default:none

Sample value:sevu

protection_key String Normal

[Not Implemented] Playback Protection Key or list of IP addresses to allow/block.

Protection of hmac requires a protection key, while none or sevu will have a protection key of null

Sample value:secret#STRING@of&charact3rs

Only for: protection: hmac protection: geoip

transcode_template Integer Normal

[Not Implemented] Select a transcode template to apply to this stream

Integer

Sample value:720p@30fps_1536kbps

hls_chunks Integer Normal

Number of HLS chunks on the playlist

Integer

Default:4

Sample value:4

hls_timeout Integer Normal

How long to wait for the stream to reconnect

Range:10 - 1200

Default:10

Sample value:300

user String Normal

Username for stream authentication

May only contain alpha numerical characters, dashes (-), and underscores (_)

Sample value:myuser

pass String Normal

Playback Protection Type

String

Sample value:myPassw0rd1

record Boolean Normal

Record This Stream

Boolean

Default:

Sample value:false

record_type String Normal

Recording Type

Enum:stream, event

Default:stream

Sample value:stream

segment_type String Normal

Recording Segmentation

Enum:disabled, schedule, duration, size

Default:duration

Sample value:schedule

segment_value String Normal

Recording Segmentation Value: the value is dependant on which segement_type is set. For size and duration a numerical value is expected. Schedule expects a cron expression. Disabled will set this field to null.

Segment type of duration or size must have a segment value that is an integer, schedule must have a valid crontab expression, and disabled must have a segment value of null

Default:1440

Sample value:* */2 * * *

Only for: segment_type: schedule segment_type: duration segment_type: size

save_folder String Normal

Folder to save recordings too

Folder names may contain lower case letters, numbers, dashes (-), and underscores (_), but must start and end with a letter or number.

Sample value:recordings/mystream

ga_key String Normal

Google Analytics

String

Sample value:UA-123456-1

flags Integer Immutable

Advanced Stream Flags, multiple flags can be combined using a logical AND

Flags:

  • 1 - Auto Generated
  • 2 - StreamFetch RTMP
  • 4 - StreamFetch HLS Origin
  • 8 - Exclude Source Stream from Transcoded Outputs
  • 16 - Exclude Audio Only Transcoded Outputs

Default:0

Sample value:10

origin_url String Synthetic

Origin URL

Sample value:rtmp://username-origin.secdn.net/username-origin/live

full_url String Synthetic

Origin URL with stream name

Sample value:rtmp://username-origin.secdn.net/username-origin/live/mystream

origin_backup_url String Synthetic

Backup Origin URL

Sample value:rtmp://username-originbk.secdn.net/username-origin/live

playback_url String Synthetic

HLS Playback URL

Sample value:rtmp://username-hls.secdn.net/username-live/play/mystream.smil/playlist.m3u8

thumbnail_url String Synthetic

Live Stream Thumbnail URL

Sample value:rtmp://username-thumb.secdn.net/username-live/play/mystream.smil/thumbnail.jpg

playback_rtmp_url String Synthetic

Legacy RTMP Stream URL (Deprecated)

Sample value:rtmp://username-vsn.secdn.net/username-live/play/mystream

option:related String

Include related object in results

Default:none

Sample value:stream_metadata

option:children String

Include child object in results

Default:none

Sample value:players

app String Immutable

Application Name

Sample value:username-origin

type String Immutable

Type of Stream

Enum:live, channel, switchboard, streamfetch

Sample value:switchboard

edge_type String Normal

Playback type

Enum:vsn, vse, dvr

Sample value:dvr

protection String Normal

Playback Protection Type

Enum:none, sevu, hmac, geoip

Sample value:sevu

transcode_template Integer Normal

[Not Implemented] Select a transcode template to apply to this stream

Sample value:720p@30fps_1536kbps

record Boolean Normal

Record This Stream

Sample value:false

ga_key String Normal

Google Analytics

Sample value:UA-123456-1

flags Integer Immutable

Advanced Stream Flags, multiple flags can be combined using a logical AND

Flags:

  • 1 - Auto Generated
  • 2 - StreamFetch RTMP
  • 4 - StreamFetch HLS Origin
  • 8 - Exclude Source Stream from Transcoded Outputs
  • 16 - Exclude Audio Only Transcoded Outputs

Sample value:10

None

Related endpoints

Stream metadata

Encoder metadata for live streams

Stream encoder

Encoder controls for live streams

Apps

Applications that a stream runs on

Child endpoints

Players

Saved players

Playlists

Playlists for a channel

Pushes

Push publishes (restreams)

Streamfetches

Streamfetches for pulling streams

Switchboard items

Items in a switchboard

Examples

Get the Streams object with id mystreamname.

Example URL

https://api.scaleengine.net/dev/v2/streams/mystreamname

Example cURL

curl --user 158:8fc8c48da81e6a2a06a9556379bf798af508dc0792497c678b4c3532ba8b637f https://api.scaleengine.net/dev/v2/streams/mystreamname

Example request body

None

Example response data

{
    "id": "N/A",
    "cdn_id": "8123",
    "app": "username-origin",
    "name": "mystreamname",
    "type": "switchboard",
    "edge_type": "dvr",
    "protection": "sevu",
    "protection_key": "secret#STRING@of&charact3rs",
    "transcode_template": "720p@30fps_1536kbps",
    "hls_chunks": "4",
    "hls_timeout": "300",
    "user": "myuser",
    "pass": "myPassw0rd1",
    "record": "false",
    "record_type": "stream",
    "segment_type": "schedule",
    "segment_value": "* */2 * * *",
    "save_folder": "recordings/mystream",
    "ga_key": "UA-123456-1",
    "flags": "10",
    "origin_url": "rtmp://username-origin.secdn.net/username-origin/live",
    "full_url": "rtmp://username-origin.secdn.net/username-origin/live/mystream",
    "origin_backup_url": "rtmp://username-originbk.secdn.net/username-origin/live",
    "playback_url": "rtmp://username-hls.secdn.net/username-live/play/mystream.smil/playlist.m3u8",
    "thumbnail_url": "rtmp://username-thumb.secdn.net/username-live/play/mystream.smil/thumbnail.jpg",
    "playback_rtmp_url": "rtmp://username-vsn.secdn.net/username-live/play/mystream"
}

Create a new Streams object.

Example URL

https://api.scaleengine.net/dev/v2/streams

Example cURL

curl -X PUT --data-binary @/path/to/request/body --user 158:8fc8c48da81e6a2a06a9556379bf798af508dc0792497c678b4c3532ba8b637f https://api.scaleengine.net/dev/v2/streams

Example request body

{
    "app": "username-origin",
    "name": "mystreamname",
    "type": "switchboard",
    "edge_type": "dvr",
    "protection": "sevu",
    "transcode_template": "720p@30fps_1536kbps",
    "hls_chunks": "4",
    "hls_timeout": "300",
    "user": "myuser",
    "pass": "myPassw0rd1",
    "record": "false",
    "record_type": "stream",
    "segment_type": "schedule",
    "segment_value": "* */2 * * *",
    "save_folder": "recordings/mystream",
    "ga_key": "UA-123456-1",
    "flags": "10"
}

Example response data

{
    "id": "N/A",
    "cdn_id": "8123",
    "app": "username-origin",
    "name": "mystreamname",
    "type": "switchboard",
    "edge_type": "dvr",
    "protection": "sevu",
    "protection_key": "secret#STRING@of&charact3rs",
    "transcode_template": "720p@30fps_1536kbps",
    "hls_chunks": "4",
    "hls_timeout": "300",
    "user": "myuser",
    "pass": "myPassw0rd1",
    "record": "false",
    "record_type": "stream",
    "segment_type": "schedule",
    "segment_value": "* */2 * * *",
    "save_folder": "recordings/mystream",
    "ga_key": "UA-123456-1",
    "flags": "10",
    "origin_url": "rtmp://username-origin.secdn.net/username-origin/live",
    "full_url": "rtmp://username-origin.secdn.net/username-origin/live/mystream",
    "origin_backup_url": "rtmp://username-originbk.secdn.net/username-origin/live",
    "playback_url": "rtmp://username-hls.secdn.net/username-live/play/mystream.smil/playlist.m3u8",
    "thumbnail_url": "rtmp://username-thumb.secdn.net/username-live/play/mystream.smil/thumbnail.jpg",
    "playback_rtmp_url": "rtmp://username-vsn.secdn.net/username-live/play/mystream"
}

Update the Streams object with id mystreamname.

Example URL

https://api.scaleengine.net/dev/v2/streams/mystreamname

Example cURL

curl -X POST --data-binary @/path/to/request/body --user 158:8fc8c48da81e6a2a06a9556379bf798af508dc0792497c678b4c3532ba8b637f https://api.scaleengine.net/dev/v2/streams/mystreamname

Example request body

{
    "edge_type": "dvr",
    "protection": "sevu",
    "transcode_template": "720p@30fps_1536kbps",
    "hls_chunks": "4",
    "hls_timeout": "300",
    "user": "myuser",
    "pass": "myPassw0rd1",
    "record": "false",
    "record_type": "stream",
    "segment_type": "schedule",
    "segment_value": "* */2 * * *",
    "save_folder": "recordings/mystream",
    "ga_key": "UA-123456-1"
}

Example response data

{
    "id": "N/A",
    "cdn_id": "8123",
    "app": "username-origin",
    "name": "mystreamname",
    "type": "switchboard",
    "edge_type": "dvr",
    "protection": "sevu",
    "protection_key": "secret#STRING@of&charact3rs",
    "transcode_template": "720p@30fps_1536kbps",
    "hls_chunks": "4",
    "hls_timeout": "300",
    "user": "myuser",
    "pass": "myPassw0rd1",
    "record": "false",
    "record_type": "stream",
    "segment_type": "schedule",
    "segment_value": "* */2 * * *",
    "save_folder": "recordings/mystream",
    "ga_key": "UA-123456-1",
    "flags": "10",
    "origin_url": "rtmp://username-origin.secdn.net/username-origin/live",
    "full_url": "rtmp://username-origin.secdn.net/username-origin/live/mystream",
    "origin_backup_url": "rtmp://username-originbk.secdn.net/username-origin/live",
    "playback_url": "rtmp://username-hls.secdn.net/username-live/play/mystream.smil/playlist.m3u8",
    "thumbnail_url": "rtmp://username-thumb.secdn.net/username-live/play/mystream.smil/thumbnail.jpg",
    "playback_rtmp_url": "rtmp://username-vsn.secdn.net/username-live/play/mystream"
}

Delete the Streams object with id mystreamname.

Example URL

https://api.scaleengine.net/dev/v2/streams/mystreamname

Example cURL

curl -X DELETE --user 158:8fc8c48da81e6a2a06a9556379bf798af508dc0792497c678b4c3532ba8b637f https://api.scaleengine.net/dev/v2/streams/mystreamname

Example request body


			
			

Example response data

None

Errors

ACCESS_VIOLATION

You do not have access to modify this field

REQUIRED_FIELD

Missing one or more required fields

TYPE_MISMATCH

Data type does not conform to required field type

MAX_LENGTH_EXCEEDED

The value exceeded maximum length allowed

APP_INVALID

The application name must begin with "username-"

STREAM_INVALID

May only contain alpha numerical characters, dashes (-), and underscores (_)

INVALID_ENUM

The value must match one of the predefined values

PROTECTION_MISMATCH

Protection of hmac requires a protection key, while none or sevu will have a protection key of null

ONLY_FOR

This field is only valid when used with another field

INVALID_RANGE

The value must be between the predefined range

USER_INVALID

May only contain alpha numerical characters, dashes (-), and underscores (_)

SEGMENT_MISMATCH

Segment type of duration or size must have a segment value that is an integer, schedule must have a valid crontab expression, and disabled must have a segment value of null

FILEPATH_INVALID

Folder names may contain lower case letters, numbers, dashes (-), and underscores (_), but must start and end with a letter or number.

INVALID_FLAG

The value must match one or more of the predefined flags