Struct flac_bound::FlacEncoderConfig

source · [−]

#[repr(transparent)]
pub struct FlacEncoderConfig(_);

Expand description

Wrapper around a FLAC encoder for configuring the output settings.

FILE* constructors unsupported, Write+Seek constructors unsupportable due to https://github.com/rust-lang/rfcs/issues/2035

Implementations

source

impl FlacEncoderConfig

source

pub fn init_write<'out>(
self,
out: &'out mut WriteWrapper<'out>
) -> Result<FlacEncoder<'out>, FlacEncoderInitError>

Initialize the encoder instance to encode native FLAC streams.

This flavor of initialization sets up the encoder to encode to a native FLAC stream. I/O is performed into the specified stream.

The call to init_write() currently will also immediately write several times, once with the fLaC signature, and once for each encoded metadata block.

source

pub fn init_write_ogg<'out>(
self,
out: &'out mut WriteWrapper<'out>
) -> Result<FlacEncoder<'out>, FlacEncoderInitError>

Initialize the encoder instance to encode Ogg FLAC streams.

This flavor of initialization sets up the encoder to encode to a FLAC stream in an Ogg container. I/O is performed into the specified stream.

The call to init_write_ogg() currently will also immediately write several times, once with the fLaC signature, and once for each encoded metadata block.

source

pub fn init_file<P: AsRef<Path>>(
self,
filename: &P
) -> Result<FlacEncoder<'static>, FlacEncoderInitError>

Initialize the encoder instance to encode native FLAC files.

This flavor of initialization sets up the encoder to encode to a plain FLAC file. If POSIX fopen() semantics are not sufficient (for example, with Unicode filenames), you must use init_write() and provide the output stream.

The file will be opened with fopen().

source

pub fn init_file_ogg<P: AsRef<Path>>(
self,
filename: &P
) -> Result<FlacEncoder<'static>, FlacEncoderInitError>

Initialize the encoder instance to encode Ogg FLAC files.

This flavor of initialization sets up the encoder to encode to a plain FLAC file. If POSIX fopen() semantics are not sufficient (for example, with Unicode filenames), you must use init_write_ogg() and provide the output stream.

The file will be opened with fopen().

source

pub fn init_stdout(self) -> Result<FlacEncoder<'static>, FlacEncoderInitError>

Initialize the encoder instance to encode native FLAC files.

This flavor of initialization sets up the encoder to encode a plain FLAC file to stdout.

Note: a proper SEEKTABLE cannot be created when encoding to stdout since it is not seekable.

source

pub fn init_stdout_ogg(
self
) -> Result<FlacEncoder<'static>, FlacEncoderInitError>

Initialize the encoder instance to encode Ogg FLAC files.

This flavor of initialization sets up the encoder to encode a plain OGG FLAC file to stdout.

Note: a proper SEEKTABLE cannot be created when encoding to stdout since it is not seekable.

source

impl FlacEncoderConfig

source

pub fn ogg_serial_number(self, serial_number: c_long) -> FlacEncoderConfig

Set the serial number for the FLAC stream to use in the Ogg container.

Note:
This does not need to be set for native FLAC encoding.

It is recommended to set a serial number explicitly as the default of ‘0’ may collide with other streams.

Default: 0

source

pub fn verify(self, value: bool) -> FlacEncoderConfig

Set the “verify” flag.

If true, the encoder will verify its own encoded output by feeding it through an internal decoder and comparing the original signal against the decoded signal. If a mismatch occurs, the process call will return false. Note that this will slow the encoding process by the extra time required for decoding and comparison.

Default: false

source

pub fn streamable_subset(self, value: bool) -> FlacEncoderConfig

Set the Subset flag.

If true, the encoder will comply with the Subset and will check the settings during init_*() to see if all settings comply. If false, the settings may take advantage of the full range that the format allows.

Make sure you know what it entails before setting this to false.

Default: true

source

pub fn channels(self, value: u32) -> FlacEncoderConfig

