Struct IcyMetadataReader

pub struct IcyMetadataReader<T> { /* private fields */ }

Reads icy metadata contained within a stream.

Seeking within the stream is supported with the following limitations:

• SeekFrom::End is not supported since seeking from the end of a stream conceptually doesn’t make sense.
• Seeking backwards is limited by the size of the metadata cache. Since the metadata values have dynamic sizes, we need to know the size of the previous metadata value to seek past it. In order to prevent unbounded memory growth, we cap the number of previous metadata sizes we keep track of. You can change this limit using Self::metadata_cache_size. In practice, most metadata is 0-sized except for at the start of each track. We use rudimentary compression so consecutive metadata entries of the same size don’t take up additional slots in the array. This means you shouldn’t exceed the default value of 128 unless you’re going really far back.

Implementations

impl<T> IcyMetadataReader<T>

pub fn new<F>( inner: T, icy_metadata_interval: Option<NonZeroUsize>, on_metadata_read: F, ) -> Self

where F: Fn(Result<IcyMetadata, MetadataParseError>) + Send + Sync + 'static,

Creates a new IcyMetadataReader. icy_metadata_interval is required in order to figure out the location of the metadata blocks. If icy_metadata_interval is None, it will treat the stream as though the metadata is absent. You can retrieve the value from IcyHeaders::metadata_interval or by extracting the value from the headers manually.

Examples found in repository

examples/stream.rs (lines 48-55)

async fn main() -> Result<(), Box<dyn Error>> {
    let (_stream, handle) = rodio::OutputStream::try_default()?;
    let sink = rodio::Sink::try_new(&handle)?;

    // We need to add a header to tell the Icecast server that we can parse the metadata embedded
    // within the stream itself.
    let client = Client::builder().request_icy_metadata().build()?;

    let stream =
        HttpStream::new(client, "https://ice6.somafm.com/insound-128-mp3".parse()?).await?;

    let icy_headers = IcyHeaders::parse_from_headers(stream.headers());
    println!("Icecast headers: {icy_headers:#?}\n");
    println!("content type={:?}\n", stream.content_type());

    // buffer 5 seconds of audio
    // bitrate (in kilobits) / bits per byte * bytes per kilobyte * 5 seconds
    let prefetch_bytes = icy_headers.bitrate().unwrap() / 8 * 1024 * 5;

    let reader = match StreamDownload::from_stream(
        stream,
        // use bounded storage to keep the underlying size from growing indefinitely
        BoundedStorageProvider::new(
            MemoryStorageProvider,
            // be liberal with the buffer size, you need to make sure it holds enough space to
            // prevent any out-of-bounds reads
            NonZeroUsize::new(512 * 1024).unwrap(),
        ),
        Settings::default().prefetch_bytes(prefetch_bytes as u64),
    )
    .await
    {
        Ok(reader) => reader,
        Err(e) => return Err(e.decode_error().await)?,
    };
    sink.append(rodio::Decoder::new(IcyMetadataReader::new(
        reader,
        // Since we requested icy metadata, the metadata interval header should be present in the
        // response. This will allow us to parse the metadata within the stream
        icy_headers.metadata_interval(),
        // Print the stream metadata whenever we receive new values
        |metadata| println!("{metadata:#?}\n"),
    ))?);

    let handle = tokio::task::spawn_blocking(move || {
        sink.sleep_until_end();
    });
    handle.await?;
    Ok(())
}

examples/seek.rs (lines 50-57)

async fn main() -> Result<(), Box<dyn Error>> {
    let (_stream, handle) = rodio::OutputStream::try_default()?;
    let sink = rodio::Sink::try_new(&handle)?;

    // We need to add a header to tell the Icecast server that we can parse the metadata embedded
    // within the stream itself.
    let client = Client::builder().request_icy_metadata().build()?;

    let stream =
        HttpStream::new(client, "https://ice6.somafm.com/insound-128-mp3".parse()?).await?;

    let icy_headers = IcyHeaders::parse_from_headers(stream.headers());
    println!("Icecast headers: {icy_headers:#?}\n");
    println!("content type={:?}\n", stream.content_type());

    // buffer 5 seconds of audio
    // bitrate (in kilobits) / bits per byte * bytes per kilobyte * 5 seconds
    let prefetch_bytes = icy_headers.bitrate().unwrap() / 8 * 1024 * 5;

    let reader = match StreamDownload::from_stream(
        stream,
        // use bounded storage to keep the underlying size from growing indefinitely
        BoundedStorageProvider::new(
            MemoryStorageProvider,
            // be liberal with the buffer size, you need to make sure it holds enough space to
            // prevent any out-of-bounds reads
            NonZeroUsize::new(512 * 1024).unwrap(),
        ),
        Settings::default().prefetch_bytes(prefetch_bytes as u64),
    )
    .await
    {
        Ok(reader) => reader,
        Err(e) => return Err(e.decode_error().await)?,
    };
    sink.append(rodio::Decoder::new(IcyMetadataReader::new(
        reader,
        // Since we requested icy metadata, the metadata interval header should be present in the
        // response. This will allow us to parse the metadata within the stream
        icy_headers.metadata_interval(),
        // Print the stream metadata whenever we receive new values
        |metadata| println!("{metadata:#?}\n"),
    ))?);

    let handle = tokio::task::spawn_blocking(move || {
        println!("seeking in 5 seconds\n");
        std::thread::sleep(Duration::from_secs(5));
        println!("seeking to beginning\n");
        sink.try_seek(Duration::from_secs(0))?;
        std::thread::sleep(Duration::from_secs(5));
        println!("seeking to 10 seconds\n");
        sink.try_seek(Duration::from_secs(10))?;
        sink.sleep_until_end();
        Ok::<_, SeekError>(())
    });
    handle.await??;
    Ok(())
}

