Struct AudioTrackStream 

pub struct AudioTrackStream<'a, R: AudioSectorReader> { /* private fields */ }

A pull-based, sector-aligned stream of raw CD-DA PCM from an AudioSectorReader.

An AudioTrackStream borrows its source and represents a fixed sector range. Each call to next_chunk synchronously reads and returns the next portion of that range. Once all sectors have been consumed, it returns Ok(None).

Unlike read_track, the stream does not allocate or retain the entire track. Callers can process and discard each returned chunk before requesting the next one. Chunks contain complete CD-DA sectors in the format specified by AudioSectorReader; the final chunk may contain fewer sectors than the configured chunk size.

The chunk size can be changed with with_sectors_per_chunk. Stream position is relative to the beginning of its sector range and can be inspected or changed with current_sector, seek_to_sector, and seek_to_seconds.

Create a stream with:

• open_track_stream to resolve a track from a Toc using TrackBounds::SessionGap.
• open_track_stream_with_bounds to resolve a track using an explicit TrackBounds policy.
• open_track_stream_at to stream an explicit absolute sector range without consulting a Toc.

This is the source-independent audio counterpart to TrackStream, which is tied to CdReader and supports drive-specific read options and data-sector formats.

Implementations

impl<'a, R: AudioSectorReader> AudioTrackStream<'a, R>

pub fn with_sectors_per_chunk(self, sectors: u32) -> Self

Set the target chunk size in sectors (default 27; a full chunk is sectors_per_chunk * 2352 bytes). Zero is normalized to one.

pub fn next_chunk(&mut self) -> Result<Option<Vec<u8>>, CdReaderError>

Read the next chunk of PCM, or Ok(None) at end-of-track.

Each chunk is sectors_per_chunk * 2352 bytes except possibly the last.

Errors

Returns CdReaderError::Backend if the backing read fails. The stream position does not advance on error, so a retry re-reads the same chunk.

Examples found in repository

examples/bin_cue_backend.rs (line 147)

fn main() -> Result<(), Box<dyn Error>> {
    let output_dir = common::fresh_output_dir("bin_cue_backend")?;

    let cue_path = match std::env::args().nth(1) {
        Some(path) => PathBuf::from(path),
        None => {
            println!("No .cue argument given — writing a demo image to work against.\n");
            write_demo_image(&output_dir)?
        }
    };

    let (bin_path, toc) = parse_cue(&cue_path)?;
    println!("Cue:   {}", cue_path.display());
    println!("Bin:   {}", bin_path.display());
    println!(
        "Toc:   {} tracks, leadout at LBA {}\n",
        toc.tracks.len(),
        toc.leadout_lba
    );

    let image = BinImage {
        bin: File::open(&bin_path)?,
    };

    // A single-FILE cue is a contiguous run of sectors, so the CD-Extra
    // inter-session gap is not part of the addressing. See `explain_bounds`.
    let bounds = TrackBounds::Gapless;
    explain_bounds(&image, &toc)?;

    for track in toc.tracks.iter().filter(|track| track.is_audio) {
        let pcm = read_track_with_bounds(&image, &toc, track.number, bounds)?;
        let wav_path = output_dir.join(format!("track{:02}.wav", track.number));
        std::fs::write(&wav_path, create_wav(pcm))?;

        println!("track {:02}: wrote {}", track.number, wav_path.display());
    }

    // The same backing streams instead of buffering — for a 74-minute image
    // that is the difference between one chunk and ~650 MB resident.
    if let Some(first_audio) = toc.tracks.iter().find(|track| track.is_audio) {
        let mut stream = open_track_stream_with_bounds(&image, &toc, first_audio.number, bounds)?;
        let (mut chunks, mut bytes) = (0u32, 0usize);
        while let Some(chunk) = stream.next_chunk()? {
            chunks += 1;
            bytes += chunk.len();
        }
        println!(
            "\nstreamed track {:02}: {bytes} bytes in {chunks} chunks ({:.1}s)",
            first_audio.number,
            stream.total_seconds()
        );
    }

    Ok(())
}

