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

INPUT AND OUTPUT FILTERS

       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

RENAMING FORMATS

       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