mp4track
********

This tool is used to manage various aspects of individual tracks in an mp4 file. Some of the actions are mp4 (generic) while others may support standards based on mp4 files such as .m4a or .m4v files. Each action has an appropriate scope upon which it acts. See individual actions for details. The following parameters are used to set scopes for actions:

--track-any
     act on any/all tracks.

--track-index IDX
     act on a single track specified by index value. A track index is 0-based and counts upwards for each track available.

--track-id ID
     act on a single track specified by id value. A track id is a unique value assigned to each track and never changes.

The list action will produce a brief report of each track for each mp4 file. Many (but not all) of the values shown may be modified by actions documented later in this article. This will produce a brief report of each track for each mp4 file.

--list
     list all tracks in mp4. Example output:

          track[0] id=1
            type           = video
            enabled        = true
            inMovie        = false
            inPreview      = false
            layer          = 0
            alternateGroup = 0
            volume         = 0.0000
            width          = 850.96295166
            height         = 360.00000000
            language       = UNDEFINED(0)
            handlerName    =
            userDataName   = <absent>

The following group of actions are used to modify the values shown by --list action. The modification of these values should be done with great care on any files, and as always you are cautioned to backup your media files before modification.

--enabled BOOL
     set trak.tkhd.flags (enabled bit). When true indicates the track is enabled.

--inmovie BOOL
     set trak.tkhd.flags (inMovie bit). When true indicates the track is used in the movie.

--inpreview BOOL
     set trak.tkhd.flags (inPreview bit). When true indicates the track is used in the movie's preview.

--layer NUM
     set trak.tkhd.layer. Specifies the front-to-back ordering of video tracks; tracks with lower numbers are closer to the viewer. 0 is the normal value, and -1 would be in front of track 0, and so on.

--altgroup NUM
     set trak.tkhd.alternate_group. An integer that specifies a group or collection of tracks. If this field is 0 there is no information on possible relations to other tracks. If this field is not 0, it should be the same for tracks that contain alternate data for one another and different for tracks belonging to different such groups. Only one track within an alternate group should be played or streamed at any one time, and must be distinguishable from other tracks in the group via attributes such as bitrate, codec, language, packet size etc. A group may have only one member.

--volume FLOAT
     set trak.tkhd.volume. Specifies the track's relative audio volume. Full volume is 1.0 and is the normal value.

--width FLOAT
     set trak.tkhd.width. Specifies the track's visual presentation width. By default this is the same as the pixel width of the images. All images in the sequence are scaled to this size before any overall transformation by the matrix.

--height FLOAT
     set trak.tkhd.height. Specifies the track's visual presentation height. By default this is the same as the pixel width of the images. All images in the sequence are scaled to this size before any overall transformation by the matrix.

--language CODE
     set trak.mdia.mdhd.language. Specifies the ISO-639-2/T langauge code of the track. For example, eng for English, fra for French.

--hdlrname STR
     set trak.mdia.hdlr.name. Specifies a human-readable track type (for debugging and inspection purposes).

--udtaname STR
     set trak.udta.name.value. Specifies an arbitrary track-name. This value is optional (may be absent).

--udtaname-remove
     remove trak.udta.name atom. This action will remove the optional atom.

The colr related actions manage Color Parameter boxes which are used by QuickTime to map numerical values of pixels in a file to a common representation of color for video tracks. They may or may not be suitable for other Apple media players. Community feedback on compatibility is welcome.

--colr-list
     list all colr-boxes in mp4.

--colr-add
     add colr-box to a video track. An individual track must be specified.

--colr-set
     set colr-box parms. An individual track must be specified.

--colr-remove
     remove colr-box from track. By default all colr-boxes will be removed unless an individual track is specified.

--colr-parms CSV
     where CSV is IDX1,IDX2,IDX3 . Specify the exact parameters of an NCLC Color Parameter box as specified in the QuickTime specification. IDX1 correlates to the 16-bit primaries index. IDX2 correlates to the 16-bit transferFunction index. IDX3 correlates to the 16-bit matrixIndex index. Effects actions --colr-add, --colr-set.

--colr-parm-hd
     equivalent to --colr-parms=1,1,1 . This is a convenience setting generally suitable for HD content. Effects actions --colr-add, --colr-set.

--colr-parm-sd
     equivalent to --colr-parms=6,1,6 . This is a convenience setting generally suitable for SD content. Effects actions --colr-add, --colr-set.

     Example, add a colr-box tuned for HD content:

          mp4track --track-id=1 --colr-add --colr-parm-hd mymovie.m4v

     Example, add a colr-box with arbitrary index parameters:

          mp4track --track-id=1 --colr-add --colr-parms=2,3,4 mymovie.m4v

The pasp related actions manage Picture Aspect Ratio boxes which are used by QuickTime to specify height-to-width ratio of pixels for video tracks. They may or may not be suitable for other Apple media players. Community feedback on compatibility is welcome.

--pasp-list
     list all pasp-boxes in mp4.

--pasp-add
     add pasp-box to a video track. An individual track must be specified.

--pasp-set
     set pasp-box parms. An individual track must be specified.

--pasp-remove
     remove pasp-box from track By default all pasp-boxes will be removed unless an individual track is specified.

--pasp-parms CSV
     where CSV is hSPACING,vSPACING. Specify the exact parameters of Picture Aspect Ratio box as specified in the QuickTime specification. Effects actions --pasp-add, --pasp-set.

     Example, add a pasp-box with default (1,1) parameters for square pixels:

          mp4track --track-id=1 --pasp-add --pasp-parms=1,1 mymovie.m4v

     Example, add a pasp-box for 16:9 digital 525 (NTSC):

          mp4track --track-id=1 --pasp-add --pasp-parms=40,33 mymovie.m4v

     Example, add a pasp-box for 16:9 digital 625 (PAL):

          mp4track --track-id=1 --pasp-add --pasp-parms=118,81 mymovie.m4v