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