examples/retry_on_failure.rs (lines 71-80)

async fn main() -> Result<(), Box<dyn Error>> {
    let (_stream, handle) = rodio::OutputStream::try_default()?;

    let restart = Arc::new(AtomicBool::new(true));

    loop {
        if !restart.swap(false, Ordering::Relaxed) {
            return Ok(());
        }

        let sink = rodio::Sink::try_new(&handle)?;

        // We need to add a header to tell the Icecast server that we can parse the metadata
        // embedded within the stream itself.
        let client = Client::builder().request_icy_metadata().build()?;

        let stream =
            HttpStream::new(client, "https://ice6.somafm.com/insound-128-mp3".parse()?).await?;

        let icy_headers = IcyHeaders::parse_from_headers(stream.headers());
        println!("Icecast headers: {icy_headers:#?}\n");
        println!("content type={:?}\n", stream.content_type());

        // buffer 5 seconds of audio
        // bitrate (in kilobits) / bits per byte * bytes per kilobyte * 5 seconds
        let prefetch_bytes = icy_headers.bitrate().unwrap() / 8 * 1024 * 5;

        let reader = match StreamDownload::from_stream(
            stream,
            // use bounded storage to keep the underlying size from growing indefinitely
            BoundedStorageProvider::new(
                MemoryStorageProvider,
                // be liberal with the buffer size, you need to make sure it holds enough space to
                // prevent any out-of-bounds reads
                NonZeroUsize::new(512 * 1024).unwrap(),
            ),
            Settings::default()
                .prefetch_bytes(prefetch_bytes as u64)
                .on_reconnect({
                    let restart = restart.clone();
                    move |_stream, cancellation_token| {
                        // If the stream reconnects after a network failure, the internal state of
                        // the metadata parser is likely invalid.
                        // We should cancel the current download task and re-instantiate it in order
                        // to reset everything.
                        cancellation_token.cancel();
                        restart.store(true, Ordering::Relaxed);
                    }
                }),
        )
        .await
        {
            Ok(reader) => reader,
            Err(e) => return Err(e.decode_error().await)?,
        };

        sink.append(rodio::Decoder::new(IcyMetadataReader::new(
            reader,
            // Since we requested icy metadata, the metadata interval header should be present in
            // the response. This will allow us to parse the metadata within the stream
            icy_headers.metadata_interval(),
            // Print the stream metadata whenever we receive new values
            |metadata| {
                println!("{metadata:#?}\n");
            },
        ))?);

        let handle = tokio::task::spawn_blocking(move || {
            sink.sleep_until_end();
        });
        handle.await?;
    }
}

impl<T> IcyMetadataReader<T>

pub fn metadata_cache_size(self, size: usize) -> Self

Set the size of the metadata cache.

Trait Implementations

impl<T> Debug for IcyMetadataReader<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Read for IcyMetadataReader<T>

where T: Read,

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

impl<T> Seek for IcyMetadataReader<T>

where T: Read + Seek,

fn seek(&mut self, seek_from: SeekFrom) -> Result<u64>

Seek to an offset, in bytes, in a stream.

fn rewind(&mut self) -> Result<(), Error>

Rewind to the beginning of a stream.

fn stream_len(&mut self) -> Result<u64, Error>

🔬This is a nightly-only experimental API. (seek_stream_len)

Returns the length of this stream (in bytes).

fn stream_position(&mut self) -> Result<u64, Error>

Returns the current seek position from the start of the stream.

fn seek_relative(&mut self, offset: i64) -> Result<(), Error>

Seeks relative to the current position.