/ 
supertag-0.2.1
River stage zero No dependents
/ supertag

NAME

supertag - organize your music collection like a real superhero

SYNOPSIS

supertag MODE [OPTIONS] file1.mp3 file2.flac file3.mp3 ...

EXAMPLES

Extract metadata from audio files to an editable format:

$ supertag -g *.mp3 *.flac

Get id3v1 and id3v2 tags back in sync, then rename files using tags:

$ supertag -g *.mp3 | supertag -s -p '%02T._%A_-_%a_-_%t'

Set missing tags in bulk; rename files using new tags:

$ supertag -g -A Pinkerton -y 1996 -G Rock *.flac | supertag -s

Extract and set missing tag data from filenames, using a pattern:

$ supertag -g -S -N -P '%a_-_%t' *.mp3 | supertag -s

Rename incoming files and import them into your music library:

$ supertag -g * | supertag -s --library ~/Music

Preview the effects of supertag's default renaming operations:

$ supertag -g * | supertag -n -s -S -N

Build a song database from your entire music collection:

$ sqlite songs.db <<EOF
  > create table song(
  >  path varchar(256) primary key,
  >  album varchar(128),
  >  artist varchar(128),
  >  track varchar(128),
  >  title varchar(128));
  > EOF
$ find . -name \*.mp3 -o -name \*.flac | \
  supertag -g -H PATH,A,a,T,t --io tabular | sed -e 1d > songs.txt
$ sqlite songs.db ".import 'songs.txt' song"

OPTIONS

Modes of Operation
-g,--get        get metadata
-s,--set        set metadata
-h,--help       print help and exit
-V,--VERSION    print version and exit
Metadata Source Options
-1,--id3v1                extract from id3v1 tags (default, mp3 only)
-2,--id3v2                extract from id3v2 tags (default, mp3 only)
-F,--flac                 extract from flac tags (default, flac only)
-N,--filename             extract from filenames (default)
-U,--audio                extract standard audio metadata
-E,--codec                extract encoder metadata
-S,--no-default-sources   don't use the default sources
-p,--rename-pattern STR   format string for renaming files
-P,--capture-pattern STR  format string for scraping filenames
Standard Recognized Tags
-A,--album   STR
-a,--artist   STR
-t,--title   STR
-T,--tracknum   NUM 
-y,--year   STR
-g,--genre   STR
-c,--composer   STR
-C,--comment   STR
Behavioral Options
-H,--headers  X,Y,Z...  output only these metadata fields
-I,--io-format  FMT     data exchange format ("editable", "tabular")
-m,--mime               get filetype from file(1) (slow, default off)
-n,--dry                dry run (don't modify anything)
-v,--verbose            verbose
-d,--debug              turn on debugging messages
-q,--quit               silence warnings

MOTIVATION

supertag is a music organization tool for ordinary people who don't mind dashing into a phone booth once in a while. By "phone booth" we mean "terminal session," the celebrated origin of all superpowers...

There are plenty of music organization tools out there, pretty much one for every occasion. supertag makes sense when:

  • You've got music pouring in from many sources, in different formats, with different levels of metadata quantity and quality.

  • There's too much entropy in the inputs for a mouse-driven interface.

  • You'd rather write a script that performs a data transformation than do it all by hand.

  • You want to do a custom search on your music collection, or you want to build a custom index.

  • You'd rather edit tag data in your favorite editor than anywhere else.

  • You're more comfortable in a unix shell.

DESCRIPTION

There are two primary operating modes of supertag: get mode and set mode. In get mode, metadata is extracted from a succession of sources in each file and printed to standard out. In set mode, metadata is read from standard input and written to all selected sources of each referenced file.

The "editable" input / output format supertag uses by default looks like this:

ALBUM: Evol
ARTIST: Sonic Youth
GENRE: Rock
PATH: ~/Music/Sonic_Youth_-_Evol/01._Sonic_Youth_-_Tom_Violence.mp3
TAGVERSION: ID3v2.3.0
TITLE: Tom Violence
TRACKNUM: 1
YEAR: 1986

ALBUM: Evol
ARTIST: Sonic Youth
GENRE: Rock
PATH: ~/Music/Sonic_Youth_-_Evol/02._Sonic_Youth_-_Shadow_of_a_Doubt.mp3
TAGVERSION: ID3v2.3.0
TITLE: Shadow of a Doubt
TRACKNUM: 2
YEAR: 1986

Each record corresponds to one file and consists of some number of "key: value" lines. Multiple records are separated by "\n\n". Non-printable or conflicting characters in keys and values are escaped in URL-encoding ("\n" = "%0a">) fashion.

By default, supertag operates on a standard set of metadata sources. Some sources are filetype-specific ("id3v2" only applies to .mp3s) and some are standard ("filename" is always available). supertag will never apply filetype-specific sources to files of the wrong filetype. Two special sources, "audio" and "codec" always give standard digital audio metadata ("SAMPLERATE", "NUMCHANNELS", "SECS", etc.) and encoding-specific metadata (e.g. "MP3_LAYER", "MP3_VBR", etc.), respectively.

In get mode, the special metadata key "PATH" is always added with the full, real path to the file being processed as the value. This metadata key must be present for every input record under set mode.

For performance reasons, filetype is by default determined by looking at file extension. Content-based filetype detection via file(1) can be enabled with the --mime flag.

Different audio filetypes are handled through a plugin architecture. This presents a uniform interface to supertag. Developers interested in adding support for new filetypes should subclass all methods in Audio::SuperTag::Plugin via a package called e.g. Audio::SuperTag::Plugin::MYFORMAT.

TODO

  • adopt (or contribute) something with id3v2 write support

  • offer capitalization fixing

  • implement Ogg plugin

AUTHOR

Alan Grow <agrow+nospam@iobound.net>

COPYRIGHT

Copyright (C) 2009 by Alan Grow

This application is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.3 or, at your option, any later version of Perl 5 you may have available.