Set the number of channels to be encoded.

Default: 2

source

pub fn bits_per_sample(self, value: u32) -> FlacEncoderConfig

Set the sample resolution of the input to be encoded.

Warning:
Do not feed the encoder data that is wider than the value you set here or you will generate an invalid stream.

Default: 16

source

pub fn sample_rate(self, value: u32) -> FlacEncoderConfig

Set the sample rate (in Hz) of the input to be encoded.

Default: 44100

source

pub fn compression_level(self, value: u32) -> FlacEncoderConfig

Set the compression level

The compression level is roughly proportional to the amount of effort the encoder expends to compress the file. A higher level usually means more computation but higher compression. The default level is suitable for most applications.

Currently the levels range from 0 (fastest, least compression) to 8 (slowest, most compression). A value larger than 8 will be treated as 8.

This function automatically calls the following other set functions with appropriate values, so the client does not need to unless it specifically wants to override them:

do_mid_side_stereo()
loose_mid_side_stereo()
apodization()
max_lpc_order()
qlp_coeff_precision()
do_qlp_coeff_prec_search()
do_escape_coding()
do_exhaustive_model_search()
min_residual_partition_order()
max_residual_partition_order()
rice_parameter_search_dist()

The actual values set for each level are:

level	do mid-side stereo	loose mid-side stereo	apodization	max lpc order	qlp coeff precision	qlp coeff prec search	escape coding	exhaustive model search	min residual partition order	max residual partition order	rice parameter search dist
0	false	false	tukey(0.5)		0	0	false	false	false	0	3	0
1	true	true	tukey(0.5)		0	0	false	false	false	0	3	0
2	true	false	tukey(0.5)		0	0	false	false	false	0	3	0
3	false	false	tukey(0.5)		6	0	false	false	false	0	4	0
4	true	true	tukey(0.5)		8	0	false	false	false	0	4	0
5	true	false	tukey(0.5)		8	0	false	false	false	0	5	0
6	true	false	tukey(0.5);partial_tukey(2)		8	0	false	false	false	0	6	0
7	true	false	tukey(0.5);partial_tukey(2)		12	0	false	false	false	0	6	0
8	true	false	tukey(0.5);partial_tukey(2);punchout_tukey(3)	12	0	false	false	false	0	6	0

Default: 5

source

pub fn blocksize(self, value: u32) -> FlacEncoderConfig

Set the blocksize to use while encoding.

The number of samples to use per frame. Use 0 to let the encoder estimate a blocksize; this is usually best.

Default: 0

source

pub fn do_mid_side_stereo(self, value: bool) -> FlacEncoderConfig

Set to true to enable mid-side encoding on stereo input.

The number of channels must be 2 for this to have any effect. Set to false to use only independent channel coding.

Default: true

source

pub fn loose_mid_side_stereo(self, value: bool) -> FlacEncoderConfig

Set to true to enable adaptive switching between mid-side and left-right encoding on stereo input.

Set to false to use exhaustive searching. Setting this to true requires do_mid_side_stereo() to also be set to true in order to have any effect.

Default: false

source

pub fn apodization(self, specification: &CStr) -> FlacEncoderConfig

Sets the apodization function(s) the encoder will use when windowing audio data for LPC analysis.

The specification is a plain ASCII string which specifies exactly which functions to use. There may be more than one (up to 32), separated by ';' characters. Some functions take one or more comma-separated arguments in parentheses.

The available functions are bartlett, bartlett_hann, blackman, blackman_harris_4term_92db, connes, flattop, gauss(STDDEV), hamming, hann, kaiser_bessel, nuttall, rectangle, triangle, tukey(P), partial_tukey(n[/ov[/P]]), punchout_tukey(n[/ov[/P]]), welch.

For gauss(STDDEV), STDDEV specifies the standard deviation (0<STDDEV<=0.5).

For tukey(P), P specifies the fraction of the window that is tapered (0<=P<=1). P=0 corresponds to rectangle and P=1 corresponds to hann.

