|
|
|
(Software Download;
in "tools" directory.)
tag311 (short for "Tag ID3v1.1") lists, creates, and modifies both ID3 Version 1 and ID3 Version 2 tags commonly found in MP3 files.
For many years, to maintain MP3 tags under Linux, I used:
However, I also wanted a simple command-line program that combined these capabilities and that would run under Windows and Linux. Hence, my id3_util library and tag311. The single-letter abbreviations for the field-setting options and the long listing format were borrowed from id3edit. The "-strip 2" option replaced the need for id3convert and the "-set parts" option eliminated the need for the shell scripts. (And tag311 runs on Linux and Windows — and other systems!)
NOTE: For a full-featured, Windows GUI program, I use and highly recommend Florian Heidenreich's "universal tag editor", Mp3tag. tag311 meets my relatively simple needs, but Mp3tag offers much more powerful single-file and batch processing capabilities. Mp3tag also supports many media file types other than MP3, as well as tagging systems other than ID3.
The base entries in ID3_UTIL's internal frame information lookup table were generated by an awk(1) script from Mp3tag's "Tag Field Mappings Table", so tag311 uses the same frame type names as Mp3tag (e.g., "CONDUCTOR" for TPE3 frames). Also borrowed was Mp3tag's syntax for involved-people lists. No code however.
Two usage conventions that should be noted before using tag311:
tag311 processes the options and arguments on the command line from left to right, so options specifying operations and affecting these operations must appear before the names of the files to which the operations are to be applied.
The "-glob" option causes tag311 to treat each file name argument as a wildcard file specification and to internally perform directory scans to find the matching file names. This option is useful when invoking tag311 in a shell that doesn't support wildcard expansion; e.g., the Windows Command Prompt. As with the other options, "-glob" must be specified before the wildcard file names.
Some more general notes off the top of my head:
tag311 reads and writes ID3v1.1, ID3v2.3, and ID3v2.4 tags.
Existing ID3v1 tags in a file are all treated as ID3v1.1.
Obsolete ID3v2.2 tags (with 3-character frame IDs) are not supported. All ID3v2 tags have the tag size at the same location in the tag header, so existing ID3v2.2 tags can be removed from files using tag311's "-strip 2" option.
Version 2 tags are written as ID3v2.3 tags in most or all cases. The ID3v2.4 standard was published in 2001, but, after 20 years, it has still not supplanted ID3v2.3. tag311 is not strict and will happily include ID3v2.4's few new frame types in the ID3v2.3 tags it writes. I'm not sure how strict other MP3 applications are on this.
tag311 can read and write unsynchronized ID3v2 tags. By default, written tags are not unsynchronized. See the Unsynchronization section below for more details.
tag311 does not support compression and encryption.
Existing compressed and/or encrypted frames in a file's ID3 tag are
treated as pass-through frames that are stored internally as
an opaque block of bytes and written out as such (subject to
unsynchronization). I've never encountered compressed or encrypted
frames in real files. A test data file,
compressed_id3_frame.mp3, in the source distribution for
TagLib caught my eye, but the tag
size is 5,684 for a 5,000-byte file. tag311 correctly signals
an error when attempting to read the truncated ID3 tag. I changed
the size to 4,990 bytes and tag311 was able to read the tag
and its compressed APIC frame, as well as some other, non-compressed
frames. I updated the track number and tag311 successfully
passed through the APIC frame as is.
The ID3v2.4 standard allows tags to be written at the end of a media file. (See Section 5 of the ID3v2.4 "Main Structure" document.) tag311 and the id3_util library neither supports nor detects these "appended" tags.
Without any options, tag311 lists the ID3v1 and ID3v2 tags in one or more MP3 files. The default listing format for ID3v1 tags is "-brief"; the "-long" option produces an id3edit-compatible listing. For ID3v2 tags, the frames in the tag are listed. (An audio file can have multiple ID3v2 tags, but tag311 only detects and lists the first one. You must strip the first tag to see the second tag, and so forth.) A useful example listing (with ellipses to fit the listing in this prologue):
FILE: 02 - Funky Beatles Medley - Pigeons Playing Ping Pong.mp3
2 Funk E/Drive My Car/Why Don't ()
Pigeons Playing Ping Pong 10-26-2012 at 8x10 Baltimore, 2012 (Funk)
ID3v2.3: size 19792 flags 0x00 9 frames
TRACK: 2
TITLE: Funk E/Drive My Car/Why Don't We Do It In The Road/...
ARTIST: Pigeons Playing Ping Pong
ALBUM: 10-26-2012 at 8x10 Baltimore, MD
YEAR: 2012
GENRE: Funk
WWWARTIST: https://www.pigeonsplayingpingpong.com/
WWW (URL:Album): https://archive.org/details/pppp2012-10-26...
ATTACHEDPIC: Cover (front) 19207 bytes
The "-number" option displays frame numbers in the ID3v2 listing, useful to know for operations such as deleting specific frames and saving images/objects to files:
ID3v2.3: size 19792 flags 0x00 9 frames
1 TRACK: 2
2 TITLE: Funk E/Drive My Car/Why Don't We Do It In The Road/...
3 ARTIST: Pigeons Playing Ping Pong
...
9 ATTACHEDPIC: Cover (front) 19207 bytes
An ID3 tag consists of one or more frames whose values describe the audio file in one way or another. For example, separate frames give the song title, the artist's name, the album name, the track number, the musical genre, etc.
NOTE: Version 2 tags actually have frames. A version 1 tag is a 128-byte structure with a fixed set of fixed-length fields. tag311 treats all tags as version 2 tags to which you can add any type of frame, whether or not it has a corresponding field in the ID3v1 tag. When encoding the fields in an ID3v1 tag, tag311 copies the values of the frames, truncating them if necessary, into the ID3v1 tag. In the listing example above, you can see that the ID3v2 song title and album name have been truncated in the ID3v1 tag.
The following command-line options, which must be specified before the file or files to which they apply, set the most common (for me!) frame values:
-track number[/total]
-song title
-artist name
-album name (or -b name)
-year number
-genre string (or -genre number)
-comment text
-front imageFile
If there is no existing tag in an audio file, a tag with only the command-line-specified frames is created and written to the file. If there is an existing tag in the audio file, the command-line-specified frames are copied to the existing tag, overwriting old frames or adding new frames as the case may be. For example, if a batch of audio files have existing tags, none with a cover picture, the following command will update the artist and album names in the tags and add a cover image:
% tag311 -a "The Beatles" -b "Abbey Road" -front "cover.jpg" *.mp3
where "-a" is short for "-artist". (As are "-ar", "-art", "-arti", and "-artis". Because tag311 tries to match "-artist" before "-album", the shortest shorthand for "-album" is "-al".)
The musical genre can be an arbitrary text string or an ID3v1 number. A list of the ID3v1 numbers can be obtained with "tag311 -table genre".
ID3v2 allows multiple comments with different language codes and/or descriptions. Languages are represented by 3-character, ISO 639-2 codes. The language code defaults to "eng" (English) and the descriptive text defaults to an empty string, "". These can be overridden as follows:
[-lang code] [-desc description] -comment text
NOTE: The corresponding operation in Mp3tag is a "Filename - Tag" conversion and the renaming operation in the following section is a "Tag - Filename" conversion. Mp3tag has a much more powerful means of specifying file name templates than my primitive, fixed parts scheme presented here.
tag311 can automatically set certain ID3 frames using fields in MP3 file names:
% tag311 -set parts file(s)
The fields/parts in the file names must be separated by " - " (a hyphen with spaces on both sides); a hyphen without spaces is not seen as a field separator. The parts are specified with single characters:
a Artist
b Album
c Comment
s Song title
t Track
y Year
For example, my naming convention for tracks in a multi-artist compilation is:
track - song - artist.mp3
and my tag311 command is:
% tag311 -set tsa file(s)
Applying that command to:
04 - Ob-La-Di, Ob-La-Da - Beatles.mp3
is equivalent to the following, explicit tag311 command:
% tag311 -track 4 -song "Ob-La-Di, Ob-La-Da" -artist Beatles 04*mp3
The default field separator is " - ", but this can be changed with the "-field separator" option.
Some characters commonly found in song titles and artist and album names are not allowed in file names; e.g., the forward slash, "/", is often used between songs in the title for a medley. tag311 supports its own encoding of such characters in file names using an escape sequence, "@char", where char is a mnemonic character identifying the encoded special character:
@f Forward slash
@b Backslash
@c Colon
@a Asterisk!
@q Question mark
@2 Double quote
@l Less than symbol
@g Greater than symbol
@v Vertical bar (pipe)
@p Period
@s Semicolon
@@ At sign (special case, see below)
For example, applying "-set ts" to this file name:
"01 - Who@q Me@q@fYes, You!.mp3"
yields this song title:
"Who? Me?/Yes, You!"
The character which signals the beginning of an escape sequence can be changed from its default, "@", to another character (or string) with the "-escape esc" option.
Note the special case of "@@" above. If the escape character is changed, that encoding rule follows the change and "<esc><esc>" (two esc characters) encodes a literal "esc". "@" is now simply itself in a file name and no encoding of it is needed.
If you want tag311 to not decode escape sequences and to instead preserve their literal values, just specify a nonsense escape character/string, e.g., "-escape xyz", assuming "xyz" doesn't occur in any of the file names.
NOTE again that Mp3tag has a much more expressive method for specifying file name templates.
tag311 can do the reverse operation, renaming a file with fields/parts drawn from selected frames in the file's tag(s):
% tag311 [-test] -rename parts file(s)
where parts is the same as in the "-set parts" option described above. For example,
% tag311 -rename tsa file(s)
will rename each file as:
"track - song - artist.mp3"
With the "-test" option, "-rename parts" will list the new file names, but not actually rename the files.
Characters in the ID3 fields which are not allowed in file names are encoded using the @-escape sequences described in the previous section.
Most items in an ID3 tag are stored in text information frames. Arbitrary text information frames can be set in a tag with this option:
-text ident,[text]
The desired frame type is identified by its name or ID. The recognized frame type names and IDs can be listed with tag311 -table lut . (The frame IDs are the 4-letter codes.) For example, many audio processing programs store the encoder settings in the output file's ID3 tag. Using tag311, encoder settings can be saved with either of these commands (and the frame type name and ID do not need to be in all upper-case):
% tag311 -text "ENCODERSETTINGS,settings string" file(s)
% tag311 -text "TSSE,settings string" file(s)
In addition to predefined text information frames, ID3 also provides user-defined text information frames, all of which have the same frame ID ("TXXX") and are distinguished solely by an added description field. tag311 lets you create arbitrary user-defined frames:
-txxx description,[text]
Descriptions must match exactly, case-sensitive, when updating an existing frame of the same type. User-defined text information frames can be created with arbitrary descriptions, but tag311 supports some "predefined" user-defined text frame types it picked up from Mp3tag's list of frame types. In particular, the MusicBrainz database types. As an example, the artist's ID in the MusicBrainz database should be stored in a user-defined text frame with a specific description. Either of the following two commands can be used to add the identical artist ID frame to a tag:
% tag311 -text "MUSICBRAINZ_ARTISTID,id" ...
% tag311 -txxx "MusicBrainz Artist Id,id" ...
Images such as front and back album covers can be embedded in ID3 tags in attached picture (APIC) frames. tag311 has two shortcut options and one general option for adding images to an ID3 tag:
-front imageFile
-back imageFile
-apic type,imageFile
where type is the ID3 picture type number (0..20) for the image. Use tag311 -table pic to list the ID3 picture types and their numbers.
An image is stored in a tag along with its image or MIME type. tag311 deduces the image type from its file extension, currently recognizing GIF ("image/gif"), JPG ("image/jpeg"), and PNG ("image/png") image types. For other image types or non-standard extensions, the image's MIME type can be specified with a preceding "-mime type" option.
Like comments, multiple images of the same ID3 picture type (e.g., front, back, etc.) are allowed if their descriptions are different. The default description is "", but "-desc description" will override that. (ID3v2 doesn't use the image's MIME type as a qualifier, so, for example, embedding a JPG version and a PNG version of the front cover apparently requires that the two front-cover frames have different descriptions.) ID3v2.3 limits an attached picture's description to 64 characters; ID3v2.4 doesn't. The former limit is not enforced by tag311.
Attached pictures in a file's ID3v2 tag can be saved to disk by specifying which image to save and the name of the output image file:
% tag311 -save front,imageFile audioFile
% tag311 -save back,imageFile audioFile
% tag311 -save index,imageFile audioFile
where index is the index 1..N of the picture frame in the audio file's ID3v2 tag. The last method is useful for saving images other than the front and back covers. The "-save" operation is only applied to the next file on the command line and tag311 immediately exits whether or not the "-save" operation was successful.
URL link frames store URLs in an ID3 tag. They are very similar to text information frames with url instead of text and the fact that url is not encoded as a Unicode string. tag311 offers a shorthand means of adding certain URLs to a tag:
-url url (implied "song"; WWWAUDIOFILE frame)
-url song,url (WWWAUDIOFILE frame)
-url artist,url (WWWARTIST frame)
-url album,url (user-defined "URL:Album")
-url venue,url (user-defined "URL:Venue")
The user-defined album and venue descriptions (e.g., "URL:Venue") are simply tag311's convention.
As with the text information frames, tag311 also supports the creation of other predefined URL link frames and user-defined URL frames:
-wurl ident,[url]
-wxxx description,[url]
Working with these options is pretty much identical to working with the text information frame options detailed in the previous section.
An involved people list is a list of paired values. ID3v2.3 provides the IPLS frame: role1, person1, role2, person2, ... ID3v2.4 offers that (as a TIPL text information frame) and adds the musician credits list (TMCL frame): instrument1, person1, instrument2, person2, ...
To create these lists, tag311 uses the colon/semicolon textual notation used by Mp3tag and other applications. The following examples illustrate how to create this type of frame:
# IPLS/TIPL frame by default.
% tag311 -ipls "role1:person1;..." ...
% tag311 -ipls "involvedpeople,role1:person1;..." ...
# TMCL frame.
% tag311 -ipls "tmcl,instrument1:person1;..." ...
Depending on your command shell, be sure to quote the "-ipls" argument as needed. The semantics of the values in the list are not strictly defined, so a single element in a TMCL list, for example, could be (i) multiple instruments played by one person or (ii) the same instrument played by multiple people.
An arbitrary file can be stored in an opaque, general encapsulated object (GEOB) frame:
[-mime type] [-desc description] -geob file
Like images, ID3 distinguishes between multiple object frames by their description alone, regardless of the optional MIME types or file names. (The file name is optional in the ID3 GEOB frame, but is obviously required for tag311's purposes.)
Given an empty file name, "", tag311 will delete the object frame having the specified or default description. The "-delete" option can also be used to delete specific object frames.
General encapslated objects in a file's ID3v2 tag can be saved to disk with the same option used for saving cover images:
-save index,dataFile audioFile
where index is the index 1..N of the object frame in the audio file's ID3v2 tag and dataFile is the name of the output file. The "-save" operation is only applied to the next file on the command line and tag311 immediately exits whether or not the "-save" operation was successful.
Song lyrics (or a transcription of an audio track) can be stored in an unsynchronized lyrics (USLT) frame:
[-lang code] [-desc description] -lyrics file
(Synchronized lyrics with timestamps, SYLT, are not supported.) The text in the lyrics file is assumed to be UTF-8. As with COMM comment frames, there can be multiple USLT frames with different language/description combinations. The default language is "eng" and the default description is an empty string, "".
Given an empty file name, "", tag311 will delete the lyrics frame having the specified or default language/description. The "-delete" option can also be used to delete specific lyrics frames.
Existing lyrics in a file's ID3v2 tag can be saved to disk in the same manner as pictures and general objects:
-save index,lyricsFile audioFile
where index is the index 1..N of the lyrics frame in the audio file's ID3v2 tag and lyricsFile is the name of the output file. The "-save" operation is only applied to the next file on the command line and tag311 immediately exits whether or not the "-save" operation was successful. This means that saving the lyrics for every track on an album to individual files is a somewhat laborious task.
The number of times a track has been played can be stored in a play count (PCNT) frame:
-play count
or, along with a rating, in a popularimeter (POPM) frame:
-play [email],[rating],count
In the POPM case, the email address is optional (but not the commas) and the rating can be (i) an empty string or 0 indicating no rating, or (ii) a value in the range 1..255.
Selected frames can be deleted from an existing tag using one of two methods. First, a frame can deleted according to its index, 1..N, in the tag's list of frame:
-delete index (Delete single frame)
-delete first,count (Delete count frames from first on)
-delete first-last (Delete first through last frames)
(tag311's "-number" option is invaluable for getting a numbered list of frames beforehand.) For example:
% tag311 -delete 3 file(s) (Delete third frame)
% tag311 -delete 3,2 file(s) (Delete third and fourth frames)
% tag311 -delete 3-4 file(s) (Delete third through fourth frames)
Use this method carefully on multiple files and only after verifying that the indicated range of frames is actually applicable to all of the files.
The second method of deleting a frame is by specifying an empty string or zero as the frame type's value. The following examples should give you the general idea:
-track 0
-song ""
-year 0
-genre ""
-back ""
For text information and URL link frames, simply drop the value after the comma. Both of the following commands delete the artist ID frame from the tags in a batch of audio files:
% tag311 -text MUSICBRAINZ_ARTISTID, file(s)
% tag311 -txxx "MusicBrainz Artist Id," file(s)
When reading MP3 files, tag311 may encounter frames whose frame IDs are unrecognized (i.e., not defined in the ID3 library's lookup table). If the frame ID begins with a 'T' or 'W', the frame is assumed to be a text information or URL link frame, respectively, and decoded accordingly. Otherwise, the frame's unknown type is unsupported.
Unsupported frame types, including those with frame IDs recognized by the ID3 library but not explicitly supported, are treated as pass-through frames: such a frame's body is passed through unchanged as an opaque block of bytes.
tag311 can create unrecognized text and URL frames using an '@' prefix. How this is done is shown in the following examples, which create frames with made-up IDs of "TRAP" and "WRAP":
% tag311 -text @trap,text ...
% tag311 -wurl @wrap,url ...
When listing ID3 tags, unsupported frames are displayed in this manner:
PASSTHROUGH: id # bytes
TEXT_GENERIC/id: text
WURL_GENERIC/id: url
A listing of the two examples above:
TEXT_GENERIC/TRAP: text
WURL_GENERIC/WRAP: url
An MP3 audio frame begins with a 32-bit header. The first 11 bits, the frame sync, are all set to 1 and provide the means by which an MP3 decoder detects the beginning of the frame. ("First 11 bits" means all 8 bits set in the first byte and the 3 most significant bits set in the second byte.)
If the MP3 decoder is implemented fully in hardware, it would be ideal if the decoder, without concern for the presence or structure of ID3 tags, can just scan the input audio stream looking for 11 consecutive 1 bits and then decode the detected MP3 frame. If the decoder is partially or fully implemented in software, knowledge of and skipping of ID3 tags is easy to add and sidesteps the need to worry about false sync codes in the tag body.
False MP3 sync codes occur, for example, in the byte-order markers (BOMs) of ID3v2 Unicode strings and in the 0xFFEx and 0xFFFx segment markers in JPEG attached pictures.
ID3 unsynchronization breaks up a false sync code by inserting a 0x00 byte in between the two bytes of the sync code. For example, a two-byte 0xFFEx code will be converted to a 3-byte sequence, 0xFF00Ex. (As a special case, instances of 0xFF00 in the non-unsynchronized data are also treated as "false sync codes" and are unsynchronized into 0xFF0000 sequences.) De-unsynchronization performs the reverse operation, removing any 0x00 byte following a 0xFF.
Unsynchronization differs between ID3v2.3 and ID3v2.4 tags. ID3v2.3 tags are unsynchronized at the tag level. First, synchsafe fields are used in the tag header. By definition, only the tag size is of concern and so it is encoded as 28 bits spread over 4 bytes, with the most significant bit cleared in each byte. Second, the body of the tag (i.e., the frames) is unsynchronized by inserting a 0x00 byte into the false sync codes as described above. As a result, the frame divisions in an unsynchronized ID3v2.3 tag are not directly visible to an application.
ID3v2.4 tags are unsynchronized at the frame level and thus make the frame divisions and, in some cases, the frame contents visible to an application. In contrast to ID3v2.3 frame headers, ID3v2.4 frame headers are now synchsafe with their 28-bit size field. Unsynchronized frame bodies are only flagged as such in their frame headers if their non-unsynchronized bodies required the encoding of 0xFF bytes as 0xFF00 byte pairs. (And this will be the case for any frame having a Unicode BOM.) The unsynchronization flag in the tag header is only set if one or more of the frames were flagged as unsynchronized.
When tag311 reads/decodes an existing unsynchronized tag from a file, the tag is stored internally in non-unsynchronized form. By default, the internal tag will be written out in that same, non-unsynchronized form and thus will replace the existing unsynchronized tag. Specify tag311's "-unsync" command-line option if the output tag should be written in unsynchronized form. NOTE that this option must be given anew on each tag311 invocation when updating fields in an existing unsynchronized tag. If you forget, tag311 -unsync file(s) will rewrite the existing tags in the file(s) in unsynchronized form.
NOTE: I have never encountered unsynchronized tags in actual MP3 files, so my testing has basically consisted of tag311 reading tag311-generated unsynchronized tags. However, the ID3v2.3 and ID3v2.4 test files I generated are successfully read and decoded by Mp3tag and MP3 Diags. (MP3 Diags does complain of an "unsupported text encoding" in APIC frames, whether unsynchronized or not, but Mp3tag has no problem with them; perhaps MP3 Diags doesn't like Unicode text in APIC fields?) (Update: MP3 Diags failed to read/decode an unsynchronized tag with an extended header, although it was no problem for Mp3tag.)
By default, tag311 operates only on files with ".mp3" extensions (case-insensitive). ID3 tags can be read from and written to other types of files by specifying their extension with the "-any <ext" option. Only a single extension can be specified at a time with this option, but multiple extensions can be handled in a single invocation of tag311 by grouping the files on the command line. For example:
% tag311 ... -any flac *.flac -any mp4 *.mp4
To strip the ID3v2 tag from an MP3 file, specify "-strip 2" before the list of files. The original files are modified, so interrupting tag311 in the middle of stripping a tag may corrupt the MP3 file.
The ID3 standard allows the embedding of a CRC (CRC-32) in a tag's optional extended header to ensure the integrity of the tag. When tag311 reads an existing tag with a CRC, it recomputes the CRC for the tag and checks it against the original CRC. If the CRCs don't match, tag311 prints a warning message and continues processing the tag normally.
If an existing tag with a CRC is updated, the updated tag will also have a CRC (recomputed, of course). Existing tags without CRCs and brand new tags can be forced to have CRCs with the "-crc" option. (In the week since I implemented support for extended headers, I've only encountered it once in a real-life MP3 file. A meaningful statistic, believe you me!)
% tag311 [-debug] [-help]
[-artist artist]
[-b album] [-album album]
[-comment text]
[-genre genre]
[-song title]
[-track number[/total]]
[-year year]
[-brief] [-dump] [-long] [-number] [-sort]
[-description text] [-language code]
[-field separator] [-escape esc]
[-set parts]
[-test] [-rename parts]
[-match text] [-plus] [-table genre|lut|name|pic]
[-delete index]
[-delete first,count]
[-delete first-last]
[-save front|back|index,file]
[-clean] [-copy file] [-strip 1|2]
[-crc] [-ssi integer] [-unsync] [-version 2.3|2.4]
[-mime type] [-front file] [-back file]
[-apic type,file]
[-geob file]
[-ipls type,[list]]
[-lyrics file]
[-play [[email],[rating],]count]
[-text [@]type,[text]]
[-txxx description,[text]]
[-url [which,]url]
[-wurl [@]type,[url]]
[-wxxx description,[url]]
[-any ext] [-glob] file(s)
where
-debug- turns debug on.
-help- displays help information.
-artist artist-b album-album album-comment text-genre genre-song title-track number[/total]-year year- are used to set fields in the ID3 tags of the files that follow on the command line.
-brief-long- specifies the output format (brief, long) when listing ID3v1 tags; the default is brief.
-dump- generates a detailed a dump of a file's ID3v2 tags and frames.
-number- numbers the frames 1..N when listing ID3v2 tags.
-sort- sorts ID3v2 frames in my preferred order prior to listing them.
-description text- specifies descriptive text for certain frame types (e.g., comments); the default is an empty string, "". Note that the specified text applies to whatever affected types follow on the command line, so reset the description as needed to prevent this probably undesirable behavior:
% tag311 -desc description -comm text -desc "" -front imageFile audioFile(s)-language code- specifies a 3-character, ISO 639-2 language code for certain frame types (e.g., comments); the default is "eng" for English.
-field separator- specifies the field separator for the "-set parts" option below. The default separator is " - ".
-escape esc- specifies a character (or string) used to signal an escaped special character in file names. The default is "@". The full escape sequences are used in file names to represent characters not allowed in file names. The "-set" and "-rename" options use these escape sequences when performing file name-to-tag and tag-to-name operations, respectively. For example, "@f" in a file name is converted to a forward slash by the "-set" operation. Likewise, "/" in a song title is converted to "@f" by the "-rename" operation. The "-escape" option lets you change the escape indicator from the default.
-set parts- causes tag311 to set certain fields in a file's ID3 tags, both version 1 and version 2, using information embedded in the file's name. The argument is a string containing the ordered single-letter abbreviations for the hyphen-separated fields in the file's name: "t" for the track number, "s" for the song title, "a" for the artist, "c" for a comment, and "y" for the year. For example, specify "-set ts" if the file names are of the form: "track - song.mp3". The default field separator is " - ", although a different divider can be specified with the "-field separator" option. (File names are not always composed of convenient hyphen-separated fields; in these cases, I usually use chafn to change the file names into a form usable by tag311.)
-test- causes the "-rename" option to list the new file names, but not actually rename the files.
-rename parts- causes tag311 to rename files, assembling parts of their names from selected frames in their ID3 tags. The rename operation uses the same part designations, field separator, and escaped characters as the "-set
" option above. -match text- writes to standard output a list of the genres that contain the specified text. (Basically the equivalent of piping the output of "-plus" through "grep text".)
-plus- writes to standard output a list of all of the defined genres.
-table genre|lut|pic- writes internal tables to standard output. The table names are case-insensitive. "Genre" lists the ID3v1 genres. "Lut" lists the frame type IDs and names from the frame information lookup table. "Pic" lists the ID3v2 picture types.
-delete index-delete first,count-delete first-last- deletes the indexed frame(s) in the range from the ID3v2 tags in the files, where the index is in the range 1..N. If only index is specified, just that single frame is deleted. The second form deletes count> frames beginning with the first frame. The third form deletes all frames from first to last.
-save front,file-save back,file-save index,file- extracts a cover image (APIC), a general object (GEOB), or lyrics text (USLT) from an ID3 tag and saves it to a file. The first two forms of the option save the front and back cover images, respectively. To save other picture types, general objects, and lyrics, specify the corresponding frame's index in the tag's list of frames. This operation is applied to the next audio file encountered in the command line, after which tag311 immediately exits no matter what other options or files are specified on the command line.
-clean- is an alias for "-strip 2", which strips the version 2 ID3 tags from the files.
-copy file- loads the fields from a single file's ID3 tag(s) for the purpose of storing them in files that follow on the command line. Individual fields can be overridden using the various field options prior to specifying the destination files (but after the "-copy" option itself).
-strip version- strips the specified version (1 or 2) of ID3 tag from the files.
-crc- causes TAG311 to compute a CRC for the ID3v2 tag in each file and to store the CRC in the tag's extended header.
-ssi integer- prints out a synchsafe integer. First, integer is treated as an encoded synchsafe integer and its decoded binary value is printed. Second, integer is treated as an unencoded binary value and its synchsafe encoding is printed. The number can be in decimal or hexadecimal (e.g., 0x89AB) form.
-unsync- specifies that the existing/updated/new ID3v2 tags in the files should be put in unsynchronized form. See the "Unsynchronization" section above for the details of this option. Note that updated and new tags are, by default, not unsynchronized. In particular, updating an unsynchronized tag replaces, by default, the existing tag with one that is not unsynchronized ... unless this "-unsync" option is given. If you forget, tag311 -unsync file(s) will rewrite the existing tags in the file(s) in unsynchronized form.
-version 2.3|2.4- specifies the version for existing/updated/new ID3v2 tags in the files. Existing tags will be rewritten in the new version.
-mime type- specifies the full MIME type for cover images (e.g., "image/jpeg") and general encapsulated objects. If this option is not present for cover images, tag311 attempts to deduce the MIME type from the cover files' extensions. In the case of objects, the default MIME type is "".
-front file-back file- embed front and back cover images in a tag. The file should be a GIF, JPEG, or PNG file. (tag311 needs to store the file's MIME type in the tag, so it guesses the type based on the file's extension.)
-geob file- stores the contents of an arbitrary file in a general encapsulated object (GEOB) frame. The "-mime" and "-description" options should be specified previously if necessary; they default to empty strings, "", otherwise.
-ipls list-ipls type,[list]- sets an "involved people list" of the specified type in a tag; the default frame type is IPLS/TIPL. See the "Involved People List" section above for the details of this option.
-lyrics file- loads lyrics from a file and stores them in an unsynchronized lyrics (USLT) frame. The lyrics in the file are assumed to be UTF-8. The "-language" (default: "eng") and "-description" (default: "") options should be specified previously if necessary.
-play [[email],[rating],]count- sets the play count in a tag. If only count is specified, a Play Count (PCNT) frame is set. If email and rating are specified, a Popularimeter (POPM) frame is set. Ratings are in the range 1..255, with 0 indicating no rating. If count is an empty string (e.g., -play "" or -play ,, ), the existing PCNT or POPM frame is deleted from the tag.
-text [@]type,[text]- sets an arbitrary text information frame in a tag. See the "I Know What I'm Doing" and "Unsupported Frame Types" sections above for details.
-txxx description,[text]- sets an arbitrary, user-defined text information frame in a tag. See the "I Know What I'm Doing" section above for details.
-url [which,]url- sets a URL in a tag, where
is "song", "artist", "album", or "venue". Without which, "song" is assumed. -wurl [@]type,[url]- sets an arbitrary URL link frame in a tag. See the "URL Link Frames" and "Unsupported Frame Types" sections above for details.
-wxxx description,[url]- sets an arbitrary, user-defined URL link frame in a tag. See the "URL Link Frames" section above for details.
-any ext- enables tags to be read from and written to files with the specified, case-insensitve extension. By default, tag311 operates on ".mp3" files; this option allows tag311 to operate on both ".mp3" and ".ext" files. The extension can be specified with or without a leading dot.
-glob- instructs tag311 to treat the file names that follow as wildcard file specifications and to internally perform directory scans for matching files. Without this option, each file name argument is treated as a single file name. This option must be specified before the file names.
file(s)- specifies the file(s) to be accessed.