MPEG-DASH Packaging using GPAC’s mp4box Tool

GPAC is a versatile toolkit that can package and encrypt videos for transmission using the MPEG-DASH protocol. In this edition of the Hitchhiker’s Guide to MPEG-DASH, we dig into the GPAC MPEG-DASH tools. GPAC is available as both free, LGPL open-source, and under a paid commercial license, and very easy to use – as we’ll see in this tutorial.

---

MPEG-DASH is one of the most popular video-streaming protocols and is widely used to deliver media via Video on Demand (VOD) or Live Streaming to various end-user devices, including smartphones, tablets, SmartTVs, gaming consoles, and more.

Fundamental to the MPEG-DASH protocol is the manifest or MPD (Media Presentation Description) created when the media is packaged and prepared for transmission via DASH.

In this tutorial, we shall take a deep look at the popular GPAC set of tools and learn how to use GPAC’s mp4box tool to create MPEG-DASH compliant streams.

So, let’s get packaging!

GPAC Toolkit licensing

The GPAC toolkit developer licenses it under the LGPL v2.1 license. A non-GPL commercial license is also available.

Supported Platforms

GPAC is available with pre-compiled binaries for Windows (32 and 64 bit), macOS, Ubuntu Linux (32 and 64 bit), iOS 4.2+, and Android 2.1+. Cross-compiling for GCC+X11 and GCC+SDL platforms are also supported.

Getting the GPAC Toolkit

There are two ways to get hold of the GPAC toolkit –

1. Go to GPAC’s GitHub page and download the latest release.
2. Or, go to the GPAC website’s downloads page to download binaries for Windows, macOSX, Linux, iOS, and Android.

After you download and install it on your system, you are ready to package your videos into the MPEG-DASH protocol. Let’s learn how in the following sections.

GPAC provides a single command-line tool, mp4box, to do the fragmenting and packaging.

Packaging an On-Demand Video

Step 0: Content Preparation

The packager doesn’t change the actual video encoding – just the file packaging format. You need to encode the content for streaming before you get to the actual packaging. Encoding a video for streaming is a whole subject on its own, but here are the key things to remember.

• Codecs: HEVC is the most efficient video codec currently in use, but it is not as widely supported as H264. MPEG DASH allows you to encode the video using both codecs, each in its own Adaptation Set.
• Bitrates/Resolutions: Adaptive Bitrate (ABR) streaming lets you encode the video in a range of bitrates and resolutions, allowing for uninterrupted viewing under a wide range of network bandwidths.
• GOP Length: MPEG DASH requires all of the Representations in an Adaptation Set to have the same GOP length. Consistent GOP lengths allow the media player to switch representations from one segment to the next. Each segment will contain one or more GOPs. For example, if the GOP length is 2 seconds, you can package the content with segments that are 2 seconds, 4 seconds, 6 seconds, etc.

Note: read OTTVerse’s Introduction to Video Encoding for a deeper look at video compression.

For the rest of this tutorial, we will be using a video encoded in four different resolutions:

myvideo_1920x1080.mp4
myvideo_1280x720.mp4
myvideo_640x360.mp4
myvideo_320x180.mp4

Step 1: Fragmenting the Video

The GPAC mp4box command-line tool fragments the video during the packaging step. You do not need to fragment the video files before packaging.

Step 2: Packaging the Video

GPAC provides two different methods for packaging DASH content. Both ways combine the audio and video in a single file. 

• The default method creates one file for each representation, where the individual segments are accessed using HTTP byte ranges. A result is a small number of media files but a relatively large MPD file, where each segment is defined individually with the corresponding byte range.
• The alternative method creates separate files for each segment. The result is lots of segment files but a relatively small MPD file using segment templates.

Packaging with Byte-Range Segments

To prepare DASH content with mp4box using HTTP range requests, the only required parameter is -dash followed by the segment duration in mS, plus the video file names. 

$ mp4box -dash 4000 \
  myvideo_1920x1080.mp4 \
  myvideo_1280x720.mp4 \
  myvideo_640x360.mp4 \
  myvideo_320x180.mp4

A better way is also to use the -out parameter. You can specify the directory for the files and the name of the MPD file. If the specified directory does not exist, the packager will create it for you.

$ mp4box -dash 4000 -out gpac_range/myvideo myvideo_1920x1080.mp4 myvideo_1280x720.mp4 myvideo_640x360.mp4 myvideo_320x180.mp4

Be aware that the MPD file will have a Segment URL for each segment of each Representation, making for a very large MPD if the content is long. For short videos, the smaller number of video files to manage might make this a good choice.

Packaging with Individual Segment Files

To keep the MPD file small, you will want to break the video into individual segments. The packager uses segment templates to define the segment file names, with only one template per representation.

Use the -segment-name parameter to tell the packager to break the video into individual segment files. The -segment-name parameter supports replacement strings to simplify the file names. These are the same replacement strings used in the MPD. My favorites are $RepresentationID$ and $Number%0Nd$.

For example -segment-name ‘$RepresentationID$_$Number%03d$$init=init$' will create segment file names like 1_0001.m4s and 4_324.m4s and init file names like 2_init.mp4. Padding the file names with zeros helps the OS sort them correctly in directory listings. Remember to put single quotes around the -segment-name definition to keep the OS from recognizing the $ and % as special characters.

