Customer Sign In

upLynk

Live Slicer API

Overview

Use the Live Slicer API to:

  • Mark ads, replacement content, or content boundaries.
  • Set metadata.
  • Retrieve the Live Slicer's 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

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

Key points:

  • All methods use either POST or GET HTTP methods.
  • Most methods do not require query string parameters in the request URL.
  • All methods 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 methods include an additional msg member that provides an error message.

Authentication

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
timestampAn integer that defines a 10 second authentication window in Unix time.
cnonceAn integer that defines a unique value.
sigA string that is set to a base-64-encoded SHA-1 hash of the following string:
<Method>:<Timestamp>:<cnonce>:<Authentication Token>

Replace the above variables as indicated below.

  • Method: Replace this variable with the API method 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 your secret API key. View this key from the Playback Tokens side navigation tab of the Advanced (Gears) tab.

    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='
            
1
2
3
4
5
6
7
POST /content_start HTTP/1.1
Content-Type: application/json
Host: localhost:6300
Content-Length: 108

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

Python Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import urllib2, hashlib, time, json, base64

secret = hashlib.sha1('XH7HtD8tR3993IxfbcqX0uhKnc-mYksmPxqM2z1a').hexdigest()
timestamp = int(time.time())
method = '/content_start'
cnonce = 123
sig_input = method+':'+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:65010/' + method, 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 parameter to configure the Live Slicer to listen on a different port.

Timecode

Most Live Slicer API methods accept the start_timecode parameter. This parameter identifies the video frame where an ad or content boundary should occur. The format for this parameter is defined below.

Format: hh:mm:ss;vf

