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.
Interested in MPEG-DASH and video streaming? You’ll be interested in these articles for sure!
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.
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 –
- Go to GPAC’s GitHub page and download the latest release.
- 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.
-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
-segment-name ‘$RepresentationID$_$Number%03d$$init=init$' will create segment file names like
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-livesets the segment duration in mS and tells the packager that this is a live stream that will continue until canceled.
-outsets the output location, the same as VOD.
-segment-namedefines the segment names, the same as VOD.
-profilesets the DASH MPD profile. For live use the live profile.
-mpd-durationdefines 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
900will enable the users to go back up to 15 minutes.
-mpd-refreshdefines 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
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!
Ron has lead streaming optimization Product Management teams at companies including Ortiva Wireless, Allot Communications, and MediaMelon.
1 thought on “MPEG-DASH Packaging using GPAC’s mp4box Tool”
very helpful video for understanding the concept. I have tried exactly the same tutorial and created same versions of videos using mp4box for a high resolution video but it only plays “1x.mp4″(the first one in my case) not other versions. can you please guide what may be issue. My command is
mp4box -dash 1000 1x.mp4 2x.mp4 originalx.mp4