doc/ToolGuide.txt - platform/external/mp4v2 - Git at Google

 MP4v2 1.9.1 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
	MP4v2 1.9.1 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