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