1/* metaflac - Command-line FLAC metadata editor 2 * Copyright (C) 2001,2002,2003,2004,2005,2006,2007 Josh Coalson 3 * 4 * This program is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU General Public License 6 * as published by the Free Software Foundation; either version 2 7 * of the License, or (at your option) any later version. 8 * 9 * This program is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 * GNU General Public License for more details. 13 * 14 * You should have received a copy of the GNU General Public License 15 * along with this program; if not, write to the Free Software 16 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 17 */ 18 19#if HAVE_CONFIG_H 20# include <config.h> 21#endif 22 23#include "usage.h" 24#include "FLAC/format.h" 25#include <stdarg.h> 26#include <stdio.h> 27 28static void usage_header(FILE *out) 29{ 30 fprintf(out, "==============================================================================\n"); 31 fprintf(out, "metaflac - Command-line FLAC metadata editor version %s\n", FLAC__VERSION_STRING); 32 fprintf(out, "Copyright (C) 2001,2002,2003,2004,2005,2006,2007 Josh Coalson\n"); 33 fprintf(out, "\n"); 34 fprintf(out, "This program is free software; you can redistribute it and/or\n"); 35 fprintf(out, "modify it under the terms of the GNU General Public License\n"); 36 fprintf(out, "as published by the Free Software Foundation; either version 2\n"); 37 fprintf(out, "of the License, or (at your option) any later version.\n"); 38 fprintf(out, "\n"); 39 fprintf(out, "This program is distributed in the hope that it will be useful,\n"); 40 fprintf(out, "but WITHOUT ANY WARRANTY; without even the implied warranty of\n"); 41 fprintf(out, "MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n"); 42 fprintf(out, "GNU General Public License for more details.\n"); 43 fprintf(out, "\n"); 44 fprintf(out, "You should have received a copy of the GNU General Public License\n"); 45 fprintf(out, "along with this program; if not, write to the Free Software\n"); 46 fprintf(out, "Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.\n"); 47 fprintf(out, "==============================================================================\n"); 48} 49 50static void usage_summary(FILE *out) 51{ 52 fprintf(out, "Usage:\n"); 53 fprintf(out, " metaflac [options] [operations] FLACfile [FLACfile ...]\n"); 54 fprintf(out, "\n"); 55 fprintf(out, "Use metaflac to list, add, remove, or edit metadata in one or more FLAC files.\n"); 56 fprintf(out, "You may perform one major operation, or many shorthand operations at a time.\n"); 57 fprintf(out, "\n"); 58 fprintf(out, "Options:\n"); 59 fprintf(out, "--preserve-modtime Preserve the original modification time in spite of edits\n"); 60 fprintf(out, "--with-filename Prefix each output line with the FLAC file name\n"); 61 fprintf(out, " (the default if more than one FLAC file is specified)\n"); 62 fprintf(out, "--no-filename Do not prefix each output line with the FLAC file name\n"); 63 fprintf(out, " (the default if only one FLAC file is specified)\n"); 64 fprintf(out, "--no-utf8-convert Do not convert tags from UTF-8 to local charset,\n"); 65 fprintf(out, " or vice versa. This is useful for scripts, and setting\n"); 66 fprintf(out, " tags in situations where the locale is wrong.\n"); 67 fprintf(out, "--dont-use-padding By default metaflac tries to use padding where possible\n"); 68 fprintf(out, " to avoid rewriting the entire file if the metadata size\n"); 69 fprintf(out, " changes. Use this option to tell metaflac to not take\n"); 70 fprintf(out, " advantage of padding this way.\n"); 71} 72 73int short_usage(const char *message, ...) 74{ 75 va_list args; 76 77 if(message) { 78 va_start(args, message); 79 80 (void) vfprintf(stderr, message, args); 81 82 va_end(args); 83 84 } 85 usage_header(stderr); 86 fprintf(stderr, "\n"); 87 fprintf(stderr, "This is the short help; for full help use 'metaflac --help'\n"); 88 fprintf(stderr, "\n"); 89 usage_summary(stderr); 90 91 return message? 1 : 0; 92} 93 94int long_usage(const char *message, ...) 95{ 96 FILE *out = (message? stderr : stdout); 97 va_list args; 98 99 if(message) { 100 va_start(args, message); 101 102 (void) vfprintf(stderr, message, args); 103 104 va_end(args); 105 106 } 107 usage_header(out); 108 fprintf(out, "\n"); 109 usage_summary(out); 110 fprintf(out, "\n"); 111 fprintf(out, "Shorthand operations:\n"); 112 fprintf(out, "--show-md5sum Show the MD5 signature from the STREAMINFO block.\n"); 113 fprintf(out, "--show-min-blocksize Show the minimum block size from the STREAMINFO block.\n"); 114 fprintf(out, "--show-max-blocksize Show the maximum block size from the STREAMINFO block.\n"); 115 fprintf(out, "--show-min-framesize Show the minimum frame size from the STREAMINFO block.\n"); 116 fprintf(out, "--show-max-framesize Show the maximum frame size from the STREAMINFO block.\n"); 117 fprintf(out, "--show-sample-rate Show the sample rate from the STREAMINFO block.\n"); 118 fprintf(out, "--show-channels Show the number of channels from the STREAMINFO block.\n"); 119 fprintf(out, "--show-bps Show the # of bits per sample from the STREAMINFO block.\n"); 120 fprintf(out, "--show-total-samples Show the total # of samples from the STREAMINFO block.\n"); 121 fprintf(out, "\n"); 122 fprintf(out, "--show-vendor-tag Show the vendor string from the VORBIS_COMMENT block.\n"); 123 fprintf(out, "--show-tag=NAME Show all tags where the the field name matches 'NAME'.\n"); 124 fprintf(out, "--remove-tag=NAME Remove all tags whose field name is 'NAME'.\n"); 125 fprintf(out, "--remove-first-tag=NAME Remove first tag whose field name is 'NAME'.\n"); 126 fprintf(out, "--remove-all-tags Remove all tags, leaving only the vendor string.\n"); 127 fprintf(out, "--set-tag=FIELD Add a tag. The FIELD must comply with the Vorbis comment\n"); 128 fprintf(out, " spec, of the form \"NAME=VALUE\". If there is currently\n"); 129 fprintf(out, " no tag block, one will be created.\n"); 130 fprintf(out, "--set-tag-from-file=FIELD Like --set-tag, except the VALUE is a filename\n"); 131 fprintf(out, " whose contents will be read verbatim to set the tag value.\n"); 132 fprintf(out, " Unless --no-utf8-convert is specified, the contents will\n"); 133 fprintf(out, " be converted to UTF-8 from the local charset. This can\n"); 134 fprintf(out, " be used to store a cuesheet in a tag (e.g.\n"); 135 fprintf(out, " --set-tag-from-file=\"CUESHEET=image.cue\"). Do not try\n"); 136 fprintf(out, " to store binary data in tag fields! Use APPLICATION\n"); 137 fprintf(out, " blocks for that.\n"); 138 fprintf(out, "--import-tags-from=FILE Import tags from a file. Use '-' for stdin. Each line\n"); 139 fprintf(out, " should be of the form NAME=VALUE. Multi-line comments\n"); 140 fprintf(out, " are currently not supported. Specify --remove-all-tags\n"); 141 fprintf(out, " and/or --no-utf8-convert before --import-tags-from if\n"); 142 fprintf(out, " necessary. If FILE is '-' (stdin), only one FLAC file\n"); 143 fprintf(out, " may be specified.\n"); 144 fprintf(out, "--export-tags-to=FILE Export tags to a file. Use '-' for stdout. Each line\n"); 145 fprintf(out, " will be of the form NAME=VALUE. Specify\n"); 146 fprintf(out, " --no-utf8-convert if necessary.\n"); 147 fprintf(out, "--import-cuesheet-from=FILE Import a cuesheet from a file. Use '-' for stdin.\n"); 148 fprintf(out, " Only one FLAC file may be specified. A seekpoint will be\n"); 149 fprintf(out, " added for each index point in the cuesheet to the\n"); 150 fprintf(out, " SEEKTABLE unless --no-cued-seekpoints is specified.\n"); 151 fprintf(out, "--export-cuesheet-to=FILE Export CUESHEET block to a cuesheet file, suitable\n"); 152 fprintf(out, " for use by CD authoring software. Use '-' for stdout.\n"); 153 fprintf(out, " Only one FLAC file may be specified on the command line.\n"); 154 fprintf(out, "--import-picture-from=FILENAME|SPECIFICATION Import a picture and store it in a\n"); 155 fprintf(out, " PICTURE block. Either a filename for the picture file or\n"); 156 fprintf(out, " a more complete specification form can be used. The\n"); 157 fprintf(out, " SPECIFICATION is a string whose parts are separated by |\n"); 158 fprintf(out, " characters. Some parts may be left empty to invoke\n"); 159 fprintf(out, " default values. FILENAME is just shorthand for\n"); 160 fprintf(out, " \"||||FILENAME\". The format of SPECIFICATION is:\n"); 161 fprintf(out, " [TYPE]|[MIME-TYPE]|[DESCRIPTION]|[WIDTHxHEIGHTxDEPTH[/COLORS]]|FILE\n"); 162 fprintf(out, " TYPE is optional; it is a number from one of:\n"); 163 fprintf(out, " 0: Other\n"); 164 fprintf(out, " 1: 32x32 pixels 'file icon' (PNG only)\n"); 165 fprintf(out, " 2: Other file icon\n"); 166 fprintf(out, " 3: Cover (front)\n"); 167 fprintf(out, " 4: Cover (back)\n"); 168 fprintf(out, " 5: Leaflet page\n"); 169 fprintf(out, " 6: Media (e.g. label side of CD)\n"); 170 fprintf(out, " 7: Lead artist/lead performer/soloist\n"); 171 fprintf(out, " 8: Artist/performer\n"); 172 fprintf(out, " 9: Conductor\n"); 173 fprintf(out, " 10: Band/Orchestra\n"); 174 fprintf(out, " 11: Composer\n"); 175 fprintf(out, " 12: Lyricist/text writer\n"); 176 fprintf(out, " 13: Recording Location\n"); 177 fprintf(out, " 14: During recording\n"); 178 fprintf(out, " 15: During performance\n"); 179 fprintf(out, " 16: Movie/video screen capture\n"); 180 fprintf(out, " 17: A bright coloured fish\n"); 181 fprintf(out, " 18: Illustration\n"); 182 fprintf(out, " 19: Band/artist logotype\n"); 183 fprintf(out, " 20: Publisher/Studio logotype\n"); 184 fprintf(out, " The default is 3 (front cover). There may only be one picture each\n"); 185 fprintf(out, " of type 1 and 2 in a file.\n"); 186 fprintf(out, " MIME-TYPE is optional; if left blank, it will be detected from the\n"); 187 fprintf(out, " file. For best compatibility with players, use pictures with MIME\n"); 188 fprintf(out, " type image/jpeg or image/png. The MIME type can also be --> to\n"); 189 fprintf(out, " mean that FILE is actually a URL to an image, though this use is\n"); 190 fprintf(out, " discouraged.\n"); 191 fprintf(out, " DESCRIPTION is optional; the default is an empty string\n"); 192 fprintf(out, " The next part specfies the resolution and color information. If\n"); 193 fprintf(out, " the MIME-TYPE is image/jpeg, image/png, or image/gif, you can\n"); 194 fprintf(out, " usually leave this empty and they can be detected from the file.\n"); 195 fprintf(out, " Otherwise, you must specify the width in pixels, height in pixels,\n"); 196 fprintf(out, " and color depth in bits-per-pixel. If the image has indexed colors\n"); 197 fprintf(out, " you should also specify the number of colors used.\n"); 198 fprintf(out, " FILE is the path to the picture file to be imported, or the URL if\n"); 199 fprintf(out, " MIME type is -->\n"); 200 fprintf(out, "--export-picture-to=FILE Export PICTURE block to a file. Use '-' for stdout.\n"); 201 fprintf(out, " Only one FLAC file may be specified. The first PICTURE\n"); 202 fprintf(out, " block will be exported unless --export-picture-to is\n"); 203 fprintf(out, " preceded by a --block-number=# option to specify the exact\n"); 204 fprintf(out, " metadata block to extract. Note that the block number is\n"); 205 fprintf(out, " the one shown by --list.\n"); 206 fprintf(out, "--add-replay-gain Calculates the title and album gains/peaks of the given\n"); 207 fprintf(out, " FLAC files as if all the files were part of one album,\n"); 208 fprintf(out, " then stores them in the VORBIS_COMMENT block. The tags\n"); 209 fprintf(out, " are the same as those used by vorbisgain. Existing\n"); 210 fprintf(out, " ReplayGain tags will be replaced. If only one FLAC file\n"); 211 fprintf(out, " is given, the album and title gains will be the same.\n"); 212 fprintf(out, " Since this operation requires two passes, it is always\n"); 213 fprintf(out, " executed last, after all other operations have been\n"); 214 fprintf(out, " completed and written to disk. All FLAC files specified\n"); 215 fprintf(out, " must have the same resolution, sample rate, and number\n"); 216 fprintf(out, " of channels. The sample rate must be one of 8, 11.025,\n"); 217 fprintf(out, " 12, 16, 22.05, 24, 32, 44.1, or 48 kHz.\n"); 218 fprintf(out, "--remove-replay-gain Removes the ReplayGain tags.\n"); 219 fprintf(out, "--add-seekpoint={#|X|#x|#s} Add seek points to a SEEKTABLE block\n"); 220 fprintf(out, " # : a specific sample number for a seek point\n"); 221 fprintf(out, " X : a placeholder point (always goes at the end of the SEEKTABLE)\n"); 222 fprintf(out, " #x : # evenly spaced seekpoints, the first being at sample 0\n"); 223 fprintf(out, " #s : a seekpoint every # seconds; # does not have to be a whole number\n"); 224 fprintf(out, " If no SEEKTABLE block exists, one will be created. If\n"); 225 fprintf(out, " one already exists, points will be added to the existing\n"); 226 fprintf(out, " table, and any duplicates will be turned into placeholder\n"); 227 fprintf(out, " points. You may use many --add-seekpoint options; the\n"); 228 fprintf(out, " resulting SEEKTABLE will be the unique-ified union of\n"); 229 fprintf(out, " all such values. Example: --add-seekpoint=100x\n"); 230 fprintf(out, " --add-seekpoint=3.5s will add 100 evenly spaced\n"); 231 fprintf(out, " seekpoints and a seekpoint every 3.5 seconds.\n"); 232 fprintf(out, "--add-padding=length Add a padding block of the given length (in bytes).\n"); 233 fprintf(out, " The overall length of the new block will be 4 + length;\n"); 234 fprintf(out, " the extra 4 bytes is for the metadata block header.\n"); 235 fprintf(out, "\n"); 236 fprintf(out, "Major operations:\n"); 237 fprintf(out, "--version\n"); 238 fprintf(out, " Show the metaflac version number.\n"); 239 fprintf(out, "--list\n"); 240 fprintf(out, " List the contents of one or more metadata blocks to stdout. By default,\n"); 241 fprintf(out, " all metadata blocks are listed in text format. Use the following options\n"); 242 fprintf(out, " to change this behavior:\n"); 243 fprintf(out, "\n"); 244 fprintf(out, " --block-number=#[,#[...]]\n"); 245 fprintf(out, " An optional comma-separated list of block numbers to display. The first\n"); 246 fprintf(out, " block, the STREAMINFO block, is block 0.\n"); 247 fprintf(out, "\n"); 248 fprintf(out, " --block-type=type[,type[...]]\n"); 249 fprintf(out, " --except-block-type=type[,type[...]]\n"); 250 fprintf(out, " An optional comma-separated list of block types to be included or ignored\n"); 251 fprintf(out, " with this option. Use only one of --block-type or --except-block-type.\n"); 252 fprintf(out, " The valid block types are: STREAMINFO, PADDING, APPLICATION, SEEKTABLE,\n"); 253 fprintf(out, " VORBIS_COMMENT. You may narrow down the types of APPLICATION blocks\n"); 254 fprintf(out, " displayed as follows:\n"); 255 fprintf(out, " APPLICATION:abcd The APPLICATION block(s) whose textual repre-\n"); 256 fprintf(out, " sentation of the 4-byte ID is \"abcd\"\n"); 257 fprintf(out, " APPLICATION:0xXXXXXXXX The APPLICATION block(s) whose hexadecimal big-\n"); 258 fprintf(out, " endian representation of the 4-byte ID is\n"); 259 fprintf(out, " \"0xXXXXXXXX\". For the example \"abcd\" above the\n"); 260 fprintf(out, " hexadecimal equivalalent is 0x61626364\n"); 261 fprintf(out, "\n"); 262 fprintf(out, " NOTE: if both --block-number and --[except-]block-type are specified,\n"); 263 fprintf(out, " the result is the logical AND of both arguments.\n"); 264 fprintf(out, "\n"); 265#if 0 266 /*@@@ not implemented yet */ 267 fprintf(out, " --data-format=binary|text\n"); 268 fprintf(out, " By default a human-readable text representation of the data is displayed.\n"); 269 fprintf(out, " You may specify --data-format=binary to dump the raw binary form of each\n"); 270 fprintf(out, " metadata block. The output can be read in using a subsequent call to\n"); 271 fprintf(out, " "metaflac --append --from-file=..."\n"); 272 fprintf(out, "\n"); 273#endif 274 fprintf(out, " --application-data-format=hexdump|text\n"); 275 fprintf(out, " If the application block you are displaying contains binary data but your\n"); 276 fprintf(out, " --data-format=text, you can display a hex dump of the application data\n"); 277 fprintf(out, " contents instead using --application-data-format=hexdump\n"); 278 fprintf(out, "\n"); 279#if 0 280 /*@@@ not implemented yet */ 281 fprintf(out, "--append\n"); 282 fprintf(out, " Insert a metadata block from a file. The input file must be in the same\n"); 283 fprintf(out, " format as generated with --list.\n"); 284 fprintf(out, "\n"); 285 fprintf(out, " --block-number=#\n"); 286 fprintf(out, " Specify the insertion point (defaults to last block). The new block will\n"); 287 fprintf(out, " be added after the given block number. This prevents the illegal insertion\n"); 288 fprintf(out, " of a block before the first STREAMINFO block. You may not --append another\n"); 289 fprintf(out, " STREAMINFO block.\n"); 290 fprintf(out, "\n"); 291 fprintf(out, " --from-file=filename\n"); 292 fprintf(out, " Mandatory 'option' to specify the input file containing the block contents.\n"); 293 fprintf(out, "\n"); 294 fprintf(out, " --data-format=binary|text\n"); 295 fprintf(out, " By default the block contents are assumed to be in binary format. You can\n"); 296 fprintf(out, " override this by specifying --data-format=text\n"); 297 fprintf(out, "\n"); 298#endif 299 fprintf(out, "--remove\n"); 300 fprintf(out, " Remove one or more metadata blocks from the metadata. Unless\n"); 301 fprintf(out, " --dont-use-padding is specified, the blocks will be replaced with padding.\n"); 302 fprintf(out, " You may not remove the STREAMINFO block.\n"); 303 fprintf(out, "\n"); 304 fprintf(out, " --block-number=#[,#[...]]\n"); 305 fprintf(out, " --block-type=type[,type[...]]\n"); 306 fprintf(out, " --except-block-type=type[,type[...]]\n"); 307 fprintf(out, " See --list above for usage.\n"); 308 fprintf(out, "\n"); 309 fprintf(out, " NOTE: if both --block-number and --[except-]block-type are specified,\n"); 310 fprintf(out, " the result is the logical AND of both arguments.\n"); 311 fprintf(out, "\n"); 312 fprintf(out, "--remove-all\n"); 313 fprintf(out, " Remove all metadata blocks (except the STREAMINFO block) from the\n"); 314 fprintf(out, " metadata. Unless --dont-use-padding is specified, the blocks will be\n"); 315 fprintf(out, " replaced with padding.\n"); 316 fprintf(out, "\n"); 317 fprintf(out, "--merge-padding\n"); 318 fprintf(out, " Merge adjacent PADDING blocks into single blocks.\n"); 319 fprintf(out, "\n"); 320 fprintf(out, "--sort-padding\n"); 321 fprintf(out, " Move all PADDING blocks to the end of the metadata and merge them into a\n"); 322 fprintf(out, " single block.\n"); 323 324 return message? 1 : 0; 325} 326