Elemental® Live
Total Page:16
File Type:pdf, Size:1020Kb
ELEMENTAL® LIVE API AND USER GUIDE 2.20.3.0 RELEASE DECEMBER 23, 2020 Elemental Live API and User Guide TABLE OF CONTENTS • Overview • Web Interface • REST Interface • Elemental/Live/Live Event Parameters • SNMP Interface • Authentication • Reference • Supported Codecs • Supported Captions 12/23/20 Copyright 2020 AWS Elemental. All rights reserved. 2/171 Elemental Live API and User Guide Overview OVERVIEW • Purpose • Product Overview • Live Events • Live Event Profiles • Presets • Schedules • MPTS Multiplexers • Notifications • Statistics • Advanced Pre and Post Processing • Custom Scripts • Troubleshooting PURPOSE This document is intended for system integrators and users of Elemental® Live. It outlines interfaces for machine and human control, configuration, and monitoring. Each API is defined in enough detail to explain how to use the system and how it can be integrated into larger workflow automation systems. PRODUCT OVERVIEW Elemental Live is a powerful media encoder which can accept input through an HD-SDI interface, IP over Ethernet, or a local file. It can produce multiple video output streams using a variety of live streaming protocols. Elemental Live can be controlled, configured and monitored through the following interfaces: • Web browser via HTML • Web Services REST interface • SNMP interface Using a web browser is the easiest way to control, configure, and monitor Elemental Live. This interface is used when a human is interacting with the server, or when no automation or integration with other systems is required. Elemental recommends Mozilla Firefox as the client web browser. The REST-based interface supports all features of the web interface as well as automation features. More general information on REST-based interfaces is available online. The SNMP interface allows basic monitoring and control of the Elemental Live system. It allows a management system to query the state of the service and Live Events, as well as start and stop Live Events. Finally, secure shell access allows the user to modify the system's configuration files, directory structure, and built-in tests. The secure shell interface is provided for users who need to modify the base behavior of the Elemental Live system or for diagnostics. LIVE EVENTS A Live Event is an encoding session started and stopped by the operator of the system. Live Events are created by selecting an input from the available HD-SDI capture devices or specifying a network stream location. The operator can also select a file input, which will be decoded in real-time to simulate a live input. This feature is useful for testing encoding parameters and output destinations when a live source is not available. 12/23/20 Copyright 2020 AWS Elemental. All rights reserved. 3/171 Elemental Live API and User Guide Product Overview When using the web interface, the user can click the "Preview" button once they have filled in input parameters. Elemental Live will attempt to acquire the input source and display a scaled frame and audio level for the user to verify their source is correctly connected to Elemental Live. The operator then defines the output stream encoding parameters that they would like the system to produce. See Supported Codecs for information about which codecs Elemental Live supports. The user can select which GPU they would like the stream to utilize, or allow the system to automatically select the GPU. Output streams can be connected to multiple output groups, which define endpoints for streaming applications. Elemental Live currently supports Adobe RTMP outputs for Adobe Flash Media Server, push encoding for Microsoft Smooth Streaming, Apple iPhone live streaming, Dynamic Adaptive Streaming over HTTP (DASH), UDP output, reliable transport stream output, and archiving to the local hard drive. See Supported Codecs for a list of all the supported container formats. LIVE EVENT PROFILES A Live Event Profile is a saved Live Event definition that includes all output settings for a Live Event and, optionally, the input settings. Live Events can be submitted with a Live Event Profile ID and input parameters to re-use previously entered settings. Note that if a Live Event Profile is edited, those changes are only applied to Live Events created after the change. Live Events already in progress or in the PENDING state will retain the settings with which they were submitted. Some example Live Event Profiles are supplied by default in each release of the Elemental Live software. These examples should be copied if they are intended to be used in an actual workflow as they may change from release to release. PRESETS A preset is a predefined group of settings for a single output stream. A preset allows the user to create output streams targeted at a particular device or standard output format. For example, the H.264 HD Medium preset produces a stream with H.264 video at 1280 x 720 resolution and 2.4 mbit/s, and AAC audio at 128 kbit/s. Elemental maintains a list of common presets that are delivered to the Elemental Live system via software updates. Additionally, the user can specify named presets using any of the interfaces to the Elemental Live system. SCHEDULES Schedules can be created to run certain Live Event Profiles at scheduled times, or a set of repeating times. For example, a schedule can be created to run every weekday from 1:00PM to 2:00PM to stream a program. Each of these scheduled programs will be converted to a Live Event. MPTS MULTIPLEXER The Multi-Program Transport Stream multiplexer (MPTS mux) combines audio, video and data from multiple Live Events into a single MPEG-2 transport stream, output over UDP. MPTS muxes are managed from the MPTS Control page, accessed from the Event Control drop-down. The MPTS mux takes its inputs from one or more Live Events. In order to be eligible for MPTS muxing, a Live Event must be configured with a single UDP/TS output group that has an ‘MPTS Membership’. A setting of ‘Local’ allows the event to participate in an MPTS mux running on the Live node itself. The output also must be attached to a stream that is using either CBR or Statmux as its Rate Control Mode. If these criteria are met, the LiveEvent will be available for inclusion. Live Events can be added and removed from the MPTS at any time, but must be removed from one MPTS before joining another. When Live Events in an MPTS mux are configured with Statmux as their rate control mode, statistical multiplexing is used to allocate the total available MPTS bitrate among the video stream bitrates based on complexity. This is typically used for streams that are part of a fixed capacity transport mechanism. Bits are transferred dynamically from simple content to complex content, maximizing the overall visual quality of the output. NOTIFICATION Users can set up a Live Event so that a notification is sent if the Live Event is started, stopped, or has an alert or error. The user can be notified in the following ways: • Email 12/23/20 Copyright 2020 AWS Elemental. All rights reserved. 4/171 Elemental Live API and User Guide Product Overview • Web service callbacks - An HTTP POST will be performed to a URL that you provide, with information about the Live Event The user may also request details about a Live Event's status at any time. These details are described later in this document. STATISTICS Elemental Live is continuously logging statistics about media type, quality, speed, temperature (CPU and GPU), fan speed, and resource utilization (CPU, GPU, network, disk and memory). Historical statistics are available in the web interface, on the Stats page. ADVANCED PRE AND POST PROCESSING Most workflows have a certain number of custom commands that must be executed before or after a Live Event is run. Examples of these operations include: • Running custom validation on input or output files before or after a conversion • Running custom notifications before or after the Live Event is run Some of these commands are supported natively through the Elemental Live user interface, and the rest can be run through custom scripts that the user provides. CUSTOM SCRIPTS For each Live Event created, the user can specify a pre and/or a post script to run. The user specifies a location for the script as part of the Live Event UI or REST API. This location must be accessible by the server. It is recommended to put these scripts in the /opt/elemental_se/web/public/script directory; the Browse button for scripts is set up to search this directory. /opt/ elemental_se/web/public/script/example_script.rb is an example script that parses the input parameters using Ruby and prints them to the live_runner.output log file. The pre processing script is called from the elemental_se service just before the Live Event runs and must have execute permission for the elemental user. The Live Event's state is changed to PREPROCESSING when the pre script is running, and POSTPROCESSING when the post script is running. The Live Event can still be cancelled when it is in one of these states. The reported start and end times for a Live Event will contain the running time of these scripts; however, the elapsed time only measures the time spent processing video. The script is passed a JSON-formatted hash. The overall structure is described below: • id ID of the Live Event • script_type PRE for preprocessing, POST for post processing • inputs Array of all inputs. Each item in the array contains the following keys: • type Type of input (file_input,network_input,smpte2022_dash7_network_input,smpte2110_input,device_input) • uri Path to input file • output_groups Array of all output groups. Each item in the array contains the following keys: • name Indicates group type (Archive, Apple HLS, etc.) • outputs Array of all outputs in this group.