NAME¶
btag - A command line based multimedia tagger
SYNOPSIS¶
btag [
options]
path1 [
path2] [
path3] ...
DESCRIPTION¶
btag is a TagLib-based command line multimedia tag editor that attempts to
automate the process of tagging a lot of files at once. It uses the tags found
in the supplied files as well as interactive user input to determine new
values for the tags. It can also optionally rename files and directories based
on those new values.
You can supply paths to files or directories to btag. Directories are
recursively traversed and all files found are tagged. Directories are also
handled differently in the sense that btag will attempt to keep information
about the previously tagged files to provide sane defaults for all other files
in the same parent directory. Only files with file extensions supported by
TagLib are considered.
OPTIONS¶
- -D/--dry-run
- Don't do anything, just show what would have been done (dry
run mode)
- -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
btag supports input and output filters that are applied to the text fields
(artist, album and song title). Those filters can protect against basic
mistakes such as duplicate whitespace. Input filters are used on the tags as
they are loaded from the multimedia files. This filtered information is used
to provide suggestions to the user when the interactive tagger requests
information for those text fields. If an output filter is configured, the user
input is then filtered, and if the filtered text does not match the user
input, the user is asked for confirmation.
In most cases, the input filter should match the output filter (which is why the
-f option is handy). You may choose to specify only an input filter, in
which case the user input is not filtered. If you don't specify an input
filter, though, the default input filter will be used.
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 will follow locale-specific
context-insensitive rules depending on the value of the
-t parameter.
Note that strict title capitalization rules often depend on the context in
which the words are used, the precise analysis of which is much beyond the
scope of btag. The currently supported title locale specifications are:
- en
- English (default)
- es
- Spanish
If a format is specified with the
-r option, the tagged multimedia files
are renamed accordingly. Likewise, if the
-d option is used, the
directory in which multimedia files were tagged is renamed according to the
specified format.
The specified format is converted to a file or directory name using the
following 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 are
renamed.
btag does not prevent you from overwriting existing files using the formats
described here.
RENAMING FILTERS¶
Renaming filters are used to ensure that 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)
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