Customer Sign In

upLynk

An Introduction to the Live Slicer API Learn to manipulate your stream

Tutorial thumbnail

Summary Use the Live Slicer API (Documentation) to control your Live Slicer's behavior.

Skill level required Intermediate to Advanced

Time to complete 1-2 Hours

Things you’ll need
  • Network access to your Live Slicer

Introduction

The live Slicer API provides several methods that allow you to control the behavior of your stream. They can be used to start and stop slicing, replace a section of the stream with a VOD asset, mark ads for replacement, add metadata to the slicing asset as well as configure slicers during redundant failover scenarios.

A quick note about timecodes

Nearly all of the Live Slicer API methods accept a start_timecode (Documentation) argument. The start_timecode argument is used to achieve frame accuracy when executing the live slicer command. If timecodes are not present in the stream, the slicer will default to using the time from the system clock where it is running. Additionally, the start_timecode method argument is optional. If not provided the live slicer assumes the command should use the timecode of the oldest frame in its buffer.

Start and stop slicing

There are many reasons you may want to start and stop slicing. Using the content_start api you will end the currently slicing asset, and start a new asset, optionally giving this asset a start_timecode, title, external_id and/or metadata.

Let's look at a Python example of using the content_start API.

content_start example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import urllib2, json

SLICER_IP = "127.0.0.1"  # localhost
SLICER_PORT = 65009      # default port

body = json.dumps({"title":"My New Program"})
request = urllib2.urlopen("http://%s:%d/content_start" % (SLICER_IP, SLICER_PORT), body)
response = json.loads(request.read())
assert response["error"] == 0
		

This example finishes the current asset and starts a new asset with the title "My New Program". You might want to login to your CMS account and verify that the new asset with your title is currently slicing.

To stop slicing you can call the blackout api. You would call the content_start api to start slicing your feed once again. Here's a quick Python example which calls the blackout api.

blackout example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import urllib2, json

SLICER_IP = "127.0.0.1"  # localhost
SLICER_PORT = 65009      # default port

body = json.dumps({"start_timecode":"00:00:00:00"}) # timecode format HH:MM:SS:Frame
request = urllib2.urlopen("http://%s:%d/blackout" % (SLICER_IP, SLICER_PORT), body)
response = json.loads(request.read())
assert response["error"] == 0
		

Replace stream content with VOD asset

There are times when you will want to replace content from your linear feed with a live asset. One example could be a sporting event being broadcast that you don't have the rights to rebroadcast online. You can easily tell your live slicer to replace this content with one or more VOD assets from your library. Here's a list of things you'll need.

  • The duration of the content you plan on replacing.
  • The duration of each VOD asset being used as replacement content.
  • Make sure the External ID is set on each VOD asset being used as replacement content.
Let's look at a Python example.
replace_content example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
import urllib2, json

SLICER_IP = "127.0.0.1"  # localhost
SLICER_PORT = 65009      # default port
SECTION_TO_BE_REPLACED_DURATION = 100.0 # type=float, unit=seconds, full duration of content to be replaced
REPLACEMENT_ASSET_EXTERNAL_ID = "MyReplacementAsset"
REPLACEMENT_ASSET_DURATION = 100.0 # type=float, unit=seconds

body = json.dumps({"duration":SECTION_TO_BE_REPLACED_DURATION,"replacements": \
    [{"external_id":REPLACEMENT_ASSET_EXTERNAL_ID,"duration":REPLACEMENT_ASSET_DURATION}]})
request = urllib2.urlopen("http://%s:%d/replace_content" % (SLICER_IP, SLICER_PORT), body)
response = json.loads(request.read())
assert response["error"] == 0
			

Marking ads for replacement

You may want to replace the ads in your linear feed because of rebroadcast rights issues, pertinence to a particular locale, or to leverage your knowledge of your viewership's ad preferences. The Live Slicer provides 4 APIs for marking ads for replacement:

  • replace_pod Used when you know the exact duration of the ad break.
  • pod_start Used to start an ad break when you don't know the duration.
  • pod_end Used to end an ad break started with pod_start.
  • boundary Used to dynamically define a segment within a live stream into which ads may be inserted.

Let's look at a Python example using replace_pod.

replace_pod example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import urllib2, json

SLICER_IP = "127.0.0.1"  # localhost
SLICER_PORT = 65009      # default port
AD_POD_DURATION = 180.0  # type=float, unit=seconds

body = json.dumps({"duration":AD_POD_DURATION})
request = urllib2.urlopen("http://%s:%d/replace_pod" % (SLICER_IP, SLICER_PORT), body)
response = json.loads(request.read())
assert response["error"] == 0
			

What's Next?

Obviously there are questions we haven't answered. "Where do I get the timecodes of my breaks for use with these APIs?" is one of the biggest. Generally a playout automation system from Snell, Harris or another vendor provides this information. Find out which system you're using and let us know. We're happy to assist you with your integration.

Finished!

You're well on your way to managing your live slicers with our simple, yet flexible, APIs.

Back to tutorials