shaka-packager/html/tutorials/dash.html

410 lines
20 KiB
HTML
Raw Normal View History

2018-02-10 23:37:42 +00:00
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>DASH &#8212; Shaka Packager documentation</title>
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinxdoc_new.css" type="text/css" />
<link rel="stylesheet" type="text/css" href="../_static/graphviz.css" />
<link rel="stylesheet" type="text/css" href="../_static/table_styling.css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="HLS" href="hls.html" />
<link rel="prev" title="Basic Usage" href="basic_usage.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="hls.html" title="HLS"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="basic_usage.html" title="Basic Usage"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Shaka Packager documentation</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="tutorials.html" accesskey="U">Tutorials</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">DASH</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="dash">
<h1>DASH<a class="headerlink" href="#dash" title="Permalink to this headline"></a></h1>
<p>Dynamic Adaptive Streaming over HTTP (DASH) is an adaptive bitrate streaming
technique that enables high quality streaming of media content over HTTP.</p>
<p>Shaka Packager supports DASH content packaging. This tutorial covers DASH
packaging of VOD content without encryption. For live content packaging, see
2018-02-10 23:37:42 +00:00
<a class="reference internal" href="live.html"><span class="doc">Live</span></a>; for content encryption, see <a class="reference internal" href="drm.html"><span class="doc">DRM</span></a>; for full documentation,
see <a class="reference internal" href="../documentation.html"><span class="doc">Packager Documentation</span></a>.</p>
<div class="section" id="synopsis">
<h2>Synopsis<a class="headerlink" href="#synopsis" title="Permalink to this headline"></a></h2>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ packager &lt;stream_descriptor&gt; ... \
2018-05-23 23:12:00 +00:00
--mpd_output &lt;manifest_output_path&gt; \
[Other DASH options] \
[Other options, e.g. DRM options, HLS options]
</pre></div>
</div>
<p>See <a class="reference internal" href="#dash-options">DASH options</a> for the available DASH related options.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>DASH and HLS options can both be specified to output DASH and HLS manifests
at the same time. Note that it works only for MP4 outputs.</p>
</div>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline"></a></h2>
<p>The examples below uses the H264 streams created in <a class="reference internal" href="encoding.html"><span class="doc">Media Encoding</span></a>. It can be
applied to VP9 in the same way.</p>
<ul>
<li><p>on-demand:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ packager \
in=h264_baseline_360p_600.mp4,stream=audio,output=audio.mp4 \
2018-02-10 23:37:42 +00:00
in=input_text.vtt,stream=text,output=output_text.vtt \
in=h264_baseline_360p_600.mp4,stream=video,output=h264_360p.mp4 \
in=h264_main_480p_1000.mp4,stream=video,output=h264_480p.mp4 \
in=h264_main_720p_3000.mp4,stream=video,output=h264_720p.mp4 \
in=h264_high_1080p_6000.mp4,stream=video,output=h264_1080p.mp4 \
--mpd_output h264.mpd
</pre></div>
</div>
</li>
</ul>
<p>The above packaging command creates five single track fragmented mp4 streams
2018-08-16 00:35:22 +00:00
(4 video, 1 audio), a subtitle file and a manifest, which describes the streams.</p>
<ul>
<li><p>on-demand with trick-play tracks:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ packager \
2018-08-16 00:35:22 +00:00
in=h264_baseline_360p_600.mp4,stream=audio,output=audio.mp4 \
in=input_text.vtt,stream=text,output=output_text.vtt \
in=h264_baseline_360p_600.mp4,stream=video,output=h264_360p.mp4 \
in=h264_main_480p_1000.mp4,stream=video,output=h264_480p.mp4 \
in=h264_main_720p_3000.mp4,stream=video,output=h264_720p.mp4 \
in=h264_high_1080p_6000.mp4,stream=video,output=h264_1080p.mp4 \
in=h264_main_480p_1000.mp4,stream=video,output=h264_480p.mp4,trick_play_factor=1 \
in=h264_high_1080p_6000.mp4,stream=video,output=h264_1080p.mp4,trick_play_factor=1 \
--mpd_output h264.mpd
</pre></div>
</div>
</li>
</ul>
<p>The above packaging command creates two extra trick play tracks, besides the files
generated with the previous command.</p>
<ul>
<li><p>static-live:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ packager \
2018-02-10 23:37:42 +00:00
&#39;in=h264_baseline_360p_600.mp4,stream=audio,init_segment=audio/init.mp4,segment_template=audio/$Number$.m4s&#39; \
&#39;in=input_text.vtt,stream=text,init_segment=text/init.mp4,segment_template=text/$Number$.m4s&#39; \
&#39;in=h264_baseline_360p_600.mp4,stream=video,init_segment=h264_360p/init.mp4,segment_template=h264_360p/$Number$.m4s&#39; \
&#39;in=h264_main_480p_1000.mp4,stream=video,init_segment=h264_480p/init.mp4,segment_template=h264_480p/$Number$.m4s&#39; \
&#39;in=h264_main_720p_3000.mp4,stream=video,init_segment=h264_720p/init.mp4,segment_template=h264_720p/$Number$.m4s&#39; \
2018-08-16 00:35:22 +00:00
&#39;in=h264_high_1080p_6000.mp4,stream=video,init_segment=h264_1080p/init.mp4,segment_template=h264_1080p/$Number$.m4s&#39; \
--generate_static_live_mpd --mpd_output h264.mpd
</pre></div>
</div>
</li>
</ul>
<p>The above packaging command creates five groups of segments (each with an init
segment and a series of media segments) for the five streams and a manifest,
which describes the streams.</p>
2018-02-10 23:37:42 +00:00
<ul>
<li><p>Single file MP4 output with DASH + HLS:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ packager \
2018-02-10 23:37:42 +00:00
in=h264_baseline_360p_600.mp4,stream=audio,output=audio.mp4,playlist_name=audio.m3u8,hls_group_id=audio,hls_name=ENGLISH \
in=h264_baseline_360p_600.mp4,stream=video,output=h264_360p.mp4,playlist_name=h264_360p.m3u8,iframe_playlist_name=h264_360p_iframe.m3u8 \
in=h264_main_480p_1000.mp4,stream=video,output=h264_480p.mp4,playlist_name=h264_480p.m3u8,iframe_playlist_name=h264_480p_iframe.m3u8 \
in=h264_main_720p_3000.mp4,stream=video,output=h264_720p.mp4,playlist_name=h264_720p.m3u8,iframe_playlist_name=h264_720p_iframe.m3u8 \
in=h264_high_1080p_6000.mp4,stream=video,output=h264_1080p.mp4,playlist_name=h264_1080p.m3u8,iframe_playlist_name=h264_1080p_iframe.m3u8 \
--hls_master_playlist_output h264_master.m3u8 \
--mpd_output h264.mpd
</pre></div>
</div>
</li>
</ul>
<p>The above packaging command creates five single file MP4 streams, and HLS
playlists as well as DASH manifests.</p>
<ul>
<li><p>Output DASH + HLS with dash_only and hls_only options:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ packager \
&#39;in=h264_baseline_360p_600.mp4,stream=audio,init_segment=audio/init.mp4,segment_template=audio/$Number$.m4s&#39; \
&#39;in=input_text.vtt,stream=text,init_segment=text/init.mp4,segment_template=text/$Number$.m4s,dash_only=1&#39; \
&#39;in=input_text.vtt,stream=text,segment_template=text/$Number$.vtt,hls_only=1&#39; \
&#39;in=h264_baseline_360p_600.mp4,stream=video,init_segment=h264_360p/init.mp4,segment_template=h264_360p/$Number$.m4s&#39; \
&#39;in=h264_main_480p_1000.mp4,stream=video,init_segment=h264_480p/init.mp4,segment_template=h264_480p/$Number$.m4s&#39; \
&#39;in=h264_main_720p_3000.mp4,stream=video,init_segment=h264_720p/init.mp4,segment_template=h264_720p/$Number$.m4s&#39; \
&#39;in=h264_high_1080p_6000.mp4,stream=video,init_segment=h264_1080p/init.mp4,segment_template=h264_1080p/$Number$.m4s&#39; \
--generate_static_live_mpd --mpd_output h264.mpd \
--hls_master_playlist_output h264_master.m3u8
</pre></div>
</div>
</li>
</ul>
<p>The above packaging command creates HLS playlists and DASH manifest while using
dash_only for creating segmented WebVTT in mp4 format and hls_only option for
creating WebVTT in text format.</p>
</div>
<div class="section" id="configuration-options">
<h2>Configuration options<a class="headerlink" href="#configuration-options" title="Permalink to this headline"></a></h2>
<div class="section" id="dash-specific-stream-descriptor-fields">
<h3>DASH specific stream descriptor fields<a class="headerlink" href="#dash-specific-stream-descriptor-fields" title="Permalink to this headline"></a></h3>
<dl class="field-list simple">
<dt class="field-odd">dash_accessibilities (accessibilities)</dt>
<dd class="field-odd"><p>Optional semicolon separated list of values for DASH Accessibility element.
The value should be in the format: scheme_id_uri=value, which propagates
to the Accessibility element in the result DASH manifest. See DASH
(ISO/IEC 23009-1) specification for details.</p>
</dd>
<dt class="field-even">dash_roles (roles)</dt>
<dd class="field-even"><p>Optional semicolon separated list of values for DASH Role element. The
value should be one of: <strong>caption</strong>, <strong>subtitle</strong>, <strong>main</strong>, <strong>alternate</strong>,
<strong>supplementary</strong>, <strong>commentary</strong> and <strong>dub</strong>. See DASH (ISO/IEC 23009-1)
specification for details.</p>
</dd>
</dl>
</div>
<div class="section" id="dash-options">
<h3>DASH options<a class="headerlink" href="#dash-options" title="Permalink to this headline"></a></h3>
<dl class="option-list">
<dt><kbd><span class="option">--generate_static_live_mpd</span></kbd></dt>
<dd><p>If enabled, generates static mpd. If segment_template is specified in
stream descriptors, shaka-packager generates dynamic mpd by default; if
this flag is enabled, shaka-packager generates static mpd instead. Note
that if segment_template is not specified, shaka-packager always generates
static mpd regardless of the value of this flag.</p>
</dd>
<dt><kbd><span class="option">--mpd_output <var>&lt;file_path&gt;</var></span></kbd></dt>
<dd><p>MPD output file name.</p>
</dd>
<dt><kbd><span class="option">--base_urls <var>&lt;comma_separated_urls&gt;</var></span></kbd></dt>
<dd><dl class="simple">
<dt>Comma separated BaseURLs for the MPD:</dt><dd><p><strong>&lt;url&gt;[,&lt;url&gt;]…</strong>.</p>
</dd>
2018-05-23 23:12:00 +00:00
</dl>
<p>The values will be added as &lt;BaseURL&gt; element(s) immediately under the &lt;MPD&gt;
2018-05-23 23:12:00 +00:00
element.</p>
</dd>
<dt><kbd><span class="option">--min_buffer_time <var>&lt;seconds&gt;</var></span></kbd></dt>
<dd><p>Specifies, in seconds, a common duration used in the definition of the MPD
Representation data rate.</p>
</dd>
<dt><kbd><span class="option">--minimum_update_period <var>&lt;seconds&gt;</var></span></kbd></dt>
<dd><p>Indicates to the player how often to refresh the media presentation
description in seconds. This value is used for dynamic MPD only.</p>
</dd>
<dt><kbd><span class="option">--suggested_presentation_delay <var>&lt;seconds&gt;</var></span></kbd></dt>
<dd><p>Specifies a delay, in seconds, to be added to the media presentation time.
This value is used for dynamic MPD only.</p>
</dd>
<dt><kbd><span class="option">--time_shift_buffer_depth <var>&lt;seconds&gt;</var></span></kbd></dt>
<dd><p>Guaranteed duration of the time shifting buffer for dynamic media
presentations, in seconds.</p>
</dd>
<dt><kbd><span class="option">--preserved_segments_outside_live_window <var>&lt;num_segments&gt;</var></span></kbd></dt>
<dd><p>Segments outside the live window (defined by <cite>time_shift_buffer_depth</cite>
2018-05-23 23:12:00 +00:00
above) are automatically removed except for the most recent X segments
defined by this parameter. This is needed to accommodate latencies in
various stages of content serving pipeline, so that the segments stay
accessible as they may still be accessed by the player.</p>
<p>The segments are not removed if the value is zero.</p>
</dd>
<dt><kbd><span class="option">--utc_timings <var>&lt;scheme_id_uri_value_pairs&gt;</var></span></kbd></dt>
<dd><dl class="simple">
<dt>Comma separated UTCTiming schemeIdUri and value pairs for the MPD:</dt><dd><p><strong>&lt;scheme_id_uri&gt;=&lt;value&gt;[,&lt;scheme_id_uri&gt;=&lt;value&gt;]…</strong></p>
</dd>
2018-05-23 23:12:00 +00:00
</dl>
<p>This value is used for dynamic MPD only.</p>
</dd>
<dt><kbd><span class="option">--default_language <var>&lt;language&gt;</var></span></kbd></dt>
<dd><p>Any audio/text tracks tagged with this language will have
&lt;Role … value=&quot;main&quot; /&gt; in the manifest. This allows the player to
choose the correct default language for the content.</p>
<p>This applies to both audio and text tracks. The default language for text
tracks can be overriden by default_text_language.</p>
</dd>
<dt><kbd><span class="option">--default_text_language <var>&lt;text_language&gt;</var></span></kbd></dt>
<dd><p>Same as above, but this applies to text tracks only, and overrides the
default language for text tracks.</p>
</dd>
<dt><kbd><span class="option">--allow_approximate_segment_timeline</span></kbd></dt>
<dd><p>For live profile only.</p>
2018-05-23 23:12:00 +00:00
<p>If enabled, segments with close duration (i.e. with difference less than
one sample) are considered to have the same duration. This enables
MPD generator to generate less SegmentTimeline entries. If all segments
are of the same duration except the last one, we will do further
optimization to use <a class="reference external" href="mailto:SegmentTemplate&#37;&#52;&#48;duration">SegmentTemplate<span>&#64;</span>duration</a> instead and omit
SegmentTimeline completely.</p>
<p>Ignored if $Time$ is used in segment template, since $Time$ requires
2018-05-23 23:12:00 +00:00
accurate Segment Timeline.</p>
</dd>
</dl>
<p>dash_only=0|1</p>
<blockquote>
<div><p>Optional. Defaults to 0 if not specified. If it is set to 1, indicates the
stream is DASH only.</p>
</div></blockquote>
<dl class="option-list">
<dt><kbd><span class="option">--allow_codec_switching</span></kbd></dt>
<dd><p>If enabled, allow adaptive switching between different codecs, if they have
the same language, media type (audio, video etc) and container type.</p>
</dd>
</dl>
</div>
<div class="section" id="segment-template-formatting">
<h3>Segment template formatting<a class="headerlink" href="#segment-template-formatting" title="Permalink to this headline"></a></h3>
<p>The implementation is based on <em>Template-based Segment URL construction</em>
described in ISO/IEC 23009-1:2014.</p>
<table class="styled-table docutils align-default" id="id1">
<caption><span class="caption-text">Supported identifiers</span><a class="headerlink" href="#id1" title="Permalink to this table"></a></caption>
<colgroup>
<col style="width: 19%" />
<col style="width: 41%" />
<col style="width: 41%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="left-align head"><p>$&lt;Identifier&gt;$</p></th>
<th class="left-align head"><p>Substitution parameter</p></th>
<th class="left-align head"><p>Format</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td class="left-align"><p>$$</p></td>
<td class="left-align"><p>is an escape sequence, i.e.
2018-02-10 23:37:42 +00:00
“$$” is replaced with a single
“$”.</p></td>
<td class="left-align"><p>Not applicable.</p></td>
</tr>
<tr class="row-odd"><td class="left-align"><p>$Number$</p></td>
<td class="left-align"><p>This identifier is substitued
with the <em>number</em> of the
corresponding Segment.</p></td>
<td class="left-align"><p>The format tag may be present.</p>
<p>If no format tag is present, a
default format tag with
<em>width</em>=1 shall be used.</p>
</td>
</tr>
<tr class="row-even"><td class="left-align"><p>$Time$</p></td>
<td class="left-align"><p>This identifier is substituted
with the value of the
<strong>SegmentTimeline&#64;t</strong>
attribute for the Segment
being accessed. Either
$Number$ or $Time$ may be used
but not both at the same time.</p></td>
<td class="left-align"><p>The format tag may be present.</p>
<p>If no format tag is present, a
default format tag with
<em>width</em>=1 shall be used.</p>
</td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Identifiers $RepresentationID$ and $Bandwidth$ are not supported in this
version. Please file an <a class="reference external" href="https://github.com/google/shaka-packager/issues">issue</a> if you want it to be
supported.</p>
</div>
<p>In each URL, the identifiers shall be replaced by the substitution parameter
per the definition in the above table. Identifier matching is case-sensitive.</p>
2018-02-10 23:37:42 +00:00
<p>Each identifier may be suffixed, within the enclosing $ characters, with an
additional format tag aligned with the <em>printf</em> format tag as defined in IEEE
1003.1-2008 following this prototype:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span><span class="mi">0</span><span class="p">[</span><span class="n">width</span><span class="p">]</span><span class="n">d</span>
</pre></div>
</div>
<p>The <em>width</em> 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.</p>
<p>Strings outside identifiers shall only contain characters that are permitted
within URLs according to RFC 3986.</p>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">DASH</a><ul>
<li><a class="reference internal" href="#synopsis">Synopsis</a></li>
<li><a class="reference internal" href="#examples">Examples</a></li>
<li><a class="reference internal" href="#configuration-options">Configuration options</a><ul>
<li><a class="reference internal" href="#dash-specific-stream-descriptor-fields">DASH specific stream descriptor fields</a></li>
<li><a class="reference internal" href="#dash-options">DASH options</a></li>
<li><a class="reference internal" href="#segment-template-formatting">Segment template formatting</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="basic_usage.html"
title="previous chapter">Basic Usage</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="hls.html"
title="next chapter">HLS</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/tutorials/dash.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="hls.html" title="HLS"
>next</a> |</li>
<li class="right" >
<a href="basic_usage.html" title="Basic Usage"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Shaka Packager documentation</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="tutorials.html" >Tutorials</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">DASH</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2017, Google.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.4.3.
</div>
</body>
</html>