stream-download-rs

stream-download is a library for streaming content from a remote location to a local file-backed cache and using it as a read and seek-able source. The requested content is downloaded in the background and read or seek operations are allowed before the download is finished. Seek operations may cause the stream to be restarted from the requested position if the download is still in progress. This is useful for media applications that need to stream large files that may take a long time to download.

HTTP is the only transport supplied by this library, but you can use a custom transport by implementing the SourceStream trait.

We use Tokio to download content using an asynchronous background task. If this library is used outside of a Tokio runtime, a single-threaded runtime will be started on a separate thread for you.

Installation

cargo add stream-download

Features

• http - adds an HTTP-based implementation of the SourceStream trait (enabled by default).
• reqwest - enables streaming content over http using reqwest (enabled by default).
• reqwest-native-tls - enables reqwest's native-tls feature. Also enables the reqwest feature.
• reqwest-rustls - enables reqwest's rustls feature. Also enables the reqwest feature.

One of reqwest-native-tls or reqwest-rustls is required if you wish to use https streams.

Usage

use stream_download::{Settings, StreamDownload};
use std::{io::Read, result::Result, error::Error};

fn main() -> Result<(), Box<dyn Error>> {
    let mut reader = StreamDownload::new_http(
        "https://some-cool-url.com/some-file.mp3".parse()?,
        Settings::default(),
    )?;

    let mut buf = Vec::new();
    reader.read_to_end(&mut buf)?;
    Ok(())
}

Examples

See examples.

Streams with Unknown Length

Resources such as standalone songs or videos have a finite length that we use to support certain seeking functionality. Infinite streams or those that otherwise don't have a known length are still supported, but attempting to seek from the end of the stream will return an error. This may cause issues with certain audio or video libraries that attempt to perform such seek operations. If it's necessary to explicitly check for an infinite stream, you can check the stream's content length ahead of time.

use std::{error::Error, io::Read, result::Result};
use stream_download::{
    http::HttpStream, reqwest::client::Client, source::SourceStream, Settings, StreamDownload,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let stream =
        HttpStream::<Client>::create("https://some-cool-url.com/some-stream".parse()?).await?;
    let content_length = stream.content_length();
    let is_infinite = content_length.is_none();
    println!("Infinite stream = {is_infinite}");

    let mut reader = StreamDownload::from_stream(stream, Settings::default())?;

    let mut buf = [0; 256];
    reader.read_exact(&mut buf)?;
    Ok(())
}

Supported Rust Versions

The MSRV is currently 1.63.0.