Specifying partial_tukey or punchout_tukey works a little different. These do not specify a single apodization function, but a series of them with some overlap. partial_tukey specifies a series of small windows (all treated separately) while punchout_tukey specifies a series of windows that have a hole in them. In this way, the predictor is constructed with only a part of the block, which helps in case a block consists of dissimilar parts.

The three parameters that can be specified for the functions are n, ov and P. n is the number of functions to add, ov is the overlap of the windows in case of partial_tukey and the overlap in the gaps in case of punchout_tukey. P is the fraction of the window that is tapered, like with a regular tukey window. The function can be specified with only a number, a number and an overlap, or a number an overlap and a P, for example, partial_tukey(3), partial_tukey(3/0.3) and partial_tukey(3/0.3/0.5) are all valid. ov should be smaller than 1 and can be negative.

Example specifications are "blackman" or "hann;triangle;tukey(0.5);tukey(0.25);tukey(0.125)"

Any function that is specified erroneously is silently dropped. Up to 32 functions are kept, the rest are dropped. If the specification is empty the encoder defaults to "tukey(0.5)".

When more than one function is specified, then for every subframe the encoder will try each of them separately and choose the window that results in the smallest compressed subframe.

Note that each function specified causes the encoder to occupy a 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.

Default: "tukey(0.5)"

source

pub fn max_lpc_order(self, value: u32) -> FlacEncoderConfig

Set the maximum LPC order, or 0 to use only the fixed predictors.

Default: 8

source

pub fn qlp_coeff_precision(self, value: u32) -> FlacEncoderConfig

Set the precision, in bits, of the quantized linear predictor coefficients, or 0 to let the encoder select it based on the blocksize.

Note:
In the current implementation, qlp_coeff_precision + bits_per_sample must be less than 32.

Default: 0

source

pub fn do_qlp_coeff_prec_search(self, value: bool) -> FlacEncoderConfig

Set to false to use only the specified quantized linear predictor coefficient precision, or true to search neighboring precision values and use the best one.

Default: false

source

pub fn do_escape_coding(self, value: bool) -> FlacEncoderConfig

Deprecated. Setting this value has no effect.

Default: false

source

pub fn do_exhaustive_model_search(self, value: bool) -> FlacEncoderConfig

Set to false to let the encoder estimate the best model order based on the residual signal energy, or true to force the encoder to evaluate all order models and select the best.

Default: false

source

pub fn min_residual_partition_order(self, value: u32) -> FlacEncoderConfig

Set the minimum partition order to search when coding the residual.

This is used in tandem with max_residual_partition_order().

The partition order determines the context size in the residual.

The context size will be approximately blocksize / (2 ^ order).

Set both min and max values to 0 to force a single context, whose Rice parameter is based on the residual signal variance. Otherwise, set a min and max order, and the encoder will search all orders, using the mean of each context for its Rice parameter, and use the best.

Default: 0

source

pub fn max_residual_partition_order(self, value: u32) -> FlacEncoderConfig

Set the maximum partition order to search when coding the residual.

This is used in tandem with min_residual_partition_order().

The partition order determines the context size in the residual. The context size will be approximately blocksize / (2 ^ order).

Set both min and max values to 0 to force a single context, whose Rice parameter is based on the residual signal variance. Otherwise, set a min and max order, and the encoder will search all orders, using the mean of each context for its Rice parameter, and use the best.

Default: 5

source

pub fn rice_parameter_search_dist(self, value: u32) -> FlacEncoderConfig

Deprecated. Setting this value has no effect.

Default: 0

source

pub fn total_samples_estimate(self, value: u64) -> FlacEncoderConfig

Set an estimate of the total samples that will be encoded.

This is merely an estimate and may be set to 0 if unknown. This value will be written to the STREAMINFO block before encoding, and can remove the need for the caller to rewrite the value later if the value is known before encoding.

Default: 0