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