Live

A typical live source is UDP multicast, which is the only live protocol packager supports directly right now.

For other unsupported protocols, you can use FFmpeg to pipe the input. See FFmpeg piping for details.

Examples

The command is similar to the on-demand, see DASH and HLS.

Here are some examples.

  • DASH:

    $ packager \
  'in=udp://225.1.1.8:8001?interface=172.29.46.122,stream=audio,init_segment=audio_init.mp4,segment_template=audio_$Number$.m4s' \
  'in=udp://225.1.1.8:8001?interface=172.29.46.122,stream=video,init_segment=h264_360p_init.mp4,segment_template=h264_360p_$Number$.m4s' \
  'in=udp://225.1.1.8:8002?interface=172.29.46.122,stream=video,init_segment=h264_480p_init.mp4,segment_template=h264_480p_$Number$.m4s' \
  'in=udp://225.1.1.8:8003?interface=172.29.46.122,stream=video,init_segment=h264_720p_init.mp4,segment_template=h264_720p_$Number$.m4s' \
  'in=udp://225.1.1.8:8004?interface=172.29.46.122,stream=video,init_segment=h264_1080p_init.mp4,segment_template=h264_1080p_$Number$.m4s' \
  --mpd_output h264.mpd

  • HLS:

    $ packager \
  'in=udp://225.1.1.8:8001?interface=172.29.46.122,stream=audio,init_segment=audio_init.mp4,segment_template=audio_$Number$.m4s,playlist_name=audio.m3u8,hls_group_id=audio,hls_name=ENGLISH' \
  'in=udp://225.1.1.8:8001?interface=172.29.46.122,stream=video,init_segment=h264_360p_init.mp4,segment_template=h264_360p_$Number$.m4s,playlist_name=h264_360p.m3u8' \
  'in=udp://225.1.1.8:8002?interface=172.29.46.122,stream=video,init_segment=h264_480p_init.mp4,segment_template=h264_480p_$Number$.m4s,playlist_name=h264_480p.m3u8' \
  'in=udp://225.1.1.8:8003?interface=172.29.46.122,stream=video,init_segment=h264_720p_init.mp4,segment_template=h264_720p_$Number$.m4s,playlist_name=h264_720p.m3u8' \
  'in=udp://225.1.1.8:8004?interface=172.29.46.122,stream=video,init_segment=h264_1080p_init.mp4,segment_template=h264_1080p_$Number$.m4s,playlist_name=h264_1080p.m3u8' \
  --hls_master_playlist_output h264_master.m3u8 \
  --hls_playlist_type LIVE

Note

Packager supports removing old segments automatically. See preserved_segments_outside_live_window option in DASH options or HLS options for details.

Note

Shaka Packager ensures all segments referenced in DASH manifest / HLS playlists are available, by updating the manifest / playlists only after a segment is completed.

However, if content is not served directly from packaging output location, extra care must be taken outside of packager to avoid updating manifest / playlists without updating media segments.

Here is an example flow that avoids potential race condition. The following steps should be done SERIALLY AND IN ORDER in every sync loop when uploading manifest / playlists and media segments to content server:

  1. Upload manifest / playlists under different names
  2. Upload / Sync media segments
  3. Rename uploaded manifest / playlists back to the original names

UDP file options

UDP file is of the form:

udp://<ip>:<port>[?<option>[&<option>]...]

Here is the list of supported options:

buffer_size=<size_in_bytes>:
 UDP maximum receive buffer size in bytes. Note that although it can be set to any value, the actual value is capped by maximum allowed size defined by the underlying operating system. On linux, the maximum size allowed can be retrieved using sysctl net.core.rmem_max and configured using sysctl -w net.core.rmem_max=<size_in_bytes>.
interface=<addr>:
 Multicast group interface address. Only the packets sent to this address are received. Default to “0.0.0.0” if not specified.
reuse=0|1:Allow or disallow reusing UDP sockets.
source=<addr>:Multicast source ip address. Only the packets sent from this source address are received. Enables Source Specific Multicast (SSM) if set.
timeout=<microseconds>:
 UDP timeout in microseconds.

Example:

udp://224.1.2.30:88?interface=10.11.12.13&reuse=1

Note

UDP is by definition unreliable. There could be packets dropped.

UDP packets do not get lost magically. There are things you can do to minimize the packet loss. A common cause of packet loss is buffer overrun, either in send buffer or receive buffer.

On Linux, you can check UDP errors by monitoring the output from netstat -suna command.

If there is an increase in send buffer errors from the netstat output, then try increasing buffer_size in [FFmpeg](https://ffmpeg.org/ffmpeg-protocols.html#udp).

If there is an increase in receive buffer errors, then try increasing buffer_size in UDP options (See above) or increasing –io_cache_size. buffer_size in UDP options defines the UDP buffer size of the underlying system while io_cache_size defines the size of the internal circular buffer managed by Shaka Packager.

Segment template formatting

The implementation is based on Template-based Segment URL construction described in ISO/IEC 23009-1:2014.

Supported identifiers
$<Identifier>$ Substitution parameter Format
$$ is an escape sequence, i.e. “$$” is replaced with a single “$”. Not applicable.
$Number$ This identifier is substitued with the number of the corresponding Segment.

The format tag may be present.

If no format tag is present, a default format tag with width=1 shall be used.
$Time$ This identifier is substituted with the value of the SegmentTimeline@t attribute for the Segment being accessed. Either $Number$ or $Time$ may be used but not both at the same time.

The format tag may be present.

If no format tag is present, a default format tag with width=1 shall be used.

Note

Identifiers $RepresentationID$ and $Bandwidth$ are not supported in this version. Please file an issue if you want it to be supported.

In each URL, the identifiers shall be replaced by the substitution parameter per the definition in the above table. Identifier matching is case-sensitive.

Each identifier may be suffixed, within the enclosing ‘$’ characters, with an additional format tag aligned with the printf format tag as defined in IEEE 1003.1-2008 following this prototype:

%0[width]d

The width parameter is an unsigned integer that provides the minimum number of characters to be printed. If the value to be printed is shorter than this number, the result shall be padded with zeros. The value is not truncated even if the result is larger.

Strings outside identifiers shall only contain characters that are permitted within URLs according to RFC 3986.