Live Streaming

This section describes the structure of the Live Stream content object and detailed metadata configuration for recording and playout.

Live streaming basics are described in the content management Live Streaming section.

Live Stream Content Object Overview

A Live Stream is represented by a content object of type Live Stream. Each tenancy is provisioned with a default Live Stream content type and, of course, if necessary, more content types can be created if live streams need to have different behaviors.

The configuration of the live stream is in the object metadata under live_recording and it has the following structure:

  "live_recording": {
    "playout_config": {
      // Configuration of playout features
    },
    "recording_config": {
      "recording_params": {

        // Live recording parameters
        ...

        "ladder_specs": [
          // Configuration of video and audio ABR ladder rungs
        ],

        "xc_params" : {
          // Encoding parameters for video and audio
        }

      }
    }
  },

Live Stream Life Cycle

A live stream content object stores the configuration of the live stream recording.

Before the first recording is started, the object needs to be configured. This consists in probing the source stream, detecting the video and audio streams, configuring the recording parameters and optionally allowing the operator to specify or modify parameters (for example what audio streams to be recorded and what their playout labels should be).

When a recording is started, the object creates an “edge write token”, where the recording media and metadata is stored.

A recording may be interrupted or paused. In this case the recording will have multiple ‘periods’.

When recording is complete, it can be saved or discarded. A new recording may be started after having saved or discarded the previous one.

At any time during a recording, you can make VoD copies of the entire recording or portions of it. These are copies ‘by reference’, and no actual media is duplicated.

Formally, the live stream object goes through the following states:

  • uninitialized - the stream has not been configured yet
  • inactive - the stream has been configured, but a recording has not yet been started
  • starting - a recording has been started, but the source stream has not been acquired yet
  • running - a recording is in progress
  • stopped - a recording is paused or interrupted (this constitutes the end of a recording ‘period’ and a new ‘period’ can be started)
  • stalled - a recording is in progress but is not producing any output (likely because the source stream cannot be decoded or configuration is incorrect)

Advanced Playout Options

The following query parameters are supported for HLS and DASH URLs:

Parameter Values Description
dvr 1 Play “DVR” - allow the player to seek back to the beginning of the stream or to a configured position. See playout configuration dvr_enabled
scte 0 Disable SCTE event pass-through for DASH and HLS outputs.
scte 1 Enable SCTE event pass-through for DASH and HLS outputs. Can also be enabled by playout configuration scte_enabled.

Example URL query parameters:

?dvr=1&scte=1

Advanced Configuration

Recording

Recording configuration parameters available under live_recording / recording_config / recording_params:

  • listen: bool - indicate if the live stream source is pushed to the server (true) or the server is connecting and pulling (false)
  • live_delay_nano - the live edge of the manifest is pulled back this duration (typically 2-4 sec)
  • max_duration_sec - the stream recording will automatically stop after this duration (default -1, no max duration)
  • name
  • description
  • origin_url - live stream source URL (udp,srt,rtmp)
  • part_ttl - live stream recording retention (seconds)
  • playout_type: live
  • reconnect_timeout: seconds - if the source stream disconnects, attempt to reconnect for this duration (typically 1-10 min but could be set to 2-4 hours for unattended events)

Encoding parameters available under live_recording / recording_config / recording_params / xc_params

General:

  • connection_timeout: seconds - if there is no source for this duration, stop the recording

Video:

  • enc_height
  • enc_width
  • filter_descriptor - an ‘ffmpeg-style’ filter string
  • ecodec - video encoder
  • force-keyint - number of frames per GoP (forced key frame interval) (eg.50)
  • preset - encoding preset (h264, h265)
  • stream_id - if the source stream has multiple video streams, specify the video stream to record
  • video_bitrate - video recording bitrate (eg. 95000000)
  • video_seg_duration_ts - duration of ABR video segment, in timescale units (eg. 2700000)
  • video_frame_duration_ts - duration of each video frame, in timescale units (optional)
  • video_time_base - video recording timebase (optional) (eg. 90000)

