Provided by: lltag_0.14.4-2_all bug

NAME

       lltag - tag and rename mp3/ogg/flac music files automagically

SYNOPSIS

       lltag  [-C]  [-E]  [-F  <format>]  [-G]  [-p]  [-a <artist>] [-t <title>] [-A <album>] [-n
       <number>] [-g <genre>] [-d <date>] [-c <comment>] [--tag <TAG=value>]  [--spaces]  [--maj]
       [--sep <s1|s2|...>]  [--regexp  <regexp>]  [--mp3/--ogg/--flac]  [--type <type>] [--clear]
       [--append] [--no-tagging] [--preserve-time] [--rename <format>] [--rename-ext]  [--rename-
       min]  [--rename-sep  <sep>] [--rename-slash <char>] [--rename-regexp <regexp>] [--dry-run]
       [--yes] [--ask] [--cddb-query <query>]  [--cddb-server  <server[:port]>]  [-R]  [-v]  [-q]
       [--config <file>] [--gencfg <file>] [-S] [--show-tags <tags>] [-L] [-V] [-h] files...

DESCRIPTION

       lltag  is  a  command-line tool to automagically set tags of MP3, OGG or FLAC files. There
       are several ways to obtains the tags that will be set:

       Parsing the filename
              lltag may either parse the filename using its own internal  database  of  commonly-
              used  formats  (default  behavior,  or  when  -G  is passed), or some user-provided
              formats (when -F is passed).

       Requesting from CDDB
              lltag may access an online CDDB database to extract tags from a track of a CD (when
              -C is passed).

       Explicitly setting values
              lltag provides a set of command-line option to manually set various tags.

       Manually editing values
              lltag  provides  an  interactive  interface  to  edit  existing values or any value
              provided by the above strategies.

       Each time, a new audio file is processed, lltag  starts  by  trying  to  obtain  new  tags
       depending on the behavior options given by the user.

       First,  if a preferred parser has been selected before, it is used to try to parse the new
       filename.  Then, if editing is enabled (-E), the user will be able to modify existing  tag
       values.   Then,  if  CDDB is enabled (-C), the user will be asked to request tags from the
       online CDDB database.  Then, if the user provided any parsing format (-F), or if  guessing
       is enabled (-G), lltag will attempt to parse the filename.

       Note  that  if no behavior is chosen at all on command-line, including no renaming option,
       then parsing with the internal format database will be used by default (as if -G had  been
       passed).

       As  soon  as  one of the above strategies succeeds, lltag jumps to the main menu where the
       user may either accept new tags or select another behavior (see MAIN MENU  in  INTERACTIVE
       MENUS  below  for  details).   If  --yes  has  been  passed, or if automatic mode has been
       previously enabled in the menu, it will proceed with tagging (and renaming  if  requested)
       and go on with the next file.

       The  new tags that the selected strategy returns will be appended with the explicit values
       given with  -a , -t , -A , -g , -n , -d , -c or --tag .  They  will  then  either  replace
       (default),  clear  and  replace (--clear) or append to (--append) the existing tags in the
       target file.

       Once the tags are known, a backend program or library is used to apply them to  the  audio
       file  (unless --no-tagging is passed).  The MP3::Tag Perl module or mp3info is used to tag
       MP3 files while vorbiscomment is used for OGG files, and metaflac is used for FLAC files.

       In the end, when called with --rename, the target file will also be renamed according to a
       user-provided format filled with the tag values.

