BTAG(1)

💖 BTAG(1) — the btag manual, but make it cute 💖

okay bestie, welcome to the btag page from the btag Manual. it's a whole command line multimedia tagger and honestly? she's iconic. let's get into it. 🎀

---

✨ NAME ✨

btag — a command line based multimedia tagger 🦋

---

🌸 SYNOPSIS 🌸

btag [options] path1 [path2] [path3] ...

---

💅 DESCRIPTION 💅

so btag is a TagLib-based command line multimedia tag editor, and her whole thing is that she tries to automate tagging a ton of files at once. no cap. she takes the tags already chillin' in the files you give her, plus some interactive user input, and figures out new values for the tags. and if you want, she can also rename files and directories based on those new values. it's giving ✨organization✨.

you can hand her paths to files or directories. directories get recursively traversed and every file she finds gets tagged. and dirs are also handled differently in the sense that btag will try to keep info about the files she already tagged so she can give you sane defaults for all the other files in the same parent directory. 🫶 only files with file extensions that TagLib supports even get considered, so don't come at her with random stuff.

you can also specify multiple cue sheets. when you do, btag searches for track info in all of them, in the order you specified them. track numbers get automatically adjusted assuming all the cue sheets have track numbers starting from 1 — which is lowkey perfect for tagging albums that span multiple CDs. 💿💿 note though: a single encoding is assumed for all the cue sheets you specify. iykyk.

---

👑 OPTIONS 👑

• --always-ask-track — always ask for confirmation for the track number. no auto-accepting here, she wants your blessing every time 🙈
• -C/--cue-sheet file — read any existing metadata from the cue sheet file
• --cue-sheet-encoding enc — assume encoding enc for the cue sheet (often UTF-8 or ISO-8859-1)
• -D/--dry-run — don't do anything, just show what would have been done (dry run mode). vibes only, no actual changes 💀
• -d/--dir-rename-format format — use format to rename the directories where the multimedia files were found
• -i/--input-filter filter — use filter as the input filter
• -f/--filter filter — use filter as both the input and the output filter
• -h/--help — display usage information and exit
• -n/--renaming-filter filter — use filter as the renaming filter
• -o/--output-filter filter — use filter as the input filter
• -r/--file-rename-format format — use format to rename the multimedia files
• -t/--title-locale locale — use locale for proper (although lax) locale-specific title casing

---

🧚 INPUT AND OUTPUT FILTERS 🧚

btag supports input and output filters that get applied to the text fields — that's artist, album... wait no, album and song title. 💖 those filters can protect you against basic mistakes like duplicate whitespace (the audacity of extra spaces, honestly). input filters get used on the tags as they're loaded from the multimedia files. that filtered info is what's used to give you suggestions when the interactive tagger asks for those text fields. and if an output filter is configured, your input then gets filtered, and if the filtered text doesn't match what you typed, she asks you for confirmation. consent matters 💅

in most cases, the input filter should match the output filter (which is literally why the -f option is so handy). you may choose to specify only an input filter, in which case your user input is not filtered. but if you don't specify an input filter at all? the default input filter kicks in. 🎀

the currently available filters are:

• basic — provides basic filtering by removing duplicate or trailing whitespace, is the default input filter and the base for all other filters
• first_upper — the first character in the field is uppercased, while all others are lowercased
• lower — all characters are lowercased
• title — the first character of each word is uppercased (with exceptions), while all others are lowercased
• upper — all characters are uppercased

the title capitalization algorithm follows locale-specific context-insensitive rules depending on the value of the -t parameter. heads up though: strict title capitalization rules often depend on the context the words are used in, and precisely analyzing that is way beyond the scope of btag. she's doing her best. 😭 the currently supported title locale specifications are:

• en — English (default)
• es — Spanish

---

🎀 RENAMING FORMATS 🎀

if a format is specified with the -r option, the tagged multimedia files get renamed accordingly. same energy with -d: the directory where multimedia files were tagged gets renamed according to the specified format. ✨

the specified format is converted to a file or directory name using these substitutions:

• %artist — Artist name
• %album — Album name
• %year — Year of release
• %track — Track number (only replaced by the -r option)
• %title — Song title (only replaced by the -r option)

renaming happens after the tags are written, and it's relative to btag's working directory.

for directory renaming, the last known artist, album and year information is used. only directories that contain files that were tagged by btag get renamed.

⚠️ okay so listen: btag does not prevent you from overwriting existing files using the formats described here. be careful bestie, she will not stop you. 💀

---

🌈 RENAMING FILTERS 🌈

renaming filters make sure the file and directory names generated using the renaming formats (if specified) are valid (safe) in the context of the current file system. the following renaming filters are currently available:

• conservative — conservative character replacements are performed, recommended for FAT32 file systems
• unix — generates file and directory names that should be valid in an Unix environment (default)

---

⭐ NOTES ⭐

you can specify any encoding supported by iconv_open(3). 🫶

---

💀 BUGS 💀

there is no standard encoding for cue sheets, so btag assumes ISO-8859-1 if no encoding is specified. yeah. that's just how it is.

although you can specify any encoding for cue sheets, the body of the cue sheet will be read using the system's locale. only the text fields in the cue sheet get converted from the specified encoding. to prevent trouble, use an ASCII-compatible system-wide charset (preferably UTF-8) and stick to ASCII-compatible encodings for cue sheets (preferably ISO-8859-1). fr fr, do this.

---

🔥 EXAMPLE 🔥

using title casing with English rules and sensible renaming formats generating FAT32-safe file and directory names:

$ btag --file-rename-format '%track. %title' \
       --dir-rename-format '%album (%year)' \
       --filter title --title-locale en \
       --renaming-format conservative /path/to/myalbum

using an input filter only:

$ btag --input-filter lower /path/to/myalbum

---

and that's the whole page, bestie! 💖 this little gem is btag, version/date 2012-17-06, from the btag Manual — main character energy since day one. go tag something gorgeous. 👑✨🎀🦋