Audio:

  • audio_bitrate: bps - audio recording bitrate (eg. 192000, 384000)
  • audio_index: [int] - an array of ints representing the stream index for each audio stream to be recorded
  • ecodec: audio codec (default aac)
  • audio_seg_duration_ts - the duration of ABR audio segment, in timescale units (eg. 1428480)
  • sample_rate: audio sample rate (eg. 48000)
  • sync_audio_to_stream_id - if the source stream has multiple video streams, sync audio to this stream ID

Quality tuning:

  • level - codec level (eg: “52”, “41”)
  • profile - codec profile (eg: high, main, baseline)
  • rc - codec rate control mode (eg: vbr, cbr, vbr_hq, cbr_hq)
  • cq - constant quality factor (0 to 51)
  • tune - encoding tuning (eg: hq, ll, ull, lossless)
  • multi_pass - encoding multi pass setting (eg: qres, fullres)
  • bframes - allowed B-frames per GOP (0 to 5, default 0)
  • buf_size - rate control buffer size (eg. 1x or 2x desired bitrate)
  • max_rate - rate control max limit (eg. 1x or 2x desired birate)

Quality tuning examples

  1. For best quality and minimum bandwidth

Using rate control mode vbr_hq (8388609) with a quality factor (cq) will produce high quality output and will reduce the rate of the output when the quality can be met. Use the max rate and buffers size parameters to cap the rate.

          "rc_mode": 8388609,
          "cq": 18.0,
          "rc_buffer_size": 5000000,
          "rc_max_rate": 5000000,
  1. For smoother bandwidth

Using rate control mode vbr will produce a smooth output bitrate, much closer to the avarage bitrate than vbr_hq. The overall bitrate will be higher, so not as efficient as vbr_hq. Use the multi pass option for content that can’t achive a good enough quality for the desired output bitrate.

          "rc_mode": 1,
          "cq": 20.0,
          "rc_buffer_size": 5000000,
          "rc_max_rate": 5000000,
          "multi_pass": 2,
  1. For constant bandwidth

Using rate control mode cbr will produce a constant bitrate, very close to the average bitrate, potentially at the expense of output quality.

          "rc_mode": 2,
          "cq": 20.0,
          "rc_buffer_size": 5000000,
          "rc_max_rate": 5000000,
          "multi_pass": 2,

Playout ABR ladder

The playout ABR ladder is specified under live_recording / recording_config / recording_params / ladder_specs

It is an array of ‘rungs’, for both video and audio.

Video:

  • bit_rate: bps
  • codecs: codec descriptor (eg: “avc1.640028,mp4a.40.2”)
  • height: eg. 1080
  • width: eg. 1920
  • media_type: 1 (1 = video)
  • representation: identifier for this rung (eg: 1920x1080_h264@95000000)
  • stream_index: video stream index (typically 0)
  • stream_name: video stream name (eg: “video”)