examples/file_backend.rs (line 94)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let output_dir = common::fresh_output_dir("file_backend")?;

    // A real backing derives this TOC from the image's own track metadata.
    // Here we fabricate a 2-track disc: 2 seconds + 3 seconds of audio.
    let track1_sectors = 75 * 2;
    let track2_sectors = 75 * 3;
    let total_sectors = track1_sectors + track2_sectors;

    let toc = Toc {
        first_track: 1,
        last_track: 2,
        tracks: vec![
            Track {
                number: 1,
                start_lba: 0,
                start_msf: lba_to_msf(0),
                is_audio: true,
            },
            Track {
                number: 2,
                start_lba: track1_sectors,
                start_msf: lba_to_msf(track1_sectors),
                is_audio: true,
            },
        ],
        leadout_lba: total_sectors,
    };

    // Silence, just for the demo — a real backing decodes actual audio here.
    let disc = InMemoryDisc {
        pcm: vec![0u8; total_sectors as usize * 2352],
    };

    for track in &toc.tracks {
        let pcm = read_track(&disc, &toc, track.number)?;
        println!(
            "track {}: {} bytes ({} sectors)",
            track.number,
            pcm.len(),
            pcm.len() / 2352
        );

        let wav = create_wav(pcm);
        let output_path = output_dir.join(format!("track{:02}.wav", track.number));
        std::fs::write(&output_path, wav)?;
        println!("  wrote {}", output_path.display());
    }

    // The same backing can be streamed instead of buffered: pull sector-aligned
    // chunks so a player never holds a whole track in memory at once. (A backing
    // whose tracks are addressed contiguously — a gap-stripped extract — would
    // open with `TrackBounds::Gapless`, or supply its own bounds via
    // `open_track_stream_at`; this demo TOC has no trailing data track, so plain
    // `open_track_stream` is equivalent.)
    let mut stream = open_track_stream(&disc, &toc, 1)?;
    let (mut chunks, mut bytes) = (0u32, 0usize);
    while let Some(chunk) = stream.next_chunk()? {
        chunks += 1;
        bytes += chunk.len();
    }
    println!(
        "streamed track 1: {bytes} bytes in {chunks} chunks ({:.1}s of audio)",
        stream.total_seconds()
    );

    Ok(())
}

pub fn total_sectors(&self) -> u32

Total number of sectors in this track.

Examples found in repository

examples/bin_cue_backend.rs (line 171)

fn explain_bounds(image: &BinImage, toc: &Toc) -> Result<(), Box<dyn Error>> {
    let Some(track) = last_audio_before_data(toc) else {
        return Ok(());
    };

    let gapless =
        open_track_stream_with_bounds(image, toc, track, TrackBounds::Gapless)?.total_sectors();
    let physical = match open_track_stream_with_bounds(image, toc, track, TrackBounds::SessionGap) {
        Ok(stream) => format!("{} sectors", stream.total_sectors()),
        // The gap is larger than the track, so subtracting it underflows.
        Err(e) => format!("fails ({e})"),
    };

    println!(
        "Track {track:02} is the last audio track before a data track, the one track \
         the two bounds policies disagree on:\n  \
         Gapless (used here): {gapless} sectors\n  \
         SessionGap:          {physical}\n"
    );
    Ok(())
}

pub fn current_sector(&self) -> u32

Current position as a track-relative sector index.

pub fn seek_to_sector(&mut self, sector: u32) -> Result<(), CdReaderError>

Seek to a track-relative sector position (valid range 0..=total_sectors()).

Errors

Returns CdReaderError::Io containing std::io::ErrorKind::InvalidInput if sector exceeds the track length.

pub fn current_seconds(&self) -> f32

Current position in seconds (75 sectors = 1 second).

pub fn total_seconds(&self) -> f32

Total track duration in seconds (75 sectors = 1 second).

Examples found in repository

examples/bin_cue_backend.rs (line 154)

