Packaging for Unified Origin

Package MP4 to fragmented-MP4 and back

Fragmented-MP4 is also known as PIFF and ISMV. Converting from an MP4 file to a fragmented mp4 file (.ismv):

#!/bin/bash

mp4split -o example.ismv \
  example.mp4

The other way around, from fragmented MP4 / PIFF / ISMV to MP4:

#!/bin/bash

mp4split -o example.mp4 \
  example.ismv

Or from Adobe's F4F to MP4:

#!/bin/bash

mp4split -o example.mp4 \
  example.f4f

You can also use the server manifest file as input. All the audio and video streams referenced in the manifest file are combined into one MP4 file.

#!/bin/bash

mp4split -o example.mp4 \
  example.ism

Options for fragmented-MP4 packaging

The packager supports the following options.

--use_dref

Create a (progressive) mp4 that references a fragmented mp4 file, for ''progressive download'' to older players. Unified Origin will resolve media data references on playout.

--use_dref_no_subs

New in version 1.7.27.

Like "--use_dref" creates mp4 that references an mp4 file, but without explicitly referencing sub-samples, resulting in a (considerably) smaller video mp4.

Note

Do not use if you want offer a download to own option, because that requires sub-sample data.

--dry_run

Do not write the output.

--timescale

The output timescale used for media. Defaults to the original media or 10MHz when the "piff" brand is used.

--fragment_duration

The target duration of each fragment (in milliseconds), default 2000. When sync-samples are present, then the fragments for the streams are aligned. This parameter can be useful for optimizing the fragment duration for a specific playout format e.g. HLS which recommends a fragment duration of 8 seconds. In rare cases it could also be useful for aligning audio or video fragments, although it is highly recommended to start with all sources GOP aligned from the outset.

--brand

Sets the 'compatibility brand'. Options: "piff", "iso6", "ccff" and "dash". Default is "iso6", but with timescale=10000000 (10Mhz) the default is "piff".

When creating (progressive) mp4 files with negative-composition-times "iso4" is used as brand. When using "iso2" negative composition time offsets are disabled and an edit list is used to compensate for the ct_offset.

Input track selection and editing

You can also make a selection of tracks when generating a server manifest file. Note that these options appear after (each) specification of an input file. The available options for track selection are:

--track_id

Select the one track that matches this track id.

--track_type

Select only the tracks that match the track type (audio/video/text/data)

All track properties are generated based on the input track. It is possible to override some properties. But note that is not necessary in the general case. The following track properties can be overridden:

--track_name

Specifies the trackName to be used.

--track_language

The three character ISO 639-2/T language specifier.

--track_description

A user-friendly description of the track.

--track_bitrate

Specifies the systemBitrate to be used.

--track_subtype

Specifies the Subtype, default CAPT.

Options are SCMD, CHAP, SUBT, CAPT, DESC, CTRL and DATA.

--track_role

A specific role of the track.

Options are main, alternate, supplementary, commentary and dub.

Notes

  • mp4split guarantees that track_name is unique. It uses track_type (audio/video/data/text) as its basename and (if present) adds the language modifier. If another track_name is then identical, but with a different codec, mp4split adds a _1, _2, postfix.
  • By default track_language is taken from the track's media info. Make sure to use the correct language codes, e.g. spa for Spanish, eng for English, nld for Dutch, etc.
  • When set, track_description overrides the defaults for the LABEL attribute (for alternative audio tracks in HDS) and the NAME attribute (for media tracks in HLS).
  • By default track_bitrate is the average bitrate (either from the metadata info of the input track, or calculated from the source samples). You can also set this to max, in that case the maximum/peak bitrate is used.

Packaging Smooth Streaming with track selection

Say you have one MP4 video and would like to store the audio and video track in separate fragmented files:

#!/bin/bash

mp4split -o example-64k.isma \
  example.mp4 --track_type=audio

mp4split -o example-800k.ismv \
  example.mp4 --track_type=video

Generating the required server manifest file:

#!/bin/bash

mp4split -o example.ism \
  example-64k.isma \
  example-800k.ismv

The track selection options always come after the input file. Next to --track_type you can also use --track_id to specify a specific track. Say you have two input files, example-audio.mp4 (containing 4 audio tracks) and example-video.mp4 (containing 4 video tracks) and you want to create a fragmented output file containing the first track of the audio and the last track of the video.

#!/bin/bash

mp4split -o example.ismv \
  example-audio.mp4 --track_id=1 \
  example-video.mp4 --track_id=4

Packaging with track order and defaults

New in version 1.7.17.

It is possible to place tracks in the manifest in a specific order. This order is set by the order in which the tracks are added in the packaging command line. For playout formats that support it e.g. HLS, this in turn also means that the chosen track can be set to DEFAULT=YES.

#!/bin/bash

# create a sorted .isma file
mp4split -o audio_sort.isma \
  swe_audio.mp4 \
  eng_audio.mp4 \
  dan_audio.mp4 \
  nor_audio.mp4

# create ismv with video and sorted audio
mp4split -o video_audio.ismv \
  video1-4.mp4 \
  audio_sort.isma

# create a sorted subtitle file
mp4split -o sorted_subtitles.ismt \
  swe_sub.dfxp \
  eng_sub.dfxp \
  dan_sub.dfxp \
  nor_sub.dfxp

# combine into manifest
mp4split -o sorted_manifest.ism \
  video_audio.ismv \
  sorted_subtitles.ismt

Therefore in the example above both the Swedish audio and subtitle track would be the first track in their respective groups and in the HLS manifest both set to DEFAULT=YES

The HLS manifest would look like this (additional tracks intentionally omitted):

sorted_manifest.ism/.m3u8

# AUDIO groups
#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="audio-aacl-139",NAME="Swedish",LANGUAGE="sv",AUTOSELECT=YES,DEFAULT=YES
...

# SUBTITLES groups
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="textstream",NAME="Swedish",LANGUAGE="sv",AUTOSELECT=YES,DEFAULT=YES,URI="sorted_manifest-textstream_swe=1000.m3u8"
...

Packaging content for delivery by Unified Origin

The first step is to package all the source content into the format that is used by Unified Origin. This is the fragmented-MP4 format.

The example uses this Source Content.

#!/bin/bash

mp4split -o video_400k.ismv \
  video_400k.mp4 \
  audio_aac-lc.mp4

mp4split -o video_800k.ismv \
  video_800k.mp4 \
  audio_he-aac.mp4

mp4split -o video.ismv \
  video_200k.mp4 \
  video_600k.mp4 \
  audio_dts.mp4 \
  audio_ac3.mp4 \
  audio_eac3.mp4

Now that we have packaged all the audio and video, the following step is to create the two progressive download files. Instead of creating a completely new MP4 video file we will create an MP4 video that only contains the necessary index and references the actual movie data that is stored in the fragmented-MP4 format.

#!/bin/bash

mp4split -o video_400k.mp4 --use_dref \
  video_400k.ismv
#!/bin/bash

mp4split -o video_800k.mp4 --use_dref \
  video_800k.ismv

As a last step we create the server manifest file. This is an XML file that contains the media information about all the tracks and is used by the USP webserver module.

#!/bin/bash

mp4split -o video.ism \
  video.ismv \
  video_400k.ismv \
  video_800k.ismv

At this point we have six files stored for our presentation.

File Description
video_400k.ismv AAC-LC, 400 kbps video
video_800k.ismv HE-AAC, 800 kbps video
video.ismv 200/600 kbps video, DTS, AC3, EAC3
video_400k.mp4 AAC-LC, 400 kbps video
video_800k.mp4 HE-AAC, 800 kbps video
video.ism USP server manifest file

The USP webserver module makes the following URLs available. Note that all these URLs are virtual. They do not exist on disk.

Playout format URL
Smooth Streaming http://www.example.com/usp/video.ism/Manifest
HTTP Live Streaming http://www.example.com/usp/video.ism/video.m3u8
HTTP Dynamic Streaming http://www.example.com/usp/video.ism/video.f4m
MPEG DASH http://www.example.com/usp/video.ism/video.mpd
Progressive download http://www.example.com/usp/video_400k.mp4
Progressive download http://www.example.com/usp/video_800k.mp4

Please download the advanced-usp.sh sample script which creates the various server manifest as discussed above. The sample content is Tears of Steel.