lltag - tag and rename mp3/ogg/flac music files automagically
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...
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.
- -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 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 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
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.
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.
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
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.
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.
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
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.
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.
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 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.
/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
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: