1
2
3
4
5 _ _ __ _ _ __ ___
6| ' \/ _` | ' \/ -_)
7|_||_\__,_|_|_|_\___|
8
9 id3 - a command line mass tagger
10
11 _
12 ____ _ _ _ ___ _ __ __(_)___
13(_-< || | ' \/ _ \ '_ (_-< (_-<
14/__/\_, |_||_\___/ .__/__/_/__/
15 |__/ |_|
16 id3 [-v] [-m] [-123] [-d] [-t title] [-a artist] [-l album]
17 [-n tracknr] [-y year] [-g genre] [-c comment]
18 [-f template] [-q format] [-D file] [-R] [-M]
19 [-E] [-s size] [-u] [-rFRAME] [-wFRAME data] "filespec"
20
21 _ _ _ _
22 __| |___ ___ __ _ _(_)_ __| |_(_)___ _ _
23/ _` / -_|_-</ _| '_| | '_ \ _| / _ \ ' \
24\__,_\___/__/\__|_| |_| .__/\__|_\___/_||_|
25 |_|
26 id3 mass tagger is a tool for listing and manipulating ID3 and Lyrics3
27 tags in multiple files. It can generate tag fields from the filename
28 and other variables, and/or rename files, using an intuitive syntax.
29
30 id3 currently supports old-style ID3v1 tags, Lyrics3v2, as well as the
31 more complex ID3v2 format. This means its use is limited to audio
32 files which use these formats, i.e. MPEG-1 Layer III.
33
34 _ _
35 ___ _ __| |_(_)___ _ _ ___
36/ _ \ '_ \ _| / _ \ ' \(_-<
37\___/ .__/\__|_\___/_||_/__/
38 |_|
39 Order of the options is only important where specified.
40
41 filespec ...
42 specifies the file(s) to be affected by the command.
43
44 If you use wildcards, it is necessary to enclose the specifica-
45 tion in double quotes ("") for pattern matching to work.
46
47 -h, --help
48 show command line help
49
50 -V, --version
51 display version number and copyright
52
53 -v, --verbose
54 be verbose
55
56 -1 process/add ID3v1 tags.
57
58 -2 process/add ID3v2 tags.
59
60 -3 process/add Lyrics3 tags.
61
62 If more than one tag type is specified, they are all written,
63 and the left-most one that is found is used for variable substi-
64 tution. If no tag type is specified, id3 will by default attempt
65 to read ID3v2, Lyrics3 and ID3v1 tags in that order, only modify
66 existing ID3v2 and Lyrics3 tags, and modify/add ID3v1 tags.
67
68 -R, --recursive
69 searches recursively; When this is enabled, `*' wildcards in
70 filespec will also match against directory separators. Normally,
71 this is not the case.
72
73 -M, --keep-time
74 preserve last modification time of files operated on
75
76 -- force the following argument to be interpreted as a filename.
77 Use this for files that start with a `-' (dash).
78
79 Modifying operations
80 The default operation of id3 is to list the tags found. By using any of
81 the following options, this behaviour is inhibited.
82
83 -d, --delete
84 do not re-use existing tag data. If no new tag information is
85 specified in conjunction with this option, all selected tags
86 will be removed.
87
88 -t title, --title title
89 -a artist, --artist artist
90 -l album, --album album
91 -n tracknr, --track tracknr
92 -y year, --year year
93 -g genre, --genre genre
94 -c comment, --comment comment
95
96 add/replace the specified fields in all selected tags with the
97 values given. Field values are scanned for substitution vari-
98 ables, see SUBSTITUTION below. If a field value is a single
99 variable, and its substitution fails, no operation is performed.
100
101 Genres can be specified either directly or with their assigned
102 number, regardless of tag format.
103
104 -f filename-template, --rename filename-template
105 rename files encountered according to filename-template. The
106 argument is scanned for substitution variables. An empty vari-
107 able will by default get replaced with "Unknown". Trying to
108 rename to an already existing file will cause an error.
109
110 -q format, --query format
111 for each file encountered, format will get scanned for substitu-
112 tion variables, and written to standard output. Using this
113 option will block any attempt to modify files.
114
115 -m, --match
116 match mode; interpret any substitution variables (see SUBSTITU-
117 TION below) found in a filespec as a wildcard, and set the cor-
118 responding tag field to the matched portion of the filename.
119
120 Thus, `id3 -m "%a - %t.mp3"' is short-hand for `id3
121 -a %1 -t %2 "* - *.mp3"'.
122
123 -D filename, --duplicate filename
124 duplicate and copy the tags found in filename to the target
125 files. The tag in each target file is replaced after any vari-
126 ables have been read, but before any fields are updated.
127
128 Any original tag values not explicitly written to the new tag
129 (for example, by using -u) are lost. If filename does not have
130 any tags, this option is identical to the -d option.
131
132 The following options only apply on the tag most recently selected
133 before them, and only have meaning where relevant.
134
135 -E, --if-exists
136 only write a tag of the most recently selected type if a file
137 already contains it; do not add new ones.
138
139 -u, --update
140 update all standard tag fields by copying them from the source
141 tag. This is similar to writing `-talnygc %t %a %l %n %y %g %c',
142 but only operates on the most recent tag. It is possible for the
143 source and destination tag to be the same.
144
145 -s size, --size size
146 try to write a new tag using exactly size bytes, adding / remov-
147 ing padding as necessary. The resulting tag will have no padding
148 if size is smaller than the actual size necessary.
149
150 -rFRAME, --remove=FRAME
151 remove occurrences of frames named FRAME from the tag. Consult
152 the format documentation for valid FRAME names. For text
153 frames, it is equivalent to `-wFRAME ""'.
154
155 -wFRAME data, --frame=FRAME data
156 add / update a frame named FRAME with data in the tag. data is
157 scanned for substitution variables. Again, consult the format
158 documentation. See COMPATIBILITY for more information.
159
160 Short-form options can be stacked in a single argument for more conve-
161 nience. For example, running
162
163 id3 -2d -alt "Artist" "Album" "Title" *.mp3
164
165 is equivalent to:
166
167 id3 -2 -d -a "Artist" -l "Album" -t "Title" *.mp3
168
169
170 _ _ _ _ _ _
171 ____ _| |__ __| |_(_) |_ _ _| |_(_)___ _ _
172(_-< || | '_ (_-< _| | _| || | _| / _ \ ' \
173/__/\_,_|_.__/__/\__|_|\__|\_,_|\__|_\___/_||_|
174
175 id3 can perform "printf-like" substitution on the values prior to writ-
176 ing them to a tag. Note that if you want to use pattern matching, you
177 HAVE TO enclose the wildcard specification on the command line in dou-
178 ble quotes to prevent your shell from expanding any wildcards.
179
180 \c escape sequence. \n, \r, \t, \v, \f, \b, \a, get replaced as in
181 C, any other character will be stripped of any special meaning.
182 E.g., \n becomes the newline character, \\ a single backslash.
183
184 %<modifiers>N
185 where N <- [0..9] replaced with the portion of the file path
186 matching the nth `*' (asterisk) wildcard in the file specifica-
187 tion. 0 is taken to mean 10.
188
189 %<modifiers>c
190 where c <- [a..z]
191 replaced by values according to the following table:
192
193 %t title
194 %a artist
195 %l album title
196 %n track number
197 %y year
198 %g genre
199 %c comment field
200 %f file name (without path)
201 %p path to filename
202 %x auto-increasing counter
203 %X file counter
204
205 Values get read (where applicable) from the source tag, which is
206 the left-most tag selected on the command line, and reflect the
207 state of the file before any modifications were made. If the
208 source value is not available, the variable fails. "%_p%_f"
209 combines to the raw full path and file name. The "%x" value gets
210 increased every time it has been substituted inside the same
211 directory, and is intended for auto-numbering. "%X" increases
212 for every file processed.
213
214 %<modifiers>{FRAME}
215 replaced by the content of the FRAME frame in the selected
216 source tag; any frame writeable with the -w option can be used;
217 see COMPATIBILITY for more information.
218
219 %% replaced with a single "%", equivalent to \%
220
221 %|text||alt text||...|?
222 substituted by the first text that was completely successful, or
223 fails as empty, see fall-backs below. This can be used as an
224 all-or-nothing substitution. A lone "%?" always fails.
225
226 Available <modifiers> (optional):
227 + (plus sign)
228 Capitalize the substituted value
229
230 - (minus sign)
231 Convert all characters to lowercase
232
233 _ (underscore)
234 Use the raw value of the variable. Normally, substitution
235 replaces any underscores with spaces, and condenses empty white-
236 space.
237
238 * (asterisk)
239 Split the variable into separate words by looking at the capi-
240 talization.
241
242 # (hash or pound sign)
243 Attempt to fit numeric values in the substituted string to a
244 desired width, by removing or adding leading zeros. Multiple
245 hash signs can be stacked to indicate the desired width. If
246 there are no numeric values, this modifier has no effect.
247
248 |fall-back|
249 If substitution for a variable fails, attempt fall-back instead.
250 fall-back itself may be empty or contain other variables
251 (including other fall-backs). If fall-back contains variables
252 that fail, the fall-back fails and will not be used. If more
253 than one fall-back is provided, successive fall-backs are tried
254 until one succeeds.
255
256 _
257 _____ ____ _ _ __ _ __| |___ ___
258/ -_) \ / _` | ' \| '_ \ / -_|_-<
259\___/_\_\__,_|_|_|_| .__/_\___/__/
260 |_|
261 Here are some examples of using id3 :
262
263 id3 -a "Stallman" -t "Free Software Song" fs_song.mp3"
264 Add a simple tag to a file.
265
266 id3 muzak.mp3
267 List tag information in a file.
268
269 id3 -d *.mp3
270 Removes all ID3v1 tags from all mp3's.
271
272 id3 -2 -1u fs_song.mp3
273 Copy ID3v2 tag to ID3v1 tag in selected file.
274
275 id3 -D source.mp3 -1 -2 dest.mp3
276 Duplicate ID3v1 and ID3v2 tags of source.mp3
277
278 id3 -a "TAFKAT" -n "%1" -t "%+2" "*. *.mp3"
279 Update tag fields similar to this;
280 -a "TAFKAT" -n "01" -t "My Song" "01. my_song.mp3"
281 -a "TAFKAT" -n "02" -t "Untitled" "02. untitled.mp3"
282
283 id3 -2 -f "%a - %t.mp3" blaet.mp3
284 Rename file to a standard format, using ID3v2 values.
285
286 id3 -a %t -t %a "*.mp3"
287 Swap artist and title fields in all mp3's.
288
289 id3 -2 -rAPIC -s 0 *.mp3
290 Removes embedded images and padding from all mp3's.
291
292 id3 -2d -u *.mp3
293 Rewrite ID3v2 tag while keeping only the basic fields.
294
295 id3 -2 -wUSLT "foo, bar0alala!0 blaet.mp3
296 Adds an ID3v2 lyric frame to blaet.mp3.
297
298 id3 -v -g alt-rock -alnt "The Author" %1 %2 %3 "Author - */(*) *.mp3"
299 Process multiple directories at once.
300
301 id3 -v -g alt-rock -a "The Author" -m "Author - %l/(%n) %t.mp3"
302 Shorthand for the previous example.
303
304 id3 -2 -c "Was: %_f" -f "%|Nobody|a - %|Untitled (%x)|t.mp3" "*.mp3"
305 Rename with missing values replaced. Saves previous filename in the comments.
306
307 id3 -2 -q "%|%{TPE2}||%{TXXX:ALBUM ARTIST}|?"
308 Tries to print the "album artist" using two possible ID3v2 frames.
309
310 id3 -2 -q "%| %a - %|Untitled|t || %t || %1 |?" "*.mp3"
311 Generate a simple list of songs.
312
313 _
314 _ _ ___| |_ ___ ___
315| ' \/ _ \ _/ -_|_-<
316|_||_\___/\__\___/__/
317
318 The internal pattern matching emulates the normal pattern matching of
319 "sh". It supports ?, * and [].
320
321 A shell pattern will never match a forward slash ("/") or a dot (".")
322 beginning a filename. Wildcards can be used for directories as well (to
323 arbitrary depths), in which case a search will be performed.
324
325 In an ambiguous situation, the pattern matcher will always resolve a
326 "*" wildcard to the shortest possible sequence of tokens. This differs
327 from the behavior of regular expressions, however it tends to make
328 sense in the context of filenames.
329
330 Do NOT add ID3 tags to files for which it does not make sense, i.e, add
331 them only to MP3 files. In particular, do not add ID3v2 tags to Ogg
332 files, since ID3v2 tags start at the beginning of the file.
333
334 _ _ _ _ _ _ _
335 __ ___ _ __ _ __ __ _| |_(_) |__(_) (_) |_ _ _
336/ _/ _ \ ' \| '_ \/ _` | _| | '_ \ | | | _| || |
337\__\___/_|_|_| .__/\__,_|\__|_|_.__/_|_|_|\__|\_, |
338 |_| |__/
339 id3 has a built-in genre list of 148 genres. If you pass the -g parame-
340 ter a string instead of a number when using ID3v1, id3 tries to find
341 the specified genre in this list, and selects the closest possible
342 match (if any). For the genre numbers and exact spelling, see id3v1.c
343 in the source distribution. An empty or invalid genre is assigned the
344 number 0.
345
346 The ID3v1 format only supports to the ISO-8859-1 (Latin 1) encoding. If
347 you need other Unicode characters, you need to use ID3v2 tags.
348
349 When using -2, id3 will write ID3v2.3 by default, unless a file is
350 already tagged with the older ID3v2.2. id3 can read ID3v2.4 tags, but
351 these will be converted to ID3v2.3 when modified.
352
353 Furthermore, with ID3v2 tags, the -wFRAME option and %{FRAME} substitu-
354 tion only support the following ID3v2.2 (3 letter)/ID3v2.3 (4 letter)
355 frames: T??/T??? (text), W??/W??? (links), COM/COMM (comment), IPL/IPLS
356 (involved people), ULT/USLT (lyrics), CNT/PCNT (numeric play counter)
357 and USER (tos, v2.3 only). Attempts to write ID3v2.2 frames to ID3v2.3
358 or vice versa will be ignored.
359
360 Several ID3v2 frames can be specialized with additional descriptors
361 (TXXX, WXXX, COMM, USLT). These can be read or written using the
362 extended syntax -wFRAME:descriptor and %{FRAME:descriptor}. Descrip-
363 tors are case sensitive and may contain whitespace. For frames that
364 are language-specific (COMM, USLT), the form FRAME:descriptor:xxx may
365 also be used, where xxx is a three letter ISO-639-2 language code.
366 Which descriptors are meaningful is application-specific.
367
368 id3 does not support unnecessary ID3v2 features such as compression,
369 encryption, or embedding binary data (including image files).
370
371 _ _
372 __ _ _ _| |_| |_ ___ _ _
373/ _` | || | _| ' \/ _ \ '_|
374\__,_|\_,_|\__|_||_\___/_|
375
376 Written by Marc R. Schoolderman <squell@alumina.nl>.
377
378 _ _ _
379 __ ___ _ __ _ _ _ _(_)__ _| |_| |_
380/ _/ _ \ '_ \ || | '_| / _` | ' \ _|
381\__\___/ .__/\_, |_| |_\__, |_||_\__|
382 |_| |__/ |___/
383 This is free software; see the source for copying conditions. There is
384 NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
385 PURPOSE.
386
387 _
388 ___ ___ ___ __ _| |___ ___
389(_-</ -_) -_) / _` | (_-</ _ \
390/__/\___\___| \__,_|_/__/\___/
391
392 Program homepage: https://squell.github.io/id3
393
394
395
396