fn main() -> Result<(), Box<dyn Error>> {
    let output_dir = common::fresh_output_dir("bin_cue_backend")?;

    let cue_path = match std::env::args().nth(1) {
        Some(path) => PathBuf::from(path),
        None => {
            println!("No .cue argument given — writing a demo image to work against.\n");
            write_demo_image(&output_dir)?
        }
    };

    let (bin_path, toc) = parse_cue(&cue_path)?;
    println!("Cue:   {}", cue_path.display());
    println!("Bin:   {}", bin_path.display());
    println!(
        "Toc:   {} tracks, leadout at LBA {}\n",
        toc.tracks.len(),
        toc.leadout_lba
    );

    let image = BinImage {
        bin: File::open(&bin_path)?,
    };

    // A single-FILE cue is a contiguous run of sectors, so the CD-Extra
    // inter-session gap is not part of the addressing. See `explain_bounds`.
    let bounds = TrackBounds::Gapless;
    explain_bounds(&image, &toc)?;

    for track in toc.tracks.iter().filter(|track| track.is_audio) {
        let pcm = read_track_with_bounds(&image, &toc, track.number, bounds)?;
        let wav_path = output_dir.join(format!("track{:02}.wav", track.number));
        std::fs::write(&wav_path, create_wav(pcm))?;

        println!("track {:02}: wrote {}", track.number, wav_path.display());
    }

    // The same backing streams instead of buffering — for a 74-minute image
    // that is the difference between one chunk and ~650 MB resident.
    if let Some(first_audio) = toc.tracks.iter().find(|track| track.is_audio) {
        let mut stream = open_track_stream_with_bounds(&image, &toc, first_audio.number, bounds)?;
        let (mut chunks, mut bytes) = (0u32, 0usize);
        while let Some(chunk) = stream.next_chunk()? {
            chunks += 1;
            bytes += chunk.len();
        }
        println!(
            "\nstreamed track {:02}: {bytes} bytes in {chunks} chunks ({:.1}s)",
            first_audio.number,
            stream.total_seconds()
        );
    }

    Ok(())
}

examples/file_backend.rs (line 100)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let output_dir = common::fresh_output_dir("file_backend")?;

    // A real backing derives this TOC from the image's own track metadata.
    // Here we fabricate a 2-track disc: 2 seconds + 3 seconds of audio.
    let track1_sectors = 75 * 2;
    let track2_sectors = 75 * 3;
    let total_sectors = track1_sectors + track2_sectors;

    let toc = Toc {
        first_track: 1,
        last_track: 2,
        tracks: vec![
            Track {
                number: 1,
                start_lba: 0,
                start_msf: lba_to_msf(0),
                is_audio: true,
            },
            Track {
                number: 2,
                start_lba: track1_sectors,
                start_msf: lba_to_msf(track1_sectors),
                is_audio: true,
            },
        ],
        leadout_lba: total_sectors,
    };

    // Silence, just for the demo — a real backing decodes actual audio here.
    let disc = InMemoryDisc {
        pcm: vec![0u8; total_sectors as usize * 2352],
    };

    for track in &toc.tracks {
        let pcm = read_track(&disc, &toc, track.number)?;
        println!(
            "track {}: {} bytes ({} sectors)",
            track.number,
            pcm.len(),
            pcm.len() / 2352
        );

        let wav = create_wav(pcm);
        let output_path = output_dir.join(format!("track{:02}.wav", track.number));
        std::fs::write(&output_path, wav)?;
        println!("  wrote {}", output_path.display());
    }

    // The same backing can be streamed instead of buffered: pull sector-aligned
    // chunks so a player never holds a whole track in memory at once. (A backing
    // whose tracks are addressed contiguously — a gap-stripped extract — would
    // open with `TrackBounds::Gapless`, or supply its own bounds via
    // `open_track_stream_at`; this demo TOC has no trailing data track, so plain
    // `open_track_stream` is equivalent.)
    let mut stream = open_track_stream(&disc, &toc, 1)?;
    let (mut chunks, mut bytes) = (0u32, 0usize);
    while let Some(chunk) = stream.next_chunk()? {
        chunks += 1;
        bytes += chunk.len();
    }
    println!(
        "streamed track 1: {bytes} bytes in {chunks} chunks ({:.1}s of audio)",
        stream.total_seconds()
    );

    Ok(())
}

pub fn seek_to_seconds(&mut self, seconds: f32) -> Result<(), CdReaderError>

Seek to a track-relative time in seconds, clamped to the track length.

Errors

Returns CdReaderError::Io containing std::io::ErrorKind::InvalidInput if seconds is negative or not finite.