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 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

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”)

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",
            "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",
            "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

Example:

    "playout_config": {
      "dvr_enabled": true,
      "dvr_max_duration": 0,
      "rebroadcast_start_time_sec_epoch": 0,
      "vod_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"
    }
  }