Live Slicer API

Use the Live Slicer API to:

Mark ads, replacement content, or content boundaries.
Set metadata.
Retrieve detailed Live Slicer status information.

The Live Slicer API, which is exposed by the Live Slicer via an internal web server, may be called from any programming language that provides a simple HTTP client interface.

API Conventions

Live Slicer API calls are not session-based or password protected. It is assumed that the Live Slicer is running in a secure environment.

The Live Slicer API follows a simplified version of RESTful conventions.

Key points:

All endpoints use either POST or GET HTTP methods.
Most endpoints do not require query string parameters in the request URL.
All endpoints accept a serialized JSON object as the request body. This object may contain request body parameters.
All responses include a response body set to a JSON object. This object includes an error member set to an integer value.
- Success: The error member is set to "0."
- Error(s): The error member is set to a non-zero value. Additionally, most endpoints include an additional msg member that provides an error message.

Authentication

Authentication requires Live Slicer version 15091000 or higher.

By default, the Live Slicer does not require authentication. However, the Live Slicer may be configured to allow authenticated API requests over the port defined by the authenticated_api_port configuration parameter. The data sent over this port is unencrypted.

Authenticate a request by adding the following request body parameters:

Parameter	Description
timestamp	An integer that defines a 10 second authentication window in Unix time.
cnonce	An integer that defines a unique value.
sig	A string that is set to a base-64-encoded SHA-1 hash of the following string: Endpoint:Timestamp:cnonce:Authentication Token Replace the above variables as indicated below. Endpoint: Replace this variable with the endpoint being requested (e.g., content_start). Timestamp: Replace this variable with the value defined in the timestamp query string parameter. cnonce: Replace this variable with the value defined in the cnonce query string parameter. Authentication Token: Replace this variable with the hexadecimal representation of the SHA-1 hash of the API key through which the desired Live Slicer authenticated. Where can I find my API key(s)? Navigate to the Integration Keys page by clicking the Settings tab and then clicking Integration Keys from the side navigation tab. Your API key(s) are listed under the API Keys section. Example: The following example demonstrates the proper format for authentication tokens: API Key: XH7HtD8tR3993IxfbcqX0uhKnc-mYksmPxqM2z1a SHA-1 Hash (Hexadecimal): 2adf9dd93ca0261ccd04dd879258ef35fa3ff17d

Parameter

Description

timestamp

An integer that defines a 10 second authentication window in Unix time.

cnonce

An integer that defines a unique value.

sig

A string that is set to a base-64-encoded SHA-1 hash of the following string:

Endpoint:Timestamp:cnonce:Authentication Token

Replace the above variables as indicated below.

Endpoint: Replace this variable with the endpoint being requested (e.g., content_start).
Timestamp: Replace this variable with the value defined in the timestamp query string parameter.
cnonce: Replace this variable with the value defined in the cnonce query string parameter.
Authentication Token: Replace this variable with the hexadecimal representation of the SHA-1 hash of the API key through which the desired Live Slicer authenticated.
Where can I find my API key(s)?
1. Navigate to the Integration Keys page by clicking the Settings tab and then clicking Integration Keys from the side navigation tab.
2. Your API key(s) are listed under the API Keys section.
Example:

The following example demonstrates the proper format for authentication tokens:
- API Key: XH7HtD8tR3993IxfbcqX0uhKnc-mYksmPxqM2z1a
- SHA-1 Hash (Hexadecimal): 2adf9dd93ca0261ccd04dd879258ef35fa3ff17d

Example:

timestamp = 1438101883

cnonce = 123

sig_input = '/content_start:1438101883:123:2adf9dd93ca0261ccd04dd879258ef35fa3ff17d'

sig = Base64(SHA1(sig_input)) = '49bQGXKTRYPQ5b22m89zKe1zcKk='

Sample request (HTTP):

POST /content_start HTTP/1.1

Content-Type: application/json

Host: localhost:65009

Content-Length: 108

{
	"timestamp": 1438101883,
	"cnonce": 123,
	"sig": "49bQGXKTRYPQ5b22m89zKe1zcKk=",
	"start_timecode": "11:22:33;04"
}

Sample request (Python):

import urllib2, hashlib, time, json, base64

secret = hashlib.sha1('XH7HtD8tR3993IxfbcqX0uhKnc-mYksmPxqM2z1a').hexdigest()
timestamp = int(time.time())
endpoint = '/content_start'
cnonce = 123
sig_input = endpoint+':'+str(timestamp)+':'+str(cnonce)+':'+secret
sig = base64.b64encode(hashlib.sha1(sig_input).digest())
body = json.dumps({"timestamp": timestamp, "cnonce": cnonce, "sig": sig })
request = urllib2.urlopen('http://localhost:65009/' + endpoint, body)
response = json.loads(request.read())

