### Set MP3 Encoder Sample Rate

Source: https://context7.com/doumanash/mp3lame-encoder/llms.txt

Sets the input PCM sample rate. Supported values depend on the MPEG version (MPEG1, MPEG2, MPEG2.5). Defaults to 44100 Hz. This example creates a 48 kHz stereo encoder.

```rust
use mp3lame_encoder::Builder;

// 48 kHz stereo encoder
let encoder = Builder::new().expect("alloc")
    .with_num_channels(2).expect("ch")
    .with_sample_rate(48_000).expect("48kHz")
    .build().expect("init");

assert_eq!(encoder.sample_rate(), 48_000);
assert_eq!(encoder.num_channels(), 2);
```

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

### Set MP3 Encoder Constant Bitrate (CBR)

Source: https://context7.com/doumanash/mp3lame-encoder/llms.txt

Sets the Constant Bitrate (CBR) for MP3 encoding. All standard MP3 bitrates are available as typed variants of the Bitrate enum, from Kbps8 to Kbps320. This example configures a 320 kbps CBR encoder for highest quality.

```rust
use mp3lame_encoder::{Builder, Bitrate};

let enc = Builder::new().expect("alloc")
    .with_sample_rate(44_100).expect("sr")
    .with_brate(Bitrate::Kbps320).expect("320kbps")
    .build().expect("init");
// Produces highest quality CBR MP3 at 320 kbps
```

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

### Create and Use Default MP3 Encoder

Source: https://context7.com/doumanash/mp3lame-encoder/llms.txt

This convenience constructor creates a ready-to-use Encoder with default settings (192 kbps bitrate, best quality). It's suitable for simple use cases. Ensure the output buffer is reserved using max_required_buffer_size before encoding.

```rust
use mp3lame_encoder::{encoder, DualPcm, FlushNoGap, max_required_buffer_size};

let mut enc = encoder().expect("create default encoder");

let left: Vec<i16>  = vec![0i16; 1152];
let right: Vec<i16> = vec![0i16; 1152];
let input = DualPcm { left: &left, right: &right };

let mut out = Vec::new();
out.reserve(max_required_buffer_size(left.len()));

enc.encode_to_vec(input, &mut out).expect("encode");
enc.flush_to_vec::<FlushNoGap>(&mut out).expect("flush");

// `out` now contains a complete MP3 stream
println!("Encoded {} bytes of MP3", out.len());
```

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

### Configure MP3 Encoder using Builder Pattern

Source: https://context7.com/doumanash/mp3lame-encoder/llms.txt

Configure encoding parameters like sample rate, bitrate, quality, and channel count using the Builder pattern. Both mutable set_* methods and chainable with_* methods are available. Returns None if memory allocation fails.

```rust
use mp3lame_encoder::{Builder, Bitrate, Quality, VbrMode, Mode};

// Mutable style
let mut b = Builder::new().expect("alloc lame");
b.set_num_channels(2).expect("channels");
b.set_sample_rate(44_100).expect("sample rate");
b.set_brate(Bitrate::Kbps192).expect("bitrate");
b.set_quality(Quality::Best).expect("quality");
let encoder = b.build().expect("init");

// Builder (method-chaining) style
let encoder = Builder::new().expect("alloc lame")
    .with_num_channels(2).expect("channels")
    .with_sample_rate(44_100).expect("sample rate")
    .with_brate(Bitrate::Kbps192).expect("bitrate")
    .with_quality(Quality::Best).expect("quality")
    .with_mode(Mode::JointStereo).expect("mode")
    .build().expect("init");
```

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

### Builder::new()

Source: https://context7.com/doumanash/mp3lame-encoder/llms.txt

Initializes a new `Builder` for configuring an MP3 encoder. It sets default values for J-Stereo, 44.1 kHz sample rate, 128 kbps CBR, and quality 5. Returns `None` if memory allocation fails.

```APIDOC
## Builder::new() -> Option<Builder>

### Description
Allocates a new LAME encoder context with defaults: J-Stereo, 44.1 kHz, 128 kbps CBR, quality 5. Returns `None` if memory allocation fails. All configuration methods come in two flavors: a mutable `set_*` variant and a chainable `with_*` builder-pattern variant.

### Usage Example (Mutable Style)
```rust
use mp3lame_encoder::{Builder, Bitrate, Quality, VbrMode, Mode};

