Program Usage

Commandline options

The Unified Packager is a command-line driven program. It's generic format is:

mp4split -o output_file [options] <input_file(s)> [track-options]

Important

The options come before the input file(s), except for the --track options which come behind the track 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 that your shell may require quoting the input file.

URLs and paths

Most character combinations are supported by USP. Limits only exist as imposed by the shell or OS used.

A few examples:

mp4:urn:ufapi:object:myco:57c7898d-9279-4bc9-b8ae-caf6ac889c76;format=mp4;resolution=426x240
./urn:ufapi:object:myco:57c7898d-caf6;format=mp4;resolution=426x240
/z/mawebvid29ue_0@82569/manifest.f4m
http://example/z/mawebvid29ue_0@82569/manifest.f4m?hdcore
/var/www//ism_proxy_pass/alvin+800k.ismv

Off course this is also dependent on the OS used. On Windows for instance colons (e.g. ':') are not working well, but it does not 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.

Status codes

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 %ERRORLEVEL%. 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).

The internal 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.

400 - FMP4_400

Bad Request.

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).

409 - FMP4_409

Conflict.

410 - FMP4_410

Not found.

412 - FMP4_412

Precondition failure.

412 - FMP4_ISS_FRAGMENT_MISSING

Fragment is missing, could not be retrieved or contains no samples (discontinuty).

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.

500 - FMP4_500

Internal Server Error

500 - FMP4_FRAGMENT_NOT_FOUND

The requested fragment number is less than the first fragment available in the DVR window.

500 - FMP4_FRAGMENT_MISSING

The requested fragment number is missing from the DVR window.

500 - FMP4_FRAGMENT_NOT_AVAILABLE

The requested fragment number is larger than the last fragment available in the DVR window.

501 - FMP4_NOT_IMPLEMENTED

The requested functionality is not implemented.