assert response['error'] == 0

Port Configuration

By default, the Live Slicer listens for API requests on port 65009. Use the api_port configuration setting to configure the Live Slicer to listen on a different port.

Scheduling Actions

Schedule when the action defined within an API request will take effect by passing one of the following parameters:

start_timecode: Identifies the video frame when an operation will take effect.
offset_time_ms: Identifies a time relative to now (local system time), in milliseconds, when an operation will take effect.
offset_from_now_ms: Identifies a time relative to the start of the current asset, in milliseconds, when an operation will take effect.

Most Live Slicer API endpoints accept the above parameters.

Timecode

The start_timecode parameter defines a timecode that identifies a specific video frame at which the action will take place. For example, you may use this parameter to determine the video frame where an ad or content boundary should occur.

Key information:

UDP and RTMP

You must enable the useSystemClockAsTimecode setting within the Live Slicer's configuration file to use the start_timecode parameter with UDP (including RTP) and RTMP signal sources.
A Live Slicer accepts timecodes defined using either drop frame or non-drop frame format.

Drop frame format:

hh:mm:ss;vf

Non-drop frame format:

hh:mm:ss:vf

Drop frame example:

The following value identifies the second frame at 15 minutes and two seconds after midnight (Live Slicer's local time):

00:15:02;01
Where do I get timecodes for my breaks?

Timecodes are typically provided via a playout automation system (e.g., Snell or Harris).

Resolving Timecodes

By default, the Live Slicer resolves an API request's timecode from a short buffer of frames (e.g., 5 seconds) known as the capture delay buffer.

If this buffer contains a frame with a timecode, then the Live Slicer sets the boundary to the frame's presentation timestamp (PTS).
If a timecode is not found or if the start_timecode parameter is omitted, then the Live Slicer will set the boundary at the oldest frame in the capture delay buffer.

Configure the duration of the capture delay buffer through the capture_delay setting.

Future Timecodes

Configure a Live Slicer to resolve timecodes up to 12 hours in the future by enabling the future_timecodes setting:

future_timecodes:on

Upon enabling this configuration parameter, the Live Slicer will resolve timecodes as described below.

Condition	Behavior
Buffered Frame The start_timecode parameter identifies a video frame contained by the capture delay buffer.	The Live Slicer will apply the action requested via the API when it reaches the video frame identified by the start_timecode parameter.
Future Timecode (< 12 hours) The start_timecode parameter identifies a video frame that takes place 12 hours or less in the future.	The endpoint will return an id response body parameter. The Live Slicer will apply the action requested via the API when it reaches the video frame identified by the start_timecode parameter.
Future Timecode (> 12 hours) or Missing Frame The start_timecode parameter identifies a video frame that either: Takes place more than 12 hours in the future. Is not found in the capture delay buffer.	The requested operation will take effect immediately.
Past Timecode The start_timecode parameter identifies a video frame that takes place in the past.	Your signal source determines how the Live Slicer will behave: SDI: The requested operation will take effect immediately. UDP (including RTP) and RMTP: The requested operation will take effect 24 hours from the specified timecode. Example: If the current time is 11:01 AM, then passing the following timecode will cause the Live Slicer to apply the requested action at 11:00 AM tomorrow: 11:00:00;01

Scheduled Break Expiration

A time limit may be placed on breaks scheduled in the future through the future_break_expiration_minutes setting:

future_break_expiration_minutes: Minutes

This setting requires the Live Slicer to expire API requests for scheduled breaks that have been retained the specified number of minutes. The drop_expired_breaks setting determines how a Live Slicer will handle expired API requests.

drop_expired_breaks	Description
On	Expired API requests will be ignored.
Off or Missing	Expired API requests are processed once they have been retained for the length of time defined within the future_break_expiration_minutes setting. This occurs regardless of whether the specified timecode has elapsed.

View or delete breaks scheduled for the future through the remove_break and list_breaks endpoints.

Relative Time

An alternative to the start_timecode parameter is to define a relative time through one of the following parameters:

Parameter	Value
offset_from_now_ms	Identifies a time relative to now (local system time), in milliseconds, when an operation will take effect.
offset_time_ms	Identifies a time relative to the start of the current asset, in milliseconds, when an operation will take effect.

The order of precedence between these parameters is:

offset_time_ms > offset_from_now_ms > start_timecode

For example, if all three parameters are included in the request, then the offset_time_ms parameter will take precedence over the other two parameters.

An operation takes effect immediately when none of the above parameters are included in the request.

Examples

Sample requests are provided below.

Sample request (HTTP):

POST /blackout HTTP/1.1

Content-Type: application/json

Host: localhost:65009

Content-Length: 33

{
	"start_timecode": "11:22:33;04"
}

Sample response (HTTP):

HTTP/1.1 200 OK

Content-Type: application/json

Content-Length: 12

{
	"error": 0
}

Sample request (Python):

import urllib2, json

body = json.dumps({"start_timecode":"11:22:33;04"})request = urllib2.urlopen('http://localhost:65009/blackout', body)
response = json.loads(request.read())

assert response['error'] == 0

Sample request (curl):

curl --data '{"start_timecode":"11:22:33;04"}' http://localhost:65009/blackout

Endpoints

The Live Slicer API supports the following endpoints:

Endpoint	Description
add_cc608	Inject EIA/CEA-608/708 captions into the stream.
add_imagebug	Schedules an image overlay.
add_meta	Adds metadata to the asset currently being sliced.
blackout	Ends the current asset and stops capturing until further notice. Use the content_start endpoint to resume capture.
boundary	Creates and defines the starting/ending point of a boundary.
content_start	Performs either of the following tasks: Ends the current asset and starts a new one. Ends a blackout event and returns to the live event.
ignore_schedule	Enables or disables the ignore state for slicing schedules.
list_breaks	Returns a list of scheduled breaks.
list_imagebug	Lists all scheduled image overlays.
pod_end	Ends an ad pod and resumes capture for the current asset.
pod_start	Marks an ad pod for replacement when the duration is unknown.
remove_break	Removes a break from the schedule.
remove_imagebug	Removes an image overlay
replace_content	Replaces a section of the live stream with pre-encoded content.
replace_pod	Marks an ad pod for replacement with a specific duration.
restart_later	Instructs the Live Slicer to restart at the next ad break, blackout, or content_start.
server_time	Returns server time for both the Live Slicer and the CMS.
state	Returns the Live Slicer's operating state.
status	Returns information describing the Live Slicer's status.
timedmeta	Inserts a timed metadata key/value pair into the stream for the asset currently being sliced.

boundary

Marks the start and the end of a boundary as described below.

Start: Mark the start of a boundary by calling the boundary endpoint with the type parameter.
End: Mark the end of a boundary by either:
- Defining the duration parameter when the boundary is created.
- Calling the boundary endpoint without parameters.

Request body parameters are described below.

Request Parameter	Type	Description
expected_duration	Float	Specifies the expected duration, in seconds, of the segment. An ending boundary will automatically be triggered after the specified time.
type	String	Creates a boundary whose type is determined by the value assigned to this parameter. Learn more.
meta	Dictionary	Requires the type parameter. Contains key-value pairs that defines the set of metadata that will be supplied at the start of a new boundary. Use the Asset Info API to access an asset's metadata. Example: {"My Metadata Field": "Value 1"}
offset_from_now_ms	Integer	Requires Live Slicer version 17061500 or higher. Identifies a time relative to now (local system time), in milliseconds, when an operation will take effect.
offset_time_ms	Integer	Identifies a time relative to the start of the current asset, in milliseconds, when an operation will take effect.
start_timecode	String	Identifies a video frame at which this operation will take effect.

Create a Boundary Example:

POST /boundary HTTP/1.1

{
	"type": "c3"
}

End a Boundary Example:

POST /boundary HTTP/1.1

{}

Alternative Workflow: Create a Boundary With a Duration Example:

POST /boundary HTTP/1.1

{
	"type": "c3",
	"expected_duration": 30.5
}

content_start

Marks the beginning of a new asset.

Request body parameters are described below.

Request Parameter	Type	Description
external_id	String	Assigns the specified external ID to the asset.
meta	Dictionary	Assigns the specified metadata to the asset. Use the Asset Info API to access an asset's metadata.
offset_from_now_ms	Integer	Requires Live Slicer version 17061500 or higher. Identifies a time relative to now (local system time), in milliseconds, when an operation will take effect.
offset_time_ms	Integer	Identifies a time relative to the start of the current asset, in milliseconds, when an operation will take effect.
start_timecode	String	Identifies a video frame at which this operation will take effect.
title	String	Assigns the specified title to the asset.

Sample request:

POST /content_start HTTP/1.1

{
	"start_timecode": "00:15:21;09",
	"title": "Some Title",
	"external_id": "asdf1234"
}

replace_pod

Marks an ad for replacement.

Request body parameters are described below.

Request Parameter	Type	Description
duration Required	Float	Defines the length of the ad break in seconds.
meta	Dictionary	Assigns the specified metadata to the asset. Use the Asset Info API to access an asset's metadata.
offset_from_now_ms	Integer	Requires Live Slicer version 17061500 or higher. Identifies a time relative to now (local system time), in milliseconds, when an operation will take effect.
offset_time_ms	Integer	Identifies a time relative to the start of the current asset, in milliseconds, when an operation will take effect.
start_timecode	String	Identifies the video frame at which this operation will take effect.

Sample request:

POST /replace_pod HTTP/1.1

{
	"start_timecode": "00:15:21;09",
	"duration": 213.32
}

pod_start

Marks an ad for replacement when the duration of the ad pod is unknown. The Live Slicer will remain in blackout state until further notice.

Request body parameters are described below.

Request Parameter	Type	Description
meta	Dictionary	Assigns the specified metadata to the asset. Use the Asset Info API to access an asset's metadata.
offset_from_now_ms	Integer	Requires Live Slicer version 17061500 or higher. Identifies a time relative to now (local system time), in milliseconds, when an operation will take effect.
offset_time_ms	Integer	Identifies a time relative to the start of the current asset, in milliseconds, when an operation will take effect.
start_timecode	String	Identifies the video frame at which this operation will take effect.

Sample request:

POST /pod_start HTTP/1.1

{
	"start_timecode": "00:15:21;09"
}

pod_end

Ends an ad pod and resumes capture for the current asset.

Request body parameters are described below.

Request Parameter	Type	Description
offset_from_now_ms	Integer	Requires Live Slicer version 17061500 or higher. Identifies a time relative to now (local system time), in milliseconds, when an operation will take effect.
offset_time_ms	Integer	Identifies a time relative to the start of the current asset, in milliseconds, when an operation will take effect.
start_timecode	String	Identifies the video frame at which this operation will take effect.

Request Parameter

Type

Description

offset_from_now_ms

Integer

Requires Live Slicer version 17061500 or higher.

Identifies a time relative to now (local system time), in milliseconds, when an operation will take effect.

offset_time_ms

Integer

Identifies a time relative to the start of the current asset, in milliseconds, when an operation will take effect.

start_timecode

String

Identifies the video frame at which this operation will take effect.

Sample request:

POST /pod_end HTTP/1.1

{
	"start_timecode": "00:15:21;09"
}

replace_content

Blacks out a section of the live feed and replaces it with pre-encoded content.

Request body parameters are described below.

Request Parameter	Type	Description
duration Required	Float	Defines the duration, in seconds, of the segment that will be removed from the live feed.
replacements Required	List	Defines a list of replacement content as described below.
offset_from_now_ms	Integer	Requires Live Slicer version 17061500 or higher. Identifies a time relative to now (local system time), in milliseconds, when an operation will take effect.
offset_time_ms	Integer	Identifies a time relative to the start of the current asset, in milliseconds, when an operation will take effect.
start_timecode	String	Identifies the video frame at which this operation will take effect.

The replacements parameter is a list of dictionaries. Each dictionary may contain the following parameters:

Request Parameter	Type	Description
duration	Float	Defines the duration, in seconds, of the replacement content that may be inserted into the live feed. By default, the full duration is used.
external_id Required	String	Identifies replacement content by its external ID.

Request Parameter

Type

Description

duration

Float

Defines the duration, in seconds, of the replacement content that may be inserted into the live feed. By default, the full duration is used.

external_id

Required

String

Identifies replacement content by its external ID.

Sample request:

POST /replace_content HTTP/1.1

{
	"start_timecode": "00:15:21;09",
	"duration": 213.32,
	"replacements": [{
			"external_id": "asdf1234",
			"duration": 104.2
		}, {
			"external_id": "asdf4321"
		}
	]
}

blackout

Blacks out the live feed until further notice. Use the content_start endpoint to stop a blackout window.

A request body parameter is described below.

Request Parameter	Type	Description
offset_from_now_ms	Integer	Requires Live Slicer version 17061500 or higher. Identifies a time relative to now (local system time), in milliseconds, when an operation will take effect.
offset_time_ms	Integer	Identifies a time relative to the start of the current asset, in milliseconds, when an operation will take effect.
start_timecode	String	Identifies the video frame at which this operation will take effect.

Request Parameter

Type

Description

offset_from_now_ms

Integer

Requires Live Slicer version 17061500 or higher.

Identifies a time relative to now (local system time), in milliseconds, when an operation will take effect.

offset_time_ms

Integer

Identifies a time relative to the start of the current asset, in milliseconds, when an operation will take effect.

start_timecode

String

Identifies the video frame at which this operation will take effect.

Sample request:

POST /blackout HTTP/1.1

{
	"start_timecode": "00:15:21;09"
}

add_meta

Adds metadata to the asset being sliced.

A request body parameter is described below.

Request Parameter

Type

Description

ignore_schedule

Toggles the ignore state for the slicing schedule. Enabling the ignore state causes the Live Slicer to discard commands given by the slicing schedule.

A request body parameter is described below.

Request Parameter	Type	Description
ignore Required	Boolean	Valid values are: true: The slicing schedule is ignored until further notice. false: The Live Slicer will resume honoring the slicing schedule.

Request Parameter

Type

Description

ignore

Required

Boolean

Valid values are:

true: The slicing schedule is ignored until further notice.
false: The Live Slicer will resume honoring the slicing schedule.

Sample request:

POST /ignore_schedule HTTP/1.1

{
	"ignore": true
}

status

Returns status information about a Live Slicer.

The response for this endpoint includes a status dictionary that contains the following key-value pairs:

Response Parameter	Type	Description
brokerid	String	Identifies the broker assigned to the Live Slicer by its system-defined ID. Sample value: 5bbf3fcf8ac8453caae8bc9a6015cb1e
brokerzone	String	Identifies the zone corresponding to the broker assigned to the Live Slicer. Sample value: ausw3
capture_delay	Integer	Indicates the length of the capture delay as measured in seconds.
cc_last_seen	Dictionary	Indicates the time at which the Live Slicer received the most recent caption for each channel. The Live Slicer updates these timestamps every ten seconds. Syntax: "Channel Number":Unix Time This parameter will report a null value until a caption is detected.
connect_info	Dictionary	Indicates connection information for the Live Slicer. This dictionary contains the following parameters: ips: This dictionary contains key-value pairs that identifies an interface and its IP address. Sample value: "en5" : "192.168.1.238" port: A string that identifies the port through which the Live Slicer established a connection. Sample value: 65009 public_ip: A string that indicates the Live Slicer's public IP address. Sample value: 192.16.26.2 uplynk_dns: A string that identifies the CNAME to which the Live Slicer established a connection. Sample value: f8ac3d43fee64e51bf39efe8a9fcd896.slicer.uplynk.net
current_profile	String	Identifies the current encoding profile by its system-defined ID.
delivered	Integer	Indicates the number of slices that have been uploaded to cloud storage since the Live Slicer was started.
dropped	Integer	Indicates the number of frames that have been dropped for the current beam. Prior to Live Slicer version 19022000, this metric reported the number of dropped frames since the Live Slicer was started. Dropped frames are indicative that the Live Slicer is experiencing severe egress bandwidth problems or insufficient system resources (CPU/memory).
dropped_frames_usec	Integer	Measures the duration, in microseconds, of a gap in the live stream due to dropped frames. This measurement is reset on content_start.
dropped_since_last	Integer	Indicates the number of dropped frames in the CMS asset being encoded.
duration	Integer	Indicates the duration, in seconds, of the live stream.
lastBeamID	String	Identifies the last beam by its system-defined ID.
luma	Integer	Indicates the average luminosity percentage for the last few seconds of video. This percentage will only be returned when the Live Slicer has reported a luma value.
meta	Dictionary	Contains key-value pairs that describe the metadata fields that have been applied to the live stream. This dictionary does not include metadata manually defined via the CMS. It may take a few seconds before recently added metadata is reported within this dictionary. Syntax: "FieldName" : "Value"
method	String	Identifies the method through which the Live Slicer communicates with the encoder. Sample value: broker
rtp_stats	Dictionary	Contains statistics for each RTP feed being ingested by the Live Slicer. Learn more.
signal	String	Indicates the input signal type. Blackmagic Capture Devices: Indicates the signal format reported by the card. Sample value: HD 1080i 60fps UDP Transport Streams Reports the following information: TS multicast \| unicast Source IP Address:Port Resolution Width x Height No Signal: Reports the following value when the signal is lost: No signal
slicer_id	String	Indicates the Live Slicer's ID as defined in the Live Slicer configuration file.
slices	List	Identifies the slices being encoded to the current CMS asset.
software	String	Identifies the Live Slicer's OS version (e.g., slicer_linux_64).
source_queue_depth	Integer	Requires Live Slicer version 15080700 or higher. Indicates the number of packets waiting to be read by the Live Slicer.
source_queue_max_depth	Integer	Requires Live Slicer version 15080700 or higher. Indicates the highest number of packets queued to be read by the Live Slicer since it started running.
state	Integer	Valid values are: 0: Capture 1: Ad break 2: Replacing content 3: Blackout
sys_info	Dictionary	Contains system information (i.e., CPU, memory usage, network interface bandwidth, Nvidia graphics card, and OS) about the hardware on which the Live Slicer is running.
version	String	Indicates the Live Slicer's version number.
vol	Integer	Indicates the average loudness percentage for the last few seconds of audio. This percentage will only be returned when the Live Slicer has reported a volume value.
waiting	Integer	Indicates the number of slices waiting to be uploaded.

rtp_stats Dictionary

The rtp_stats dictionary contains the following key-value pairs:

Response Parameter	Type	Description
90Khz_stream_time	Integer	Indicates the current stream time in Unix time.
downstream_timeout	Boolean	Indicates whether the Live Slicer has stopped reading the payload.
fec	Dictionary	Contains information on how forward error correction (FEC) packets were generated. This dictionary contains the following key-value pairs: D: A string that indicates that FEC packets were generated based on the depth of the FEC matrix. L: A string that indicates that FEC packets were generated based on the spacing between non-consecutive packets. Key information: Each key-value pair defines a FEC period for packet sampling. The syntax for the value is: XORRepresents "exclusive or." XOR identifies how FEC packets are computed from either the column or row of the FEC matrix.,cnt:n,step:n Sample value: XOR,cnt:8,step:1 The value defined for cnt determines FEC strength and the bandwidth overhead required for FEC. Smaller values indicate a shorter FEC period which translates to stronger FEC and more bandwidth overhead. Configure your encoder to adjust the size of the FEC period sent to the Live Slicer.
realtime	Dictionary	Contains real-time statistics for the last three seconds. This dictionary contains the following key-value pairs: avg_bw: A string that indicates the average bandwidth uploaded by the Live Slicer. Sample value: 13.2Mb/sec packet_drop_rate: A string that indicates the percentage of packets dropped due to network congestion. Percentage is reported as a decimal value from 0 to 1. packet_loss_rate: A string that indicates the percentage of packets that were lost. Percentage is reported as a decimal value from 0 to 1. packet_recovery_rate: A string that indicates the percentage of packets recovered due to FEC. Percentage is reported as a decimal value from 0 to 1.
total	Dictionary	Contains packet statistics. This dictionary contains the following key-value pairs: gaps_detected: An integer that indicates the number of gaps between packets detected. packets_dropped: An integer that indicates the number of dropped packets that were detected. A high number of dropped packets is indicative of high CPU utilization on the computer hosting the Live Slicer. packets_lost: An integer that indicates the number of lost packets that were detected. A high number of lost packets is indicative of network issues between the Live Slicer and the origin server for RTP playout. packets_received: An integer that indicates the number of packets that were received. packets_recovered: An integer that indicates the number of dropped/lost packets that were recovered. A low number of recovered packets is indicative of either network issues, high latency between the audio/video feed and the FEC stream, or that the FEC is not sufficiently dense. timeouts_detected: An integer that indicates the number of timeouts that were detected.
redundancy	Dictionary	Contains information about each RTP feed. This dictionary contains the following key-value pairs: feeds: A dictionary that identifies each RTP feed. This dictionary contains the following key-value pairs: desc: A string that indicates either the main or redundant RTP feed's IP address and port. status: A string that indicates the status of a RTP feed. Valid values are: active: Indicates that the RTP feeds are synchronized. pending: Indicates that a single payload packet has not been received from this RTP feed. incompatible: Indicates that this RTP feed is bit-stream incompatible with the other RTP feed. timedout: Indicates that payload data is no longer being received from this RTP feed. outofsync: Indicates that the RTP feeds are not synchronized due to latency. Check your rtp_readahead_dur and the rtp_backlog_dur parameters and increase as needed. skew_sec: A string that indicates the duration of the latency between the RTP feeds. Treat a value higher than 1 second or the rtp_readahead_dur parameter as an error.

Sample request:

GET /status HTTP/1.1

state

Indicates the Live Slicer's current operating state.

Response body parameters are described below.

Response Parameter	Type	Description
state	Integer	Valid values are: 0: Capturing content 1: Ad break 2: Replacing content 3: Blackout
state_name	String	Valid values are: Capture Ad Replace Blackout

Response Parameter

Type

Description

state

Integer

Valid values are:

0: Capturing content
1: Ad break
2: Replacing content
3: Blackout

state_name

String

Valid values are:

Capture
Ad
Replace
Blackout

Sample request:

GET /state HTTP/1.1

server_time

Indicates server time.

Response body parameters are described below.

Response Parameter	Type	Description
corrected	Integer	Indicates the current Unix time reported by the CMS.
time	Integer	Indicates the current Unix time on the Live Slicer's host machine.

Sample request:

GET /server_time HTTP/1.1

timedmeta

Inserts a timed metadata key/value pair into the stream for the asset currently being sliced.

Request body parameters are described below.

Request Parameter	Type	Description
key Required	String	Sets the key value of the key/value pair that will be inserted into the stream.
offset_from_now_ms	Integer	Requires Live Slicer version 17061500 or higher. Identifies a time relative to now (local system time), in milliseconds, when an operation will take effect.
offset_time_ms	Integer	Identifies a time relative to the start of the current asset, in milliseconds, when an operation will take effect.
start_timecode	String	Identifies the video frame at which this operation will take effect.
value Required	String	Set the value element of the key/value pair that will be inserted into the stream.

Sample request:

POST /timedmeta HTTP/1.1

{
	"start_timecode": "00:15:21;09",
	"key": "myKey",
	"value": "myValue"
}

The timedmeta endpoint may also be used to insert PRIV metadata with the following parameters:

Request Parameter	Type	Description
owner Required	String	Identifies the organization that owns a video frame by either of the following: A URL containing an email address. A link to a location where an email address can be found. Please refer to section 4.27 of the ID3v2.4.0 specification for more information.
offset_from_now_ms	Integer	Requires Live Slicer version 17061500 or higher. Identifies a time relative to now (local system time), in milliseconds, when an operation will take effect.
offset_time_ms	Integer	Identifies a time relative to the start of the current asset, in milliseconds, when an operation will take effect.
start_timecode	String	Identifies the video frame at which this operation will take effect.
value Required	String	Defines the base64-encoded data that will be contained by the PRIV frame.

Sample request:

POST /timedmeta HTTP/1.1

{
	"start_timecode": "00:15:21;09",
	"type": "PRIV",
	"owner": "http://example.com",
	"value": "bXlWYWx1ZQ=="
}

add_cc608

Inserts a base64-encoded EIA/CEA-608/708 payload into the stream.

Request body parameters are described below.

Request Parameter	Type	Description
data Required	String	Base64-encoded EIA/CEA-608/708 cc_data_pkt data.
offset_from_now_ms	Integer	Requires Live Slicer version 17061500 or higher. Identifies a time relative to now (local system time), in milliseconds, when an operation will take effect.
offset_time_ms	Integer	Identifies a time relative to the start of the current asset, in milliseconds, when an operation will take effect.

Request Parameter

Type

Description

data

Required

String

Base64-encoded EIA/CEA-608/708 cc_data_pkt data.

offset_from_now_ms

Integer

Requires Live Slicer version 17061500 or higher.

Identifies a time relative to now (local system time), in milliseconds, when an operation will take effect.

offset_time_ms

Integer

Identifies a time relative to the start of the current asset, in milliseconds, when an operation will take effect.

Sample request:

POST /add_cc608 HTTP/1.1

{
	"data": "/BQg/BRQ/EFu/G90/Ghl/HIg/FRl/HN0/BQg/BQs/BQv",
	"offset_time_ms": 10000
}

restart_later

Instructs the Live Slicer to restart at the next ad break, blackout, or content_start. Using this endpoint in tandem with a service manager (e.g., Upstart) allows Live Slicer restarts to be scheduled to match discontinuities.

Request body parameters are described below.

Request Parameter	Type	Description
offset_from_now_ms	Integer	Requires Live Slicer version 17061500 or higher. Identifies a time relative to now (local system time), in milliseconds, when an operation will take effect.
offset_time_ms	Integer	Identifies a time relative to the start of the current asset, in milliseconds, when an operation will take effect.
start_timecode	String	Identifies the video frame at which this operation will take effect.

Request Parameter

Type

Description

offset_from_now_ms

Integer

Requires Live Slicer version 17061500 or higher.

Identifies a time relative to now (local system time), in milliseconds, when an operation will take effect.

offset_time_ms

Integer

Identifies a time relative to the start of the current asset, in milliseconds, when an operation will take effect.

start_timecode

String

Identifies the video frame at which this operation will take effect.

Sample request:

POST /restart_later HTTP/1.1

{
	"start_timecode": "00:15:21;09"
}

remove_break

Removes a scheduled break.

This endpoint is only applicable for breaks scheduled in the future when the future_timecodes parameter has been enabled.

A request body parameter is described below.

Request Parameter	Type	Description
id Required	Integer	Identifies a scheduled break by its ID. Use the list_breaks endpoint to retrieve a list of scheduled breaks and their IDs.

Request Parameter

Type

Description

Required

Integer

Identifies a scheduled break by its ID.

Use the list_breaks endpoint to retrieve a list of scheduled breaks and their IDs.

Sample request:

POST /remove_break HTTP/1.1

{
	"id": 0
}

Sample response:

{
	"error": 0
}

list_breaks

Returns a list of scheduled breaks.

This endpoint is only applicable for breaks scheduled in the future when the future_timecodes parameter has been enabled.

Sample request:

POST /list_breaks HTTP/1.1

Sample response:

{
	"breaks": [{
			"age": 19,
			"id": 2,
			"timecode": "01:01:45;00",
			"type": 5,
			"type_str": "content start"
		}, {
			"age": 27,
			"id": 1,
			"timecode": "01:01:50;00",
			"type": 5,
			"type_str": "content start"
		}
	],
	"error": 0
}

quality

Indicates the bitrate of the video that the Live Slicer is sending to the encoder.

Response body parameters are listed below.

Response Parameter	Type	Description
current_video_kbps	Integer	Indicates the current video's bit rate (Kbps).
effective_total_kbps	Integer	Indicates the effective total bit rate (Kbps).
original_video_kbps	Integer	Indicates the original video's bit rate (Kbps).

Sample request:

GET /quality HTTP/1.1

add_imagebug

Requires Live Slicer version 19022000 or higher

Overlays an image on the live stream at the specified start time for the given duration.

Request body parameters are described below.

Request Parameter	Type	Description
data Required	String	Defines the image that will be overlaid on the video. Key information: Set this parameter to the base-64-encoded value for a RGBA PNG image whose file size is 32 Kb or smaller. The image overlay effect respects the transparency defined in the PNG image. In order to match positioning information, it is strongly recommended that the specified PNG image match the resolution of the source video. If the resolution does not match, the image will be scaled to fit within the video's width or height. It will then be centered across the other axis. If multiple images overlap, then Z-order is determined by the order in which they are added to the stream.
duration	Integer	Defines the duration, in milliseconds, for which the image passed by the data parameter will be overlaid on the video. Omit this parameter or set it to 0 to overlay the image defined by the data parameter until it is removed. An image overlay will persist until one of the following conditions is true: The image overlay is removed via the remove_imagebug endpoint. The image overlay's duration has expired.
offset_from_now_ms	Integer	Requires Live Slicer version 17061500 or higher. Identifies a time relative to now (local system time), in milliseconds, when an operation will take effect.
offset_time_ms	Integer	Identifies a time relative to the start of the current asset, in milliseconds, when an operation will take effect.
start_timecode	String	Identifies the video frame at which this operation will take effect.

A response body parameter is listed below.

Response Parameter	Type	Description
id	String	Identifies an image overlay by its ID. Use the list_imagebug endpoint to retrieve a list of scheduled and currently active image overlays and their IDs.

Response Parameter

Type

Description

String

Identifies an image overlay by its ID.

Use the list_imagebug endpoint to retrieve a list of scheduled and currently active image overlays and their IDs.

Sample request:

POST /add_imagebug HTTP/1.1

{
	"data": "iVBORw0KGg ... U5Erkggg==",
	"duration": 30000
}

Sample response:

{
	"error": 0,
	"id": "40312374433b78666162691020586f12"
}

list_imagebug

Requires Live Slicer version 19022000 or higher

Provides a list of all scheduled and currently active image overlays.

Response body parameters are listed below.

Response Parameter	Type	Description
bugs	List	A list of dictionaries that describes each scheduled and currently active image overlay.
duration	Integer	Indicates the duration, in milliseconds, for which the image overlay will be applied to the live stream. A value of 0 indicates that the image overlay will persist until it is removed.
start	Integer	Indicates the scheduled start time for the image overlay. For the purpose of this parameter, start time is defined as the number of milliseconds since the start of the live stream. If the image overlay was scheduled to appear immediately, then this parameter will report the live stream's time at the moment that the add_imagebug endpoint was requested. Example: If the image overlay is scheduled for 10 seconds from the start of the live stream, then this parameter would report 10000.
id	String	Identifies an image overlay by its ID.

Sample request:

GET /list_imagebug HTTP/1.1

Sample response:

{
	"bugs": [{
			"duration": 30000,
			"start": 39516608,
			"id": "40312374433b78666162691020586f12"
		}
	],
	"error": 0
}

remove_imagebug

Requires Live Slicer version 19022000 or higher

Immediately removes an image overlay. Set the id query string parameter to the ID of the image overlay that will be removed.

Sample request:

POST /remove_imagebug?id=40312374433b78666162691020586f12 HTTP/1.1