Example: 00:15:02;01 identifies the second frame at 15 minutes and two seconds after midnight (Live Slicer's local time).

By default, the Live Slicer resolves the timecode defined in an API request from a short buffer of frames (e.g., 5 seconds) known as the capture delay buffer. The duration of this buffer may be configured via the capture_delay parameter. If the requested frame 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.

Alternatively, a Live Slicer may be configured to resolve timecodes up to 12 hours in the future. This requires that the following configuration parameter be added to the Live Slicer's configuration file (i.e., uplynk.conf):

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 ad or content boundary will be set at the specified video frame.
Future Timecode (< 12 hours)
The start_timecode parameter identifies a video frame that takes place 12 hours or less in the future.
The method will return an id response body parameter and the API request will be retained until the appropriate time. At which point, the ad or content boundary will be set at the specified video frame.
Future Timecode (> 12 hours), Past Timecode, or Missing Frame
The start_timecode parameter identifies a video frame that either:
  • Takes place more than 12 hours in the future.
  • Takes place in the past.
  • Is not found in the capture delay buffer.
The requested API method will be processed immediately.

A time limit may be placed on API requests that identify a video frame at a future date/time through the following configuration parameter:

future_break_expiration_minutes:<minutes>

Upon enabling this configuration parameter, the Live Slicer will expire API requests that have been retained the specified number of minutes. The manner in which expired requests are handled varies according to the status of the drop_expired_breaks:on configuration parameter.

drop_expired_breaks Status Behavior
On Expired requests will be ignored.
Off or Missing Expired requests will be processed immediately, regardless of whether the specified timecode has elapsed.

Manage API requests that have been retained for future execution with the remove_break and list_breaks methods.

Specifying relative time instead of start_timecode

Every Live Slicer API method that accepts the start_timecode parameter may be given offset_time_ms or offset_from_now_ms instead. Either of these parameters will supersede start_timecode.

Parameter Value
offset_time_ms Number of milliseconds from the start of the current asset.
offset_from_now_ms Number of milliseconds from now (walltime).

This capability requires Live Slicer version 17061500 or newer.

Examples

Sample request (HTTP):

1
2
3
4
5
6
POST /blackout HTTP/1.1
Content-Type: application/json
Host: localhost:65009
Content-Length: 33

{"start_timecode":"11:22:33:44"}

Sample response (HTTP):

1
2
3
4
5
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 12

{"error":0}

Sample request (Python):

1
2
3
4
5
6
import urllib2, json

body = json.dumps({"start_timecode":"11:22:33:44"})
request = urllib2.urlopen('http://localhost:65009/blackout', body)
response = json.loads(request.read())
assert response['error'] == 0

Sample request (curl):

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

API Methods

The Live Slicer API supports the following methods:

Method Description
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.
replace_podMarks an ad pod for replacement with a specific duration.
pod_startMarks an ad pod for replacement when the duration is unknown.
pod_endEnds an ad pod and resumes capture for the current asset.
replace_contentReplaces a section of the live stream with pre-encoded content.
blackoutEnds the current asset and stops capturing until further notice.

Use the content_start method to resume capture.

add_metaAdds metadata to the asset currently being sliced.
ignore_scheduleEnables or disables the ignore state for slicing schedules.
statusReturns information describing the Live Slicer's status.
stateReturns the Live Slicer's operating state.
server_timeReturns server time for both the Live Slicer and the CMS.
timedmetaInserts a timed metadata key/value pair into the stream for the asset currently being sliced.
add_cc608Inject EIA/CEA-608/708 captions into the stream.
remove_breakRemoves a break from the schedule.
list_breaksReturns a list of scheduled breaks.

boundary

The boundary method marks the start and the end of a boundary as described below.

  • Start: Mark the start of a boundary by calling the boundary method 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 method without parameters.

Request body parameters are described below.

NameTypeRequiredDescription
typestringOptionalCreates a boundary whose type is determined by the value assigned to this parameter.

Learn more.

expected_durationfloatOptionalSpecifies the expected duration, in seconds, of the segment. An ending boundary will automatically be triggered after the specified time.

Create a Boundary Example:

URL: POST /boundary
Body: {"type":"c3"}

End a Boundary Example:

URL: POST /boundary
Body: {}

OR

Create a Boundary With a Duration Example:

URL: POST /boundary
Body: {"type":"c3", "expected_duration": 30.5}

content_start

The content_start method marks the beginning of a new asset.

Request body parameters are described below.

NameTypeRequiredDescription
start_timecodestringOptionalIdentifies a video frame by timecode for the purpose of identifying a content boundary.
titlestringOptionalAssigns the specified title to the asset.
external_idstringOptionalAssigns the specified external ID to the asset.
metaobjectOptionalAssigns the specified metadata to the asset.

Use the assetinfo API to access an asset's metadata.

Example:

URL: POST /content_start
Body: {"start_timecode":"00:15:21:09","title":"Some Title","external_id":"asdf1234"}

replace_pod

The replace_pod method marks an ad for replacement.

Request body parameters are described below.

NameTypeRequiredDescription
start_timecodestringOptionalIdentifies a video frame by timecode for the purpose of identifying an ad boundary.
durationfloatRequiredDefines the length of the ad break in seconds.
metaobjectOptionalAssigns the specified metadata to the asset.

Use the assetinfo API to access an asset's metadata.

Example:

URL: POST /replace_pod
Body: {"start_timecode":"00:15:21:09","duration":213.32}

pod_start

The pod_start method 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.

NameTypeRequiredDescription
start_timecodestringOptionalIdentifies a video frame by timecode for the purpose of identifying an ad boundary.
metaobjectOptionalAssigns the specified metadata to the asset.

Use the assetinfo API to access an asset's metadata.

Example:

URL: POST /pod_start
Body: {"start_timecode":"00:15:21:09"}

pod_end

The pod_end method ends an ad pod and resumes capture for the current asset.

A request body parameter is described below.

NameTypeRequiredDescription
start_timecodestringOptionalIdentifies a video frame by timecode for the purpose of identifying an ad boundary.

Example:

URL: POST /pod_end
Body: {"start_timecode":"00:15:21:09"}

replace_content

The replace_content method blacks out a section of the live feed and replaces it with pre-encoded content.

Request body parameters are described below.

NameTypeRequiredDescription
start_timecodestringOptionalIdentifies a video frame by timecode for the purpose of identifying a content boundary.
durationfloatRequiredDefines the duration, in seconds, of the segment that will be removed from the live feed.
replacementsarrayRequiredDefines a list of replacement content as described below.

The replacements parameter contains an array of objects. Each object has the following properties:

NameTypeRequiredDescription
external_idstringRequiredIdentifies replacement content by its external ID.
durationfloatOptionalDefines the duration, in seconds, of the replacement content that may be inserted into the live feed. By default, the full duration is used.

Example:

URL: POST /replace_content
Body: {"start_timecode":"00:15:21:09","duration":213.32,"replacements":[{"external_id":"asdf1234","duration":104.2},{"external_id":"asdf4321"}]}

blackout

The blackout method blacks out the live feed until further notice. Use the content_start method to stop a blackout window.

A request body parameter is described below.

NameTypeRequiredDescription
start_timecodestringOptionalIdentifies a video frame by timecode for the purpose of identifying a content boundary.

Example:

URL: POST /blackout
Body: {"start_timecode":"00:15:21:09"}

add_meta

The add_meta method adds metadata to the asset being sliced.

A request body parameter is described below.

NameTypeRequiredDescription
metaobjectOptionalAssigns the specified metadata to the asset.

Use the assetinfo API to access an asset's metadata.

Example:

URL: POST /add_meta
Body: {"meta":{"rating":"TV-Y7"}}

ignore_schedule

The ignore_schedule method 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.

NameTypeRequiredDescription
ignore boolean Required Valid values are:
  • true: The slicing schedule is ignored until further notice.
  • false: The Live Slicer will resume honoring the slicing schedule.

Example:

URL: POST /ignore_schedule
Body: {"ignore":true}

status

The status method returns status information about the Live Slicer.

The response for this method includes a "status" response body parameter. This object contains the following name/value pairs:

Response parametersTypeDescription
  cc_last_seenobjectIndicates the time at which the Live Slicer received the most recent caption for each channel. The Live Slicer updates these timestamps every ten seconds.

Format: {"<Channel Number>":<Unix Time>}

This parameter will report a null value until a caption is detected.

  deliveredintIndicates the number of slices that have been uploaded to cloud storage since the Live Slicer was started.
  droppedintIndicates the number of frames that have been dropped 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).

  durationintIndicates the duration, in seconds, of the live stream.
  lumaintIndicates 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.
  signalstringIndicates the input signal type.
  • Blackmagic Capture Devices: Indicates the signal format reported by the card (e.g. HD 1080i 60fps).
  • UDP Transport Streams Reports the following information:
    TS <multicast | unicast> <Source IP Address>:<Port> <Resolution - width x height>
  • No Signal: Reports "No signal" when the signal is lost.
  slicer_idstringIndicates the Live Slicer's ID as defined in the Live Slicer configuration file.
  slicesarrayIdentifies slices.
  softwarestringIdentifies the Live Slicer's OS version (e.g., slicer_linux_64).
  source_queue_depthintIndicates the number of packets waiting to be read by the Live Slicer.

