Provided by: lltag_0.14.4-1_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)