LLTAG(1)

📦 version 0.14.6, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 LLTAG(1) — the lltag manual, bestie edition 💖

General Commands Manual · part 1 of 3, so don't go anywhere 🫶

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

okay yes it's a lot of brackets, it's giving "I contain multitudes" and honestly? slay 💅

🦋 DESCRIPTION 🦋

lltag is a command-line tool that automagically sets the tags on your MP3, OGG or FLAC files. And there are like, several whole ways to get the tags that are gonna get set:

💜 Parsing the filename

lltag can either parse the filename using its own internal database of commonly-used formats — that's the default behavior, or what you get when -G is passed — or it can use some formats that you provide, which happens when -F is passed.

💜 Requesting from CDDB

lltag can hit up an online CDDB database to pull tags from a track of a CD. That's the -C situation.

💜 Explicitly setting values

lltag hands you a whole set of command-line options so you can manually set various tags yourself. Very main character of you.

💜 Manually editing values

lltag also gives you an interactive interface to edit existing values, or literally any value that came out of the strategies above.

So every single time a new audio file gets processed, lltag starts by trying to obtain new tags, and exactly what it does depends on the behavior options you gave it.

Here's the order of operations, and it matters, so pay attention bestie:

  1. First, if a preferred parser was selected before, it gets used to try to parse the new filename.
  2. Then, if editing is enabled (-E), you get to modify existing tag values.
  3. Then, if CDDB is enabled (-C), you'll be asked whether to request tags from the online CDDB database.
  4. Then, if you provided any parsing format (-F), or if guessing is enabled (-G), lltag will attempt to parse the filename.
ngl this one's important: if you don't choose any behavior at all on the command line — including no renaming option — then parsing with the internal format database gets used by default, as if -G had been passed. 🫶

The moment one of those strategies succeeds, lltag jumps to the main menu, where you can either accept the new tags or pick another behavior. (Scroll to MAIN MENU in INTERACTIVE MENUS below for the deets, iykyk.) And if --yes was passed, or if automatic mode was already turned on in the menu, it'll just go ahead and do the tagging — plus renaming if you asked for it — then move on to the next file. Periodt.

The new tags that your chosen strategy returns get appended with the explicit values you gave via -a, -t, -A, -g, -n, -d, -c or --tag. Then those combined tags will either:

  • replace the existing tags in the target file (this is the default),
  • clear and replace them (--clear), or
  • append to them (--append).

Once the tags are known, a backend program or library is used to apply them to the audio file — unless --no-tagging is passed, obviously. And here's who does the work:

  • the MP3::Tag Perl module or mp3info handles tagging MP3 files 🎵
  • vorbiscomment handles OGG files 🌈
  • metaflac handles FLAC files ✨

And at the very end, when you call it with --rename, the target file also gets renamed according to a format you provide, filled in with the tag values. iconic, honestly 💖

✨ more coming in part 2, don't touch that dial ✨

✨ OPTIONS ✨