// Mutable style
let mut b = Builder::new().expect("alloc lame");
b.set_num_channels(2).expect("channels");
b.set_sample_rate(44_100).expect("sample rate");
b.set_brate(Bitrate::Kbps192).expect("bitrate");
b.set_quality(Quality::Best).expect("quality");
let encoder = b.build().expect("init");
```

### Usage Example (Builder Style)
```rust
// Builder (method-chaining) style
let encoder = Builder::new().expect("alloc lame")
    .with_num_channels(2).expect("channels")
    .with_sample_rate(44_100).expect("sample rate")
    .with_brate(Bitrate::Kbps192).expect("bitrate")
    .with_quality(Quality::Best).expect("quality")
    .with_mode(Mode::JointStereo).expect("mode")
    .build().expect("init");
```
```

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

### Encode PCM to MP3 with ID3 Tag

Source: https://github.com/doumanash/mp3lame-encoder/blob/master/README.md

Demonstrates setting encoder parameters like channels, sample rate, bitrate, and quality. It also shows how to set an ID3 tag and encode PCM data, flush the encoder, and handle ID3v2 and VBR tags.

```rust
use mp3lame_encoder::{Builder, Id3Tag, DualPcm, FlushNoGap};

let mut mp3_encoder = Builder::new().expect("Create LAME builder");
mp3_encoder.set_num_channels(2).expect("set channels");
mp3_encoder.set_sample_rate(44_100).expect("set sample rate");
mp3_encoder.set_brate(mp3lame_encoder::Bitrate::Kbps192).expect("set brate");
mp3_encoder.set_quality(mp3lame_encoder::Quality::Best).expect("set quality");
mp3_encoder.set_id3_tag(Id3Tag {
    title: b"My title",
    artist: &[],
    album: b"My album",
    year: b"Current year",
    comment: b"Just my comment",
});
let mut mp3_encoder = mp3_encoder.build().expect("To initialize LAME encoder");

//use actual PCM data
let input = DualPcm {
    left: &[0u16, 0],
    right: &[0u16, 0],
};

let mut mp3_out_buffer = Vec::new();
mp3_out_buffer.reserve(mp3lame_encoder::max_required_buffer_size(input.left.len()));
let encoded_size = mp3_encoder.encode(input, mp3_out_buffer.spare_capacity_mut()).expect("To encode");
unsafe {
    mp3_out_buffer.set_len(mp3_out_buffer.len().wrapping_add(encoded_size));
}

let encoded_size = mp3_encoder.flush::<FlushNoGap>(mp3_out_buffer.spare_capacity_mut()).expect("to flush");
unsafe {
    mp3_out_buffer.set_len(mp3_out_buffer.len().wrapping_add(encoded_size));
}
//At this point your mp3_out_buffer should have full MP3 data, ready to be written on file system or whatever

if mp3_encoder.lame_tag_size() > 0 {
   let id3v2_tag_boundary = mp3_encoder.id3v2_tag_size();
   assert_eq!(id3v2_tag_boundary, 158);
   let mut lame_tag = [core::mem::MaybeUninit::uninit(); 1024];
   assert!(lame_tag.len() >= mp3_encoder.lame_tag_size(), "Increase buffer size");
   let lame_tag_size = mp3_encoder.lame_tag_encode(&mut lame_tag).expect("to write lame tag");
   assert_eq!(mp3_encoder.lame_tag_size(), lame_tag_size.get());

   //If you need VBR tag then you need to write mp3 file in following order
   //- id3v2 tag
   //- VBR tag
   //- actual mp3 content
   let chunks_to_write = [
       &mp3_out_buffer[..id3v2_tag_boundary],
       unsafe {
           core::slice::from_raw_parts(lame_tag.as_ptr() as *const u8, lame_tag_size.get())
       },
       &mp3_out_buffer[id3v2_tag_boundary..],
   ];
} else {
   let chunks_to_write = [
       &mp3_out_buffer[..]
   ];
}
```

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

### Write VBR Tag with ID3v2 Header and MP3 Frames

Source: https://context7.com/doumanash/mp3lame-encoder/llms.txt

Demonstrates writing a VBR LAME tag along with an ID3v2 header. The final MP3 file must be assembled in the order: ID3v2 tag, LAME VBR tag, and then MP3 frames. Use `lame_tag_size()` to check for the tag and `lame_tag_encode_to_vec` to retrieve its bytes.

