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