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

       Brice Goglin

                                                  NOVEMBER 2006                                         LLTAG(1)

       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.

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:

       Parsingthefilenamelltag 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).

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

       Explicitlysettingvalueslltag provides a set of command-line option to manually set various tags.

       Manuallyeditingvalueslltag 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 MAINMENU in INTERACTIVEMENUS 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.

       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

/etc/lltag/formats
              System-wide internal format database.  See INTERNALFORMATS 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 CONFIGURATIONFILES for details.
       $HOME/.lltag/config
              User configuration file.

       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.

       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.

   MAINMENU
       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 PARSINGMENUC      Query CDDB, see CDDBMENUSE      Edit values, see EDITINGMENUD      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

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

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

       q (or EOF)
              Quit CDDB query, see MAINMENU

       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 MAINMENU

       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 EDITINGMENUv      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 MAINMENU

       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.

   PARSINGMENU
       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.

   EDITINGMENU
       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 tagFOO 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

   RENAMINGMENU
       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.

       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.

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

-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 occurrence
              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 PARSINGMENU in INTERACTIVEMENUS 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 CONFIGURATIONFILES 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 CONFIGURATIONFILES 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 occurrence 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 RENAMINGMENU in INTERACTIVEMENUS 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  INTERNALFORMATS  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.

lltag_config(5), lltag_formats(5)

       The howto.html file provided within the documentation.

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...