Customer Sign In

upLynk

Live Slicer setup

Overview

The Live Slicer is the tool used to capture content from a live signal and send it to the encoder cloud. The Live Slicer must be configured with a unique slicer ID. A channel can be created and configured to stream the output of a Live Slicer via the upLynk CMS.

The Live Slicer tool runs as a daemon process on an Ubuntu Linux system. It is controlled using the standard initctl commands.

Hardware and system software

upLynk recommends the Live Slicer run on a server with the following minimum specifications:

  • Quad-core x86-64 2GHz CPU
  • 6GB RAM
  • 80GB storage space
  • Supported Blackmagic DeckLink SDI card (required for SDI capture)
  • Connection to the internet with min 5Mb/s upload data transmission rate

The Live Slicer is built to run on Ubuntu Linux 11.04 (or newer) 64-bit server, or CentOS 6.6. It has been tested on all versions up to and including Ubuntu 14.04 LTS. The BlackMagic DeckLink drivers can be installed with the desktopvideo package downloadable from BlackMagic's website.

As an alternative to SDI, the Live Slicer can be configured to capture from a UDP unicast or multicast MPEG2 Transport Stream.

Installation

Once Ubuntu Linux 64-bit and the BlackMagic drivers are installed and configured, the Slicer package for Linux should be downloaded from the upLynk CMS. Once downloaded, the package should be extracted and installed as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
$ tar xvf- uplynk_slicer_linux_64-xxxxxxxx.tbz2
uplynk_slicer_linux_64-xxxxxxxx/
uplynk_slicer_linux_64-xxxxxxxx/liveslicer
uplynk_slicer_linux_64-xxxxxxxx/libssl.so.1.0.0
uplynk_slicer_linux_64-xxxxxxxx/libavcodec.so.53
uplynk_slicer_linux_64-xxxxxxxx/slicebot
uplynk_slicer_linux_64-xxxxxxxx/README.html
uplynk_slicer_linux_64-xxxxxxxx/example.conf
uplynk_slicer_linux_64-xxxxxxxx/libbeam-slicer.so
uplynk_slicer_linux_64-xxxxxxxx/libavutil.so.51
uplynk_slicer_linux_64-xxxxxxxx/libcrypto.so.1.0.0
uplynk_slicer_linux_64-xxxxxxxx/libcares.so.2
uplynk_slicer_linux_64-xxxxxxxx/libavdevice.so.53
uplynk_slicer_linux_64-xxxxxxxx/slicebot.cfg.example
uplynk_slicer_linux_64-xxxxxxxx/slicer
uplynk_slicer_linux_64-xxxxxxxx/ca-bundle.crt
uplynk_slicer_linux_64-xxxxxxxx/libswscale.so.0
uplynk_slicer_linux_64-xxxxxxxx/libavformat.so.53
uplynk_slicer_linux_64-xxxxxxxx/libavfilter.so.2
uplynk_slicer_linux_64-xxxxxxxx/install_live

$ cd uplynk_slicer_linux_64-xxxxxxxx
uplynk_slicer_linux_64-xxxxxxxx$ sudo ./install_live
uplynk Live Slicer installed.  Please edit /etc/uplynk.conf to configure, then run "start uplynk_liveslicer" to start.
uplynk_slicer_linux_64-xxxxxxxx$ 

Configuration

Configuration of the Live Slicer is managed via the configuration file located in /etc/uplynk.conf. An example configuration file is included in the install package, and is copied to /etc/uplynk.conf by the initial installation. The example configuration is also shown below:

