diff --git a/man/flac.md b/man/flac.md index f9d71a6346..7762fc2849 100644 --- a/man/flac.md +++ b/man/flac.md @@ -324,11 +324,6 @@ negated, see the **Negative options** section below. sign means that the \--until point is taken relative to the \--skip point. For other considerations, see \--skip. -**\--no-utf8-convert** -: Do not convert tags from local charset to UTF-8. This is useful for - scripts, and setting tags in situations where the locale is wrong. - This option must appear before any tag options! - **-s**, **\--silent** : Silent mode (do not write runtime encode/decode statistics to stderr) @@ -426,10 +421,12 @@ Encoding will default to -5, -A "tukey(5e-1)" and one CPU thread. for subset streams with higher samplerates it must be \<= 16384. **-m**, **\--mid-side** -: Try mid-side coding for each frame (stereo only, otherwise ignored). +: Try mid-side coding for each frame in addition to left and right, and + select the best compression. (Stereo only, ignored otherwise.) **-M**, **\--adaptive-mid-side** -: Adaptive mid-side coding for all frames (stereo only, otherwise ignored). +: Like -m, but choose with a heuristic (faster, slightly weaker + compression). **-r** \[\#,\]\#, **\--rice-partition-order**=\[\#,\]\# : Set the \[min,\]max residual partition order (0..15). For subset @@ -445,20 +442,19 @@ Encoding will default to -5, -A "tukey(5e-1)" and one CPU thread. : Do exhaustive model search (expensive!). **-q** \#, **\--qlp-coeff-precision**=\# -: Precision of the quantized linear-predictor coefficients. This number - must be in between 5 and 16, or 0 (the default) to let encoder decide. - Does nothing if using -l 0. +: Set precision (in bits) of the quantized linear-predictor + coefficients, 5\<= \# \<=15 or the default 0 to let encoder decide. + Does nothing if using -l 0. The encoder may reduce the actual + quantization below the \# number by signal and prediction order. **-p**, **\--qlp-coeff-precision-search** -: Do exhaustive search of LP coefficient quantization (expensive!). +: Do exhaustive search of LP coefficient precision (expensive!). Overrides -q; does nothing if using -l 0. **\--lax** -: Allow encoder to generate non-Subset files. The resulting FLAC file - may not be streamable or might have trouble being played in all - players (especially hardware devices), so you should only use this - option in combination with custom encoding options meant for - archival. +: Allow encoding to non-*subset* FLAC files (see RFC 9639 section 7). + WARNING: may cause some applications (especially legacy hardware + devices) to fail streaming or playback. **\--limit-min-bitrate** : Limit minimum bitrate by not allowing frames consisting of only @@ -467,13 +463,14 @@ Encoding will default to -5, -A "tukey(5e-1)" and one CPU thread. internet streaming. **-j** \#, **\--threads**=\# -: Try to set a maximum number of threads to use for encoding. If - multithreading was not enabled on compilation or when setting a - number of threads that is too high, this fails with a warning. The - value of 0 means a default set by the encoder; currently that is 1 - thread (i.e. no multithreading), but that could change in the - future. Currently, up to 128 threads are supported. Using a value - higher than the number of available CPU threads harms performance. +: By default, **flac** will encode with one thread. This option enables + multithreading with max \# number of threads, although "0" to let the + encoder decide. Currently, -j 0 is synonymous with -j 1 (i.e. no + multithreading), and the max supported number is 64; both could change + in the future. If \# exceeds the supported maximum (64), **flac** will + encode with a single thread (and throw a warning). The same happens + (for any \#) if **flac** was compiled with multithreading disabled. + NOTE: Exceeding the *actual* available CPU threads, harms speed. **\--ignore-chunk-sizes** : When encoding to flac, ignore the file size headers in WAV and AIFF @@ -513,6 +510,29 @@ Encoding will default to -5, -A "tukey(5e-1)" and one CPU thread. Specifying only *FILENAME* is just shorthand for "\|\|\|\|FILENAME". See the section **Picture specification** for *SPECIFICATION* format. +**\--no-utf8-convert** +: Upon tagging, do not convert tags from local charset to UTF-8. This + is useful for scripts, and for setting tags in situations where the + locale is wrong. This option must appear *before* any tag options! + +**-T** "*FIELD=VALUE*"**, \--tag**="*FIELD=VALUE*" +: Add a FLAC tag. The comment must adhere to the Vorbis comment spec; + i.e. the FIELD must contain only legal characters, terminated by an + 'equals' sign. Make sure to quote the content if necessary. This + option may appear more than once to add several Vorbis comments. + NOTE 1: All tags will be added to all encoded files. + NOTE 2: Upon re-encoding a file with one or more -T or \--tag + options, all tags in the input file will be ignored, not only those + set with -T / \--tag. + +**\--tag-from-file**="*FIELD=FILENAME*" +: Like \--tag, except FILENAME is a file whose contents will be read + verbatim to set the tag value. The contents will be converted to + UTF-8 from the local charset. This can be used to store a cuesheet + in a tag (e.g. \--tag-from-file="CUESHEET=image.cue"). + NOTE: Do not try to store binary data in tag fields! Use PICTURE + blocks for pictures and APPLICATION blocks for other binary data. + **-S** {\#\|X\|\#x\|\#s}, **\--seekpoint**={\#\|X\|\#x\|\#s} : Specifies point(s) to include in SEEKTABLE, to override the encoder's default choice of one per ten seconds ('-s 10s'). Using \#, a seek point @@ -538,20 +558,6 @@ Encoding will default to -5, -A "tukey(5e-1)" and one CPU thread. of having to rewrite the entire file. Note that a block header of 4 bytes will come on top of the length specified. -**-T** "*FIELD=VALUE*"**, \--tag**="*FIELD=VALUE*" -: Add a FLAC tag. The comment must adhere to the Vorbis comment spec; - i.e. the FIELD must contain only legal characters, terminated by an - 'equals' sign. Make sure to quote the content if necessary. This - option may appear more than once to add several Vorbis comments. - NOTE: all tags will be added to all encoded files. - -**\--tag-from-file**="*FIELD=FILENAME*" -: Like \--tag, except FILENAME is a file whose contents will be read - verbatim to set the tag value. The contents will be converted to - UTF-8 from the local charset. This can be used to store a cuesheet - in a tag (e.g. \--tag-from-file="CUESHEET=image.cue"). Do not try to - store binary data in tag fields! Use APPLICATION blocks for that. - ## FORMAT OPTIONS