$ mp4box -dash 4000 \
  -out gpac_segment/myvideo \
  -segment-name '$RepresentationID$_$Number%03d$' \
  myvideo_1920x1080.mp4 \
  myvideo_1280x720.mp4 \
  myvideo_640x360.mp4 \
  myvideo_320x180.mp4

Here is the resulting DASH MPD file myvideo.mpd.

<?xml version="1.0"?>
<!-- MPD file Generated with GPAC version 1.1.0-DEV-rev713-gd36331fb-master at 2021-04-13T18:49:21.936Z -->
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" minBufferTime="PT1.500S" type="static" mediaPresentationDuration="PT0H5M39.243S" maxSegmentDuration="PT0H0M4.000S" profiles="urn:mpeg:dash:profile:full:2011">
 <ProgramInformation moreInformationURL="http://gpac.io">
  <Title>myvideo.mpd generated by GPAC</Title>
 </ProgramInformation>

 <Period duration="PT0H5M39.243S">
  <AdaptationSet segmentAlignment="true" maxWidth="1920" maxHeight="1080" maxFrameRate="50" par="16:9" lang="und" startWithSAP="1">
   <ContentComponent id="1" contentType="video"/>
   <ContentComponent id="2" contentType="audio"/>
   <Representation id="1" mimeType="video/mp4" codecs="avc1.64002A,mp4a.40.2" width="1920" height="1080" frameRate="50" sar="1:1" bandwidth="2566319">
    <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
    <SegmentTemplate media="$RepresentationID$_$Number%03d$.m4s" initialization="$RepresentationID$_init.mp4" timescale="12800" startNumber="1" duration="51200"/>
   </Representation>
   <Representation id="2" mimeType="video/mp4" codecs="avc1.640020,mp4a.40.2" width="1280" height="720" frameRate="50" sar="1:1" bandwidth="1405236">
    <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
    <SegmentTemplate media="$RepresentationID$_$Number%03d$.m4s" initialization="$RepresentationID$_init.mp4" timescale="12800" startNumber="1" duration="51200"/>
   </Representation>
   <Representation id="3" mimeType="video/mp4" codecs="avc1.64001F,mp4a.40.2" width="640" height="360" frameRate="50" sar="1:1" bandwidth="465953">
    <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
    <SegmentTemplate media="$RepresentationID$_$Number%03d$.m4s" initialization="$RepresentationID$_init.mp4" timescale="12800" startNumber="1" duration="51200"/>
   </Representation>
   <Representation id="4" mimeType="video/mp4" codecs="avc1.640015,mp4a.40.2" width="320" height="180" frameRate="50" sar="1:1" bandwidth="157418">
    <AudioChannelConfiguration schemeIdUri="urn:mpeg:dash:23003:3:audio_channel_configuration:2011" value="2"/>
    <SegmentTemplate media="$RepresentationID$_$Number%03d$.m4s" initialization="$RepresentationID$_init.mp4" timescale="12800" startNumber="1" duration="51200"/>
   </Representation>
  </AdaptationSet>
 </Period>
</MPD>

Step 3: Publishing the video

Now that we have the video packaged, the final step is to put it onto a web server for streaming.  Copy the entire contents of the output directory to your web server, and make sure to set the MIME TYPE of .mpd files to application/dash+xml so that the web browser will know to send it to the DASH player.

Packaging a Live Video

GPAC also supports real-time DASH packaging for Live video. There are two essential differences. You will use named pipes instead of actual media files on the input side. You need to push the packaged media files and manifests to the server promptly to minimize latency on the output side. See the basic architecture below.

Live Packaging Parameters

The mp4box parameters are slightly different for live packaging.

• -dash-live sets the segment duration in mS and tells the packager that this is a live stream that will continue until canceled.
• -out sets the output location, the same as VOD.
• -segment-name defines the segment names, the same as VOD.
• -profile sets the DASH MPD profile. For live use the live profile.
• -mpd-duration defines the MPD duration in seconds. The MPD duration controls how long segments remain in the MPD, allowing users to seek backward and replay. For example, a value of 900 will enable the users to go back up to 15 minutes.
• -mpd-refresh defines the MPD update frequency in seconds. Set it to match the segment duration.

The resulting command is:

$ mp4box -dash-live 4000 \
  -out gpac_live/myvideo \
  -segment-name '$RepresentationID$_$Number%03d$' \
  -profile live \
  -mpd-duration 900 \
  -mpd-refresh 4 \
  1080p.h264 \
  720p.h264 \
  360p.h264 \
  180p.h264 \
  audio.aac 

Conclusion

Thanks for reading this tutorial on MPEG-DASH packaging using GPAC mp4box. I hope this helped you create MPEG-DASH-compliant bitstreams and you were able to successfully stream your content to a DASH-compliant player.

If you are eager to learn MPEG-DASH, then these articles will interest you for sure!

• What is MPEG-DASH – a deep dive into the basics.
• Structure of a MPEG-DASH MPD file – a deep dive
• How to package for MPEG-DASH using Bento4 mp4dash
• List of free MPEG-DASH MPDs for testing
• List of MPEG-DASH MPD players available online

Until next time, stay safe, and happy streaming!