okay bestie, this is the big one — every single flag lltag will take, what it does, and which config-file option it's lowkey twinning with. no skips, we're doing all of them 💅

  • -A, --ALBUM <album> — adds a value for the ALBUM tag 🎀
  • -a, --ARTIST <artist> — adds a value for the ARTIST tag 🌸
  • --append — forces appending of ogg/flac tags (instead of replacing existing tags). the config file option is append_tags. ⚠️ and here's the tea: since mp3 files may only get one tag of each type, appending does literally nothing for them — the first occurrence only is stored. no cap.
  • --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 config file option is ask. see PARSING MENU in INTERACTIVE MENUS below for the deets 👀
  • -C, --cddb — tries 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 config file option is cddb 🌈
  • --cddb-query <keywords>
  • --cddb-query <cat>/<id> — automatically searches for a CD matching <keywords>, or matching category <cat> and id <id>, as if the user passed --cddb and typed the query in interactively in the module. two flavors, one icon 🫶
  • --cddb-server <server[:port]> — changes the CDDB server, and eventually its port too. the default is www.freedb.org:80. the corresponding config 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 it to something like "http://my.proxy.com") 🌐
  • -c, --COMMENT <comment> — adds a value for the COMMENT tag 💬
  • --clear — forces clearing of all tags before tagging (instead of replacing existing tags). the config file option is clear_tags. fresh start energy ✨
  • --config <file> — parses an additional configuration file. see CONFIGURATION FILES below for details.
  • -d, --DATE <date> — adds a value for the DATE tag. 📅 heads up tho: the ID3 date tag may only store 4 characters (for a year), so don't get too ambitious.
  • --dry-run — does not really tag files, just shows what would have been done. the config file option is dry_run. pretend-tagging, no consequences, love that for us 🙈
  • -E, --edit — edits tags immediately ✏️
  • -F, --format <format> — adds the specified format string to the list of user-supplied formats. the config file option is format. might be used several times to try different formats. see FORMAT below for details 💖
  • --flac — tags all files as FLAC files, using the FLAC backend (based on metaflac). the config file option is type.
  • -G, --guess — guesses format using the internal database if no user-specified format worked (this is the default behavior, bestie). the config file option is guess 🔮
  • -g, --GENRE <genre> — adds 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. so like, read the room 🎵
  • --gencfg <file> — generates a configuration file. see CONFIGURATION FILES below for details.
  • -h, --help — prints a usage message and exits. the classic 🫶
  • -L, --list — lists internal formats 📋
  • --maj — upcases the first letter of each word in tags. the config file option is maj. it's giving Title Case 👑
  • --mp3 — tags all files as MP3 files, using the MP3 backend (based on either mp3info or MP3::Tag). the config file option is type.
  • --mp3v2, --id3v2 — enables the experimental MP3 ID3v2-aware backend (based on MP3::Tag) instead of the old ID3v1-only backend. experimental = proceed with cute caution 🧪
  • --mp3read=[1][2] — configures 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, so no dupes in the group chat 🚫
  • -n, --NUMBER <number> — adds a value for the NUMBER tag 🔢
  • --no-tagging — does not actually tag files. this might be used to rename files without tagging. the config file option is no_tagging.
  • -T, --preserve-time — preserves file modification time during tagging. the config file option is preserve_time. respect the timestamps 🕰️
  • --ogg — tags all files as OGG files, using the OGG backend (based on vorbiscomment). the config file option is type.
  • -p, --no-path — does not consider the path of files when matching. the config file option is no_path 🛣️
  • -q, --quiet — decreases message verbosity. the config file option is verbose, which indicates the verbose level. see -v for details about the existing verbosity levels. shhh 🤫
  • -R, --recursive — recursively searches for files in subdirectories that are given on the command line. the config file option is recursive. down the rabbit hole we go 🐇
  • --regexp <[tag,tag:]s/from/to/> — replaces from with to in tags before tagging. the config 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, renames the file according to the format. the config 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 — assumes that the file extension is provided by the rename format instead of automatically adding the extension corresponding to the file type. the config file option is rename_ext.
  • --rename-min — lowcases all tags before renaming. the config file option is rename_min. lowercase era 💅
  • --rename-regexp <[tag,tag:]s/from/to/> — replaces 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 config file option is rename_regexp.
  • --rename-sep <sep> — replaces spaces with sep when renaming. the config file option is rename_sep. see --rename-regexp for a more general replace feature.
  • --rename-slash <char> — replaces slashes with char when renaming. the config file option is rename_slash. see --rename-regexp for a more general replace feature. slashes are not the vibe in filenames 🚫
  • -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> — replaces the specified characters or strings with a space in tags. the config 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 — allows multiple or no space instead of only one when matching. also allows spaces limiting path elements. the config file option is spaces. see also INTERNAL FORMATS to get the detailed impact of this option.
  • -t, --TITLE <title> — adds a value for the TITLE tag ✨
  • --tag <TAG=value> — adds an explicit tag value. the config 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> — tags all files as <type> files. the config file option is type.
  • -v, --verbose — increases message verbosity. the config 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 — shows the version 🏷️
  • --yes — always accepts tagging without asking the user. the config file option is yes. by default, user-specified format matching is accepted while guess format matching is asked for confirmation. it also always accepts renaming without asking the user. consent mode: off, chaos mode: on 💀