OPTIONS

       -A, --ALBUM <album>
              Add a value for the ALBUM tag.

       -a, --ARTIST <artist>
              Add a value for the ARTIST tag.

       --append
              Force  appending  of  ogg/flac  tags  (instead  of  replacing  existing tags).  The
              corresponding configuration file option is append_tags.

              Since mp3 files may only get one tag of each  type,  appending  does  nothing,  the
              first occurence only is stored.

       --ask  Always  ask  confirmation  to  the  user  before  using a user-specified parser. By
              default, all actions require confirmation, except when  a  matching  user-specified
              format  is found.  The corresponding configuration file option is ask.  See PARSING
              MENU in INTERACTIVE MENUS below for details.

       -C, --cddb
              Try to find tags in the CDDB online database before trying to parse filenames.  The
              queries  are  sent using the HTTP interface, which means a HTTP proxy might be used
              when required.  The corresponding configuration file option is cddb.

       --cddb-query <keywords>

       --cddb-query <cat>/<id>
              Automatically search for CD matching <keywords> or matching category <cat>  and  id
              <id>  as  if  the  user  passed  --cddb  and entered the query interactively in the
              module.

       --cddb-server <server[:port]>
              Change the CDDB server, and eventually its port.  The default is www.freedb.org:80.
              The   corresponding   configuration   file   options   are   cddb_server_name   and
              cddb_server_port.  If a  HTTP  proxy  is  required  to  access  the  internet,  the
              environment   variable   HTTP_PROXY   may   be   used   (set   to   something  like
              "http://my.proxy.com").

       -c, --COMMENT <comment>
              Add a value for the COMMENT tag.

       --clear
              Force clearing of all tags before tagging (instead  of  replacing  existing  tags).
              The corresponding configuration file option is clear_tags.

       --config <file>
              Parse additional configuration file.  See CONFIGURATION FILES below for details.

       -d, --DATE <date>
              Add  a  value  for  the  DATE  tag.   Note  that  the ID3 date tag may only store 4
              characters (for a year).

       --dry-run
              Do not really tag files, just show what would have been  done.   The  corresponding
              configuration file option is dry_run.

       -E, --edit
              Edit tags immediately.

       -F, --format <format>
              Add  the  specified  format  string  to  the  list  of  user-supplied formats.  The
              corresponding configuration file option is format.  Might be used several times  to
              try different formats.  See FORMAT below for details.

       --flac Tag  all  files  as  FLAC  files,  using the FLAC backend (based on metaflac).  The
              corresponding configuration file option is type.

       -G, --guess
              Guess format using  the  internal  database  if  no  user-specified  format  worked
              (default behavior).  The corresponding configuration file option is guess.

       -g, --GENRE <genre>
              Add a value for the GENRE tag.  While some file types accept any string as a genre,
              some others (especially ID3v1 tags in MP3 files) require the string to match within
              a list of specified genres.

       --gencfg <file>
              Generate configuration file.  See CONFIGURATION FILES below for details.

       -h, --help
              Print a usage message and exit.

       -L, --list
              List internal formats.

       --maj  Upcase the first letter of each word in tags.  The corresponding configuration file
              option is maj.

       --mp3  Tag all files as MP3 files, using the MP3  backend  (based  on  either  mp3info  or
              MP3::Tag).  The corresponding configuration file option is type.

       --mp3v2, --id3v2
              Enable  the experimental MP3 ID3v2-aware backend (based on MP3::Tag) instead of the
              old ID3v1-only backend.

       --mp3read=[1][2]
              Configure how the MP3v2 backend reads and merges ID3v1 and v2 tags.  By default, v1
              are  appended to v2 (21).  If set to 1, only v1 are read.  If set to 2, only v2 are
              read.  If set to 12, v2 are appended to v1.  Note that merging/appending takes care
              of removing duplicates.

       -n, --NUMBER <number>
              Add a value for the NUMBER tag.

       --no-tagging
              Do not actually tag files. This might be used to rename files without tagging.  The
              corresponding configuration file option is no_tagging.

       -T, --preserve-time
              Preserve file modification time during tagging.   The  corresponding  configuration
              file option is preserve_time.

       --ogg  Tag  all  files  as OGG files, using the OGG backend (based on vorbiscomment).  The
              corresponding configuration file option is type.

       -p, --no-path
              Do not consider the path of files when matching.  The  corresponding  configuration
              file option is no_path.

       -q, --quiet
              Decrease message verbosity.  The corresponding configuration file option is verbose
              which indicates the verbose level.  See -v for details about the existing verbosity
              levels.

       -R, --recursive
              Recursively  search for files in subdirectories that are given on the command line.
              The corresponding configuration file option is recursive.

       --regexp <[tag,tag:]s/from/to/>
              Replace from with to in tags before tagging.  The corresponding configuration  file
              option is regexp.  If several tags (comma-separated) prefix the regexp, replacement
              is only applied to the corresponding fields.  This option might  be  used  multiple
              times to specify multiple replacing.

       --rename <format>
              After  tagging,  rename  the  file  according  to  the  format.   The corresponding
              configuration file option is rename_format.  The format is filled using  the  first
              occurence of each tag that was used to tag the file right before.  It means that an
              old existing tag may be used if no new one replaced it and --clear was not passed.

              By default, confirmation is asked before tagging.  See RENAMING MENU in INTERACTIVE
              MENUS below for details.

       --rename-ext
              Assume  that  the  file  extension  is  provided  by  the  rename format instead of
              automatically  adding  the  extension  corresponding  to  the   file   type.    The
              corresponding configuration file option is rename_ext.

       --rename-min
              Lowcase  all  tags before renaming.  The corresponding configuration file option is
              rename_min.

       --rename-regexp <[tag,tag:]s/from/to/>
              Replace from with to in tags before renaming.  If  several  tags  (comma-separated)
              prefix  the  regexp, replacement is only applied to the corresponding fields.  This
              option  might  be  used  multiple  times  to  specify  multiple   replacing.    The
              corresponding configuration file option is rename_regexp.

       --rename-sep <sep>
              Replace spaces with sep when renaming.  The corresponding configuration file option
              is rename_sep.  See --rename-regexp for a more general replace feature.

       --rename-slash <char>
              Replace slashes with char when  renaming.   The  corresponding  configuration  file
              option is rename_slash.  See --rename-regexp for a more general replace feature.

       -S     Instead  of  tagging,  lltag  shows  the tags that are currently set in files.  See
              --show-tags to show only some tags.

       --sep <string|string>
              Replace the specified characters or strings with space in tags.  The  corresponding
              configuration file option is sep.  They have to be |-separated.  See --regexp for a
              more general replace feature.

       --show-tags <tag1,tag2,...>
              Instead of tagging, lltag shows tags that are currently set in files.  The argument
              is  a comma separated list of tag types (artist, title, album, number, genre, date,
              comment or all).  See also -S to show all tags.

       --spaces
              Allow multiple or no space instead of only one when matching.   Also  allow  spaces
              limiting  path  elements.   The  corresponding configuration file option is spaces.
              See also INTERNAL FORMATS to get the detailled impact of this option.

       -t, --TITLE <title>
              Add a value for the TITLE tag.

       --tag <TAG=value>
              Add an explicit tag value.  The corresponding configuration  file  option  is  tag.
              Might  be used several times, even for the same tag.  When setting a common tag, it
              is similar to using -a, -A, -t, -n, -g, -d or  -c.   Note  that  mp3  tags  do  not
              support whatever TAG.

       --type <type>
              Tag  all  files  as  <type>  files.  The corresponding configuration file option is
              type.

       -v, --verbose
              Increase message verbosity.  The corresponding configuration file option is verbose
              which indicates the verbose level.

              The  default  verbosity level is 0 to show only important messages.  Other possible
              values are 1 to show usage information when a menu is displayed for the first time,
              and 2 to always show usage information before a menu appears.

              See also -q.

       -V, --version
              Show the version.

       --yes  Always  accept  tagging  without  asking the user.  The corresponding configuration
              file option is yes.  By default user-specified format matching  is  accepted  while
              guess format matching is asked for confirmation.

              Also always accept renaming without asking the user.

INTERACTIVE MENUS

       When  not running with --yes, the user has to tells lltag what to do.  Files are processed
       one after the other, with the following steps:

       *      If the preferred parser exists, try to apply it.

       *      If failed, if --cddb was passed, trying a CDDB query.

       *      If failed, try the user-provided formats, if any.

       *      If failed, if no user-format were passed, or if -G was  passed,  try  the  internal
              formats.

       *      Then we have a list of tags to apply, we may apply them, edit them, or go back to a
              CDDB query or trying to parse the filename again.

       *      Then, if --rename was passed, the file is renamed.

              When hitting Ctrl-d at the beginning of an empty line (EOF), the  general  behavior
              is to cancel the current operation without leaving.

              We now describe all interactive menus in detail.

   MAIN MENU
       Once  some tags have been obtained by either CDDB, parsing or the explicit values given on
       the command line, the main menu opens to either change the tags or apply them:

       y      Yes, use these tags (default)

       a      Always yes, stop asking for a confirmation

       P      Try to parse the file, see PARSING MENU

       C      Query CDDB, see CDDB MENUS

       E      Edit values, see EDITING MENU

       D      Only use explicit values, forget about CDDB or parsed tags

       Z      Reset to no tag values at all

       R      Revert to existing tag values from the current file

       O      Display existing tag values in the current file

       n      Do not tag this file, jump to  renaming  (or  to  the  next  file  if  renaming  is
              disabled)

       q (or EOF)
              Skip this file

       Q      Quit without tagging anything anymore

   CDDB MENUS
       When  the CDDB opens for the first time, the user must enter a query to choose a CD in the
       online database.

       <space-separated keywords>
              CDDB query for CD matching the keywords.  Search in all CD categories within fields
              artist OR album.

       q (or EOF)
              Quit CDDB query, see MAIN MENU

       Once  keywords  have  been passed as a query to CDDB, a list of matching CD titles will be
       displayed. The user then needs to choose one:

       <index>
              Choose a CD in the current keywords query results list

       V      View the list of CD matching the keywords

       k      Start again CDDB query with different keywords

       q (or EOF)
              Quit CDDB query, see MAIN MENU

       Once a CD have been chosen, the user needs to choose a track

       <index>
              Choose a track of the current CD

       <index> a
              Choose a track and do not ask for confirmation anymore

       a      Use default track and do not ask for confirmation anymore

       E      Edit current CD common tags, see EDITING MENU

       v      View the list of CD matching the keywords

       c      Change the CD chosen in keywords query results list

       k      Start again CDDB query with different keywords

       q (or EOF)
              Quit CDDB query, see MAIN MENU

       Note that entering the CDDB menus again will go back to the previous CD instead of  asking
       the user to query again, so that an entire CD may be tagged easily.

   PARSING MENU
       When  --ask  is passed or when guessing, each matching will lead to a confirmation message
       before tagging.  Available behaviors are:

       y      Tag current file with current format. This is the default.

       u      Tag current file with current format.  Then use current format  for  all  remaining
              matching  files.   When  a  non-matching file is reached, stop using this preferred
              format.

       a      Tag current file with current  format.   Then,  never  asking  for  a  confirmation
              anymore.

       n      Don't  tag  current  file  with  this  format.  Try the next matching format on the
              current file.

       p      When matching is done through combination of a path parser and a  basename  parser,
              keep the basename parser and try the next path parser on the current file.

       q (or EOF)
              Stop trying to parse this file.

   EDITING MENU
       It  is possible to edit tags, either before tagging or file, or before choosing a track in
       a CD obtained by CDDB.  The current value of all  regular  fields  is  shown  and  may  be
       modified by entering another value, deleted by entering <DELETE>, or cleared.

       The behavior depends on the installed readline library.  If it is smart, the current value
       may be edited inline and an history is available.  If not, pressing <enter> will keep  the
       current  value  while  CLEAR  will  empty it.  EOF while cancel the editing of this single
       value.

       Each field may be selected for edition by pressing its corresponding letter in the  format
       (see  FORMAT).   Since  there might be some non-standard tag names, it is also possible to
       enter tag FOO to modify tag FOO.

       Editing ends by tagging (if E is pressed) or canceling and return to confirmation menu (if
       C is pressed).

       The other options are:

       V      View the current values of tags

       y      End edition, save changes, and return to previous menu

       q (or EOF)
              Cancel edition, forget about changes, and return to previous menu

   RENAMING MENU
       By  default,  before  renaming, a confirmation is asked to the user.  You may bypass it by
       passing --yes on the command line.

       If the rename format uses a field that is not defined, a warning is shown and confirmation
       is always asked.

       Available behaviors when renaming are:

       y      Rename current file with current new filename.  This is the default.

       a      Rename  current  file with current new filename.  Then, never asking for a renaming
              confirmation anymore.

       e      Edit current new filename before renaming.  The behavior depends on  the  installed
              readline  library.   If  it is smart, the current value may be edited inline and an
              history is available.

       q (or EOF)
              Don't rename current file.

       h      Show help about confirmation.