```rust
use std::{fs, io::Write};
use mp3lame_encoder::{Builder, Bitrate, Quality, VbrMode, DualPcm, FlushNoGap, Id3Tag, max_required_buffer_size};

let mut enc = Builder::new().expect("alloc")
    .with_num_channels(2).expect("ch")
    .with_sample_rate(44_100).expect("sr")
    .with_brate(Bitrate::Kbps192).expect("brate")
    .with_quality(Quality::Best).expect("quality")
    .with_vbr_mode(VbrMode::Mtrh).expect("vbr")
    .with_vbr_quality(Quality::Best).expect("vbr q")
    .with_to_write_vbr_tag(true).expect("vbr tag")
    .with_id3_tag(Id3Tag {
        title: b"My Track", artist: b"Me", album: b"My Album",
        album_art: &[], year: b"2024", comment: &[],
    }).expect("id3")
    .build().expect("init");

let left  = vec![0i16; 1152];
let right = vec![0i16; 1152];
let mut mp3_data = Vec::new();
mp3_data.reserve(max_required_buffer_size(left.len()));
enc.encode_to_vec(DualPcm { left: &left, right: &right }, &mut mp3_data).expect("encode");
enc.flush_to_vec::<FlushNoGap>(&mut mp3_data).expect("flush");

let id3v2_end = enc.id3v2_tag_size(); // where ID3v2 ends in mp3_data

let mut lame_tag = Vec::new();
if enc.lame_tag_size() > 0 {
    lame_tag.reserve(enc.lame_tag_size());
    enc.lame_tag_encode_to_vec(&mut lame_tag).expect("lame tag");
}

// Write final file: [id3v2][lame_tag][mp3_frames]
let mut file = fs::File::create("output.mp3").expect("create");
file.write_all(&mp3_data[..id3v2_end]).expect("id3v2");
file.write_all(&lame_tag).expect("lame tag");
file.write_all(&mp3_data[id3v2_end..]).expect("mp3 frames");
```

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

### encoder()

Source: https://context7.com/doumanash/mp3lame-encoder/llms.txt

Provides a convenience constructor for creating a default MP3 encoder. This is suitable for simple use cases where fine-grained configuration is not required, defaulting to 192 kbps bitrate and best quality.

```APIDOC
## encoder() -> Result<Encoder, BuildError>

### Description
Convenience constructor that creates a ready-to-use `Encoder` with 192 kbps bitrate and best quality (`Quality::Best`). Suitable for simple use cases where fine-grained configuration is not needed.

### Usage Example
```rust
use mp3lame_encoder::{encoder, DualPcm, FlushNoGap, max_required_buffer_size};

let mut enc = encoder().expect("create default encoder");

let left: Vec<i16>  = vec![0i16; 1152];
let right: Vec<i16> = vec![0i16; 1152];
let input = DualPcm { left: &left, right: &right };

let mut out = Vec::new();
out.reserve(max_required_buffer_size(left.len()));

enc.encode_to_vec(input, &mut out).expect("encode");
enc.flush_to_vec::<FlushNoGap>(&mut out).expect("flush");

// `out` now contains a complete MP3 stream
println!("Encoded {} bytes of MP3", out.len());
```
```

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

### Encode PCM Data with MonoPcm, DualPcm, InterleavedPcm

Source: https://context7.com/doumanash/mp3lame-encoder/llms.txt

Demonstrates encoding PCM data using different input wrappers: MonoPcm for single-channel, DualPcm for separate left/right channels, and InterleavedPcm for combined channel data. Ensure the interleaved data length is even.