configuration key names prepended with the string <verbatim_>, will allow a value that contains the <#> char, which would normally denote the beginning of a comment.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
description: Live Capture    #description to give to new assets
username: example@uplynk.com #the email address used for the upLynk account
password: example            #upLynk account password
slicerID: slicer1234         #the upLynk channel ID (no spaces, alphanumeric)
autoexpire_age: 24           # # of hours until assets get deleted (0=never)
input: blackmagic            #the input source for the signal
card: 0                      #the card number for BlackMagic capture cards
capture_mode: auto           #Black magic capture mode. See "liveslicer -list"
audio_layout: stereo 1       #channel layout.Can be "stereo <pair #>", 5.1, 7.1
gain: 0.0                    #the # of decibels of gain to apply to the audio
capture_delay: 0             # # of seconds delay to add to match timecodes
SCTE104_DID: 0x41            #the DID number to use for SCTE104 triggers
SCTE104_SDID: 0x07           #the SDID number to use for SCTE104 triggers
captions_DID: 0x61           #the DID number to use for closed captions
captions_SDID: 0x01          #the SDID number to use for closed captions
ancillary_scan: off          #set to "on" to scan all ancillary lines
ancillary_lines: 9, 13       #if "ancillary_scan" is off, only scan these lines
api_port: 127.0.0.1:65009    #the port number to listen on for API calls

While most of these configuration options are explained in the comments of the example configuration file, some additional clarifications are included below:

slicerIDA slicer must be given a unique (within your account) alphanumeric ID. To view the output of a slicer, a channel must be created in the upLynk CMS and configured with the same slicer ID.
capture_modeThe mode number for the input video signal. Setting this to "auto" (recommended) will cause the Live Slicer to autodetect the video mode for BlackMagic cards that support signal detection. A list of video modes for the installed BlackMagic card can be found by running the Live Slicer command with the arguments "-card <card_number> -list".
thumbnailUse this option to create extra thumbnails of different sizes. This option can appear in the config file multiple times.
audio_layoutSDI Signal Only
Defines the audio channel layout.

Valid values are:

  • stereo [1-8]
    For example, "stereo 1" indicates a two channel layout that consists of a "left front" and a "right front" channel.
  • 5.1
  • CEA
  • 7.1

This parameter does not apply to:

  • AC-3 audio.
  • Audio transmitted via UDP.

Note: Alternatively, each audio track may be assigned a custom audio layout. Use a custom audio layout to downmix audio to mono or stereo.
Learn more.

For more advanced configuration options, see Advanced Configuration Options

Once the Live Slicer is configured, start it with the following command:

sudo start uplynk_liveslicer

To verify that it is running, check the log file (see the section on logging).

The Live Slicer should also start automatically next time the server is rebooted. If the configuration is changed, the Live Slicer will need to be restarted for changes to take effect:

sudo restart uplynk_liveslicer

To Stop the Live Slicer:

sudo stop uplynk_liveslicer

UDP Transport Stream Configuration

The example configuration above shows how to configure the slicer to capture from an SDI feed using a BlackMagic SDI capture card. To capture from a UDP unicast or multicast MPEG2 Transport stream, the following changes to the configuration are required:

  • Change the input setting from blackmagic to udp
  • The card setting can be removed. It will be ignored if not removed.
  • The capture_mode setting can be removed. It will be ignored if not removed.
  • All SCTE104, captions, and ancillary settings can be removed. They will be ignored if not removed.
  • A multicast or unicast setting should be added with the IP address of the stream.
  • A port setting should be added with the port number of the stream.
  • A progID setting may be included to specify the program ID in a multi-program transport stream. If no pids are specified, all audio tracks in the program will be consumed.
  • A pids setting may be included to specify a comma-separated list of PIDs that the slicer should consume for audio/video tracks. If this setting is used, the slicer will ignore any audio/video PIDs not in the list.
  • If no progID or pids are specified, the first audio and video track the slicer encounters will be consumed by default.
  • A audio_lang_[pid] setting may be included to specify a language for a specific audio track. Additionally, audio_desc_[pid] may be used to specify a description for a specific audio track. Audio tracks without a specified description will default to 'unspecified'.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
description: Live Capture    #description to give to new assets
username: example@uplynk.com #the email address used for the upLynk account
password: example            #upLynk account password
slicerID: slicer1234         #the upLynk channel ID (no spaces, alphanumeric)
autoexpire_age: 24           # # of hours until assets get deleted (0=never)
input: udp                   #the input source for the signal
multicast: 224.0.0.1         #the multicast address of the UDP stream
port: 1234                   #the port number of the UDP stream
progID: 128                  #which transport stream program to use for MPTS
pids: 5,6,7                  #PIDs within the program to slice
audio_lang_6: en             #Language for audio on PID 6
audio_desc_6: English        #Description for audio on PID 6
audio_lang_7: es             #Language for audio on PID 7
audio_desc_7: Spanish        #Description for audio on PID 7
gain: 0.0                    #the # of decibels of gain to apply to the audio
api_port: 127.0.0.1:65009    #the port number to listen on for API calls

