1<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ 2 3<!-- Process this file with docbook-to-man to generate an nroff manual 4 page: `docbook-to-man manpage.sgml > manpage.1'. You may view 5 the manual page with: `docbook-to-man manpage.sgml | nroff -man | 6 less'. A typical entry in a Makefile or Makefile.am is: 7 8manpage.1: manpage.sgml 9 docbook-to-man $< > $@ 10 --> 11 12<!-- This is based on an example constructed by Colin Watson 13 <email>cjwatson@debian.org</email>, based on a man page template 14 provided by Tom Christiansen <email>tchrist@jhereg.perl.com</email> 15 and a DocBook man page example by Craig Small 16 <email>csmall@debian.org</email>. 17 --> 18 19 <!-- Fill in the various UPPER CASE things here. --> 20 <!ENTITY manfirstname "<firstname>dann</firstname>"> 21 <!ENTITY mansurname "<surname>frazier</surname>"> 22 <!-- Please adjust the date whenever revising the manpage. --> 23 <!ENTITY mandate "<date>2013/04/30</date>"> 24 <!-- SECTION should be 1-8, maybe with subsection. Other parameters are 25 allowed: see man(7), man(1). --> 26 <!ENTITY mansection "<manvolnum>1</manvolnum>"> 27 <!ENTITY manemail "<email>dannf@debian.org</email>"> 28 <!ENTITY manusername "dannf"> 29 <!ENTITY manucpackage "<refentrytitle>METAFLAC</refentrytitle>"> 30 <!ENTITY manpackage "metaflac"> 31]> 32 33<refentry> 34 <refentryinfo> 35 <address> 36 &manemail; 37 </address> 38 <author> 39 &manfirstname; 40 &mansurname; 41 </author> 42 <copyright> 43 <year>2002-2005, 2011-2013</year> 44 <holder>&manusername;</holder> 45 </copyright> 46 &mandate; 47 </refentryinfo> 48 <refmeta> 49 &manucpackage; 50 51 &mansection; 52 </refmeta> 53 <refnamediv> 54 <refname>&manpackage;</refname> 55 56 <refpurpose> 57 program to list, add, remove, or edit metadata in one or more FLAC files. 58 </refpurpose> 59 </refnamediv> 60 <refsynopsisdiv> 61 <cmdsynopsis> 62 <command>&manpackage;</command> 63 64 <group choice="opt"><arg><replaceable>options</replaceable></arg></group> 65 <group choice="opt"> 66 <arg><replaceable>operations</replaceable></arg></group> 67 <arg rep="repeat" choice="req"><replaceable>FLACfile</replaceable></arg> 68 </cmdsynopsis> 69 </refsynopsisdiv> 70 <refsect1> 71 <title>DESCRIPTION</title> 72 73 <para>Use <command>&manpackage;</command> to list, add, remove, or edit 74 metadata in one or more FLAC files. You may perform one major operation, 75 or many shorthand operations at a time.</para> 76 77 </refsect1> 78 <refsect1> 79 <title>OPTIONS</title> 80 81 <variablelist> 82 <varlistentry> 83 <term><option>--preserve-modtime</option></term> 84 <listitem> 85 <para> 86 Preserve the original modification time in spite of edits. 87 </para> 88 </listitem> 89 </varlistentry> 90 <varlistentry> 91 <term><option>--with-filename</option></term> 92 <listitem> 93 <para> 94 Prefix each output line with the FLAC file name (the default if 95 more than one FLAC file is specified). 96 </para> 97 </listitem> 98 </varlistentry> 99 <varlistentry> 100 <term><option>--no-filename</option></term> 101 <listitem> 102 <para> 103 Do not prefix each output line with the FLAC file name (the default 104 if only one FLAC file is specified). 105 </para> 106 </listitem> 107 </varlistentry> 108 <varlistentry> 109 <term><option>--no-utf8-convert</option></term> 110 <listitem> 111 <para> 112 Do not convert tags from UTF-8 to local charset, or vice versa. This is 113 useful for scripts, and setting tags in situations where the locale is wrong. 114 </para> 115 </listitem> 116 </varlistentry> 117 <varlistentry> 118 <term><option>--dont-use-padding</option></term> 119 <listitem> 120 <para> 121 By default metaflac tries to use padding where possible to avoid 122 rewriting the entire file if the metadata size changes. Use this 123 option to tell metaflac to not take advantage of padding this way. 124 </para> 125 </listitem> 126 </varlistentry> 127 </variablelist> 128 </refsect1> 129 <refsect1> 130 <title>SHORTHAND OPERATIONS</title> 131 132 <variablelist> 133 <varlistentry> 134 <term><option>--show-md5sum</option></term> 135 <listitem> 136 <para> 137 Show the MD5 signature from the STREAMINFO block. 138 </para> 139 </listitem> 140 </varlistentry> 141 <varlistentry> 142 <term><option>--show-min-blocksize</option></term> 143 <listitem> 144 <para> 145 Show the minimum block size from the STREAMINFO block. 146 </para> 147 </listitem> 148 </varlistentry> 149 <varlistentry> 150 <term><option>--show-max-blocksize</option></term> 151 <listitem> 152 <para> 153 Show the maximum block size from the STREAMINFO block. 154 </para> 155 </listitem> 156 </varlistentry> 157 <varlistentry> 158 <term><option>--show-min-framesize</option></term> 159 <listitem> 160 <para> 161 Show the minimum frame size from the STREAMINFO block. 162 </para> 163 </listitem> 164 </varlistentry> 165 <varlistentry> 166 <term><option>--show-max-framesize</option></term> 167 <listitem> 168 <para> 169 Show the maximum frame size from the STREAMINFO block. 170 </para> 171 </listitem> 172 </varlistentry> 173 <varlistentry> 174 <term><option>--show-sample-rate</option></term> 175 <listitem> 176 <para> 177 Show the sample rate from the STREAMINFO block. 178 </para> 179 </listitem> 180 </varlistentry> 181 <varlistentry> 182 <term><option>--show-channels</option></term> 183 <listitem> 184 <para> 185 Show the number of channels from the STREAMINFO block. 186 </para> 187 </listitem> 188 </varlistentry> 189 <varlistentry> 190 <term><option>--show-bps</option></term> 191 <listitem> 192 <para> 193 Show the # of bits per sample from the STREAMINFO block. 194 </para> 195 </listitem> 196 </varlistentry> 197 <varlistentry> 198 <term><option>--show-total-samples</option></term> 199 <listitem> 200 <para> 201 Show the total # of samples from the STREAMINFO block. 202 </para> 203 </listitem> 204 </varlistentry> 205 <varlistentry> 206 <term><option>--show-vendor-tag</option></term> 207 <listitem> 208 <para> 209 Show the vendor string from the VORBIS_COMMENT block. 210 </para> 211 </listitem> 212 </varlistentry> 213 <varlistentry> 214 <term><option>--show-tag=name</option></term> 215 <listitem> 216 <para> 217 Show all tags where the field name matches 'name'. 218 </para> 219 </listitem> 220 </varlistentry> 221 <varlistentry> 222 <term><option>--remove-tag=name</option></term> 223 <listitem> 224 <para> 225 Remove all tags whose field name is 'name'. 226 </para> 227 </listitem> 228 </varlistentry> 229 <varlistentry> 230 <term><option>--remove-first-tag=name</option></term> 231 <listitem> 232 <para> 233 Remove first tag whose field name is 'name'. 234 </para> 235 </listitem> 236 </varlistentry> 237 <varlistentry> 238 <term><option>--remove-all-tags</option></term> 239 <listitem> 240 <para> 241 Remove all tags, leaving only the vendor string. 242 </para> 243 </listitem> 244 </varlistentry> 245 <varlistentry> 246 <term><option>--set-tag=field</option></term> 247 <listitem> 248 <para> 249 Add a tag. The field must comply with the 250 Vorbis comment spec, of the form "NAME=VALUE". If there is 251 currently no tag block, one will be created. 252 </para> 253 </listitem> 254 </varlistentry> 255 <varlistentry> 256 <term><option>--set-tag-from-file=field</option></term> 257 <listitem> 258 <para> 259 Like --set-tag, except the VALUE is a filename whose 260 contents will be read verbatim to set the tag value. 261 Unless --no-utf8-convert is specified, the contents will be 262 converted to UTF-8 from the local charset. This can be used 263 to store a cuesheet in a tag (e.g. 264 --set-tag-from-file="CUESHEET=image.cue"). Do not try to 265 store binary data in tag fields! Use APPLICATION blocks for 266 that. 267 </para> 268 </listitem> 269 </varlistentry> 270 <varlistentry> 271 <term><option>--import-tags-from=file</option></term> 272 <listitem> 273 <para> 274 Import tags from a file. Use '-' for stdin. Each 275 line should be of the form NAME=VALUE. Multi-line comments 276 are currently not supported. Specify --remove-all-tags and/or 277 --no-utf8-convert before --import-tags-from if necessary. If 278 FILE is '-' (stdin), only one FLAC file may be specified. 279 </para> 280 </listitem> 281 </varlistentry> 282 <varlistentry> 283 <term><option>--export-tags-to=file</option></term> 284 <listitem> 285 <para> 286 Export tags to a file. Use '-' for stdout. Each 287 line will be of the form NAME=VALUE. Specify 288 --no-utf8-convert if necessary. 289 </para> 290 </listitem> 291 </varlistentry> 292 <varlistentry> 293 <term><option>--import-cuesheet-from=file</option></term> 294 <listitem> 295 <para> 296 Import a cuesheet from a file. Use '-' for stdin. Only one 297 FLAC file may be specified. A seekpoint will be added for each 298 index point in the cuesheet to the SEEKTABLE unless 299 --no-cued-seekpoints is specified. 300 </para> 301 </listitem> 302 </varlistentry> 303 <varlistentry> 304 <term><option>--export-cuesheet-to=file</option></term> 305 <listitem> 306 <para> 307 Export CUESHEET block to a cuesheet file, suitable for use by 308 CD authoring software. Use '-' for stdout. Only one FLAC file 309 may be specified on the command line. 310 </para> 311 </listitem> 312 </varlistentry> 313 <varlistentry> 314 <term><option>--import-picture-from</option>={<replaceable>FILENAME</replaceable>|<replaceable>SPECIFICATION</replaceable>}</term> 315 <listitem> 316 <para>Import a picture and store it in a PICTURE metadata block. More than one --import-picture-from command can be specified. Either a filename for the picture file or a more complete specification form can be used. The SPECIFICATION is a string whose parts are separated by | (pipe) characters. Some parts may be left empty to invoke default values. FILENAME is just shorthand for "||||FILENAME". The format of SPECIFICATION is</para> 317 <para>[TYPE]|[MIME-TYPE]|[DESCRIPTION]|[WIDTHxHEIGHTxDEPTH[/COLORS]]|FILE</para> 318 <para>TYPE is optional; it is a number from one of:</para> 319 <para>0: Other</para> 320 <para>1: 32x32 pixels 'file icon' (PNG only)</para> 321 <para>2: Other file icon</para> 322 <para>3: Cover (front)</para> 323 <para>4: Cover (back)</para> 324 <para>5: Leaflet page</para> 325 <para>6: Media (e.g. label side of CD)</para> 326 <para>7: Lead artist/lead performer/soloist</para> 327 <para>8: Artist/performer</para> 328 <para>9: Conductor</para> 329 <para>10: Band/Orchestra</para> 330 <para>11: Composer</para> 331 <para>12: Lyricist/text writer</para> 332 <para>13: Recording Location</para> 333 <para>14: During recording</para> 334 <para>15: During performance</para> 335 <para>16: Movie/video screen capture</para> 336 <para>17: A bright coloured fish</para> 337 <para>18: Illustration</para> 338 <para>19: Band/artist logotype</para> 339 <para>20: Publisher/Studio logotype</para> 340 <para>The default is 3 (front cover). There may only be one picture each of type 1 and 2 in a file.</para> 341 342 <para>MIME-TYPE is optional; if left blank, it will be detected from the file. For best compatibility with players, use pictures with MIME type image/jpeg or image/png. The MIME type can also be --> to mean that FILE is actually a URL to an image, though this use is discouraged.</para> 343 344 <para>DESCRIPTION is optional; the default is an empty string.</para> 345 346 <para>The next part specifies the resolution and color information. If the MIME-TYPE is image/jpeg, image/png, or image/gif, you can usually leave this empty and they can be detected from the file. Otherwise, you must specify the width in pixels, height in pixels, and color depth in bits-per-pixel. If the image has indexed colors you should also specify the number of colors used. When manually specified, it is not checked against the file for accuracy.</para> 347 348 <para>FILE is the path to the picture file to be imported, or the URL if MIME type is --></para> 349 350 <para>For example, "|image/jpeg|||../cover.jpg" will embed the JPEG file at ../cover.jpg, defaulting to type 3 (front cover) and an empty description. The resolution and color info will be retrieved from the file itself.</para> 351 352 <para>The specification "4|-->|CD|320x300x24/173|http://blah.blah/backcover.tiff" will embed the given URL, with type 4 (back cover), description "CD", and a manually specified resolution of 320x300, 24 bits-per-pixel, and 173 colors. The file at the URL will not be fetched; the URL itself is stored in the PICTURE metadata block.</para> 353 </listitem> 354 </varlistentry> 355 <varlistentry> 356 <term><option>--export-picture-to=file</option></term> 357 <listitem> 358 <para> 359 Export PICTURE block to a file. Use '-' for stdout. Only one FLAC file may be specified on the command line. The first PICTURE block will be exported unless --export-picture-to is preceded by a --block-number=# option to specify the exact metadata block to extract. Note that the block number is the one shown by --list. 360 </para> 361 </listitem> 362 </varlistentry> 363 <varlistentry> 364 <term><option>--add-replay-gain</option></term> 365 <listitem> 366 <para> 367 Calculates the title and album gains/peaks of the given FLAC 368 files as if all the files were part of one album, then stores 369 them as FLAC tags. The tags are the same as 370 those used by vorbisgain. Existing ReplayGain tags will be 371 replaced. If only one FLAC file is given, the album and title 372 gains will be the same. Since this operation requires two 373 passes, it is always executed last, after all other operations 374 have been completed and written to disk. All FLAC files 375 specified must have the same resolution, sample rate, and 376 number of channels. The sample rate must be one of 8, 11.025, 377 12, 16, 18.9, 22.05, 24, 28, 32, 37.8, 44.1, 48, 56, 64, 88.2, 378 96, 112, 128, 144, 176.4, or 192kHz. 379 </para> 380 </listitem> 381 </varlistentry> 382 <varlistentry> 383 <term><option>--scan-replay-gain</option></term> 384 <listitem> 385 <para> 386 387 Like --add-replay-gain, but only analyzes the files rather 388 than writing them to the tags. 389 </para> 390 </listitem> 391 </varlistentry> 392 <varlistentry> 393 <term><option>--remove-replay-gain</option></term> 394 <listitem> 395 <para> 396 Removes the ReplayGain tags. 397 </para> 398 </listitem> 399 </varlistentry> 400 <varlistentry> 401 <term><option>--add-seekpoint</option>={<replaceable>#</replaceable>|<replaceable>X</replaceable>|<replaceable>#x</replaceable>|<replaceable>#s</replaceable>}</term> 402 <listitem> 403 <para> 404 Add seek points to a SEEKTABLE block. Using #, a seek point at 405 that sample number is added. Using X, a placeholder point is 406 added at the end of a the table. Using #x, # evenly spaced seek 407 points will be added, the first being at sample 0. Using #s, a 408 seekpoint will be added every # seconds (# does not have to be a 409 whole number; it can be, for example, 9.5, meaning a seekpoint 410 every 9.5 seconds). If no SEEKTABLE block exists, one will be 411 created. If one already exists, points will be added to the 412 existing table, and any duplicates will be turned into placeholder 413 points. You may use many --add-seekpoint options; the resulting 414 SEEKTABLE will be the unique-ified union of all such values. 415 Example: --add-seekpoint=100x --add-seekpoint=3.5s will add 100 416 evenly spaced seekpoints and a seekpoint every 3.5 seconds. 417 </para> 418 </listitem> 419 </varlistentry> 420 <varlistentry> 421 <term><option>--add-padding=length</option></term> 422 <listitem> 423 <para> 424 Add a padding block of the given length (in bytes). The overall 425 length of the new block will be 4 + length; the extra 4 bytes is 426 for the metadata block header. 427 </para> 428 </listitem> 429 </varlistentry> 430 </variablelist> 431 </refsect1> 432 <refsect1> 433 <title>MAJOR OPERATIONS</title> 434 435 <variablelist> 436 <varlistentry> 437 <term><option>--list</option></term> 438 <listitem> 439 <para> 440 List the contents of one or more metadata blocks to stdout. By 441 default, all metadata blocks are listed in text format. Use the 442 following options to change this behavior: 443 </para> 444 <variablelist> 445 <varlistentry> 446 <term><option>--block-number=#[,#[...]]</option></term> 447 <listitem> 448 <para> 449 An optional comma-separated list of block numbers to display. 450 The first block, the STREAMINFO block, is block 0. 451 </para> 452 </listitem> 453 </varlistentry> 454 <varlistentry> 455 <term><option>--block-type=type[,type[...]]</option></term> 456 <listitem><para></para></listitem> 457 </varlistentry> 458 <varlistentry> 459 <term><option>--except-block-type=type[,type[...]]</option></term> 460 <listitem> 461 <para> 462 An optional comma-separated list of block types to be included 463 or ignored with this option. Use only one of --block-type or 464 --except-block-type. The valid block types are: STREAMINFO, 465 PADDING, APPLICATION, SEEKTABLE, VORBIS_COMMENT, PICTURE. You 466 may narrow down the types of APPLICATION blocks displayed as 467 follows: 468 </para> 469 <para> 470 APPLICATION:abcd The APPLICATION block(s) whose textual repre- 471 sentation of the 4-byte ID is "abcd" 472 APPLICATION:0xXXXXXXXX The APPLICATION block(s) whose hexadecimal big- 473 endian representation of the 4-byte ID is 474 "0xXXXXXXXX". For the example "abcd" above the 475 hexadecimal equivalalent is 0x61626364 476 </para> 477 <note> 478 <para> 479 if both --block-number and --[except-]block-type are 480 specified, the result is the logical AND of both 481 arguments.</para></note> 482 </listitem> 483 </varlistentry> 484 <varlistentry> 485 <term><option>--application-data-format=hexdump|text</option></term> 486 <listitem> 487 <para> 488 If the application block you are displaying contains binary 489 data but your --data-format=text, you can display a hex dump 490 of the application data contents instead using 491 --application-data-format=hexdump. 492 </para> 493 </listitem> 494 </varlistentry> 495 </variablelist> 496 </listitem> 497 </varlistentry> 498 <varlistentry> 499 <term><option>--remove</option></term> 500 <listitem> 501 <para> 502 Remove one or more metadata blocks from the metadata. Unless 503 --dont-use-padding is specified, the blocks will be replaced with 504 padding. You may not remove the STREAMINFO block. 505 </para> 506 <variablelist> 507 <varlistentry> 508 <term><option>--block-number=#[,#[...]]</option></term> 509 <listitem><para></para></listitem> 510 </varlistentry> 511 <varlistentry> 512 <term><option>--block-type=type[,type[...]]</option></term> 513 <listitem><para></para></listitem> 514 </varlistentry> 515 <varlistentry> 516 <term><option>--except-block-type=type[,type[...]]</option></term> 517 <listitem> 518 <para>See --list above for usage.</para> 519 <note> 520 <para> 521 if both --block-number and --[except-]block-type are 522 specified, the result is the logical AND of both arguments. 523 </para></note> 524 </listitem> 525 </varlistentry> 526 </variablelist> 527 </listitem> 528 </varlistentry> 529 <varlistentry> 530 <term><option>--remove-all</option></term> 531 <listitem> 532 <para> 533 Remove all metadata blocks (except the STREAMINFO block) from the 534 metadata. Unless --dont-use-padding is specified, the blocks will 535 be replaced with padding. 536 </para> 537 </listitem> 538 </varlistentry> 539 <varlistentry> 540 <term><option>--merge-padding</option></term> 541 <listitem> 542 <para> 543 Merge adjacent PADDING blocks into single blocks. 544 </para> 545 </listitem> 546 </varlistentry> 547 <varlistentry> 548 <term><option>--sort-padding</option></term> 549 <listitem> 550 <para> 551 Move all PADDING blocks to the end of the metadata and merge them 552 into a single block. 553 </para> 554 </listitem> 555 </varlistentry> 556 </variablelist> 557 </refsect1> 558 559 <refsect1> 560 <title>SEE ALSO</title> 561 562 <para>flac(1).</para> 563 </refsect1> 564</refentry> 565 566<!-- Keep this comment at the end of the file 567Local variables: 568mode: sgml 569sgml-omittag:t 570sgml-shorttag:t 571sgml-minimize-attributes:nil 572sgml-always-quote-attributes:t 573sgml-indent-step:2 574sgml-indent-data:t 575sgml-parent-document:nil 576sgml-default-dtd-file:nil 577sgml-exposed-tags:nil 578sgml-local-catalogs:nil 579sgml-local-ecat-files:nil 580End: 581--> 582