```rust
use mp3lame_encoder::{Builder, Bitrate, Quality, MonoPcm, DualPcm, InterleavedPcm, FlushNoGap, max_required_buffer_size};

let mut enc = Builder::new().expect("alloc")
    .with_num_channels(2).expect("ch")
    .with_sample_rate(44_100).expect("sr")
    .with_brate(Bitrate::Kbps192).expect("brate")
    .with_quality(Quality::Best).expect("quality")
    .build().expect("init");

let mut out = Vec::new();

// --- MonoPcm: single channel, any supported numeric type ---
let mono_f32: Vec<f32> = vec![0.0f32; 1152];
out.reserve(max_required_buffer_size(mono_f32.len()));
enc.encode_to_vec(MonoPcm(&mono_f32), &mut out).expect("mono f32");

// --- DualPcm: two separate channel slices ---
let left:  Vec<f32> = vec![0.0f32; 1152];
let right: Vec<f32> = vec![0.0f32; 1152];
out.reserve(max_required_buffer_size(left.len()));
enc.encode_to_vec(DualPcm { left: &left, right: &right }, &mut out).expect("dual f32");

// --- InterleavedPcm: [L0, R0, L1, R1, ...] format; len must be even ---
let interleaved: Vec<i16> = vec![0i16; 2304]; // 1152 frames × 2 channels
out.reserve(max_required_buffer_size(interleaved.len() / 2));
enc.encode_to_vec(InterleavedPcm(&interleaved), &mut out).expect("interleaved i16");

enc.flush_to_vec::<FlushNoGap>(&mut out).expect("flush");
```

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

### Builder::set_sample_rate / with_sample_rate

Source: https://context7.com/doumanash/mp3lame-encoder/llms.txt

Configures the input PCM sample rate for the encoder. The default is 44,100 Hz. Supported rates include MPEG1 (32,000, 44,100, 48,000 Hz), MPEG2 (16,000, 22,050, 24,000 Hz), and MPEG2.5 (8,000, 11,025, 12,000 Hz).

```APIDOC
## Builder::set_sample_rate / with_sample_rate

### Description
Sets the input PCM sample rate. Defaults to 44 100 Hz. Supported values: MPEG1 — 32 000, 44 100, 48 000; MPEG2 — 16 000, 22 050, 24 000; MPEG2.5 — 8 000, 11 025, 12 000.

### Usage Example
```rust
use mp3lame_encoder::Builder;

// 48 kHz stereo encoder
let encoder = Builder::new().expect("alloc")
    .with_num_channels(2).expect("channels")
    .with_sample_rate(48_000).expect("48kHz")
    .build().expect("init");

assert_eq!(encoder.sample_rate(), 48_000);
assert_eq!(encoder.num_channels(), 2);
```
```

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

### Calculate Max Required Buffer Size for MP3 Encoding

Source: https://context7.com/doumanash/mp3lame-encoder/llms.txt

Use this function to pre-allocate or reserve capacity in the output Vec<u8> before calling encode. It calculates the maximum output buffer size needed for a given number of PCM samples, including headroom and a fixed MP3 frame constant.

```rust
use mp3lame_encoder::max_required_buffer_size;

let pcm_samples = 4096_usize;
let needed = max_required_buffer_size(pcm_samples);
// needed = 4096 + 1024 + 7200 = 12320

let mut output: Vec<u8> = Vec::new();
output.reserve(needed);
// output buffer is now ready to receive encoded MP3 data
```

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

### Enable Variable Bitrate Encoding with `VbrMode`

Source: https://context7.com/doumanash/mp3lame-encoder/llms.txt

Enables Variable Bitrate (VBR) encoding. `VbrMode::Off` results in CBR. Recommended mode is `VbrMode::Mtrh`. Ensure `set_vbr_quality` and `set_to_write_vbr_tag` are also configured.

```rust
use mp3lame_encoder::{Builder, Bitrate, Quality, VbrMode};

let enc = Builder::new().expect("alloc")
    .with_num_channels(2).expect("ch")
    .with_sample_rate(44_100).expect("sr")
    .with_brate(Bitrate::Kbps192).expect("brate")  // acts as maximum for VBR
    .with_quality(Quality::Best).expect("quality")
    .with_vbr_mode(VbrMode::Mtrh).expect("vbr mode")
    .with_vbr_quality(Quality::Best).expect("vbr quality")
    .with_to_write_vbr_tag(true).expect("vbr tag")
    .build().expect("init");

```

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

### Builder::set_quality / with_quality

Source: https://context7.com/doumanash/mp3lame-encoder/llms.txt

Sets the psychoacoustic algorithm quality from `Quality::Best` (0) to `Quality::Worst` (9). This applies to both CBR and VBR quality settings.

```APIDOC
## Builder::set_quality / with_quality — Quality enum

### Description
Sets the psychoacoustic algorithm quality from `Quality::Best` (0) to `Quality::Worst` (9). Applies to both CBR and the VBR quality via `set_vbr_quality`.

### Method
Builder

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use mp3lame_encoder::{Builder, Bitrate, Quality};

let enc = Builder::new().expect("alloc")
    .with_sample_rate(44_100).expect("sr")
    .with_brate(Bitrate::Kbps128).expect("brate")
    .with_quality(Quality::NearBest).expect("quality") // value 2
    .build().expect("init");
```