FORMAT

       User-specified formats must be a string composed  of  any  characters  and  the  following
       special codes:

              %a to match the author.

              %A to match the album.

              %g to match the genre.

              %n to match the track number.

              %t to match the title.

              %d to match the date.

              %c to match the comment.

              %i to match anything and ignore it.

              %% to match %.

       Additionally, while renaming, the following codes are available:

              %F is replaced by the original basename of the file.

              %E is replaced by the original extension of the file.

              %P is replaced by the original path of the file.

INTERNAL FORMATS

       The  internal  format  database  is  usually  stored  in /etc/lltag/formats.  The user may
       override this file by defining a $HOME/.lltag/formats.  If this file exists,  the  system-
       wide one is ignored.

       See the manpage of lltag_formats or /etc/lltag/formats for details.

CONFIGURATION FILES

       lltag reads some configuration files before parsing command line options.  The system-wide
       configuration file is defined in /etc/lltag/config if it exists.

       It also reads $HOME/.lltag/config if it exists.

       The user may also add another configurable file with --config.

       lltag may also generate a configuration with --gencfg.

       See  the  manpage  of  lltag_config  or  the  example  of  config  file  provided  in  the
       documentation for details.

FILES

       /etc/lltag/formats
              System-wide internal format database.  See INTERNAL FORMATS for details.
       $HOME/.lltag/formats
              User internal format database. If it exists, the system-wide one is ignored.
       $HOME/.lltag/edit_history
              History of last entered values in the edition mode if the Readline library supports
              this feature.
       /etc/lltag/config
              System-wide configuration file, if it exists.  See CONFIGURATION FILES for details.
       $HOME/.lltag/config
              User configuration file.

EXAMPLES

       Show all tags for each OGG files in the current directory:
              lltag -S *.ogg
       Show only a selected list of tags for all files in all subdirectories:
              lltag --show-tags artist,album,title,number -R .
       Set an arbitrary tag in a file (only works with OGG vorbis or FLAC files):
              lltag --tag foo=nil foo.ogg
       Delete the foo tag from a file:
              lltag --tag foo= bar.ogg
       Set the ALBUM, ARTIST and GENRE tag values of the MP3 files in the current directory:
              lltag --ARTIST "Queen" --ALBUM "Innunendo"  --GENRE  "rock"  --COMMENT="very  cool"
              *.mp3
       Rename a file by assembling its current NUMBER, ARTIST and TITLE tag values:
              lltag --no-tagging --rename "%n - %a - %t" foobar.ogg
       Clear all tags in all FLAC files:
              lltag --clear *.flac

SEE ALSO

       lltag_config(5), lltag_formats(5)

       The howto.html file provided within the documentation.

AUTHOR

       Brice Goglin

                                          NOVEMBER 2006                                  LLTAG(1)