Audio:

  • bit_rate: bps
  • channels: number of channels (typically 2=stereo 6=surround)
  • codecs: codec descriptor (eg. “mp4a.40.2”)
  • media_type: 2 (2 = audio)
  • representation: identifier for this rung (eg: audioaudio_aac@96000")
  • stream_index: audio stream index (eg: 1, 2, …)
  • stream_label: display lable for this audio stream (if not present, this stream will not be available for playout)
  • stream_name: audio stream name (eg: “audio_1”, “audio_2”)
  • lang: audio language, in standard format (eg: eng, spa)
  • default: bool - default audio stream (the player will autoselect this stream)

Example:

        "ladder_specs": [
          {
            "bit_rate": 95000000,
            "codecs": "avc1.640028,mp4a.40.2",
            "height": 1080,
            "media_type": 1,
            "representation": "videovideo_1920x1080_h264@95000000",
            "stream_index": 0,
            "stream_name": "video",
            "width": 1920
          },
          {
            "bit_rate": 4500000,
            "codecs": "avc1.64001F,mp4a.40.2",
            "height": 720,
            "media_type": 1,
            "representation": "videovideo_1920x1080_h264@4500000",
            "stream_index": 0,
            "stream_name": "video",
            "width": 1280
          },
          {
            "bit_rate": 500000,
            "codecs": "avc1.42C01E,mp4a.40.2",
            "height": 360,
            "media_type": 1,
            "representation": "videovideo_1920x1080_h264@500000",
            "stream_index": 0,
            "stream_name": "video",
            "width": 640
          },
          {
            "bit_rate": 192000,
            "channels": 2,
            "codecs": "mp4a.40.2",
            "lang": "eng",
            "default": true,
            "media_type": 2,
            "representation": "audioaudio_aac@96000",
            "stream_index": 1,
            "stream_label": "English",
            "stream_name": "audio_1"
          },
          {
            "bit_rate": 192000,
            "channels": 2,
            "codecs": "mp4a.40.2",
            "lang": "spa",
            "media_type": 2,
            "representation": "audioaudio_aac@96000",
            "stream_index": 2,
            "stream_label": "Spanish",
            "stream_name": "audio_2"
          }
        ]

Playout Features

Playout features configuration is available under live_recording / playout_config

  • dvr_enabled: bool - allow players to seek back (aka DVR playout)
  • dvr_max_duration: secs - players may only seek back this period
  • dvr_start_time: ISO - players may only seek back to this particular time
  • rebroadcast_start_time_sec_epoch: EPOCH - rebroadcast a previously recorded stream starting at this time
  • vod_enabled: bool - allow players to play a completed recording as vod
  • scte_enabled: bool - always pass SCTE events through to HLS and DASH outputs

Example:

    "playout_config": {
      "dvr_enabled": true,
      "dvr_max_duration": 0,
      "rebroadcast_start_time_sec_epoch": 0,
      "vod_enabled": false,
      "scte_enabled": false
    }

DRM

Playout formats and DRM are configured for each ‘offering’, under offering / default / playout_formats

Each format + DRM combination is represented by an element in the playout formats object, and must contain:

  • protocol.type: ProtoDash | ProtoHls
  • drm section:
    • enc_scheme_name: cenc | cbcs
    • type: DrmWidevine | DrmAes128 | DrmSampleAes | DrmFairplay | DrmPlayready

Optionally the drm section may contain:

  • audio_clear: always|on_demand|never Allows a client to request clear audio or forces clear audio (always)
  • ext_params:
    • asset_id: external DRM asset ID

Example:

{
        "playout_formats": {
          "dash-clear": {
            "drm": null,
            "protocol": {
              "min_buffer_length": 2,
              "type": "ProtoDash"
            }
          },
          "dash-widevine": {
            "drm": {
              "audio_clear": "always",
              "content_id": "",
              "enc_scheme_name": "cenc",
              "license_servers": [],
              "type": "DrmWidevine"
            },
            "protocol": {
              "min_buffer_length": 2,
              "type": "ProtoDash"
            }
          },
          "hls-aes128": {
            "drm": {
              "audio_clear": "always",
              "enc_scheme_name": "aes-128",
              "type": "DrmAes128"
            },
            "protocol": {
              "type": "ProtoHls"
            }
          },
          "hls-clear": {
            "drm": null,
            "protocol": {
              "type": "ProtoHls"
            }
          },
          "hls-fairplay": {
            "drm": {
              "audio_clear": "always",
              "enc_scheme_name": "cbcs",
              "license_servers": [],
              "type": "DrmFairplay"
            },
            "protocol": {
              "type": "ProtoHls"
            }
          },
          "hls-playready-cenc": {
            "drm": {
              "enc_scheme_name": "cenc",
              "type": "DrmPlayReady"
            },
            "protocol": {
              "type": "ProtoHls"
            }
          },
          "hls-sample-aes": {
            "drm": {
              "audio_clear": "always",
              "enc_scheme_name": "cbcs",
              "type": "DrmSampleAes"
            },
            "protocol": {
              "type": "ProtoHls"
            }
          },
          "hls-widevine-cenc": {
            "drm": {
              "enc_scheme_name": "cenc",
              "type": "DrmWidevine"
            },
            "protocol": {
              "type": "ProtoHls"
            }
          }
        }
}

External DRM

Example:

  "hls-fairplay": {
    "drm": {
      "audio_clear": "always",
      "enc_scheme_name": "cbcs",
      "ext_params": {
        "asset_id": "eluvio_001"
      },
      "license_servers": [],
      "type": "DrmFairplay"
    },
    "protocol": {
      "type": "ProtoHls"
    }
  }