Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update main.c with new help text #708

Merged
merged 5 commits into from
Jun 26, 2024
Merged

Update main.c with new help text #708

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0b3135c
Update main.c with new help text
H2Swine Jun 11, 2024
f365c1d
Update src/flac/main.c
H2Swine Jun 12, 2024
9917643
Fix indentation
ktmf01 Jun 13, 2024
9fb7285
Move analysis options down in help
ktmf01 Jun 13, 2024
a839d50
Remove extraneous whitespace and add missing quotation marks
ktmf01 Jun 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 61 additions & 52 deletions src/flac/main.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1278,98 +1278,109 @@ void show_help(void)
{
usage_header();
usage_summary();
printf("general options:\n");
printf("\n");
printf("General options:\n");
printf(" -v, --version Show the flac version number\n");
printf(" -h, --help Show this screen\n");
printf(" -H, --explain Show detailed explanation of usage and options\n");
printf(" -d, --decode Decode (the default behavior is to encode)\n");
printf(" -t, --test Same as -d except no decoded file is written,\n");
printf(" with some additional checks.\n");
printf(" -a, --analyze Same as -d except an analysis file is written\n");
printf(" -t, --test As -d except no decoded file is written,\n");
printf(" and with some additional checks.\n");
printf(" -a, --analyze As -d except an analysis file is written\n");
printf(" -c, --stdout Write output to stdout\n");
printf(" -s, --silent Do not write runtime encode/decode statistics\n");
printf(" --totally-silent Do not print anything, including errors\n");
printf(" --no-utf8-convert Do not convert tags from local charset to UTF-8\n");
printf(" -w, --warnings-as-errors Treat all warnings as errors\n");
printf(" -f, --force Force overwriting of output files\n");
printf(" --delete-input-file Deletes after a successful encode/decode\n");
printf(" -o, --output-name=FILENAME Force the output file name\n");
printf(" --output-prefix=STRING Prepend STRING to output names\n");
printf(" --delete-input-file Deletes after a successful encode/decode\n");
printf(" --preserve-modtime Output files keep timestamp of input (default)\n");
printf(" --preserve-modtime (default) Output files keep timestamp of input\n");
printf(" --keep-foreign-metadata Save/restore WAVE or AIFF non-audio chunks\n");
printf(" --keep-foreign-metadata-if-present Save/restore WAVE or AIFF non-audio\n");
printf(" but not return an error when no such chunks are found\n");
printf(" --keep-foreign-metadata-if-present Save/restore WAVE or AIFF non-audio\n");
printf(" but not return an error when no such chunks are found\n");
printf(" --skip={#|mm:ss.ss} Skip the given initial samples for each input\n");
printf(" --until={#|[+|-]mm:ss.ss} Stop at the given sample for each input file\n");
#if FLAC__HAS_OGG
printf(" --ogg Use Ogg as transport layer\n");
printf(" --serial-number Serial number to use for the FLAC stream\n");
#endif
printf("analysis options:\n");
printf(" --residual-text Include residual signal in text output\n");
printf(" --residual-gnuplot Generate gnuplot files of residual distribution\n");
printf("decoding options:\n");
printf(" --until={#|[+|-]mm:ss.ss} Stop at the given sample for each input file\n");
printf(" --no-utf8-convert Do not convert tags from local charset to UTF-8\n");
printf(" -s, --silent Do not write runtime encode/decode statistics\n");
printf(" --totally-silent Do not print anything, including errors\n");
printf(" -w, --warnings-as-errors Treat all warnings as errors\n");
printf("\n");
printf("Decoding options:\n");
printf(" -F, --decode-through-errors Continue decoding through stream errors\n");
printf(" --cue=[#.#][-[#.#]] Set the beginning and ending cuepoints to decode\n");
printf("encoding options:\n");
printf(" -V, --verify Verify a correct encoding\n");
printf(" --lax Allow encoder to generate non-Subset files\n");
printf(" --ignore-chunk-sizes Ignore data chunk sizes in WAVE/AIFF files\n");
printf(" --replay-gain Calculate ReplayGain & store in FLAC tags\n");
printf(" --cuesheet=FILENAME Import cuesheet and store in CUESHEET block\n");
printf(" --picture=SPECIFICATION Import picture and store in PICTURE block\n");
printf(" -T, --tag=FIELD=VALUE Add a FLAC tag; may appear multiple times\n");
printf(" --tag-from-file=FIELD=FILENAME Like --tag but gets value from file\n");
printf(" -S, --seekpoint={#|X|#x|#s} Add seek point(s)\n");
printf(" -P, --padding=# Write a PADDING block of length #\n");
printf("\n");
H2Swine marked this conversation as resolved.
Show resolved Hide resolved
printf("Analysis options:\n");
H2Swine marked this conversation as resolved.
Show resolved Hide resolved
printf(" --residual-text Include residual signal in text output\n");
printf(" --residual-gnuplot Generate gnuplot files of residual distribution\n");
printf("\n");
printf("Encoding options, defaulting to -5, -A \"tukey(5e-1)\" and one CPU thread:\n");
printf(" -V, --verify Verify a correct encoding\n");
printf(" -0, --compression-level-0, --fast Synonymous with -l 0 -b 1152 -r 3\n");
printf(" -1, --compression-level-1 Synonymous with -l 0 -b 1152 -M -r 3\n");
printf(" -2, --compression-level-2 Synonymous with -l 0 -b 1152 -m -r 3\n");
printf(" -3, --compression-level-3 Synonymous with -l 6 -b 4096 -r 4\n");
printf(" -4, --compression-level-4 Synonymous with -l 8 -b 4096 -M -r 4\n");
printf(" -5, --compression-level-5 Synonymous with -l 8 -b 4096 -m -r 5\n");
printf(" -6, --compression-level-6 Synonymous with -l 8 -b 4096 -m -r 6\n");
printf(" -A subdivide_tukey(2)\n");
printf(" -A \"subdivide_tukey(2)\"\n");
printf(" -7, --compression-level-7 Synonymous with -l 12 -b 4096 -m -r 6\n");
printf(" -A subdivide_tukey(2)\n");
printf(" -A \"subdivide_tukey(2)\"\n");
printf(" -8, --compression-level-8, --best Synonymous with -l 12 -b 4096 -m -r 6\n");
printf(" -A subdivide_tukey(3)\n");
printf(" -A \"subdivide_tukey(3)\"\n");
printf(" -l, --max-lpc-order=# Max LPC order; 0 => only fixed predictors\n");
printf(" -b, --blocksize=# Specify blocksize in samples\n");
printf(" -m, --mid-side Try mid-side coding for each frame\n");
printf(" -M, --adaptive-mid-side Adaptive mid-side coding for all frames\n");
printf(" -M, --adaptive-mid-side Adaptive choice of mid-side coding\n");
printf(" -r, --rice-partition-order=[#,]# Set [min,]max residual partition order\n");
printf(" -A, --apodization=\"function\" Window audio data with given function(s)\n");
printf(" -e, --exhaustive-model-search Do exhaustive model search (expensive!)\n");
printf(" -A, --apodization=\"function\" Window audio data with given the function\n");
printf(" -l, --max-lpc-order=# Max LPC order; 0 => only fixed predictors\n");
printf(" -q, --qlp-coeff-precision=# Specify quantization precision in bits\n");
printf(" (default: let encoder decide)\n");
printf(" -p, --qlp-coeff-precision-search Exhaustively search LP coeff quantization\n");
printf(" -q, --qlp-coeff-precision=# Specify precision in bits\n");
printf(" -r, --rice-partition-order=[#,]# Set [min,]max residual partition order\n");
printf(" --lax Allow encoder to generate non-Subset files\n");
printf(" --limit-min-bitrate Limit minimum bitrate (for streaming)\n");
printf(" -j, --threads=# Set number of encoding threads\n");
printf("format options:\n");
printf(" --force-raw-format Treat input or output as raw samples\n");
printf(" --ignore-chunk-sizes Ignore data chunk sizes in WAVE/AIFF files\n");
printf(" --replay-gain Calculate ReplayGain & store in FLAC tags\n");
printf(" --cuesheet=FILENAME Import cuesheet & store in CUESHEET block\n");
printf(" --picture=SPECIFICATION Import picture & store in PICTURE block\n");
printf(" -T, --tag=FIELD=VALUE Add a FLAC tag; may appear multiple times\n");
printf(" --tag-from-file=FIELD=FILENAME Like --tag but gets value from file\n");
printf(" -S, --seekpoint={#|X|#x|#s} Add seek point(s)\n");
printf(" -P, --padding=# Write a PADDING block of length # bytes\n");
printf("\n");
printf("Format options (encoding defaults to FLAC not OGG; decoding defaults to WAVE, \n");
printf(" chunks found by --keep-foreign-metadata-if-present will override):\n");
#if FLAC__HAS_OGG
printf(" --ogg Use Ogg transport layer, output .oga\n");
printf(" --serial-number Ogg serial number to assign (encoding)\n);
printf(" or to select for decoding\n);
H2Swine marked this conversation as resolved.
Show resolved Hide resolved
#endif
printf(" --force-aiff-format Decode to AIFF format\n");
printf(" --force-rf64-format Decode to RF64 format\n");
printf(" --force-wave64-format Decode to Wave64 format\n");
printf(" --force-legacy-wave-format Decode to legacy wave format\n");
printf(" --force-extensible-wave-format Decode to extensible wave format\n");
printf(" --force-aiff-c-none-format Decode to AIFF-C NONE format\n");
printf(" --force-aiff-c-sowt-format Decode to AIFF-C sowt format\n");
printf("raw format options:\n");
printf(" --endian={big|little} Set byte order for samples\n");
printf(" --channels=# Number of channels\n");
printf(" --bps=# Number of bits per sample\n");
printf(" --sample-rate=# Sample rate in Hz\n");
printf(" --sign={signed|unsigned} Sign of samples\n");
printf(" --input-size=# Size of the raw input in bytes\n");
printf("negative options:\n");
printf(" --force-raw-format Treat input or output as raw samples\n");
printf("raw format options mandatory for encoding; --sign and --endian also for decoding\n");
H2Swine marked this conversation as resolved.
Show resolved Hide resolved
printf(" --sign={signed|unsigned} Sign of samples\n");
printf(" --endian={big|little} Byte order for samples\n");
printf(" --channels=# Number of channels in raw input\n");
printf(" --bps=# Number of bits per sample in raw input\n");
printf(" --sample-rate=# Sample rate in Hz in raw input\n");
printf(" --input-size=# Size of the raw input in bytes\n");
printf("\n");
printf("Negative options (rightmost applied takes precedence):\n");
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure this is best placed here, because it applies to all options, not just negative ones. AFAIK flac -8l32 is different from flac -l32 -8. Maybe add a note at the top, before general options, something like: `the order in which options are applied is important, options applied last take precedence over options applied first.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is maybe a new issue, combining -d, -t and -a don't work that way. And now -t makes checks -d don't.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, interesting. I usually don't like changing behaviour because it breaks scripts, but this seems wrong. If I use -t and -a together I get a warning that that combination is not possible. Maybe I should add the same for any combination of -d, -t and -a?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is turning into a new issue especially with the latter paragraph here, but to pursue the train of thought:

If anyone has used -t and -d together - say, mistakenly thinking that -dt is the test-decode option - then erring out on that might break scripts too. As for other combinations I see that -da and -ad both work as -a. And -t -c (which isn't too sensible?!) works as -t. One may change it to "last one decides", but let me suggest two or three other ways out:

  • One is to -td or -ta work as -d or -a would, but invoke the extra tests of -t. Change is biggest for -td which as of now doesn't output any file. It can be "rationalized" by saying that "-t switches to decode with all tests, but switches off output; -d / -a will switch on output but not switch off the tests". With that logic, -dt should work as currently. Then -at will either have to change (but currently it errs out, so how many use it?) or stick with some inconsistency.
  • The other is to let -d and -a actually do those extra tests that -t does, but only report warning. Unexpected to those who invoke -w?
  • Probably not a good idea, but still thinking aloud: had you not already made -t more zealous (reverting that is maybe not a good idea at this stage), you could have considered the -V switch. Provided that I understand correctly that -V does nothing except when encoding? There is no natural analog to decoding-the-encode, but had one started from scratch, -tV or -dV or -aV could have been the extra zealous one that goes to greater lengths to catch all errors. But again, with the recent changes to -t, it might just be dumb to do that?

Since this brings up how much checks -d and -a should do, it is maybe natural to ask for the demand for a "fast test" option that doesn't decode. As you have pointed out elsewhere, FLAC is maybe the codec least in need for this since it decodes so fast, but still even OptimFROG has a verification that is faster than FLAC's. I was initially thinking that one could implement some -t --no-md5-sum for non-decoding verification (because what do you need the audio for if not to MD5 it?), but if I am right, -t checks more about the audio than the MD5? (Like, decoded values don't exceed -2^(N-1) ... 2^(N-1)-1?)
Anyway I think that if you consider to change what is tested, then a fast-verification option could also be part of the consideration.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If anyone has used -t and -d together - say, mistakenly thinking that -dt is the test-decode option - then erring out on that might break scripts too.

Yes, but I think breaking scripts isn't a bad thing here.

printf(" --no-adaptive-mid-side\n");
printf(" --no-cued-seekpoints\n");
printf(" --no-decode-through-errors\n");
printf(" --no-delete-input-file\n");
printf(" --no-error-on-compression-fail\n");
printf(" --no-force\n");
printf(" --no-preserve-modtime\n");
printf(" --no-keep-foreign-metadata\n");
printf(" --no-exhaustive-model-search\n");
printf(" --no-ignore-chunk-sizes\n");
printf(" --no-lax\n");
printf(" --no-mid-side\n");
#if FLAC__HAS_OGG
Expand All @@ -1380,10 +1391,8 @@ void show_help(void)
printf(" --no-replay-gain\n");
printf(" --no-residual-gnuplot\n");
printf(" --no-residual-text\n");
printf(" --no-ignore-chunk-sizes\n");
printf(" --no-seektable\n");
printf(" --no-silent\n");
printf(" --no-force\n");
printf(" --no-verify\n");
printf(" --no-warnings-as-errors\n");
}
Expand Down
Loading