🎀 INTERACTIVE MENUS 🎀

So when you're not running with --yes, bestie, you have to tell lltag what to do. It's not gonna guess your whole life for you. Files get processed one after the other, and each one goes through this lil journey:

  • If the preferred parser exists, it tries to apply it. Go parser go ✨
  • If that failed, and if --cddb was passed, it tries a CDDB query.
  • If that failed too, it tries the user-provided formats, if any were given.
  • Still failed? Then if no user-format was passed, or if -G was passed, it tries the internal formats.
  • Then boom — we have a list of tags to apply, and we may apply them, edit them, or go back to a CDDB query / try parsing the filename again.
  • Then, if --rename was passed, the file gets renamed. Glow up 💅
Okay but real talk: when you hit Ctrl-d at the beginning of an empty line (that's EOF), the general behavior is to cancel the current operation without leaving. So you can bail on the thing you're doing without yeeting the whole program. Iconic.

Now let's describe all the interactive menus in detail, because there are a lot of them and they all have lore. 🧚

Once some tags have been obtained by either CDDB, parsing, or the explicit values you gave on the command line, the main menu opens so you can either change the tags or just 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. Bye bestie 😭

💿 CDDB MENUS 💿

When the CDDB opens for the very first time, you must enter a query to choose a CD in the online database. No skipping, it's the rules.

  • space-separated keywords — CDDB query for CD matching the keywords. It searches in all CD categories within the fields artist OR album. So like, it's searching everywhere, periodt.
  • 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 gets displayed. Then you gotta 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 has been chosen, you need 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.
✨ Pro tip from the manpage itself: entering the CDDB menus again will go back to the previous CD instead of asking you to query again, so that an entire CD may be tagged easily. That's genuinely so convenient, we love efficiency here 🫶

🔍 PARSING MENU 🔍

When --ask is passed, or when it's guessing, each matching leads to a confirmation message before tagging. Here's what you can do:

  • 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 ✏️

You can edit tags, either before tagging a file, or before choosing a track in a CD obtained by CDDB. The current value of all regular fields is shown, and you may modify it by entering another value, delete it by entering <DELETE>, or clear it.

The behavior depends on the installed readline library, and honestly that library is the main character of this whole section:

  • If it's smart, the current value may be edited inline and a history is available. So bougie ✨
  • If it's not smart, pressing <enter> will keep the current value while CLEAR will empty it.
  • EOF will cancel the editing of this single value.

Each field may be selected for edition by pressing its corresponding letter in the format (see FORMAT). And since there might be some non-standard tag names, it's also possible to enter tag FOO to modify tag FOO. Very flexible of you, honestly.

Editing ends by tagging (if E is pressed) or canceling and returning to the 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 from the user. You may bypass it by passing --yes on the command line. (Living dangerously, I respect it.)

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

Available behaviors when renaming:

  • 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's smart, the current value may be edited inline and a 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. Think of these as the little spell-codes of the tag world 🪄:

  • %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, these extra 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 — user wins, always 💅

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

⚙️ CONFIGURATION FILES ⚙️

lltag reads some configuration files before parsing command line options. Order matters, periodt.

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. Slay, it writes its own config 🎀

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 👀

The howto.html file provided within the documentation. Go read it, iykyk 📖

👑 AUTHOR 👑

Brice Goglin

And that's a wrap on LLTAG(1), bestie 🫶 This page came from the lltag source and its date stamp says NOVEMBER 2006 — vintage but still serving, fr fr. Go tag something and make it iconic ✨💅

📦 where this page comes from