### Response
#### Success Response (200)
None

#### Response Example
None
```

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

### Builder::set_vbr_mode / with_vbr_mode

Source: https://context7.com/doumanash/mp3lame-encoder/llms.txt

Enables Variable Bitrate encoding. `VbrMode::Off` signifies CBR (the default). `VbrMode::Mtrh` is the recommended mode. This should be paired with `set_vbr_quality` and `set_to_write_vbr_tag`.

```APIDOC
## Builder::set_vbr_mode / with_vbr_mode — VbrMode enum

### Description
Enables Variable Bitrate encoding. `VbrMode::Off` means CBR (the default). The recommended mode is `VbrMode::Mtrh`. Pair with `set_vbr_quality` and `set_to_write_vbr_tag`.

### Method
Builder

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use mp3lame_encoder::{Builder, Bitrate, Quality, VbrMode};

let enc = Builder::new().expect("alloc")
    .with_num_channels(2).expect("ch")
    .with_sample_rate(44_100).expect("sr")
    .with_brate(Bitrate::Kbps192).expect("brate")  // acts as maximum for VBR
    .with_quality(Quality::Best).expect("quality")
    .with_vbr_mode(VbrMode::Mtrh).expect("vbr mode")
    .with_vbr_quality(Quality::Best).expect("vbr quality")
    .with_to_write_vbr_tag(true).expect("vbr tag")
    .build().expect("init");
```

### Response
#### Success Response (200)
None

#### Response Example
None
```

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

### Encode PCM Audio to MP3 Bytes

Source: https://context7.com/doumanash/mp3lame-encoder/llms.txt

Encodes chunks of PCM audio data into MP3 format and writes the resulting bytes to an output buffer. `encode_to_vec` is a convenient wrapper for appending to a `Vec<u8>`. Remember to reserve sufficient capacity for the output vector.

```rust
use mp3lame_encoder::{Builder, Bitrate, Quality, DualPcm, FlushNoGap, max_required_buffer_size};

let mut enc = Builder::new().expect("alloc")
    .with_num_channels(2).expect("ch")
    .with_sample_rate(44_100).expect("sr")
    .with_brate(Bitrate::Kbps192).expect("brate")
    .with_quality(Quality::Best).expect("quality")
    .build().expect("init");

// Simulate streaming PCM in chunks
let chunk_left:  Vec<i16> = vec![0i16; 1152];
let chunk_right: Vec<i16> = vec![0i16; 1152];

let mut output = Vec::new();

for _ in 0..10 {
    let input = DualPcm { left: &chunk_left, right: &chunk_right };
    output.reserve(max_required_buffer_size(chunk_left.len()));
    enc.encode_to_vec(input, &mut output).expect("encode chunk");
}

// Finalize the stream
enc.flush_to_vec::<FlushNoGap>(&mut output).expect("flush");
println!("Final MP3 size: {} bytes", output.len());

```

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

### Embed ID3v2 Metadata with `Id3Tag`

Source: https://context7.com/doumanash/mp3lame-encoder/llms.txt

Embeds ID3v2 metadata such as title, artist, album, and album art into the MP3 stream. Use empty slices for fields that are not provided. Album art must be PNG, JPG, or GIF and not exceed 128 KB.

```rust
use mp3lame_encoder::{Builder, Bitrate, Quality, Id3Tag};

static COVER: &[u8] = include_bytes!("album_art.jpg");

let enc = Builder::new().expect("alloc")
    .with_num_channels(2).expect("ch")
    .with_sample_rate(44_100).expect("sr")
    .with_brate(Bitrate::Kbps192).expect("brate")
    .with_quality(Quality::Best).expect("quality")
    .with_id3_tag(Id3Tag {
        title:     b"Track Title",
        artist:    b"Artist Name",
        album:     b"Album Name",
        album_art: COVER,
        year:      b"2024",
        comment:   b"Encoded with mp3lame-encoder",
    }).expect("id3 tag")
    .build().expect("init");

```

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

### Finalize MP3 Stream with `flush_to_vec`

Source: https://context7.com/doumanash/mp3lame-encoder/llms.txt