SCTE 35/104 Signalling

By default, the slicer has some basic SCTE 35/104 signal processing. SCTE 104 is converted to SCTE 35 and then processed by the same processes that 35 is processed by. This way, one plugin can support both SDI and UDP Transport Stream signalling. If the default plugin for SCTE signalling is insufficient, you may use the python plugin to write custom plugins in python code for processing. If you wish to disable the default scte processing, you can specify:

1
scte_type: none

in your slicer config

Metadata

By default, metadata is not assigned to assets generated by the Live Slicer. However, metadata may be defined through any of the following methods:

  • Live Slicer Configuration File: Use the meta configuration parameter to define a key/value pair for the desired metadata field. By default, the metadata defined by this parameter will be assigned to assets generated by the Live Slicer. Define additional metadata fields by specifying this configuration parameter on a separate line for each desired field.

    Example:
    meta: MyField1=ValueA
    meta: MyField2=ValueB
  • Live Slicer API: Assign metadata to a particular asset through the add_meta method. This method overrides the default values defined in the Live Slicer configuration file.

Advanced Configuration Options

Some additional configuration options for more advanced features are listed below:

  • parse_XDS - By default, the slicer will make use of Extended Data Services (XDS) data if it is present in the stream. It will update the current asset's title and rating information based on XDS data. To disable this, add parse_XDS: no to the slicer config.
  • timecard (SDI capture only) - If enabled, the slicer will attempt to load a dynamic library called libuplynk_timecode.so to integrate with an external timecode generator. To enable, add timecard: true to the slicer config file.
  • no_signal_pad <seconds> (UDP capture only) - If set, the slicer will show black instead of green for the specified number of seconds when the signal is lost.
  • no_signal_image <filename> (UDP capture only) - Used with no_signal_pad to show an image instad of black when the signal is lost.
  • no_signal_shutdown_time <seconds> (UDP capture only) - Tells the slicer to shut down if the signal is lost for more than the specified number of consecutive seconds.
  • start_blackout Tells the slicer to start in blackout mode. Values: "yes" = start in blackout, "sticky" = start in blackout mode only if that particular slicer (based on slicerID) stopped while in blackout mode.
  • nielsen <1> Enables scanning for Nielsen audio watermarks.
  • nielsen_distributor <distributor id> - Defines the Nielsen distributor for use with Nielsen audio watermarks and ID3 tags assigned to assets generated by the Live Slicer. By default, this distributor is set to "www.uplynk.com." Override this value by setting this parameter to the ID of the desired distributor.
  • nielsen_ad_mode <code> - Defines the Nielsen breakout code. Valid values are: 00 (default value), 03, 07, and 09.
  • wallclock Adds ID3 tag based timestamp to each slice, derived from the system time of the slicing server.
  • timecode Adds ID3 tag that contains the HH:MM:SS:FF of the pic_timing data in the SEI NAL Unit, if present.
  • cc_filter Set to "off" to disable filtering CEA-608/708 capptions for all channels except channel 1. Note that a bug in iOS versions prior to 7.1 will cause devices to improperly render all caption channels if more than channel 1 is present.
  • ccX_lang The language code for CC channel X. e.g. cc1_lang: en
  • ccX_desc A description for CC channel X. e.g. cc1_desc: English
  • debugoverlay <1> (Not for production use.) Burns a text display into the video that contains debug information, information is subject to change between releases.
  • authenticated_api_port The port number (or ip:port) on which to expose the authenticated API. Requires slicer version 16090200 or newer.
  • backup If set to "true" the slicer will follow an alternate upload path and use alternate origin storage.
  • video_sync_ms <milliseconds> Sets an audio/video sync offset, in milliseconds. If it is a positive number, the video will be forced ahead of the audio by the specified amount of time. If it is a negative number, the video will be forced behind the audio.
  • forcePTS <1> Prevents the video decoder from falling back to DTS if there are PTS discrepancies.

