MP4Box

Content Authoring with MP4Box

This page is dedicated to MP4Box, the GPAC command line swiss army knife. You will find here a detailed documentation on major switches of MP4Box. Not all tools are documented, so do not hesitate to look at the MP4Box usage by typing MP4Box -h. General Considerations This document may refer to IsoMedia files. IsoMedia is a generic name for all formats based on the MPEG-4 Part 12 specification: MP4, 3GP and MJ2K files. Support for MJ2K files has not be tested in GPAC yet. As of version 0.2.4, MP4Box performs in-place rewrite of IsoMedia files (the input file is overwritten). You can change this behaviour by using the -out Filename option. For older versions, when MP4Box is used to modify an existing IsoMedia file, the original file (for example AFILE.mp4) is NOT overwritten, the resulting file is stored in out_AFILE.mp4. To specify another name for the resulting file, use the -out Filename option. As of version 0.2.4, MP4Box always stores the file with 0.5 second interleaving and meta-data at the begining, making it suitable for HTTP streaming. MP4Box usually generates a temporary file when creating a new IsoMedia file. The location of this temporary file is OS-dependent, and it may happen that the drive/partition the temporary file is created on has not enough space. In such an event, you may specify the temporary file location with the -tmp path_to_dir option. MP4Box does NOT perform audio/video/image transcoding (re-encoding media tracks to a different coded format). If you need to transcode content, you will need other tools. As of version 0.2.2, you don't need to follow any specific option ordering at prompt. Please be aware that this page documents the latest version of MP4Box and may therefore give details on options available only on GPAC CVS. If your version of MP4Box does not support an option please upgrade. File conversion MP4Box can convert the following files into compliant IsoMedia files: RAW Formats and extensions: MPEG-4 Video (.cmp .m4v) MPEG-4 Audio ADTS-AAC (.aac) - ADIF or RAW formats not supported MPEG-1/2 Audio (.mp3) JPEG and PNG Images (.jpg .jpeg .m4v) H263 Video (.263 .h263) AVC/H264 Video (.264 .h264, .26l .h26l) AMR and AMR-WideBand Speech (.amr .awb) EVRC Speech (.evc) SMV Speech (.smv) NHNT (.media .info .nhnt) AV Containers and extensions: AVI (.avi) - Only MPEG-4 video and MP3 audio supported at the current time. MPEG-PS (.mpg .mpeg .vob) - Only MPEG-1/2 video and MPEG-1/2 audio supported at the current time. QCP (.qcp) XIPH OGG (.ogg) - EXPERIMENTAL and not relevant to any IsoMedia-based standards. Only Vorbis audio and Theora video supported. IsoMedia files (no extension checking) Text formats and extensions: SRT Subtitles (.srt) SUB Subtitles (.sub) QuickTime TeXML (.xml) - cf QT documentation GPAC Timed Text (.ttxt) The conversion syntax is MP4Box -add inputFile destinationFile. This option is used to import media from several sources. You can specify up to 20 -add to MP4Box. This process will create the destination file if not existing, and add the track(s) to it. If you wish to erase the destination file, just add the -new option Note: You can also use this option to merge tracks from different IsoMedia files. Input file track selection To select a desired media track, the following syntax is used: -add inputFile#video: adds the first video track in inputFile. DOES NOT WORK for IsoMedia files. -add inputFile#audio: adds the first audio track in inputFile. DOES NOT WORK for IsoMedia files. -add inputFile#trackID=ID or -add inputFile#ID: adds the specified track. For IsoMedia files, ID is the track ID. For other media files, ID is the value indicated by MP4Box -info inputFile. MP4Box can import a desired amount of the input file rather than the whole file. To do this, use the syntax -add inputFile%N, where N is the number of seconds you wish to import from input. MP4Box cannot start importing from a random point in the input, it always import from the begining. When using -add option, MP4Box will automatically create default BIFS and OD tracks to make the resulting file compliant with the ISMA 1.0 standard if possible. If the destination file extension is .3gp or .3g2, MP4Box will automatically make the file 3GP(2) compliant. This means that MP4Box will always remove any systems tracks when using -add, you may prevent this by using the -keepsys option. Note on text import : When importing SRT or SUB files, MP4Box will choose default layout options to make the subtitle appear at the bottom of the video. You SHOULD NOT import such files before any video track is added to the destination file, otherwise the results will be likelly not be usefull (default SRT/SUB importing uses default serif font, fontSize 18 and display size 400x60). For more details on 3GPP timed text, please go here. Import Options There are several media-specific options which can be used when importing media. To know which options are supported for non-IsoMedia files, use the -info option for the desired media track, for example MP4Box -info 2 file.mpg. -sbr : forces importing the AAC-ADTS file as AAC SBR (aka HE-AAC, aka aacPlus) with backward compatible signaling (eg non SBR aware decoders should play the file). -sbrx : forces importing the AAC-ADTS file as AAC SBR (aka HE-AAC, aka aacPlus) with non-backward compatible signaling (eg non SBR aware decoders should NOT play the file). Note : MP4Box CANNOT detect whether AAC input is regular or SBR AAC, so you must use one fo these options if you want to import AAC SBR files. -dref : MP4Box can import media data without copying it, this is called data referencing. The resulting file only contains the meta-data of the presentation (frame sizes, timing, etc...) and references media data in the original file. This is extremely usefull when developping content, since importing and storage of the MP4 file is much faster and the resulting file much smaller. Use the -dref option to enable data referencing. NOTE : Data referencing may fail on some files because it requires the framed data (eg an IsoMedia sample) to be continuous in the original file, which is not always the case depending on the original interleaving or bitstream format. -nodrop : Some AVI files may have non-coded frames (n-VOPs) introduced by the encoder. By default, MP4Box will discard these frames, hence producing a variable frame-rate visual stream. You can force MP4Box to keep constant frame-rate by specifying -nodrop while importing the AVI file. -packed: When importing raw MPEG-4 Video, forces considering the bitstream as the dump of an AVI Packed Bitstream (removes all n-vops and import as constant FPS). -fps FrameRate : If possible, will override the original video frame rate. This option is also used when importing SUB text files to specify the SUB framerate. Framerate is a double-precision number. -mpeg4 : This option forces MPEG-4 stream descriptions for formats having several description syntax available - only possible for QCELP, EVRC and SMV audio. -agg N : Aggregates N audio frames in an IsoMedia sample. This option is only valid for some 3GP(2) audio formats (AMR, QCELP, EVRC and SMV audio). The maximum acceptable value is 15. When importing several tracks/sources, all options will be applied if relevant to each source. Note on OGG Support : MP4Box can import OGG files containing either Vorbis audio or Theora video. This feature is experimental and support for these media formats in IsoMedia files is NOT STANDARDIZED anywhere. This should only be used for development and R&D purposes, and you must be aware that files created this way may be unusable, even with future versions of GPAC. File Splitting and Concatenation MP4Box can split IsoMedia files by size, duration or extract a given part of the file to new IsoMedia file(s). This process requires that at most one track in the input file has non random-access points (typically one video track at most). This process will also ignore all MPEG-4 Systems tracks and hint tracks, but will attempt to split private media tracks. Note : The input file must have enough random access points in order to be splitted. This may not be the case with some video files where only the very first sample of the video track is a key frame (many 3GP files with H263 video are recorded that way). In order to split such files you will have to use a real video editor and re-encode the content. -split time_in_seconds : splits the input file in a sequence of files lasting at most the specified time. Depending on random access distribution in the file (sync samples), the duration of the resulting files may be less than specified. -splits size_in_kb : splits the input file in a sequence of files of maximum specified size. Depending on random access distribution in the file (sync samples), the size of the resulting files may be less than specified. -splitx StartTime:EndTime : extracts a subfile from the input file. StartTime and EndTime are specified in seconds. Depending on random access distribution in the file (sync samples), the startTime will be adjusted to the previous random access time in the file. -cat a_file : concatenates a_file to input file (samples are added to existing tracks rather than added to new tracks). The usage is the same as -add, you may use non IsoMedia input files (for example, AVIs or MPEGs) and concatenates them directly into a new IsoMedia file. This process will remove all MPEG-4 systems tracks from the final file and make it compliant to ISMA or 3GP just like the -add process. You can instruct MP4Box not to remove MPEG-4 systems tracks by specifying -keepsys. General File operations MP4Box can rewrite IsoMedia files for distribution purposes - these options may also be used while converting files. -isma: converts file to ISMA 1.0 specification. This is extremely usefull since most MPEG-4 players only understand ISMA-like content. All systems information and tracks numbering are rewritten to comply to the specification. WARNING: some media tracks may be removed. -3gp : converts to 3GPP specification. This will remove all MPEG-4 Systems information, leaving only the audio/video/text media tracks supported by 3GPP. WARNING: some media tracks may be removed. -nosys : removes all MPEG-4 systems tracks and keeps an empty InitialObjectDescriptor will be left in the file for MPEG-4 Level@Profile indications. -inter Duration : interleaves media data in chunks of desired duration (in seconds). This is usefull to optimize the file for HTTP/FTP streaming. All meta data are placed first in the file, allowing a player to start playback while downloading the content. By default MP4Box always stores files with half a second interleaving. Specifying a 0 interleaving time will result in the file being stored without interleaving, with all meta-data placed at beginning of the file. -flat : forces flat storage of the file: media data placed at the begining of the file without interleaving, and meta-data at the end of the file. When used with -add to create a new file, no temporary file is created (faster storage). -rem trackID : removes given track from file. -cprt string : adds copyright to file. -chap chap_file : adds chapter information located in chap_file to the destination file. Chapter extensions have been introduced by Nero and are NOT standard extensions of IsoMedia file format, don't be surprised if some players don't understand them. The following syntaxes are supported in the chapter text file, with one chapter entry per line: ZoomPlayer chapter files : AddChapter(nb_frames,chapter name), AddChapterBySeconds(nb_sec,chapter name) and AddChapterByTime(h,m,s,chapter name). One chapter entry per line. Time codes : h:m:s name, h:m:s:ms name and h:m:s.ms name. One chapter entry per line. SMPTE codes : h:m:s;nb_f/fps name and h:m:s;nb_f name with nb_f the number of frames and fps the framerate. One chapter entry per line. Common syntax : CHAPTERX=h:m:s[:ms or .ms] on one line and CHAPTERXNAME=name on the other - the order is not important but chapter lines MUST be declared sequencially (same X value expected for 2 consecutive lines). Some existing MP4 files may use MPEG-4 Visual tracks with B-Frames in an improper way. There is currently no automatic cleaning of such files in MP4Box, but reimporting the track will solve the problem. To do this: MP4Box -avi trackID file.mp4: exports track to avi (raw MPEG-4 video also possible). MP4Box -import file.avi dest.mp4: converts avi into MP4 and handles B-Frame correct import (packed bitstreams, n-Vops). File hinting IsoMedia File Hinting consists in creating special tracks in the file that contain transport protocol specific information and optionally multiplexing information. These tracks are then used by the server to create the actual packets being sent over the network, in other words they provide the server 'hints' regarding packet building, hence their names: Hint Tracks. MP4Box can generate these hint tracks for the RTP protocol (the most widely used protocol for multimedia streaming). The resulting file can then be streamed to clients with any streaming server understanding the IsoMedia file format and hint tracks, such as Apple's QTSS/DSS servers. -hint : hints the given file for RTP/RTSP -mtu : specifies the desired maximum packet size, or MTU (Maximum Transmission Unit). This must be choosen carefully: specifying too large packets will result in undesired packet fragmentation at lower transport layers. The default size when hinting is 1500 bytes (Ethernet MTU). -multi [maxptime] : enables sample concatenation in a single RTP packet for payload formats supporting it. maxptime is an optional integer specifying the maximum packet duration in milliseconds, used for some audio payloads. Its default value is 100 ms. -copy : forces hinted data to be copied to the hint track. This speeds up packet building at server side but takes much more space on disk. -tight : performs sample-based interleaving of media tracks and hint tracks. This should reduce disk seeks at server side (depending on server implementation) but results in a bigger file. -mpeg4 : forces usage of MPEG-4 Generic Payload whenever possible. -ocr : forces all media tracks in the file to be served synchronized. This is needed because most streaming servers don't support desynchronized tracks in a single file. Be extremelly carefull when designing MPEG-4 interactive presentations for streaming since you will have to take care of the streaming server capabilities... MP4Box generates warnings when the file timeline can be ambiguously interpreted by the server. -iod : prevents ISMA-like IOD generation in SDP. MP4Box automatically detects ambiguous (ISMA/non-ISMA) files but nobody's perfect. This shouldn't be used with -isma option. -sdp_ex string : adds the given text to the movie SDP information ( -sdp_ex "a=x-test: an sdp test") or to a track ( -sdp_ex "N:a=x-test", where N is the hint track or its base track ID). This will take care of SDP line ordering. WARNING: You cannot add anything to SDP, please refer to RFC2327 for more info. -unhint : removes all hint tracks and SDP information from file. This can be usefull since MP4Box doesn't remove any existing hint tracks when hinting the file. MP4Box always detects the best payload possible and when not found gets back to MPEG-4 Generic payload. The configuration of the MPEG-4 Generic payload is quite complex, so MP4Box always computes the most suitable configuration for you. However there are more hinting options available to configure the MPEG-4 Generic RTP payload (type -h hint for help) in case you need to transport MPEG-4 specific informations. Examples: Prepare any mp4 for ISMA streaming: MP4Box -isma -hint myfile. mp4 Prepare an mp4 optimized for server: MP4Box -hint -copy -tight myfile. mp4 Prepare a complex mp4 with BIFS for streaming: MP4Box -ocr -iod -hint myfile. mp4 Prepare any 3GP/MP4 for safe streaming: MP4Box -nosys -hint myfile.3gp   Q&As: Can I stream MP4 files created with MPEG4IP's mp4creator to GPAC? It depends. mp4creator hints mp3 audio with MPA or MPA-robust payload formats, specific to mp3 streams. MPA-robust is not supported in GPAC and is not on the list of priorities, we strongly prefer working with RFC3640 payload for MPEG-4 streams. However if no MPA-robust payload is used, both players and hinters should interoperate. Can I stream MP4 files created with MP4Box to MPEG4IP player? It depends. MPEG4IP works with ISMA / plain AV files, therefore you should first convert your file to ISMA before hinting. Can I stream complex MPEG-4 presentations created with MP4Box to any player ??? Yes and no. GPAC uses RFC3640 to stream MPEG-4 systems information, and most players don't accept that (they usually use their own format). Moreover RTSP servers as known today only understand simple synchronized presentations, and most MPEG-4 presentations have too complex timing for servers to handle. If you need to know more about that join us in our forum.   File Dumping and information MP4Box has many dump functionalities, from simple track listing to more complete reporting of special tracks -info : prints some file information. File can be an IsoMedia file or any file supported by MP4Box for import. -info TrackID : prints extended track information for IsoMedia files, and supported import flags for other files. -diso : creates XML image of the file structure. -drtp : creates XML image of all hint tracks samples of a hinted mp4 file. -sdp : creates SDP file associated with a hinted mp4 file. -ttxt : converts input subtitle (SRT, SUB) to GPAC TTXT format. -ttxt TrackID : dumps text track to TTXT XML format. -srt : converts input subtitle (TTXT, SUB) to SRT format. -srt TrackID : dumps text track to SRT format. -std : dumps to stdout instead of file.   Media track Extraction MP4Box can extract media tracks in a variety of formats: -raw TrackID : extracts track to its native format. -raws TrackID : extracts each track sample to a file. To extract a single sample, use -raws TrackID:N -avi TrackID : extracts visual track in avi format (MPEG-4 Visual and AVC/H264 supported). -nhnt TrackID : extracts track in NHNT format. -qcp TrackID : same as -raw but defaults to QCP file for EVRC/SMV. -aviraw track : extracts avi track to its native format. track can be one of video, audio, audioN N being the number of the audio track. -single TrackID : extracts track in a new MP4 with a single track. MPEG-4 Systems, VRML and X3D Handling MP4Box can be used to encode and decode MPEG-4 Scene Description. It may also be used to convert to and from the various textual format: BT, XMT-A, WRL (VRML97) and X3D in XML or VRML format. These conversions will not always work since these standards do not use the same set of nodes. -mp4 : specifies input file is to be encoded. Supports .bt (BT), .xmt (XMT-A) , .wrl (VRML97) and .swf (Flash) input. For more details on flash input, try MP4Box -h swf. For more details on BT/XMT-A, go here. -def : encodes DEF/USE nodes and routes names as strings. This is usefull when developping content otherwise the decoded scene becomes quickly messy. -ms : specifies the media source to check for track importing. This is needed when no MuxInfo is present in the BT file, although this is not recommended. By default, MP4Box looks for tracks in MYFILE. mp4 when encoding MYFILE.bt -bt : dumps scene in a BT file. -xmt : dumps scene in an XMT-A file. -wrl : dumps scene into VRML97 format - unknown/incompatible nodes are removed. -x3d : dumps scene into X3D/XML format - unknown/incompatible nodes are removed. -x3dv : dumps scene into X3D/text format - - unknown/incompatible nodes are removed. ISMA Encryption and description MP4Box supports ISMA E&A specification, better known as ISMACryp. -crypt drm_file : encrypts IsoMedia file according to rules specified drm_file. More info on this is available here. -decrypt drm_file : decrypts IsoMedia file. drm_file is optional if the keys are stored within the file. More info on this is available here. Misc -nodes : prints list of MPEG-4 nodes supported in this MP4Box build. -node NodeName : prints MPEG-4 node syntax: fields, their type, event type, default value and quantization info if any. Note this works only for nodes supported in the current built. -xnodes : prints list of X3D nodes supported in this MP4Box build. -node NodeName : prints X3D node syntax: fields, their type, event type and default value. Note this works only for nodes supported in the current built.