Table of Contents
The Unified Packager is a command-line driven program. Its generic format is:
mp4split -o output_file [options] <input_file(s)> [track-options]
The options are listed before the input file(s), except for the
options which come after the input file they refer to.
The input_file(s) are files that are stored locally. They can also be fully qualified URLs. Note that when using the URL format, your shell may require quoting the input file.
If one of the filenames starts with a
- character, it will be interpreted as
an option. To avoid this, add a
-- option just before such filenames.
You can make a sub selection of tracks. Note that these options appear after (each) input file. The available options for track selection are:
Select the one track that matches this track id. For example, if you want to create an ismv file using track 1 from example-audio.mp4 and track 4 from example-video.mp4, you would enter something like:
#!/bin/bash mp4split -o example.ismv \ example-audio.mp4 --track_id=1 \ example-video.mp4 --track_id=4
Select only the tracks that match the track type (audio/video/text/data). For example, if you have an .mp4 which has audio and video, but you want to generate an .isma including only the audio, you can use the --track_type=audio argument, which will only select the audio tracks in your .mp4 file.
#!/bin/bash mp4split -o example-64k.isma \ example.mp4 --track_type=audio mp4split -o example-800k.ismv \ example.mp4 --track_type=video
Most character combinations are supported by USP. Limits only exist as imposed by the shell or OS used.
A few examples:
Of course this is also dependent on the OS used. On Windows for instance colons (e.g. ':') do not work well, but this doesn't matter on Linux.
The possible length of filenames is determined by the OS or browser used.
mp4split is a command line tool which means shell escape rules apply.
The actual rules depend on the shell used, but for bash the following
is a good overview: bash escaping.
Using double quotes (e.g. "") is usually a good starting point.
For fully qualified URLs all RFC rules for URIs apply RFC 3986.
Packager can also be used to decrypt encrypted media, if you have the Content Encryption Key (CEK).
#!/bin/bash mp4split -o decrypted.mp4 --key=KID:CEK encrypted.mp4
In case the encryption/DRM does not use a KID the CEK may be passed
--key=:CEK, omitting the KID.
This is similar to how you use the '--key=KID:CEK' option to decrypt a stream using Capture (see: Decrypt).
Or using a CPIX document:
#!/bin/bash unified_capture -o decrypted.mp4 --decrypt_cpix=filename.cpix encrypted.mp4
This is similar to how you use the '--decrypt_cpix=filename.cpix' option to decrypt a stream using Capture (see: Decrypt using CPIX).
When working with content that you have stored remotely on AWS S3, you may need
to authenticate your requests with a signature to gain access to the S3 bucket,
if the bucket is set up to be secured this way. You can instruct
add the required information to your request by specifying your S3 access key,
S3 secret key and S3 region using the following options:
On successful completion
mp4split returns a program exit code 0.
Non-0 exit codes indicate an error, usually following standard HTTP status
codes like 404, 500.
Note that some shells do not support integer exit codes, but for example on
Windows you can use
Also beware that the exit code returned by
mp4split is sometimes altered in
unpredictable ways by OS or shell to fit into word-size limitations.
For example, a typical Linux-BASH environment will wrap error code 404 to 148
(truncating any bits beyond single byte).
mp4split status code is also printed to stderr. It is a more
detailed description of the error and is listed below.
The following status codes are defined:
0 - FMP4_OK¶
All okay. Please note the status code is '0' and not '200'. Shells like 'bash' or programs like 'make' interpret '0' as success and any other code as failure.
400 - FMP4_400¶
400 - FMP4_IO_HTTP_ERROR¶
The I/O backend returned an IO error.
400 - FMP4_PARSE_ERROR¶
A parse error occurred.
400 - FMP4_UNSUPPORTED_REQUEST_FOR_FILE¶
The requested server manifest file exists, but the virtual file request wasn't understood.
403 - FMP4_ISS_FORBIDDEN¶
Output to Smooth Streaming is not allowed.
403 - FMP4_HLS_FORBIDDEN¶
Output to HTTP Live Streaming is not allowed.
403 - FMP4_HDS_FORBIDDEN¶
Output to HTTP Dynamic Streaming is not allowed.
403 - FMP4_MPD_FORBIDDEN¶
Output to MPEG-DASH is not allowed.
404 - FMP4_IO_NO_SUCH_FILE_OR_DIRECTORY¶
The file cannot be found.
404 - FMP4_MISSING_DRM_OPTIONS_FOR_ISS¶
Missing DRM options for Smooth streaming.
404 - FMP4_MISSING_DRM_OPTIONS_FOR_HLS¶
Missing DRM options for HTTP Live Streaming.
404 - FMP4_MISSING_DRM_OPTIONS_FOR_MPD¶
Missing DRM options for MPEG-DASH streaming.
404 - FMP4_NO_SYNC_SAMPLES¶
The requested fragment contains no samples.
404 - FMP4_NO_INPUT_TRACKS¶
No tracks are listed in the server manifest (e.g. when a given predicate doesn't match any input tracks).
404 - FMP4_ISS_FRAGMENT_NOT_FOUND¶
The requested fragment number is less than the first fragment available in the DVR window.
404 - FMP4_HLS_FRAGMENT_MISSING¶
The requested fragment is missing from the DVR window. This may be caused by a temporarily hickup in the encoding.
409 - FMP4_409¶
410 - FMP4_410¶
412 - FMP4_412¶
412 - FMP4_ISS_FRAGMENT_NOT_AVAILABLE¶
This is a special error code for live smooth streaming. It means the client request is too far ahead of the encoder stream.
415 - FMP4_415¶
Unsupported Media Type.
415 - FMP4_MISSING_FTYP¶
The filetype box is missing from the MP4 source.
415 - FMP4_MISSING_MOOV¶
The movie box is missing from the MP4 source.
415 - FMP4_MISSING_MOOF¶
The movie fragment is missing from the MP4 source.
415 - FMP4_MISSING_MFRO¶
The movie fragment random access offset box is missing from the MP4 source.
415 - FMP4_MISSING_TFRA¶
The track fragment random access box is missing from the MP4 source.
415 - FMP4_MISSING_SIDX¶
The segment index box is missing from the MP4 source. This error may be returned when creating an MPD from audio/video files that are not packaged using the --package-mpd option.
415 - FMP4_MISSING_NAL_SIZE¶
The H.264 stream is missing the NAL size header (most likely a corrupt file).
415 - FMP4_INVALID_NAL_SIZE¶
The specified NAL size in the H.264 stream is invalid (most likely a corrupt file).
415 - FMP4_MISSING_NAL_DATA¶
The sample data is truncated (most likely a corrupt file).
415 - FMP4_INVALID_SEI¶
The SEI message embedded in the H.264 stream is invalid.
415 - FMP4_PREMATURE_END_OF_BOX¶
This error is thrown when an MP4 input file is parsed and there is data missing. Most likely this is because a corrupt input file (e.g., when an FTP upload has failed partway through).
500 - FMP4_500¶
Internal Server Error
501 - FMP4_NOT_IMPLEMENTED¶
The requested functionality is not implemented.