Flacenc Rs

https://github.com/yotarok/flacenc-rs
Admin
Flacenc Rs is a pure-Rust library and companion CLI for embedding a customizable FLAC (Free Lossless...
Tokens:31,523
Snippets:532
Trust Score:7
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install flacenc-bin with nightly Rust

Source: https://github.com/yotarok/flacenc-rs/blob/main/flacenc-bin/README.md

Recommended installation command using the nightly Rust toolchain and SIMD features.

```bash
cargo +nightly install flacenc-bin --features "simd-nightly"
```

--------------------------------

### FrameBuf Initialization Example

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/source.md

Example of creating a FrameBuf and accessing its channel and size properties.

```rust
use flacenc::source::FrameBuf;

let fb = FrameBuf::with_size(2, 4096)?;
println!("Channels: {}", fb.channels());
println!("Size: {}", fb.size());
```

--------------------------------

### Install flacenc-bin with stable Rust

Source: https://github.com/yotarok/flacenc-rs/blob/main/flacenc-bin/README.md

Installation command for users on the stable Rust channel.

```bash
cargo install flacenc-bin
```

--------------------------------

### Using MemSource for Audio Input

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/source.md

Example demonstrating how to initialize a MemSource and query its properties.

```rust
use flacenc::source::{Source, MemSource};

let samples = vec![0i32; 4096 * 2]; // stereo
let mut source = MemSource::from_samples(&samples, 2, 16, 44100);

println!("Channels: {}", source.channels());
println!("Sample rate: {}", source.sample_rate());
println!("Bits per sample: {}", source.bits_per_sample());
```

--------------------------------

### write Example

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/bitsink.md

Writes all bits of an unsigned integer to the sink.

```rust
use flacenc::bitsink::{ByteSink, BitSink};

let mut sink = ByteSink::new();
sink.write(0x55u16)?;  // Writes all 16 bits
```

--------------------------------

### Verify configuration example

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/errors.md

Demonstrates validating an Encoder configuration and handling the resulting VerifyError.

```rust
use flacenc::config::Encoder;
use flacenc::error::Verify;

let mut config = Encoder::default();
config.block_size = 16;  // Invalid: too small

match config.into_verified() {
    Ok(verified) => println!("Config OK"),
    Err((original, err)) => {
        eprintln!("Error at {}: {}", err.path(), err);
        // Prints: "Error at config.block_size: verification error: `config.block_size` is not valid. reason: must be >= 32"
    }
}
```

--------------------------------

### align_to_byte Example

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/bitsink.md

Demonstrates padding the sink with zeros until it is byte-aligned.

```rust
use flacenc::bitsink::{ByteSink, BitSink};

let mut sink = ByteSink::new();
sink.write_lsbs(0xFFu8, 3)?;
let padding = sink.align_to_byte()?;
assert_eq!(padding, 5);
```

--------------------------------

### Qlpc Usage Examples

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/config.md

Demonstrates initializing Qlpc with default values and modifying fields for a custom configuration.

```rust
use flacenc::config::{Qlpc, Window};

// Default configuration
let qlpc = Qlpc::default();
assert_eq!(qlpc.lpc_order, 10);

// Custom configuration with higher order
let mut qlpc = Qlpc::default();
qlpc.lpc_order = 16;
qlpc.window = Window::Rectangle;
```

--------------------------------

### Encoder configuration example

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/config.md

Demonstrates how to initialize an Encoder with default settings, modify specific fields, and verify the configuration.

```rust
use flacenc::config::Encoder;
use flacenc::error::Verify;

let mut config = Encoder::default();
config.block_size = 2048;
config.multithread = false;

let verified = config.into_verified()?;
```

--------------------------------

### ByteSink instantiation example

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/bitsink.md

Creates a new empty ByteSink instance.

```rust
use flacenc::bitsink::ByteSink;

let sink = ByteSink::new();
println!("Created sink");
```

--------------------------------

### Create MemSource from Samples

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/source.md

Example usage of MemSource::from_samples to initialize a source with stereo audio data.

```rust
use flacenc::source::MemSource;

let stereo = vec![0i32, 0, 1, -1, 2, -2];
let source = MemSource::from_samples(&stereo, 2, 16, 44100);
```

--------------------------------

### OutputError Usage Example

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/bitsink.md

Example showing how to instantiate an OutputError with a ByteSink.

```rust
use flacenc::error::OutputError;
use flacenc::bitsink::ByteSink;

let err: OutputError<ByteSink> = OutputError::Range(/* ... */);
```

--------------------------------

### Stream usage example

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/component.md

Demonstrates initializing a new Stream and accessing its frame count and metadata.

```rust
use flacenc::component::Stream;

let mut stream = Stream::new(44100, 2, 16)?;
println!("Frames: {}", stream.frame_count());
println!("StreamInfo: {:?}", stream.stream_info());
```

--------------------------------

### Creating and configuring a SourceError

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/types.md

Example showing how to create a SourceError with a specific reason and associate a file path with it.

```rust
use flacenc::error::{SourceError, SourceErrorReason};

let err = SourceError::by_reason(SourceErrorReason::Open);
let err = err.set_path("audio.wav");

println!("{}", err);  // "error occurred while reading audio.wav. reason: cannot open file."
```

--------------------------------

### FrameBuf::resize Usage Example

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/source.md

Demonstrates resizing a FrameBuf, which triggers a reallocation.

```rust
let mut fb = FrameBuf::with_size(2, 1024)?;
fb.resize(2048);
assert_eq!(fb.size(), 2048);
```

--------------------------------

### ByteSink usage example

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/bitsink.md

Demonstrates writing bits and bytes to a ByteSink and retrieving the results.

```rust
use flacenc::bitsink::{ByteSink, BitSink};

let mut sink = ByteSink::new();
sink.write_msbs(0xF0u8, 3)?;
sink.align_to_byte()?;
sink.write(0x55u8)?;

println!("Bytes: {:?}", sink.as_slice());
println!("Bits: {}", sink.to_bitstring());
println!("Total bits: {}", sink.len());
```

--------------------------------

### write_zeros Example

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/bitsink.md

Writes a specified number of zero bits to the sink.

```rust
use flacenc::bitsink::{ByteSink, BitSink};

let mut sink = ByteSink::new();
sink.write_zeros(16)?;  // Write 16 zero bits
```

--------------------------------

### SourceError format

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/errors.md

Example of a source error message occurring during file input.

```text
error occurred while reading input.wav. reason: cannot open file.
```

--------------------------------

### MemSink usage example

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/bitsink.md

Demonstrates using a MemSink with u64 storage to write bits and aligned bytes.

```rust
use flacenc::bitsink::{MemSink, BitSink};

let mut sink = MemSink::<u64>::new();
sink.write_msbs(0xF0u8, 3)?;
sink.write_bytes_aligned(&[0xAA, 0xF0])?;

println!("Bytes: {:?}", sink.as_slice());
```

--------------------------------

### Verify Trait Implementation

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/modules.md

Example of validating and wrapping a configuration object using the Verify trait.

```rust
use flacenc::error::Verify;

let config = Encoder::default();
let verified = config.into_verified()?;  // Validates and wraps
```

--------------------------------

### Implement a basic FLAC encoder

Source: https://github.com/yotarok/flacenc-rs/blob/main/README.md

Demonstrates the standard workflow for encoding interleaved audio samples into a FLAC stream, including configuration setup and writing the resulting data to a sink.

```rust
use flacenc::component::BitRepr;
use flacenc::error::Verify;

let samples: &[i32] = &[0i32; 4096]; // replace this with real samples.

let (channels, bits_per_sample, sample_rate) = (2, 16, 44100);
let config = flacenc::config::Encoder::default().into_verified().expect(
  "Config data error."
);
let source = flacenc::source::MemSource::from_samples(
    samples, channels, bits_per_sample, sample_rate);
let flac_stream = flacenc::encode_with_fixed_block_size(
    &config, source, config.block_size
).expect("Encode failed.");

// `Stream` implements `BitRepr` so you can obtain the encoded stream via
// `ByteSink` struct that implements `BitSink`.
let mut sink = flacenc::bitsink::ByteSink::new();
flac_stream.write(&mut sink);

// Then, e.g. you can write it to a file.
std::fs::write("/dev/null", sink.as_slice());

// or you can write only a specific frame.
let mut sink = flacenc::bitsink::ByteSink::new();
flac_stream.frame(0).unwrap().write(&mut sink);
```

--------------------------------

### Encoding a complete FLAC stream

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/encoding.md

Example demonstrating how to encode a signal using a memory source and default encoder configuration.

```rust
use flacenc::config;
use flacenc::error::Verify;
use flacenc::source::MemSource;

let signal = vec![0i32; 8000 * 2]; // 2 channels, 8000 samples each
let source = MemSource::from_samples(&signal, 2, 16, 44100);

let config = config::Encoder::default().into_verified()?;
let stream = flacenc::encode_with_fixed_block_size(&config, source, 4096)?;

println!("Encoded {} frames", stream.frame_count());
```

--------------------------------

### Verify MSRV

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/README.md

Installs the required Rust version and checks the project against the MSRV of 1.83.0.

```bash
rustup install 1.83.0
cargo +1.83.0 check --no-default-features
```

--------------------------------

### write_msbs Example

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/bitsink.md

Writes the specified number of most-significant bits from an unsigned integer.

```rust
use flacenc::bitsink::{ByteSink, BitSink};

let mut sink = ByteSink::new();
sink.write_msbs(0xF0u8, 3)?;  // Writes bits 111 (MSBs of 0xF0)
```

--------------------------------

### Encoding a single FLAC frame

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/encoding.md

Example showing how to manually fill a frame buffer and encode it as a single FLAC frame.

```rust
use flacenc::config;
use flacenc::component::StreamInfo;
use flacenc::error::Verify;
use flacenc::source::{FrameBuf, MemSource, Source};

let signal = vec![0i32; 4096 * 2];
let mut source = MemSource::from_samples(&signal, 2, 16, 44100);

let mut fb = FrameBuf::with_size(2, 4096)?;
source.read_samples(4096, &mut fb)?;

let stream_info = StreamInfo::new(44100, 2, 16)?;
let config = config::Encoder::default().into_verified()?;

let frame = flacenc::encode_fixed_size_frame(&config, &fb, 0, &stream_info)?;
println!("Frame encoded: {} bytes", frame.count_bits() / 8);
```

--------------------------------

### Typical Usage Flow for flacenc-rs

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/modules.md

This flow demonstrates the sequential steps required to encode audio data, starting from configuration creation to writing the final FLAC file.

```text
┌─────────────────────────────────────────────────┐
│ 1. Create Configuration                         │
│    config = Encoder::default()                  │
│    verified = config.into_verified()?           │
└──────────────────┬──────────────────────────────┘

┌──────────────────┴──────────────────────────────┐
│ 2. Prepare Audio Source                         │
│    source = MemSource::from_samples(&data)      │
│    or implement custom Source trait             │
└──────────────────┬──────────────────────────────┘

┌──────────────────┴──────────────────────────────┐
│ 3. Encode Stream                                │
│    stream = encode_with_fixed_block_size(       │
│        &verified, source, block_size)?          │
└──────────────────┬──────────────────────────────┘

┌──────────────────┴──────────────────────────────┐
│ 4. Serialize to Output                          │
│    let mut sink = ByteSink::new()               │
│    stream.write(&mut sink)?                     │
│    bytes = sink.as_slice()                      │
└──────────────────┴──────────────────────────────┘

┌──────────────────┴──────────────────────────────┐
│ 5. Write to File                                │
│    std::fs::write("output.flac", bytes)?        │
└─────────────────────────────────────────────────┘
```

--------------------------------

### VerifyError usage example

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/types.md

Demonstrates creating a VerifyError, adding context with within, and accessing the error path.

```rust
use flacenc::error::VerifyError;

let err = VerifyError::new("block_size", "must be >= 32");
let err = err.within("config");

println!("{}", err.path());  // "config.block_size"
println!("{}", err);         // "verification error: `config.block_size` is not valid. reason: must be >= 32"
```

--------------------------------

### BitRepr Usage Example

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/component.md

Demonstrates how to use the BitRepr trait to write an encoded stream to a ByteSink.

```rust
use flacenc::component::BitRepr;
use flacenc::bitsink::{ByteSink, BitSink};

let stream = /* encoded stream */;
let mut sink = ByteSink::new();
stream.write(&mut sink)?;
let bytes = sink.as_slice();
```

--------------------------------

### Fill Trait Usage Example

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/source.md

Demonstrates filling a FrameBuf using either interleaved i32 samples or little-endian byte streams.

```rust
use flacenc::source::{Fill, FrameBuf};

let mut fb = FrameBuf::with_size(2, 1024)?;

// Interleaved i32 samples: [L0, R0, L1, R1, ...]
fb.fill_interleaved(&[100, 200, 300, 400])?;

// Or from little-endian bytes
let mut fb2 = FrameBuf::with_size(2, 1024)?;
fb2.fill_le_bytes(&[0x12, 0x34, 0x56, 0x78], 2)?;
```

--------------------------------

### write_twoc Example

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/bitsink.md

Writes a signed integer using two's complement format for a specified number of bits.

```rust
use flacenc::bitsink::{ByteSink, BitSink};

let mut sink = ByteSink::new();
sink.write_msbs(0xF0u8, 3)?;
sink.write_twoc(-3i32, 5)?;  // Two's complement of -3 in 5 bits
```

--------------------------------

### EncodeError::Source format

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/errors.md

Example of a source error message indicating an I/O connection reset.

```text
error occurred while reading <unknown>. reason: I/O error: connection reset by peer.
```

--------------------------------

### EncodeError Usage Example

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/errors.md

Demonstrates encoding with fixed block size and handling potential EncodeError results.

```rust
use flacenc::encode_with_fixed_block_size;
use flacenc::config;
use flacenc::error::Verify;
use flacenc::source::MemSource;

let signal = vec![0i32; 1000];
let config = config::Encoder::default().into_verified()?;
let source = MemSource::from_samples(&signal, 1, 16, 44100);

match encode_with_fixed_block_size(&config, source, 256) {
    Ok(stream) => println!("Encoded {} frames", stream.frame_count()),
    Err(EncodeError::Source(e)) => eprintln!("Source error: {}", e),
    Err(EncodeError::Config(e)) => eprintln!("Config error: {}", e),
}
```

--------------------------------

### FrameBuf::filled_size Usage Example

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/source.md

Demonstrates checking the number of samples currently in the buffer before and after filling.

```rust
use flacenc::source::{FrameBuf, Fill};

let mut fb = FrameBuf::with_size(2, 1024)?;
assert_eq!(fb.filled_size(), 0);

fb.fill_interleaved(&[1, 2, 3, 4])?;
assert_eq!(fb.filled_size(), 2); // 4 samples / 2 channels
```

--------------------------------

### EncodeError::Config format

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/errors.md

Example of a configuration error message indicating an invalid block size.

```text
verification error: `config.block_size` is not valid. reason: must be >= 32
```

--------------------------------

### Basic Encoding Workflow

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/README.md

Demonstrates the standard process of preparing audio samples, configuring the encoder, encoding the stream, and serializing the output to a file.

```rust
use flacenc::config::Encoder;
use flacenc::error::Verify;
use flacenc::source::MemSource;
use flacenc::component::BitRepr;
use flacenc::bitsink::{ByteSink, BitSink};

// Prepare audio
let samples: Vec<i32> = vec![/* 16-bit samples */];
let source = MemSource::from_samples(&samples, 2, 16, 44100);

// Configure encoder
let config = Encoder::default().into_verified()?;

// Encode
let stream = flacenc::encode_with_fixed_block_size(&config, source, 4096)?;

// Serialize
let mut sink = ByteSink::new();
stream.write(&mut sink)?;

// Write to file
std::fs::write("output.flac", sink.as_slice())?;
```

--------------------------------

### Build and run benchmark container with podman

Source: https://github.com/yotarok/flacenc-rs/blob/main/bench_runner/README.md

Commands to build the container image for the linux/arm64 platform and execute it interactively.

```bash
podman build --platform linux/arm64  .
podman run --rm -it [Digest]
```

--------------------------------

### Build with all features

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/README.md

Builds the project with all available features enabled in release mode.

```bash
cargo build --all-features --release
```

--------------------------------

### write_lsbs Example

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/bitsink.md

Writes the specified number of least-significant bits from an unsigned integer.

```rust
use flacenc::bitsink::{ByteSink, BitSink};

let mut sink = ByteSink::new();
sink.write_lsbs(0x0Fu8, 3)?;  // Writes bits 111 (LSBs of 0x0F)
```

--------------------------------

### VerifyError format

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/errors.md

Example of a verification error message indicating an invalid LPC order.

```text
verification error: `subframe_coding.qlpc.lpc_order` is not valid. reason: must be <= 24
```

--------------------------------

### Build check

Source: https://github.com/yotarok/flacenc-rs/blob/main/how_to_make_a_release.md

Perform a release build for both the main project and the flacenc-bin component.

```bash
cargo build --release
cd flacenc-bin
cargo build --release
```

--------------------------------

### Pattern Matching EncodeError

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/errors.md

Example of handling EncodeError variants using pattern matching.

```rust
use flacenc::error::EncodeError;

match result {
    Ok(stream) => { /* success */ },
    Err(EncodeError::Source(e)) => eprintln!("Read error: {}", e),
    Err(EncodeError::Config(e)) => eprintln!("Config error: {}", e),
}
```

--------------------------------

### Implementing a Custom Audio Source

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/README.md

Shows how to implement the Source trait to create a custom audio input source, such as reading from a file.

```rust
use flacenc::source::{Source, Fill, SourceError};
use std::io::Read;

struct FileSource<R: Read> {
    reader: R,
    channels: usize,
    bits_per_sample: usize,
    sample_rate: usize,
}

impl<R: Read> Source for FileSource<R> {
    fn channels(&self) -> usize { self.channels }
    fn bits_per_sample(&self) -> usize { self.bits_per_sample }
    fn sample_rate(&self) -> usize { self.sample_rate }
    
    fn read_samples<F: Fill>(
        &mut self,
        block_size: usize,
        dest: &mut F,
    ) -> Result<usize, SourceError> {
        // Read from file, convert, fill buffer
        // Return number of samples read
        todo!()
    }
}
```

--------------------------------

### Create new Context

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/source.md

Initializes a new Context for a specific audio format. Panics if bits_per_sample exceeds 32.

```rust
use flacenc::source::Context;

let ctx = Context::new(16, 2);
```

--------------------------------

### Context::new

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/source.md

Creates a new Context instance for a specified audio format.

```APIDOC
## Context::new

### Description
Creates a new Context for the given audio format.

### Signature
`pub fn new(bits_per_sample: usize, channels: usize) -> Self`

### Panics
Panics if `bits_per_sample > 32`.
```

--------------------------------

### MetadataBlockData enum

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/types.md

Enum representing different types of metadata blocks, starting with StreamInfo.

```rust
pub enum MetadataBlockData {
    StreamInfo(StreamInfo),
    // ... other blocks
}
```

--------------------------------

### Loading Configuration from TOML

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/README.md

Demonstrates initializing an Encoder configuration from a TOML string using the toml crate.

```rust
use flacenc::config::Encoder;
use flacenc::error::Verify;

let toml_str = r#"
block_size = 8192
multithread = true

[subframe_coding.qlpc]
lpc_order = 12

[subframe_coding.fixed.order_sel]
type = "BitCount"
"#;

let config: Encoder = toml::from_str(toml_str)?;
let verified = config.into_verified()?;
```

--------------------------------

### Default Configuration (Balanced Compression)

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/configuration.md

Uses all default settings, resulting in a 4096 block size, enabled stereo/subframe options, fixed LPC with ApproxEnt order selection, and QLPC with order 10 and Tukey window.

```toml
# Uses all defaults
```

--------------------------------

### Loading Configuration from File

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/configuration.md

Demonstrates how to read a TOML file from disk and deserialize it into an Encoder configuration object in Rust.

```rust
use flacenc::config::Encoder;
use flacenc::error::Verify;
use std::fs;

let toml_content = fs::read_to_string("config.toml")?;
let config: Encoder = toml::from_str(&toml_content)?;
let verified = config.into_verified()?;
```

--------------------------------

### Build with minimal features

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/README.md

Builds the project with minimal features enabled in release mode.

```bash
cargo build --no-default-features --release
```

--------------------------------

### Check documentation

Source: https://github.com/yotarok/flacenc-rs/blob/main/how_to_make_a_release.md

Verify that there are no documentation errors.

```bash
cargo doc
```

--------------------------------

### Run tests

Source: https://github.com/yotarok/flacenc-rs/blob/main/how_to_make_a_release.md

Execute clippy and integration tests using makers.

```bash
makers clippy
makers integration
```

--------------------------------

### Window Variant Usage

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/config.md

Shows how to instantiate Rectangle and Tukey window variants.

```rust
use flacenc::config::Window;

// Rectangular window
let win = Window::Rectangle;

// Tukey window with 0.5 taper
let win = Window::Tukey { alpha: 0.5 };
```

--------------------------------

### Publish flacenc-bin

Source: https://github.com/yotarok/flacenc-rs/blob/main/how_to_make_a_release.md

Package, verify, and publish the flacenc-bin crate.

```bash
cd flacenc-bin
cargo package
cd target/package/flacenc-bin-0.2.7
cargo build && cargo test
```

```bash
cargo publish --dry-run
cargo publish
```

--------------------------------

### Run tests

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/README.md

Executes the test suite. The second command runs tests with all features enabled.

```bash
cargo test
cargo test --all-features
```

--------------------------------

### Publish flacenc

Source: https://github.com/yotarok/flacenc-rs/blob/main/how_to_make_a_release.md

Package, verify, and publish the flacenc crate.

```bash
cargo package
cd target/package/flacenc-0.5.1
cargo build && cargo test
```

```bash
cargo publish --dry-run
cargo publish
```

--------------------------------

### Encoder configuration verification methods

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/configuration.md

Demonstrates three ways to verify encoder configuration: automatic verification, manual verification, and unsafe assumption.

```rust
// Type 1: Automatic verification
let config = Encoder::default();
let verified = config.into_verified()?;  // Returns Err if invalid
if let Err((original, err)) = verified {
    eprintln!("Config error: {}", err);
}

// Type 2: Manual verification
let config = Encoder::default();
if let Err(err) = config.verify() {
    eprintln!("Config error: {}", err);
}

// Type 3: Unsafe assumption
let config = Encoder::default();
let verified = unsafe { config.assume_verified() };  // Caller guarantees validity
```

--------------------------------

### Fast Real-Time Configuration

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/configuration.md

Optimized for speed with a smaller block size of 1024 and multithreading enabled with 4 workers.

```toml
block_size = 1024
multithread = true
workers = 4

[subframe_coding]
use_constant = true
use_fixed = true
use_lpc = false

[subframe_coding.fixed]
max_order = 2

[subframe_coding.fixed.order_sel]
type = "ApproxEnt"
partitions = 8

[subframe_coding.prc]
max_parameter = 14
```

--------------------------------

### Project File Structure

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/INDEX.md

The directory layout of the documentation files.

```text
/output/
├── README.md                          # Start here
├── INDEX.md                           # This file
├── types.md                           # Type definitions
├── configuration.md                   # Configuration reference
├── errors.md                          # Error reference
└── api-reference/
    ├── modules.md                     # Module overview
    ├── encoding.md                    # Encoding functions
    ├── config.md                      # Configuration types
    ├── source.md                      # Source/input API
    ├── component.md                   # Output component types
    └── bitsink.md                     # Bitstream output API
```

--------------------------------

### Prc Default Usage

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/config.md

Demonstrates initializing the Prc configuration with default values.

```rust
use flacenc::config::Prc;

let prc = Prc::default();
assert_eq!(prc.max_parameter, 30);
```

--------------------------------

### Configure and verify Encoder

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/README.md

Construct an Encoder, modify settings if necessary, and call into_verified() to ensure the configuration is valid before encoding.

```rust
let config = Encoder::default();
// Modify as needed:
// config.block_size = 8192;
// config.subframe_coding.qlpc.lpc_order = 12;

let verified = config.into_verified()?;  // Validates settings
```

--------------------------------

### Encoding to bytes using ByteSink

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/modules.md

Demonstrates how to use ByteSink to encode a stream and write the resulting bytes to a file.

```rust
use flacenc::component::BitRepr;
use flacenc::bitsink::{ByteSink, BitSink};

let stream = /* encoded stream */;
let mut sink = ByteSink::new();
stream.write(&mut sink)?;  // Encodes to bytes

let bytes: &[u8] = sink.as_slice();
std::fs::write("output.flac", bytes)?;
```

--------------------------------

### Generate default configuration file

Source: https://github.com/yotarok/flacenc-rs/blob/main/flacenc-bin/README.md

Generates a default configuration file for the encoder.

```bash
flacenc --output output.flac --dump-config config.toml input.wav
```

--------------------------------

### OrderSel Variant Usage

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/config.md

Demonstrates selecting between BitCount and ApproxEnt order selection methods.

```rust
use flacenc::config::OrderSel;

// Accurate but slower method
let sel = OrderSel::BitCount;

// Fast approximation with 32 partitions
let sel = OrderSel::ApproxEnt { partitions: 32 };
```

--------------------------------

### Pattern 1: Into Verified Conversion

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/errors.md

Demonstrates converting an encoder configuration to a verified state while handling potential verification errors.

```rust
use flacenc::config::Encoder;
use flacenc::error::Verify;

let config = Encoder::default();
let verified = config.into_verified()
    .map_err(|(original, err)| {
        eprintln!("Config verification failed: {}", err);
        // Can still access original config if needed
        original
    })?;
```

--------------------------------

### Pattern 3: Context Chaining

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/errors.md

Illustrates wrapping file I/O errors with specific SourceError reasons and paths.

```rust
use flacenc::error::SourceError;

fn open_source(path: &str) -> Result<Source, SourceError> {
    let file = std::fs::File::open(path)
        .map_err(|_| SourceError::by_reason(SourceErrorReason::Open)
            .set_path(path))?;
    // ...
    Ok(source)
}
```

--------------------------------

### Encoder::verify()

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/config.md

Validates the current encoder configuration settings.

```APIDOC
## Encoder::verify()

### Description
Validates that the block_size is within the allowed range (32..=32767) and that all nested configurations are valid.

### Signature
`fn verify(&self) -> Result<(), VerifyError>`
```

--------------------------------

### Run remote benchmark

Source: https://github.com/yotarok/flacenc-rs/blob/main/how_to_make_a_release.md

Execute the remote benchmark script.

```bash
cd bench_runner
bash ./gce_run_job.sh
```

--------------------------------

### Minimum Resources Configuration

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/configuration.md

A single-threaded configuration using a block size of 4096 and limited subframe coding options.

```toml
block_size = 4096
multithread = false

[subframe_coding]
use_constant = true
use_fixed = true
use_lpc = false

[subframe_coding.fixed]
max_order = 2
```

--------------------------------

### MemSource::from_samples Signature

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/source.md

The function signature for creating a MemSource from an i32 sample array.

```rust
pub fn from_samples(
    samples: &[i32],
    channels: usize,
    bits_per_sample: usize,
    sample_rate: usize,
) -> Self
```

--------------------------------

### Project directory layout

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/README.md

Visual representation of the flacenc-rs project structure.

```text
flacenc-rs/
├── src/
│   ├── lib.rs              # Crate root
│   ├── coding.rs           # Encoding functions
│   ├── config.rs           # Configuration types
│   ├── source.rs           # Input handling
│   ├── bitsink.rs          # Output interface
│   ├── error.rs            # Error types
│   ├── component/          # FLAC components
│   │   ├── datatype.rs     # Component definitions
│   │   ├── bitrepr.rs      # Bitstream serialization
│   │   ├── verify.rs       # Verification
│   │   ├── decode.rs       # Decoder (if decode feature)
│   │   └── parser.rs       # Parser (if decode feature)
│   ├── constant.rs         # Constants and limits
│   ├── lpc.rs              # LPC computation
│   ├── rice.rs             # Rice coding
│   └── ...
├── flacenc-bin/            # CLI tool (separate crate)
└── Cargo.toml
```

--------------------------------

### Encode with custom configuration

Source: https://github.com/yotarok/flacenc-rs/blob/main/flacenc-bin/README.md

Uses a previously generated and edited configuration file to encode the input.

```bash
flacenc --output output.flac --config config.toml input.wav
```

--------------------------------

### Login to crates.io

Source: https://github.com/yotarok/flacenc-rs/blob/main/how_to_make_a_release.md

Authenticate with crates.io using an API key.

```bash
cargo login
# Paste your API key
```

--------------------------------

### Crate-Level Exports

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/modules.md

Main entry points and module structure for the flacenc crate.

```rust
pub use coding::encode_fixed_size_frame;
pub use coding::encode_with_fixed_block_size;

pub mod bitsink;
pub mod component;
pub mod config;
pub mod constant;
pub mod error;
pub mod source;
```

--------------------------------

### Programmatic Configuration

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/configuration.md

Shows how to instantiate and modify an Encoder configuration object directly within Rust code.

```rust
use flacenc::config::*;
use flacenc::error::Verify;

let mut config = Encoder::default();
config.block_size = 8192;
config.multithread = true;
config.workers = Some(std::num::NonZeroUsize::new(4).unwrap());

config.stereo_coding.use_midside = true;
config.subframe_coding.qlpc.lpc_order = 12;

let verified = config.into_verified()?;
```

--------------------------------

### Standard Rust error handling integration

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/errors.md

Demonstrates using error types with the ? operator, error wrapping, and standard error reporting.

```rust
// Works with ? operator
let verified = config.into_verified()?;

// Works with error wrapping
.map_err(|e| Box::new(e) as Box<dyn Error>)?;

// Works with error reporting
eprintln!("{:?}", error);
```

--------------------------------

### Verbatim::from_samples

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/component.md

Creates a Verbatim subframe from raw sample data.

```APIDOC
## pub fn from_samples(samples: &[i32], bits_per_sample: u8) -> Self

### Description
Creates a Verbatim subframe containing raw, uncompressed samples.

### Parameters
- **samples** (&[i32]) - The raw sample data.
- **bits_per_sample** (u8) - The bit depth of the samples.
```

--------------------------------

### Verification Flow Diagram

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/INDEX.md

The required sequence for configuration validation using Verified<T>.

```text
Create Config → Verify → Use Verified<T>
```

--------------------------------

### Run fuzz test

Source: https://github.com/yotarok/flacenc-rs/blob/main/how_to_make_a_release.md

Run the frame_encode fuzz test using the nightly toolchain.

```bash
cd fuzz
cargo +nightly fuzz run frame_encode
```

--------------------------------

### Encode audio with fixed block size

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/README.md

Demonstrates the basic usage of the flacenc library to encode a stereo audio stream using a fixed block size. Requires a MemSource initialized with audio samples and a verified Encoder configuration.

```rust
use flacenc::config::Encoder;
use flacenc::error::Verify;
use flacenc::source::MemSource;

let samples = vec![0i32; 4096 * 2]; // stereo
let source = MemSource::from_samples(&samples, 2, 16, 44100);
let config = Encoder::default().into_verified()?;
let stream = flacenc::encode_with_fixed_block_size(&config, source, 4096)?;
```

--------------------------------

### Check version numbers

Source: https://github.com/yotarok/flacenc-rs/blob/main/how_to_make_a_release.md

Use ack to search for the previous version number across the project, excluding target and .venv directories.

```bash
ack --ignore-dir=target --ignore-dir=.venv '0\.5\.0'
```

--------------------------------

### FrameBuf::with_size

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/source.md

Creates a new FrameBuf instance with the specified number of channels and frame size.

```APIDOC
## FrameBuf::with_size

### Description
Creates a new FrameBuf with specified dimensions.

### Signature
`pub fn with_size(channels: usize, size: usize) -> Result<Self, VerifyError>`

### Parameters
- **channels** (usize) - Required - Number of channels (1..=8)
- **size** (usize) - Required - Frame size in samples (32..=32767)

### Returns
- **FrameBuf** - A new instance of FrameBuf
- **VerifyError** - Returned if parameters are out of range
```

--------------------------------

### MemSource::from_samples

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/source.md

Creates a new MemSource instance from an array of i32 samples, specifying channel count, bit depth, and sample rate.

```APIDOC
## MemSource::from_samples

### Description
Creates a MemSource from an i32 sample array.

### Signature
`pub fn from_samples(samples: &[i32], channels: usize, bits_per_sample: usize, sample_rate: usize) -> Self`

### Parameters
- **samples** (&[i32]) - Required - Interleaved samples
- **channels** (usize) - Required - Number of channels
- **bits_per_sample** (usize) - Required - Resolution (8..=24)
- **sample_rate** (usize) - Required - Sample rate in Hz

### Example
```rust
use flacenc::source::MemSource;

let stereo = vec![0i32, 0, 1, -1, 2, -2];
let source = MemSource::from_samples(&stereo, 2, 16, 44100);
```
```

--------------------------------

### Enable SIMD features for nightly toolchain

Source: https://github.com/yotarok/flacenc-rs/blob/main/README.md

Use this configuration in Cargo.toml if you are using a nightly toolchain and wish to enable SIMD features for improved performance.

```toml
flacenc = { version = "0.5.1", features = ["simd-nightly"] }
```

--------------------------------

### Verbatim Method Signatures

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/component.md

Methods for creating Verbatim subframes from samples and calculating encoded size from metadata.

```rust
pub fn from_samples(samples: &[i32], bits_per_sample: u8) -> Self
```

```rust
pub fn count_bits_from_metadata(
    sample_count: usize,
    bits_per_sample: usize,
) -> usize
```

--------------------------------

### Pattern 4: Configuration Validation

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/errors.md

Shows a function that applies user settings to a default encoder and returns a verified configuration.

```rust
use flacenc::config::Encoder;
use flacenc::error::VerifyError;

fn build_config(user_settings: UserSettings) -> Result<Verified<Encoder>, VerifyError> {
    let mut config = Encoder::default();
    config.block_size = user_settings.block_size;
    config.into_verified().map_err(|(_cfg, err)| err)
}
```

--------------------------------

### Generate ChangeLog prompt

Source: https://github.com/yotarok/flacenc-rs/blob/main/how_to_make_a_release.md

A prompt template for use with codex to update the CHANGELOG.md file.

```text
Update "[CHANGELOG.md](http://changelog.md/)" for release version 0.5.1 (flacenc-bin: 0.2.7) with the latest updates since the previous release. Please check the git history to describe the changes.
```

--------------------------------

### Window Configuration Enum

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/config.md

Defines the analysis window function options for LPC estimation.

```rust
#[derive(Clone, Debug, PartialEq, PartialOrd)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "serde", serde(tag = "type"))]
#[non_exhaustive]
pub enum Window {
    Rectangle,
    Tukey { alpha: f32 },
}
```

--------------------------------

### Retrieve path with path

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/errors.md

Returns the full dot-separated path to the component where the error occurred.

```rust
let err = VerifyError::new("alpha", "must be <= 1.0")
    .within("Tukey")
    .within("window");
println!("{}", err.path());  // "window.Tukey.alpha"
```

--------------------------------

### Tag release branch

Source: https://github.com/yotarok/flacenc-rs/blob/main/how_to_make_a_release.md

Apply git tags for the released versions.

```bash
git tag flacenc-v0.5.1
git tag flacenc-bin-0.2.7
```

--------------------------------

### Qlpc Configuration Struct

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/config.md

The Qlpc struct defines parameters for quantized linear predictive coding.

```rust
#[derive(Clone, Debug)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "serde", serde(default))]
#[non_exhaustive]
pub struct Qlpc {
    pub lpc_order: usize,
    pub quant_precision: usize,
    pub use_direct_mse: bool,
    pub mae_optimization_steps: usize,
    pub window: Window,
}
```

--------------------------------

### MemSource::as_slice Signature

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/source.md

The function signature for retrieving the internal sample buffer.

```rust
pub fn as_slice(&self) -> &[i32]
```

--------------------------------

### Encoder::default()

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/config.md

Creates a new Encoder instance with default settings (4096 block size, default stereo/subframe coding).

```APIDOC
## Encoder::default()

### Description
Returns an encoder instance initialized with default settings.

### Signature
`fn default() -> Self`
```

--------------------------------

### Encode WAV to FLAC

Source: https://github.com/yotarok/flacenc-rs/blob/main/flacenc-bin/README.md

Basic command to encode an input WAV file into a FLAC file.

```bash
flacenc --output output.flac input.wav
```

--------------------------------

### Decode FLAC to WAV

Source: https://github.com/yotarok/flacenc-rs/blob/main/flacenc-bin/README.md

Experimental command to decode a FLAC file back into a WAV file.

```bash
flacenc decode --output output.wav input.flac
```

--------------------------------

### Context::total_samples

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/source.md

Returns the total number of samples consumed.

```APIDOC
## Context::total_samples

### Description
Returns total samples consumed.

### Signature
`pub fn total_samples(&self) -> usize`

### Returns
Total per-channel samples.
```

--------------------------------

### SourceError::by_reason

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/errors.md

Creates a new SourceError instance with a specific reason.

```APIDOC
### Method
`pub fn by_reason(reason: SourceErrorReason) -> Self`

### Description
Creates a SourceError with a specific reason.

### Example
```rust
let err = SourceError::by_reason(SourceErrorReason::Open);
```
```

--------------------------------

### Create SourceError from std::io::Error

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/errors.md

Creates a SourceError instance from a standard library I/O error.

```rust
use std::io;
let io_err = io::Error::new(io::ErrorKind::NotFound, "File not found");
let err = SourceError::from_io_error(io_err);
```

--------------------------------

### Add flacenc to Cargo.toml

Source: https://github.com/yotarok/flacenc-rs/blob/main/README.md

Include this line in your Cargo.toml file to use the default stable toolchain configuration.

```toml
flacenc = "0.5.1"
```

--------------------------------

### MemSource::as_slice

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/source.md

Retrieves the internal sample buffer as a slice of i32 values.

```APIDOC
## MemSource::as_slice

### Description
Returns the internal sample buffer.

### Signature
`pub fn as_slice(&self) -> &[i32]`

### Returns
- **&[i32]** - Reference to interleaved sample data
```

--------------------------------

### Context::bytes_per_sample

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/source.md

Returns the computed bytes per sample.

```APIDOC
## Context::bytes_per_sample

### Description
Returns computed bytes per sample.

### Signature
`pub fn bytes_per_sample(&self) -> usize`

### Returns
Bytes per sample (1, 2, 3, or 4).
```

--------------------------------

### SourceError::from_unknown

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/errors.md

Creates a new SourceError instance with an unknown reason.

```APIDOC
### Method
`pub fn from_unknown() -> Self`

### Description
Creates a SourceError with an unknown reason.

### Example
```rust
let err = SourceError::from_unknown();
```
```

--------------------------------

### QuantizedParameters::order method signature

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/component.md

Signature for retrieving the LPC order.

```rust
pub fn order(&self) -> usize
```

--------------------------------

### Fill Trait

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/modules.md

Defines the interface for buffer receptacles.

```APIDOC
## trait Fill

### Description
Defines the interface for objects that can receive audio sample data.

### Methods
- **fill_interleaved(&mut self, interleaved: &[i32]) -> Result<(), SourceError>**: Fills the buffer with interleaved audio samples.
- **fill_le_bytes(&mut self, bytes: &[u8], bytes_per_sample: usize) -> Result<(), SourceError>**: Fills the buffer with little-endian byte data.
```

--------------------------------

### Residual::from_parts method signature

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/component.md

Signature for creating a Residual instance.

```rust
pub fn from_parts(
    partition_order: u8,
    block_size: usize,
    warmup_length: usize,
    rice_params: [u8; 1 << partition_order],
    quotients: Vec<u32>,
    remainders: Vec<u32>,
) -> Self
```

--------------------------------

### SourceError::from_io_error

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/errors.md

Creates a new SourceError instance from a standard IO error.

```APIDOC
### Method
`pub fn from_io_error<E: Error + 'static>(e: E) -> Self`

### Description
Creates a SourceError from a standard library IO error.

### Example
```rust
use std::io;
let io_err = io::Error::new(io::ErrorKind::NotFound, "File not found");
let err = SourceError::from_io_error(io_err);
```
```

--------------------------------

### Stream::new signature

Source: https://github.com/yotarok/flacenc-rs/blob/main/_autodocs/api-reference/component.md

Creates a new Stream with StreamInfo metadata. Returns a VerifyError if parameters are invalid.

```rust
pub fn new(
    sample_rate: usize,
    channels: usize,
    bits_per_sample: usize,
) -> Result<Self, VerifyError>
```
Tokens:
Raw