This capability requires Live Slicer version 15080700 or newer.

  source_queue_max_depthintIndicates the highest number of packets queued to be read by the Live Slicer since it started running.

This capability requires Live Slicer version 15080700 or newer.

  stateintValid values are:
  • 0: Capture
  • 1: Ad break
  • 2: Replacing content
  • 3: Blackout
  versionstringIndicates the Live Slicer's version number.
  volintIndicates 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.
  waitingintIndicates the number of slices waiting to be uploaded.

Example:

URL: GET /status

state

The state method indicates the Live Slicer's current operating state.

The response body for a successful request includes the following response elements:

Response parametersTypeDescription
  stateintValid values are:
  • 0: Capturing content
  • 1: Ad break
  • 2: Replacing content
  • 3: Blackout
  state_namestringValid values are:
  • Capture
  • Ad
  • Replace
  • Blackout

Example:

URL: GET /state

server_time

The server_time method indicates server time.

The response body for a successful request includes the following response elements:

Response parametersTypeDescription
  correctedintIndicates the current Unix time reported by the CMS.
  timeintIndicates the current Unix time on the Live Slicer's host machine.

Example:

URL: GET /server_time

timedmeta

The timedmeta method inserts a timed metadata key/value pair into the stream for the asset currently being sliced.

Request body parameters are described below.

NameTypeRequiredDescription
start_timecodestringOptionalIdentifies a video frame by timecode for the purpose of identifying the boundary for inserting metadata.
keystringRequiredSets the key value of the key/value pair that will be inserted into the stream.
valuestringRequiredSet the value element of the key/value pair that will be inserted into the stream.

Example:

URL: POST /timedmeta
Body: {"start_timecode":"00:15:21:09", "key":"myKey", "value":"myValue"}

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

NameTypeRequiredDescription
start_timecodestringOptionalIdentifies a video frame by timecode for the purpose of identifying the boundary for inserting metadata.
ownerstringRequiredIdentifies 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.

valuestringRequiredDefines the Base64-encoded data that will be contained by the PRIV frame.

Example:

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

add_cc608

The add_cc608 method inserts a base64-encoded EIA/CEA-608/708 payload into the stream.

Request body parameters are described below.

NameTypeRequiredDescription
datastringRequiredBase64-encoded EIA/CEA-608/708 cc_data_pkt data.
offset_time_msintegerOptionalThe number of milliseconds from the start of the current asset where the caption data should be injected.
offset_from_now_msintegerOptionalThe number of milliseconds from now where the caption data should be injected.

This capability requires Live Slicer version 17061500 or newer.

Example:

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

restart_later

The restart_later method 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.

A request body parameter is described below.

NameTypeRequiredDescription
start_timecodestringOptionalIdentifies a video frame by timecode for the purpose of delaying a restart. If specified, the Live Slicer will wait until the specified timecode and then restart at the next ad break, blackout, or content_start.

Example:

URL: POST /restart_later
Body: {"start_timecode":"00:15:21:09"}

remove_break

The remove_break method removes a scheduled break.

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

A request body parameter is described below.

NameTypeRequiredDescription
idintegerRequiredIdentifies a scheduled break by its ID.

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

Example:

URL: POST /remove_break
Body: {"id":0}
Response:{"error" :0}

list_breaks

The list_breaks method returns a list of scheduled breaks.

This method only returns breaks scheduled in the future when future_timecodes has been enabled.

Example:

URL: POST /list_breaks
Body:(empty)
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

The quality method indicates the bitrate of the video that the Live Slicer is sending to the encoder.

The response for this method includes the following response body parameters:

Response parametersTypeDescription
  current_video_kbpsintIndicates the current video's bit rate (Kbps).
  effective_total_kbpsintIndicates the effective total bit rate (Kbps).
  original_video_kbpsintIndicates the original video's bit rate (Kbps).

Example:

URL: GET /quality