Finalizes the MP3 stream by flushing all internally buffered data. This must be called after all encoding operations. `FlushNoGap` is suitable for gapless playback, while `FlushGap` pads with zeros and may prevent ID3v1 tag writing.

```rust
use mp3lame_encoder::{Builder, Bitrate, Quality, MonoPcm, FlushGap, FlushNoGap, max_required_buffer_size};

let mut enc = Builder::new().expect("alloc")
    .with_num_channels(1).expect("ch")
    .with_sample_rate(22_050).expect("sr")
    .with_brate(Bitrate::Kbps64).expect("brate")
    .with_quality(Quality::Good).expect("quality")
    .build().expect("init");

let pcm: Vec<i16> = vec![0i16; 2048];
let mut out = Vec::new();
out.reserve(max_required_buffer_size(pcm.len()));
enc.encode_to_vec(MonoPcm(&pcm), &mut out).expect("encode");

// Use FlushNoGap for gapless; FlushGap for zero-padded
out.reserve(7200);
enc.flush_to_vec::<FlushNoGap>(&mut out).expect("flush no-gap");
// -- or --
// enc.flush_to_vec::<FlushGap>(&mut out).expect("flush gap");

```

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

### max_required_buffer_size

Source: https://context7.com/doumanash/mp3lame-encoder/llms.txt

Calculates the maximum output buffer size needed for encoded MP3 data given a number of PCM samples. This function is useful for pre-allocating memory for the output buffer.

```APIDOC
## max_required_buffer_size(sample_number: usize) -> usize

### Description
A `const fn` that calculates the maximum output buffer size needed to hold the encoded MP3 data for a given number of input PCM samples. It adds 25% headroom plus a fixed 7200-byte MP3 frame constant. Use this to pre-allocate or `reserve` capacity in the output `Vec<u8>` before calling `encode`.

### Usage Example
```rust
use mp3lame_encoder::max_required_buffer_size;

let pcm_samples = 4096_usize;
let needed = max_required_buffer_size(pcm_samples);
// needed = 4096 + 1024 + 7200 = 12320

let mut output: Vec<u8> = Vec::new();
output.reserve(needed);
// output buffer is now ready to receive encoded MP3 data
```
```

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

### Builder::set_brate / with_brate — Bitrate enum

Source: https://context7.com/doumanash/mp3lame-encoder/llms.txt

Sets the Constant Bitrate (CBR) for MP3 encoding. The `Bitrate` enum provides typed variants for all standard MP3 bitrates, ranging from `Kbps8` to `Kbps320`.

```APIDOC
## Builder::set_brate / with_brate — `Bitrate` enum

### Description
Sets the CBR bitrate. All standard MP3 bitrates are available as typed variants of the `Bitrate` enum (also aliased as `Birtate` for backwards compatibility): `Kbps8` through `Kbps320`.

### Usage Example
```rust
use mp3lame_encoder::{Builder, Bitrate};

let enc = Builder::new().expect("alloc")
    .with_sample_rate(44_100).expect("sr")
    .with_brate(Bitrate::Kbps320).expect("320kbps")
    .build().expect("init");
// Produces highest quality CBR MP3 at 320 kbps
```
```

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

### Builder::set_id3_tag / with_id3_tag

Source: https://context7.com/doumanash/mp3lame-encoder/llms.txt

Embeds ID3v2 metadata into the MP3 stream. The `Id3Tag` struct holds byte-slice references for title, artist, album, album art, year, and comment. Use empty slices for absent fields.

```APIDOC
## Builder::set_id3_tag / with_id3_tag — Id3Tag

### Description
Embeds ID3v2 metadata into the MP3 stream. The `Id3Tag` struct holds byte-slice references for `title`, `artist`, `album`, `album_art` (PNG/JPG/GIF, max 128 KB), `year`, and `comment`. Use empty slices for absent fields.

### Method
Builder

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use mp3lame_encoder::{Builder, Bitrate, Quality, Id3Tag};

static COVER: &[u8] = include_bytes!("album_art.jpg");

let enc = Builder::new().expect("alloc")
    .with_num_channels(2).expect("ch")
    .with_sample_rate(44_100).expect("sr")
    .with_brate(Bitrate::Kbps192).expect("brate")
    .with_quality(Quality::Best).expect("quality")
    .with_id3_tag(Id3Tag {
        title:     b"Track Title",
        artist:    b"Artist Name",
        album:     b"Album Name",
        album_art: COVER,
        year:      b"2024",
        comment:   b"Encoded with mp3lame-encoder",
    }).expect("id3 tag")
    .build().expect("init");
```

