'\" t .\" Title: flactag .\" Author: Andy Hawkins .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 03/20/2024 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" .TH "FLACTAG" "1" "03/20/2024" "\ \&" "\ \&" .\" ----------------------------------------------------------------- .\" * 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 (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 (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 , \-\-override\-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, .sp Daniel Pocock, .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\&. .SH "AUTHOR" .PP \fBAndy Hawkins\fR <\&andy@gently\&.org\&.uk\&> .RS 4 Author. .RE