Custom Audio Layout (SDI Signal Only)

The Live Slicer may be configured to use a preconfigured or a custom audio channel layout. A custom audio channel layout allows each audio track to be mapped to one or more channels. Additionally, a custom level may be assigned to each mapped channel.

Basic Terminology

Before defining a custom audio layout, it is important to become acquainted with the following terminology:

  • SDI Channel: Identifies a single unit within a representation of an audio stream. For example, the left portion of a stereo feed may consist of one or more SDI channels.
  • Track: Identifies the set of channels required to produce a single representation of an audio stream. For example, an audio track for a stereo feed may consist of two or more SDI channels.

Basic Setup

Setting up a custom audio channel layout requires replacing the audio_layout configuration setting with audio_custom_layout_Track. The configuration for this setting varies according to how audio should be mapped.

Use the following syntax to downmix audio to mono:

audio_custom_layout_Track: mono|X=SDI_Input_Channel@Level

Use the following syntax to downmix audio to stereo:

audio_custom_layout_Track: stereo|L=SDI_Input_Channel@Level,R=SDI_Input_Channel@Level

Instructions on how to configure this setting are provided below.

  1. Replace Track with the ID of the audio track that will be assigned a custom audio layout.
  2. Set X or L and R (Left and Right) to an ampersand delimited list of SDI channels that will serve as the source for the specified audio track. The valid range for each channel is 0 - 15.

    The following sample mono configuration sets the source for audio track 0 to SDI channels 0, 1, and 3.

    audio_custom_layout_0: mono|X=0&1&3

    The level for each assigned SDI channel may be defined by appending the @ symbol followed by the desired value. Use the following formula to calculate level:

    (Volume %) * 10

    The following sample stereo configuration sets Left to SDI channel 0 at 70.7% and SDI channel 2 at 80%, while Right is set to SDI channel 4 at 20.2%.

    audio_custom_layout_0: stereo|L=0@707&2@800,R=4@202

    If the audio level is missing, then it will be set to 100%. The following sample stereo configuration sets Left to SDI channel 0 at 100% and Right is set to SDI channels 3 and 4 at 100%.

    audio_custom_layout_0: stereo|L=0,R=3&4

Multiple Track Setup

A custom audio layout may be defined for multiple tracks (e.g., language-specific tracks). This type of setup requires informing the Live Slicer as to the number of tracks that will be mapped via the audio_tracks configuration setting.

Warning: The Live Slicer will only generate audio for a single track when this configuration setting is omitted.

Use the following syntax to indicate the number of audio tracks that will be mapped:

audio_tracks: Quantity

For example, use the following configuration to indicate that a custom audio layout for three audio tracks (e.g., English, French, and Spanish) will be mapped:

audio_tracks: 3

Audio Normalization

upLynk attempts to encode all assets at approximately the same loudness. For file encodes, this is achieved by running an analysis on the file to determine it's loudness prior to encoding. Based on the calculated loudness, gain or attenuation is applied to the source audio at encode time.

For live, a full analysis pass cannot be run on the source signal to determine the loudness. The gain setting in the configuration file described in the previous section is used to configure the gain (or attenuation, using a negative number) that should be applied to the live signal at encode time. The configuration value should be in units of decibels.

The Live Slicer will log the calculated gain value as it captures every ten seconds. Watch the logs to find the appropriate value for the gain configuration parameter. The slicer must be restarted for configuration changes to take effect.

Logging

The Live Slicer will output verbose logging information to syslog. A default syslog configuration will send these messages to /var/log/syslog. Included in the log is the ongoing calculated gain values.

In the event of an upLynk related error, the log should be compressed and sent to upLynk for analysis.

Network Ports and Firewalls

The slicer relies on both ports 80 and 443 to communicate with the upLynk services and upload the encrypted slices for encoding. Outbound connections must be allowed on these ports.