._  _.._ _  _  
| |(_|| | |(/_ 
~~~~~~~~~~~~~~~
       id3 - a commandline mass tagger

                   
 _  ._  _ ._  _o _ 
_>\/| |(_)|_)_>|_> 
~~/~~~~~~~|~~~~~~~~
       id3 [-v] [-M] [-12] [-d] [-t title] [-a artist] [-l album]
	 [-n tracknr] [-y year] [-g genre] [-c comment]
	 [-f template] [-q format] [-m] [-D file] [-R]
	 [-s size] [-E] [-u] [-rFRAME] [-wFRAME data] "filespec"

                          
 _| _  _ _._o.__|_o _ ._  
(_|(/__>(_| ||_)|_|(_)| | 
~~~~~~~~~~~~~|~~~~~~~~~~~~
       id3 mass tagger is a tool for manipulating id3 and id3v2 tags in multi-
       ple files. It can generate tag fields from the filename and other vari-
       ables, and/or rename files, using an intuitive syntax.

       id3  currently  supports  the  old-style  ID3  format with track-number
       extension (ID3 v1.1), as  well  as  the	more  complicated  ID3v2  (ID3
       v2.2.0,	v2.3.0) format.  This also means use is pretty much limited to
       audio files which use these formats, e.g, MPEG-1 Layer III.

                  
 _ .__|_o _ ._  _ 
(_)|_)|_|(_)| |_> 
~~~|~~~~~~~~~~~~~~
       Order of the options is only important where specified.

       filespec ...
	      specifies the file(s) to be affected by the command.

	      If you use wildcards, it is STRONGLY recommended to enclose  the
	      specification  in  double  quotes  ("").	id3 has internal shell
	      pattern matching which will not work if your shell also performs
	      this function.

	      The shell pattern matching can be applied to both file names and
	      directory names.

       -h     show commandline help

       -V     display version number and copyright

       -v     be verbose

       -M     preserve last modification time of files operated on

       -1     process/add ID3v1 tags (default).

       -2     process/add ID3v2 tags.

       -3     process/add Lyrics3 tags.

	      If more than one tag type is specified, they  are  all  written,
	      but only the left-most tag is read from. If no tag type is spec-
	      ified, this is equivalent to `-1 -3E'.

       -d     do not re-use existing tag data. If no new  tag  information  is
	      specified  in  conjunction  with	this option, all selected tags
	      will be removed.

       -t title
       -a artist
       -l album
       -n tracknr
       -y year
       -g genre
       -c comment

	      add/replace the specified fields in all selected tags  with  the
	      values  given.  Field  values are scanned for substitution vari-
	      ables, see SUBSTITUTION below. If a  field  value  is  a	single
	      variable, and its substitution fails, no operation is performed.

	      Genres can be specified either directly or with  their  assigned
	      number, regardless of tag format.

       -f filename-template
	      rename  files  encountered  according to filename-template.  The
	      argument is scanned for substitution variables. An  empty  vari-
	      able  will  by  default  get replaced with "Unknown".  Trying to
	      rename to an already existing file will cause an error.

       -q format
	      for each file encountered, format will get scanned for substitu-
	      tion  variables,	and  written  to  standard  output. Using this
	      option will block any attempt to modify files.

       -m     match mode; interpret any variables found in  a  filespec  as  a
	      wildcard,  and  set  the	tag field corresponding to the matched
	      wildcard.    Thus,   `-m "%a - %t.mp3"'	is   equivalent    for
	      `-a %1 -t %2 "* - *.mp3"'.   This  option  is merely a shorthand
	      and does not add any intelligence; in particular,  any  variable
	      interpreted  still counts as a wildcard, see SUBSTITUTION below.

       -D filename
	      duplicate and copy the tags of the specified format as found  in
	      filename	to  the target files. The tag in each file is replaced
	      after any variables have been read, but before  any  fields  are
	      updated.

	      Any  original  tag  values  not explicitly copied to the new tag
	      (for example, by using -u) are lost. If filename does  not  have
	      any tags, this option is identical to the -d option.

       -R     searches	recursively;  Normally, path seperators in filespec do
	      not get matched by `?' or `*' wildcards. With this switch,  they
	      are treated as an ordinary character.

       --     force  the  following  argument to be interpreted as a filename.
	      Use this for files that start with a `-'	(dash).   SUBSTITUTION
	      below.

       The  following  options	only  apply  on the tag most recently selected
       before them, and only have meaning where relevant.

       -u     update all standard tag fields by copying them from  the	source
	      tag. This is similar to writing `-talnygc %t %a %l %n %y %g %c',
	      but only operates on the most recent tag. It is possible for the
	      source and destination tag to be the same.

       -E     only write a tag of the selected type if a file already contains
	      it; do not add new ones. If `-3' is not specified, this  is  the
	      default behaviour for Lyrics3 tags.

       -s size
	      try to write a new tag using exactly size bytes, adding / remov-
	      ing padding as necessary. The resulting tag will have no padding
	      if size is smaller than the actual size necessary.

       -rFRAME
	      remove  all occurrences of frames named FRAME from the tag. Con-
	      sult the format documentation for valid FRAME names.

       -wFRAME data
	      add / update a frame named FRAME with data in the  tag.  data is
	      scanned  for  substitution  variables. Again, consult the format
	      documentation. See COMPATIBILITY for more information.

       Individual options can be stacked in a single argument for more	conve-
       nience.	For example, running

	  id3 -2d -alt "Artist" "Album" "Title" *.mp3

       is equivalent to:

	  id3 -2 -d -a "Artist" -l "Album" -t "Title" *.mp3


                              
 _   |_  __|_o_|_  _|_o _ ._  
_>|_||_)_> |_| |_|_||_|(_)| | 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
       id3 can perform "printf-like" substitution on the values prior to writ-
       ing them to a tag. Note that if you want to use pattern	matching,  you
       HAVE TO enclose the wildcard specification on the commandline in double
       quotes to prevent your shell from expanding any wildcards.

       \c     escape sequence. \n, \r, \t, \v, \f, \b, \a, get replaced as  in
	      C,  any other character will be stripped of any special meaning.
	      E.g., \n becomes the newline character, \\ a single backslash.

       %<modifiers>N
	      where N <- [0..9] replaced with the portion  of  the  file  path
	      matching	the nth `*' (asterisk) wildcard in the file specifica-
	      tion. 0 is taken to mean 10.

       %<modifiers>c
	      where c <- [a..z]
	      replaced by values according to the following table:

	      %t title
	      %a artist
	      %l album title
	      %n track number
	      %y year
	      %g genre
	      %c comment field
	      %f file name (without path)
	      %p path to filename
	      %x auto-increasing counter
	      %X file counter

	      Values get read (where applicable) from the source tag, which is
	      the  left-most tag selected on the command line, and reflect the
	      state of the file before any modifications  were	made.  If  the
	      source  value  is  not available, the variable fails.  %p%f com-
	      bines to the  full  path	and  file  name.  The  %x  value  gets
	      increased  every	time  it  has been substituted inside the same
	      directory, and is intended for auto-numbering. %X increases  for
	      every file processed.

       %%     replaced with a single "%", equivalent to \%

       %|text||alt text||...|?
	      substituted by the first text that was completely successful, or
	      fails as empty, see fall-backs below. This can  be  used	as  an
	      all-or-nothing substitution. A lone "%?" always fails.

   Available <modifiers> (optional):
       + (plus sign)
	      Capitalize the substituted value

       - (minus sign)
	      Convert all characters to lowercase

       _ (underscore)
	      Use  the	raw  value  of	the  variable.	Normally, substitution
	      replaces	any  underscores  with	spaces,  and  condenses  empty
	      whitespace.

       * (asterisk)
	      Split  the  variable into seperate words by looking at the capi-
	      talization.

       # (hash or pound sign)
	      Pad all numeric values within the substituted value,  if	neces-
	      sary.   Multiple	hash  signs can be stacked to increase desired
	      width. If there are no numeric  values,  this  modifier  has  no
	      effect.

       |fall-back|
	      If substitution for a variable fails, attempt fall-back instead.
	      fall-back  itself  may  be  empty  or  contain  other  variables
	      (including  other  fall-backs).  If fall-back contains variables
	      that fail, the fall-back fails and will not  be  used.  If  more
	      than  one fall-back is provided, successive fall-backs are tried
	      until one succeeds.

                       
 _    _.._ _ ._ | _  _ 
(/_><(_|| | ||_)|(/__> 
~~~~~~~~~~~~~|~~~~~~~~~
       Here are some examples of using id3:

       id3 -a "Stallman" -t "Free Software Song" fs_song.mp3"
	      Add a simple tag to a file.

       id3 -d *.mp3
	      Removes all ID3v1 tags from all mp3's.

       id3 -2 -1u fs_song.mp3
	      Copy ID3v2 tag to ID3v1 tag in selected file.

       id3 -D source.mp3 -1 -2 dest.mp3
	      Duplicate ID3v1 and ID3v2 tags of source.mp3

       id3 -a "TAFKAT" -n "%1" -t "%+2" "*. *.mp3"
	      Update tag fields similar to this;
		-a "TAFKAT" -n "01" -t "My Song"  "01. my_song.mp3"
		-a "TAFKAT" -n "02" -t "Untitled" "02. untitled.mp3"

       id3 -2 -f "%a - %t.mp3" blaet.mp3
	      Rename file to a standard format, using ID3v2 values.

       id3 -a %t -t %a "*.mp3"
	      Swap artist and title fields in all mp3's.

       id3 -2 -rAPIC -s 0 *.mp3
	      Removes embedded images and padding from all mp3's.

       id3 -2d -u *.mp3
	      Rewrite ID3v2 tag while keeping only the basic fields.

       id3 -2 -wUSLT "foo, bar0alala!0 blaet.mp3
	      Adds an ID3v2 lyric frame to blaet.mp3.

       id3 -v -g alt-rock -alnt "The Author" %1 %2 %3 "Author - */(*) *.mp3"
	      Process multiple directories at once.

       id3 -v -g alt-rock -a "The Author" -m "Author - %l/(%n) %t.mp3"
	      Shorthand for the previous example.

       id3 -2 -c "Was: %_f" -f "%|Nobody|a - %|Untitled (%x)|t.mp3" "*.mp3"
	      Advanced rename. Saves previous filename in the comment field.

       id3 -2 -q "%| %a - %|Untitled|t || %t || %1 |?" "*.mp3"
	      Generate a playlist.

              
._  __|_ _  _ 
| |(_)|_(/__> 
~~~~~~~~~~~~~~
       The internal pattern matching emulates the normal pattern  matching  of
       "sh". It supports ?, * and [].

       A  shell  pattern will never match a forward slash ("/") or a dot (".")
       beginning a filename. Wildcards can be used for directories as well (to
       arbitrary depths), in which case a search will be performed.

       In  an  ambiguous  situation, the pattern matcher will always resolve a
       "*" wildcard to the shortest possible sequence of tokens. This  differs
       from  the  behavior  of	regular  expressions, however it tends to make
       sense in the context of filenames.

       Do NOT add ID3 tags to files for which it does not make sense, i.e, add
       them  only  to  MP3  files. In particular, do not add ID3v2 tags to Ogg
       files, since ID3v2 tags start at the beginning of the file.

                                
 _ _ ._ _ ._  _._|_o|_ o|o_|_   
(_(_)| | ||_)(_| |_||_)||| |_\/ 
~~~~~~~~~~|~~~~~~~~~~~~~~~~~~/~~
       id3 has a built-in genre list of 148 genres. If you pass the -g parame-
       ter  a  string  instead of a number when using ID3v1, id3 tries to find
       the specified genre in this list,  and  selects	the  closest  possible
       match  (if  any). For the genre numbers and exact spelling, see id3v1.c
       in the source distribution. An empty or invalid genre is  assigned  the
       number 0.

       id3  automatically  writes  Unicode  tags where necessary. Depending on
       your system, you may only be able to fully work with all characters  if
       you are using an UTF-8 locale.

       id3  will write the ID3v2 tag version that was encountered and does not
       convert from one version to another. If no existing tag is  found,  ID3
       v2.3 will be written (this may change in a future version).

       The  -wFRAME  parameter	only  knows  the  following  ID3v2.2  (3  let-
       ter)/ID3v2.3 (4 letter)	frames:  T??/T???  (text),  W??/W???  (links),
       COM/COMM  (comment),  IPL/IPLS  (involved   people), ULT/USLT (lyrics),
       CNT/PCNT (numeric play counter) and USER (tos, v2.3 only).  Frames that
       do not match the tag type encountered are ignored and not converted. It
       is a no-op for ID3v1.

       id3 does not (currently) support ID3v2 v4.0 tags. It also does not sup-
       port ID3v2 features as compression, encryption, ...

                 
 _.  _|_|_  _ ._ 
(_||_||_| |(_)|  
~~~~~~~~~~~~~~~~~
       Written by Marc R. Schoolderman <squell@alumina.nl>.

                      
 _ _ ._   ._o _ |__|_ 
(_(_)|_)\/| |(_|| ||_ 
~~~~~|~~/~~~~~_|~~~~~~
       This  is free software; see the source for copying conditions. There is
       NO warranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR
       PURPOSE.

                   
 _ _  _   _.| _ _  
_>(/_(/_ (_||_>(_) 
~~~~~~~~~~~~~~~~~~~
       Program homepage: http://home.wanadoo.nl/squell/id3.html