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