### Response
#### Success Response (200)
None

#### Response Example
None
```

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

### Encoder::encode / encode_to_vec

Source: https://context7.com/doumanash/mp3lame-encoder/llms.txt

Encodes a chunk of PCM audio and writes MP3 bytes to the output buffer. `encode_to_vec` is a wrapper that appends to a `Vec<u8>`.

```APIDOC
## Encoder::encode / encode_to_vec

### Description
Encodes a chunk of PCM audio and writes MP3 bytes to the output buffer. Returns the number of bytes written (may be 0 if LAME is buffering). `encode` writes into `&mut [MaybeUninit<u8>]`; `encode_to_vec` is the ergonomic wrapper that appends to a `Vec<u8>` and adjusts its length.

### Method
Encoder

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use mp3lame_encoder::{Builder, Bitrate, Quality, DualPcm, FlushNoGap, max_required_buffer_size};

let mut enc = Builder::new().expect("alloc")
    .with_num_channels(2).expect("ch")
    .with_sample_rate(44_100).expect("sr")
    .with_brate(Bitrate::Kbps192).expect("brate")
    .with_quality(Quality::Best).expect("quality")
    .build().expect("init");

// Simulate streaming PCM in chunks
let chunk_left:  Vec<i16> = vec![0i16; 1152];
let chunk_right: Vec<i16> = vec![0i16; 1152];

let mut output = Vec::new();

for _ in 0..10 {
    let input = DualPcm { left: &chunk_left, right: &chunk_right };
    output.reserve(max_required_buffer_size(chunk_left.len()));
    enc.encode_to_vec(input, &mut output).expect("encode chunk");
}

// Finalize the stream
enc.flush_to_vec::<FlushNoGap>(&mut output).expect("flush");
println!("Final MP3 size: {} bytes", output.len());
```

### Response
#### Success Response (200)
None

#### Response Example
None
```

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

### Encoder::flush / flush_to_vec

Source: https://context7.com/doumanash/mp3lame-encoder/llms.txt

Finalizes the MP3 stream, flushing all internally buffered data. Must be called once after all `encode` calls. Supports `FlushNoGap` (gapless) and `FlushGap` (zero-padded).

```APIDOC
## Encoder::flush / flush_to_vec — FlushNoGap / FlushGap

### Description
Finalizes the MP3 stream, flushing all internally buffered data. Must be called once after all `encode` calls. Two strategies are available:
- **`FlushNoGap`** — pads using ancillary data (gapless playback-friendly).
- **`FlushGap`** — pads with zeros; note this prevents ID3v1 tag from being written.

### Method
Encoder

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use mp3lame_encoder::{Builder, Bitrate, Quality, MonoPcm, FlushGap, FlushNoGap, max_required_buffer_size};

let mut enc = Builder::new().expect("alloc")
    .with_num_channels(1).expect("ch")
    .with_sample_rate(22_050).expect("sr")
    .with_brate(Bitrate::Kbps64).expect("brate")
    .with_quality(Quality::Good).expect("quality")
    .build().expect("init");

let pcm: Vec<i16> = vec![0i16; 2048];
let mut out = Vec::new();
out.reserve(max_required_buffer_size(pcm.len()));
enc.encode_to_vec(MonoPcm(&pcm), &mut out).expect("encode");

// Use FlushNoGap for gapless; FlushGap for zero-padded
out.reserve(7200);
enc.flush_to_vec::<FlushNoGap>(&mut out).expect("flush no-gap");
// -- or --
// enc.flush_to_vec::<FlushGap>(&mut out).expect("flush gap");
```

### Response
#### Success Response (200)
None

#### Response Example
None
```

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

### Set Encoder Quality with `Quality` Enum

Source: https://context7.com/doumanash/mp3lame-encoder/llms.txt

Configures the psychoacoustic algorithm quality for encoding. This setting affects both CBR and VBR encoding quality.

```rust
use mp3lame_encoder::{Builder, Bitrate, Quality};

let enc = Builder::new().expect("alloc")
    .with_sample_rate(44_100).expect("sr")
    .with_brate(Bitrate::Kbps128).expect("brate")
    .with_quality(Quality::NearBest).expect("quality") // value 2
    .build().expect("init");

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.