[][src]Struct flac_bound::FlacEncoderConfig

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

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

Methods

impl FlacEncoderConfig[src]

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

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.

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

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.

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

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().

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

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().

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

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.

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

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.

impl FlacEncoderConfig[src]

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

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

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

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

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

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

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

Set the number of channels to be encoded.

Default: 2

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

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

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

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

Default: 44100

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

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:

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

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

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

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

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

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

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

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

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)"

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

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

Default: 8

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

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

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

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

Deprecated. Setting this value has no effect.

Default: false

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

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

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

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

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

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

Deprecated. Setting this value has no effect.

Default: 0

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

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

Trait Implementations

impl Debug for FlacEncoderConfig[src]

impl Eq for FlacEncoderConfig[src]

impl Hash for FlacEncoderConfig[src]

impl Ord for FlacEncoderConfig[src]

impl PartialEq<FlacEncoderConfig> for FlacEncoderConfig[src]

impl PartialOrd<FlacEncoderConfig> for FlacEncoderConfig[src]

impl StructuralEq for FlacEncoderConfig[src]

impl StructuralPartialEq for FlacEncoderConfig[src]

Auto Trait Implementations

impl RefUnwindSafe for FlacEncoderConfig

impl !Send for FlacEncoderConfig

impl !Sync for FlacEncoderConfig

impl Unpin for FlacEncoderConfig

impl UnwindSafe for FlacEncoderConfig

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.