You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
416 lines
15 KiB
416 lines
15 KiB
MP4v2 2.0.0 Command-line Tools Guide
|
|
************************************
|
|
|
|
Table of Contents
|
|
*****************
|
|
|
|
1 Overview
|
|
2 Introduction
|
|
3 Common Options
|
|
4 mp4file
|
|
5 mp4track
|
|
6 mp4art
|
|
|
|
|
|
1 Overview
|
|
**********
|
|
|
|
MP4v2 bundles several command-line tools which, in general, allow some
|
|
basic manipulation of mp4 files which have been created by other means.
|
|
They are not meant to be a complete solution to management of mp4 file
|
|
structure.
|
|
|
|
The following is a brief summary of the tools available and the
|
|
functionality offered. Other tools may be packaged with the
|
|
distribution but are not yet stable enough to even document. User
|
|
beware.
|
|
|
|
`mp4file'
|
|
Operates on the entire file with actions such as list (summary
|
|
information), optimization and ASCII dumps.
|
|
|
|
`mp4track'
|
|
Operates on individual tracks with actions such as colr-box and
|
|
pasp-box manipulation.
|
|
|
|
`mp4art'
|
|
Operates on iTunes Metadata Cover-art Boxes with actions such as
|
|
list, add, replace, remove and extraction of Cover-art images.
|
|
|
|
2 Introduction
|
|
**************
|
|
|
|
The tools are invoked by their command-name, followed by one or more
|
|
options, actions, parameters for actions, and finally one or more files
|
|
on which the tool will operate. Options are specified in one of two
|
|
ways; in short or long syntax. A short-syntax option is prefixed with
|
|
exactly one dash while a long-syntax option is prefixed with exactly
|
|
two dashes. Depending on the option, it may or may not expect an
|
|
argument. Specifying an option which expects an argument usually
|
|
follows either of the following patterns:
|
|
|
|
toolname --something value ...
|
|
toolname --something=value ...
|
|
|
|
The rest of this guide will use the equals sign method.
|
|
|
|
3 Common Options
|
|
****************
|
|
|
|
Many of the tools share a common set of options which. These common
|
|
options usually have identically behaving short or long syntax. In some
|
|
cases short-syntax differs from long-syntax in that it may not require
|
|
an argument. This style is used sparingly and only when truly
|
|
convenient. Even though it is common practice in many unix-style tools
|
|
to permit optional arguments, the tools used in this project will tend
|
|
to avoid that because it can create a great deal of confusion.
|
|
|
|
The following is a list of common options available:
|
|
|
|
`-y, --dryrun'
|
|
do not actually create or modify any files. In situations where
|
|
the command will create new or modify existing files, specifying
|
|
this option will cause the tool to do as much as possible stopping
|
|
short of performing any actual writes. This is useful to guard
|
|
against user mistakes or unexpected behavior.
|
|
|
|
`-k, --keepgoing'
|
|
continue batch processing even after errors. When actions involve
|
|
multiple files or operations, the default behavior is to stop and
|
|
exit on the first error encountered. Specify this option if it is
|
|
desirable to record the error but continue processing.
|
|
|
|
`-o, --overwrite'
|
|
overwrite existing files when creating. In situations where a new
|
|
file will be created, the default behavior is to not overwrite a
|
|
file if it already exists. Use this option to allow overwriting.
|
|
|
|
`-f, --force'
|
|
force overwrite even if file is read-only. If overwriting is
|
|
enabled, file permissions may prevent writes. Specify this option
|
|
to try and overwrite the file anyways. This usually involves
|
|
deleting the file, then creating a new one.
|
|
|
|
`-q, --quiet'
|
|
equivalent to -verbose 0. Default behavior is to print a low
|
|
amount of informative information, usually one line of text per
|
|
action/file. Specify this option to omit normal messages. Errors
|
|
will still be reported.
|
|
|
|
`-d, --debug NUM'
|
|
increase debug or long-option to set NUM. File I/O with mp4 file
|
|
structures have special debug options available to users
|
|
interested in all the fine details. Default is level 1 . The
|
|
short-syntax is accumulative and takes no argument, while
|
|
long-syntax takes an argument. For exmaple, the following are
|
|
equivalent and would set level 3: `-dd' or `-d -d' or `--debug=3'.
|
|
The following levels are available:
|
|
0. supressed
|
|
|
|
1. add warnings and errors (default)
|
|
|
|
2. add table details
|
|
|
|
3. add implicits
|
|
|
|
4. everything
|
|
|
|
`-v, --verbose NUM'
|
|
increase verbosity or long-option to set NUM. Tool activity by
|
|
default will generally print one informative message per
|
|
action/file. Specify this option to change the default behavior.
|
|
The short-syntax is accumulative and takes no argument, while
|
|
long-syntax takes an argument.
|
|
0. warnings and errors
|
|
|
|
1. normal informative messages (default)
|
|
|
|
2. more informative messages
|
|
|
|
3. everything
|
|
|
|
`-h, --help'
|
|
print brief help or long-option for extended help. The
|
|
short-syntax will produce brief help. Specify the long-option for
|
|
more extensive help.
|
|
|
|
`--version'
|
|
print version information and exit. Extended version information
|
|
used for SCM purposes is not listed in help, but is available by
|
|
specifying `--verionx'.
|
|
|
|
4 mp4file
|
|
*********
|
|
|
|
`--list'
|
|
list (summary information). This will produce brief report when
|
|
summarizing each mp4 file. BRAND shows the file's main brand
|
|
identifier. COMPAT shows additional brands for which the file
|
|
purports to be comaptible with. SIZING displays if the file has
|
|
64-bit extensions of any kind, otherwise 32-bit. Example output:
|
|
BRAND COMPAT SIZING FILE
|
|
----------------------------------------------------------------------
|
|
M4A M4A,isom,mp42 32-bit Song.m4a
|
|
mp42 isom,mp42 32-bit Movie1.m4v
|
|
mp42 isom,mp42 32-bit Movie2.m4v
|
|
|
|
`--optimize'
|
|
optimize mp4 structure. This will rewrite the entire mp4 file
|
|
which, if needed, will clean up any unused (free) sections, and
|
|
re-order the atoms in a manner somewhat consistent with the
|
|
best-practices described in the ISO base media file specification.
|
|
|
|
`--dump'
|
|
dump mp4 structure in human-readable format. An ASCII dump of mp4
|
|
atoms is printed to stdout. This action is heavily influenced by
|
|
`--debug' option.
|
|
|
|
Example, list some files:
|
|
mp4file --list *.mp4 *.m4a *.m4v
|
|
|
|
Example, dump a file with more than usual debugging information:
|
|
mp4file -dd --dump movie.m4v
|
|
|
|
5 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
|
|
|
|
|
|
6 mp4art
|
|
********
|
|
|
|
This tool is used to manage iTunes Metadata Cover-art which is
|
|
typically used to embed an image to a song file. For example, the songs
|
|
in an album collection might all contain an image of the album cover
|
|
art. This data is usually found in `.m4a', `.m4v' and `.mov' files.
|
|
|
|
`--art-any'
|
|
act on all covr-boxes (default). Specifies the scope of the
|
|
action to operate on all, if applicable, covr-boxes.
|
|
|
|
`--art-index IDX'
|
|
act on covr-box index IDX. Specifies the scope of the action to
|
|
operate on single covr-box INDEX.
|
|
|
|
`--list'
|
|
list all covr-boxes.
|
|
IDX BYTES CRC32 TYPE FILE
|
|
----------------------------------------------------------------------
|
|
0 173613 710a3ec9 JPEG 01 Life In Technicolor.m4a
|
|
0 173613 710a3ec9 JPEG 02 Cemeteries Of London.m4a
|
|
0 173613 710a3ec9 JPEG 03 Lost!.m4a
|
|
0 173613 710a3ec9 JPEG 04 42.m4a
|
|
0 173613 710a3ec9 JPEG 05 Lovers In Japan _ Reign Of Love.m4a
|
|
0 173613 710a3ec9 JPEG 06 Yes.m4a
|
|
0 173613 710a3ec9 JPEG 07 Viva La Vida.m4a
|
|
0 173613 710a3ec9 JPEG 08 Violet Hill.m4a
|
|
0 173613 710a3ec9 JPEG 09 Strawberry Swing.m4a
|
|
0 173613 710a3ec9 JPEG 10 Death And All His Friends.m4a
|
|
|
|
`--add IMG'
|
|
add covr-box from IMG file.
|
|
|
|
`--replace IMG'
|
|
replace covr-box with IMG file.
|
|
|
|
`--remove'
|
|
remove covr-box.
|
|
|
|
`--extract'
|
|
extract covr-box. This will extract all covr-box data to image
|
|
files in the format of `BASENAME.art[INDEX].TYPE' .
|
|
|
|
Example, add PNG image file:
|
|
mp4art --add ACDC.png mysong.m4a
|
|
|
|
Example, extract image files from file:
|
|
mp4art --extract mysong.m4a
|
|
|
|
|