diff options
author | Martijn van Beurden <mvanb1@gmail.com> | 2022-09-17 13:09:00 +0200 |
---|---|---|
committer | Martijn van Beurden <mvanb1@gmail.com> | 2022-09-20 19:54:32 +0200 |
commit | 89a1620c423ad405faeee5438d5919b9d9e03c1b (patch) | |
tree | 7115e059e5fd4ab160ac629353118a66eeb13a0c | |
parent | c65713b340b79b2aa3053534c8c9faf648431160 (diff) | |
download | flac-89a1620c423ad405faeee5438d5919b9d9e03c1b.tar.gz |
Update API and tool docs
-rw-r--r-- | include/FLAC/format.h | 3 | ||||
-rw-r--r-- | include/FLAC/stream_encoder.h | 39 | ||||
-rw-r--r-- | src/flac/main.c | 12 |
3 files changed, 34 insertions, 20 deletions
diff --git a/include/FLAC/format.h b/include/FLAC/format.h index 7835f839..99d637f0 100644 --- a/include/FLAC/format.h +++ b/include/FLAC/format.h @@ -120,8 +120,7 @@ extern "C" { #define FLAC__REFERENCE_CODEC_MAX_BITS_PER_SAMPLE (32u) /** The maximum sample rate permitted by the format. The value is - * ((2 ^ 16) - 1) * 10; see <A HREF="../format.html">FLAC format</A> - * as to why. + * ((2 ^ 20) - 1) */ #define FLAC__MAX_SAMPLE_RATE (1048575u) diff --git a/include/FLAC/stream_encoder.h b/include/FLAC/stream_encoder.h index a39d0ed2..1d7bd258 100644 --- a/include/FLAC/stream_encoder.h +++ b/include/FLAC/stream_encoder.h @@ -311,8 +311,7 @@ typedef enum { FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BITS_PER_SAMPLE, /**< The encoder has an invalid setting for bits-per-sample. - * FLAC supports 4-32 bps but the reference encoder currently supports - * only up to 24 bps. + * FLAC supports 4-32 bps. */ FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_SAMPLE_RATE, @@ -843,15 +842,15 @@ FLAC_API FLAC__bool FLAC__stream_encoder_set_sample_rate(FLAC__StreamEncoder *en * <td>max residual partition order</td> * <td>rice parameter search dist</td> * </tr> - * <tr> <td><b>0</b></td> <td>false</td> <td>false</td> <td>tukey(0.5)<td> <td>0</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>3</td> <td>0</td> </tr> - * <tr> <td><b>1</b></td> <td>true</td> <td>true</td> <td>tukey(0.5)<td> <td>0</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>3</td> <td>0</td> </tr> - * <tr> <td><b>2</b></td> <td>true</td> <td>false</td> <td>tukey(0.5)<td> <td>0</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>3</td> <td>0</td> </tr> - * <tr> <td><b>3</b></td> <td>false</td> <td>false</td> <td>tukey(0.5)<td> <td>6</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>4</td> <td>0</td> </tr> - * <tr> <td><b>4</b></td> <td>true</td> <td>true</td> <td>tukey(0.5)<td> <td>8</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>4</td> <td>0</td> </tr> - * <tr> <td><b>5</b></td> <td>true</td> <td>false</td> <td>tukey(0.5)<td> <td>8</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>5</td> <td>0</td> </tr> - * <tr> <td><b>6</b></td> <td>true</td> <td>false</td> <td>tukey(0.5);partial_tukey(2)<td> <td>8</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>6</td> <td>0</td> </tr> - * <tr> <td><b>7</b></td> <td>true</td> <td>false</td> <td>tukey(0.5);partial_tukey(2)<td> <td>12</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>6</td> <td>0</td> </tr> - * <tr> <td><b>8</b></td> <td>true</td> <td>false</td> <td>tukey(0.5);partial_tukey(2);punchout_tukey(3)</td> <td>12</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>6</td> <td>0</td> </tr> + * <tr> <td><b>0</b></td> <td>false</td> <td>false</td> <td>tukey(0.5)</td> <td>0</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>3</td> <td>0</td> </tr> + * <tr> <td><b>1</b></td> <td>true</td> <td>true</td> <td>tukey(0.5)</td> <td>0</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>3</td> <td>0</td> </tr> + * <tr> <td><b>2</b></td> <td>true</td> <td>false</td> <td>tukey(0.5)</td> <td>0</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>3</td> <td>0</td> </tr> + * <tr> <td><b>3</b></td> <td>false</td> <td>false</td> <td>tukey(0.5)</td> <td>6</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>4</td> <td>0</td> </tr> + * <tr> <td><b>4</b></td> <td>true</td> <td>true</td> <td>tukey(0.5)</td> <td>8</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>4</td> <td>0</td> </tr> + * <tr> <td><b>5</b></td> <td>true</td> <td>false</td> <td>tukey(0.5)</td> <td>8</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>5</td> <td>0</td> </tr> + * <tr> <td><b>6</b></td> <td>true</td> <td>false</td> <td>subdivide_tukey(2)</td> <td>8</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>6</td> <td>0</td> </tr> + * <tr> <td><b>7</b></td> <td>true</td> <td>false</td> <td>subdivide_tukey(2)</td> <td>12</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>6</td> <td>0</td> </tr> + * <tr> <td><b>8</b></td> <td>true</td> <td>false</td> <td>subdivide_tukey(2)</td> <td>12</td> <td>0</td> <td>false</td> <td>false</td> <td>false</td> <td>0</td> <td>6</td> <td>0</td> </tr> * </table> * * \default \c 5 @@ -921,7 +920,7 @@ FLAC_API FLAC__bool FLAC__stream_encoder_set_loose_mid_side_stereo(FLAC__StreamE * \c blackman, \c blackman_harris_4term_92db, \c connes, \c flattop, * \c gauss(STDDEV), \c hamming, \c hann, \c kaiser_bessel, \c nuttall, * \c rectangle, \c triangle, \c tukey(P), \c partial_tukey(n[/ov[/P]]), - * \c punchout_tukey(n[/ov[/P]]), \c welch. + * \c punchout_tukey(n[/ov[/P]]), \c subdivide_tukey(n[/P]), \c welch. * * For \c gauss(STDDEV), STDDEV specifies the standard deviation * (0<STDDEV<=0.5). @@ -948,6 +947,20 @@ FLAC_API FLAC__bool FLAC__stream_encoder_set_loose_mid_side_stereo(FLAC__StreamE * and partial_tukey(3/0.3/0.5) are all valid. ov should be smaller than 1 * and can be negative. * + * subdivide_tukey(n) is a more efficient reimplementation of + * partial_tukey and punchout_tukey taken together, recycling as much data + * as possible. It combines all possible non-redundant partial_tukey(n) + * and punchout_tukey(n) up to the n specified. Specifying + * subdivide_tukey(3) is equivalent to specifying tukey, partial_tukey(2), + * partial_tukey(3) and punchout_tukey(3), specifying subdivide_tukey(5) + * equivalently adds partial_tukey(4), punchout_tukey(4), partial_tukey(5) + * and punchout_tukey(5). To be able to reuse data as much as possible, + * the tukey taper is taken equal for all windows, and the P specified is + * applied for the smallest used window. In other words, + * subdivide_tukey(2/0.5) results in a taper equal to that of tukey(0.25) + * and subdivide_tukey(5) in a taper equal to that of tukey(0.1). The + * default P for subdivide_tukey when none is specified is 0.5. + * * Example specifications are \c "blackman" or * \c "hann;triangle;tukey(0.5);tukey(0.25);tukey(0.125)" * @@ -963,6 +976,8 @@ FLAC_API FLAC__bool FLAC__stream_encoder_set_loose_mid_side_stereo(FLAC__StreamE * floating point array in which to store the window. Also note that the * values of P, STDDEV and ov are locale-specific, so if the comma * separator specified by the locale is a comma, a comma should be used. + * A locale-independent way is to specify using scientific notation, + * e.g. 5e-1 instad of 0.5 or 0,5. * * \default \c "tukey(0.5)" * \param encoder An encoder instance to set. diff --git a/src/flac/main.c b/src/flac/main.c index 2b9d8ca5..c6f79933 100644 --- a/src/flac/main.c +++ b/src/flac/main.c @@ -1297,11 +1297,11 @@ void show_help(void) 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 tukey(0.5) -A partial_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 tukey(0.5) -A partial_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 tukey(0.5) -A partial_tukey(2) -A punchout_tukey(3)\n"); + printf(" -A subdivide_tukey(3)\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"); @@ -1606,11 +1606,11 @@ void show_explain(void) printf(" -5, --compression-level-5 Synonymous with -l 8 -b 4096 -m -r 5\n"); printf(" -5 is the default setting\n"); printf(" -6, --compression-level-6 Synonymous with -l 8 -b 4096 -m -r 6\n"); - printf(" -A tukey(0.5) -A partial_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 tukey(0.5) -A partial_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 tukey(0.5) -A partial_tukey(2) -A punchout_tukey(3)\n"); + printf(" -A subdivide_tukey(3)\n"); printf(" -m, --mid-side Try mid-side coding for each frame\n"); printf(" (stereo only)\n"); printf(" -M, --adaptive-mid-side Adaptive mid-side coding for all frames\n"); |