'\" t
.\"     Title: flactag
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 06/19/2012
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "FLACTAG" "1" "06/19/2012" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
flactag \- A tagger for whole album FLACs using data from the MusicBrainz service
.SH "SYNOPSIS"
.sp
\fBflactag\fR [options] flacfile [ flacfile ] [ flacfile ]
.sp
\fBripflac\fR basename [ /path/to/cdrom ]
.sp
\fBripdataflac\fR basename numtracks [ /path/to/cdrom ]
.sp
\fBcheckflac\fR flacfile
.sp
\fBdiscid\fR devicename
.SH "RIPPING CDS TO FLAC"
.sp
\fBIMPORTANT: I think I found a bug in \fR\fBcueconvert\fR\fB which means that any FLAC files generated from CDs that used INDEX marks to separate tracks that didn\(cqt have any pre\-gap would generate invalid disc IDs\&. I would urge you to use the \fR\fBcheckflac\fR\fB script provided to compare any disks you may have ripped with their FLAC files to ensure that the discids match correctly\&. Included in this release is a SED script which will massage the TOC file of a CD to work around this problem\&. Unfortunately, the only way to recover from this is to re\-rip the CD\&.\fR
.sp
To rip a CD to flac, simply enter ripflac <basename> (where basename is used as the base name of the FLAC file you will be creating\&. The CD in the drive will be ripped, and a FLAC file created containing an embedded CUE sheet\&. ripflac takes an optional final parameter for the path to the CD drive, which defaults to /dev/cdrom\&.
.sp
If the original CD contains data tracks, then the FLAC conversion will fail\&. Should this happen, enter ripdataflac <basename> <range> (where basename is the same one specified in the first rip attempt, and range is the range of tracks to rip (e\&.g\&. if the CD has 13 tracks, where track 13 is the data track, then the range would be 1\-12)\&. ripdataflac takes an optional final parameter for the path to the CD drive, which defaults to /dev/cdrom\&.
.sp
During the ripping of the data CD, you will be provided with the CUE sheet in an editor\&. You should delete the data track from this CUE sheet file and save it (I will try to automate this process at some point)\&.
.sp
Both these scripts will compare the calculated discid of the FLAC file with the discid of the CD in the drive\&. If they do not match, a warning will be issued\&.
.sp
The \fBdiscid\fR command can be used to display the disc ID of a CD in the drive\&.
.SH "DESCRIPTION"
.sp
The \fBflactag\fR command retrieves and writes tag information for a whole\-album FLAC file\&. The data is retrieved from the MusicBrainz service\&. Additionally, if an Amazon ASIN is associated with the release, then cover art will be included in the FLAC file\&.
.sp
\fBflactag\fR can be used either interactively or in batch mode
.SH "OPTIONS"
.PP
\-v, \-\-version
.RS 4
Display the software version\&.
.RE
.PP
\-h, \-\-help
.RS 4
Display brief usage information\&.
.RE
.PP
\-d, \-\-discid
.RS 4
Display the calculated disc ID for the specified FLAC file and exit\&.
.RE
.PP
\-s, \-\-submit\-url
.RS 4
Display the URL used to submit information for this file to the MusicBrainz service\&. Use this to submit data for your CD if the data returned does not match\&.
.RE
.PP
\-c, \-\-check
.RS 4
This option will compare the file\(cqs tags against those returned from the MusicBrainz service\&. A message will be displayed indicating where the tags match or not\&.
.RE
.PP
\-w, \-\-write
.RS 4
This option implies
\fB\-\-check\fR\&. If the files tags differ from those returned from the MusicBrainz service, the tags will be written to the file\&.
.RE
.PP
\-f, \-\-force\-write
.RS 4
If \-\-write is specified then tags will be written even if they appear to match those already in the file\&.
.RE
.PP
\-r, \-\-rename
.RS 4
The filename will be compared with that specified by the rename rules, and if it doesn\(cqt match, the file will be renamed\&.
.RE
.PP
\-o, \-\-overwrite\-existing
.RS 4
If \-\-rename is specified then existing files will be overwritten when renaming\&.
.RE
.PP
\-O <discID>, \-\-override\-discid <discID>
.RS 4
Instead of calculating disc ID from the cuesheet, flactag will use the provided disc ID to query MusicBrainz\&. Only one FLAC file can be processed when this option is used\&.
.RE
.SH "BATCH MODE"
.sp
\fBflactag\fR can be used in batch mode to process an entire music collection\&. For example, to check every FLAC file, write new tags and rename appropriately:
.sp
find /var/spool/music \-name "*\&.flac" \-print0 | xargs \-0 flactag \-\-write \-\-rename
.SH "INTERACTIVE MODE"
.sp
If \fBflactac\fR is executed without any options, it will interactively process all FLAC files given as arguments\&.
.sp
If the flactag utility does not find information for your CD, a URL will be provided to submit information for it\&. Often the MusicBrainz server will have information about the tracks and artist, but cannot match this up to your CD\&. In these circumstances, it is simply a matter of \*(Aqassociating\e\*(Aq your CD\(cqs DiskID with the correct album data on the MusicBrainz server\&. In other instances, you may be required to enter the track and album information into the MusicBrainz service\&. Once you have entered this information, you can re\-run flactag, and the data should be downloaded from the MusicBrainz server\&.
.sp
If the flactag utility finds information for your CD at the musicbrainz server, the application\(cqs main window will be shown\&.
.sp
This contains three main areas:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The
\fB\*(AqAlbums\*(Aq\fR
window\&. This will contain a list of albums that match the DiskID for your FLAC file\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The
\fB\*(AqTracks\*(Aq\fR
window\&. This contains a list of all the tracks on the currently selected album\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The
\fB\*(AqTags\*(Aq\fR
window\&. At startup, this will contain a list of the tags currently found in your FLAC file\&. If there are no tags present, then an empty set appropriate for the album will be displayed\&. If you make changes to these tags, an asterisk (\*(Aq*\*(Aq) will be displayed to indicate that this information has been changed\&.
.RE
.sp
The currently active window will be highlighted by the border and window title changing colour\&. To switch between the three windows, press the \fBTAB\fR key\&. To scroll around the active window, use the \fBcursor UP\fR and \fBcursor DOWN\fR keys (to scroll one line at a time) or the \fBPAGE UP\fR and \fBPAGE DOWN\fR keys (to scroll half a page at a time)\&. Scrolling in the \fB\*(AqAlbums\*(Aq\fR window will update the information in the \fB\*(AqTracks\*(Aq\fR window appropriately\&.
.sp
Once the appropriate album has been selected, pressing \fBc\fR will copy the tags for that album into the \fB\*(AqTags\*(Aq\fR window\&. These tags can then be saved to the FLAC file by pressing the \fBw\fR key\&.
.sp
Pressing \fBr\fR will rename the file based on the settings in the configuration file (~/\&.flactag \- this file is created automatically the first time you run \fBflactag\fR)\&. Note that this facility uses the tags that are actually written to the file, so should generally be performed after the new tags have been written\&. This option will be unavailable if the filename and location are already correct\&.
.sp
Pressing \fBq\fR will move to the next file specified on the command line\&. If all files have been processed, the application will exit\&.
.SH "FILE RENAMING DETAILS"
.sp
The following configuration file (~/\&.flactag) entries affect file renaming:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBBasePath\fR
\- This is the
\fIroot\fR
directory of where your music files should be stored\&. (e\&.g\&. /var/spool/music)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBSingleDiskFileName\fR
\- This template is used to rename disks that are not part of a multi\-disk set\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBMultiDiskFileName\fR
\- This template is used to rename disks that are part of a multi\-disk set\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBDirectoryCreatePermissions\fR
\- The permissions to be set on any directory that is created (e\&.g\&. 0755)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBCreateCuesheetAfterRename\fR
\- If set to true, flactag will generate a cuesheet file to accompany the renamed FLAC file\&.
.RE
.sp
The FileName templates can accept the following parameters:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fB%A\fR
\- This will be replaced with the artist name
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fB%S\fR
\- This will be replaced with the artist sort name
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fB%T\fR
\- This will be replaced with the album title
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fB%D\fR
\- This will be replaced with the disk number
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fB%Y\fR
\- This will be replaced with the year
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fB%G\fR
\- This will be replaced with the genre
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fB%1\fR
\- This will be replaced with the first character of the artist sort name
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fB%E\fR
\- This will be replaced by the appropriate filename extension (flac or cue)
.RE
.sp
If any item is used but does not have a value, then it will be stored as (for example) NOGENRE (if the genre tag is empty)\&.
.SH "USING A DIFFERENT MUSICBRAINZ SERVER"
.sp
To use a different MusicBrainz server (for example if you have a local mirror) you can set the \fIServer\fR and \fIPort\fR parameters in the configuration file\&.
.sp
e\&.g\&.
.sp
Server=mbserver\&.localdomain
.sp
Port=5000
.SH "BUGS / LIMITATIONS / FUTURE ENHANCEMENTS"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Once changes are written to the FLAC file, there is no way of reverting back to the original tags\&.
.RE
.SH "AUTHOR"
.sp
Written by
.sp
Andy Hawkins, <andy@gently\&.org\&.uk>
.sp
Daniel Pocock, <daniel@pocock\&.com\&.au>
.SH "RESOURCES"
.sp
Main web site: http://flactag\&.sourceforge\&.net
.SH "COPYING"
.sp
Copyright (C) 2007\-2012 Andy Hawkins Copyright (C) 2011\-2012 Daniel Pocock
.sp
Use of this software is granted under the terms of the GNU General Public License (GPL) v3\&.