feat(streaming): implement incremental decoding for true streaming playback

BREAKING CHANGE: Replace blocking decode_streaming_source with IncrementalStreamingSource

Key improvements:
- IncrementalStreamingSource implements rodio::Source and decodes packets on-demand
- Playback starts immediately after initial buffer (512KB default) fills
- Audio is decoded incrementally while download continues in background
- Reduced initial buffer from 2MB to 512KB for faster startup
- Added fast_start() config option for minimal 256KB buffer

The previous implementation blocked until the ENTIRE file was downloaded
and decoded, making streaming slower than traditional download-first.
Now playback truly starts within ~1 second of initial buffer filling.

Signed-off-by: cpvsc
This commit is contained in:
vicrodh committed 2026-01-25 13:50:24 -06:00
1 parent 36b3a4da56
commit 7d0aa215a5
2 files changed
+278 -114

No files matched your search

+29 -107
View File
@@ -13,7 +13,7 @@
mod playback_engine;
mod streaming_source;
pub use streaming_source::{BufferedMediaSource, BufferWriter, StreamingConfig};
pub use streaming_source::{BufferedMediaSource, BufferWriter, StreamingConfig, IncrementalStreamingSource};
use std::io::{BufReader, Cursor, Read, Seek, SeekFrom};
use std::panic::{self, AssertUnwindSafe};
@@ -188,96 +188,6 @@ fn decode_with_symphonia(data: &[u8]) -> Result<AudioSpecs, String> {
})
}
/// Decode audio from a streaming source (BufferedMediaSource).
/// Returns decoded samples as they become available.
/// This allows playback to start before the full file is downloaded.
fn decode_streaming_source(
source: &BufferedMediaSource,
) -> Result<AudioSpecs, String> {
// Create a new reader from the source - shares buffer but has its own read position
let reader = source.create_reader();
let media_source = Box::new(reader) as Box<dyn MediaSource>;
let mss = MediaSourceStream::new(media_source, Default::default());
let mut hint = Hint::new();
hint.with_extension("m4a");
let format_opts = FormatOptions {
enable_gapless: true,
..Default::default()
};
let metadata_opts: MetadataOptions = Default::default();
let mut probed = get_probe()
.format(&hint, mss, &format_opts, &metadata_opts)
.map_err(|err| format!("Symphonia probe failed for streaming: {}", err))?;
let track = probed
.format
.default_track()
.ok_or_else(|| "Symphonia: no supported audio tracks in stream".to_string())?;
let track_id = track.id;
let codec_params = track.codec_params.clone();
let mut decoder = get_codecs()
.make(&codec_params, &DecoderOptions::default())
.map_err(|err| format!("Symphonia decoder init failed for streaming: {}", err))?;
let mut sample_rate = 0;
let mut channels = 0u16;
let mut samples: Vec<i16> = Vec::new();
loop {
let packet = match probed.format.next_packet() {
Ok(packet) => packet,
Err(SymphoniaError::IoError(e)) => {
// Check if we got WouldBlock (not enough data buffered yet)
if e.kind() == std::io::ErrorKind::WouldBlock {
// Wait for more data
std::thread::sleep(Duration::from_millis(10));
continue;
}
// EOF or other IO error - we're done
break;
}
Err(err) => return Err(format!("Symphonia read error in stream: {}", err)),
};
if packet.track_id() != track_id {
continue;
}
match decoder.decode(&packet) {
Ok(audio_buf) => {
let spec = *audio_buf.spec();
if sample_rate == 0 {
sample_rate = spec.rate;
channels = spec.channels.count() as u16;
}
let mut sample_buf = SampleBuffer::<i16>::new(audio_buf.frames() as u64, spec);
sample_buf.copy_interleaved_ref(audio_buf);
samples.extend_from_slice(sample_buf.samples());
}
Err(SymphoniaError::DecodeError(_)) => continue,
Err(SymphoniaError::ResetRequired) => {
decoder.reset();
continue;
}
Err(err) => return Err(format!("Symphonia decode error in stream: {}", err)),
}
}
if samples.is_empty() || sample_rate == 0 || channels == 0 {
return Err("Symphonia streaming decode produced no audio".to_string());
}
Ok(AudioSpecs {
samples: SamplesBuffer::new(channels, sample_rate, samples),
sample_rate,
channels,
})
}
fn is_isomp4(data: &[u8]) -> bool {
if data.len() < 12 {
return false;
@@ -1294,7 +1204,7 @@ impl Player {
let volume = thread_state.volume.load(Ordering::SeqCst) as f32 / 100.0;
engine.set_volume(volume);
// Wait for minimum buffer before decoding
// Wait for minimum buffer before starting playback
log::info!("Streaming: waiting for initial buffer...");
let start_wait = Instant::now();
let max_wait = Duration::from_secs(30);
@@ -1308,25 +1218,38 @@ impl Player {
return;
}
log::info!("Streaming: initial buffer ready, starting decode...");
let buffer_wait_ms = start_wait.elapsed().as_millis();
log::info!(
"Streaming: initial buffer ready in {}ms, creating incremental decoder...",
buffer_wait_ms
);
// Decode from streaming source (pass reference, it uses create_reader internally)
let decoded = match decode_streaming_source(&source) {
Ok(specs) => specs,
// Create incremental streaming source - this starts playback IMMEDIATELY
// while continuing to decode/download in background
let incremental_source = match IncrementalStreamingSource::new(source.clone()) {
Ok(s) => s,
Err(e) => {
log::error!("Failed to decode streaming audio: {}", e);
log::error!("Failed to create incremental streaming source: {}", e);
return;
}
};
let actual_duration = decoded.samples
.total_duration()
.map(|d| d.as_secs())
.unwrap_or(0);
thread_state.duration.store(actual_duration, Ordering::SeqCst);
// Verify sample rate/channels match what we expected
let actual_sr = incremental_source.get_sample_rate();
let actual_ch = incremental_source.get_channels();
if actual_sr != sample_rate || actual_ch != channels {
log::warn!(
"Streaming: detected format {}Hz/{}ch differs from expected {}Hz/{}ch",
actual_sr, actual_ch, sample_rate, channels
);
}
// The samples are already a SamplesBuffer which implements Source
let source_to_play: Box<dyn Source<Item = i16> + Send> = Box::new(decoded.samples);
// Duration unknown until download completes - estimate from content-length if available
// For now, set to 0 and update when known
thread_state.duration.store(0, Ordering::SeqCst);
// Box the incremental source to match the expected type
let source_to_play: Box<dyn Source<Item = i16> + Send> = Box::new(incremental_source);
if let Err(e) = engine.append(source_to_play) {
log::error!("Failed to append streaming source to engine: {}", e);
return;
@@ -1338,10 +1261,9 @@ impl Player {
thread_state.start_playback_timer(0);
*current_engine = Some(engine);
// Note: We don't store streaming data in current_audio_data since it's handled differently
log::info!(
"Audio thread: streaming playback started, duration: {}s",
actual_duration
"Audio thread: streaming playback STARTED in {}ms (incremental decode active)",
start_wait.elapsed().as_millis()
);
}
AudioCommand::Pause => {
+249 -7
View File
@@ -1,8 +1,11 @@
//! Buffered media source for streaming playback.
//!
//! Wraps an async HTTP response to provide a synchronous `Read + Seek` interface
//! required by rodio/symphonia decoders. This allows playback to start before
//! the entire file is downloaded.
//! Provides two main components:
//! 1. `BufferedMediaSource` - Wraps an async HTTP response to provide a synchronous
//! `Read + Seek` interface required by symphonia decoders.
//! 2. `IncrementalStreamingSource` - A rodio Source that decodes audio packets
//! incrementally as they become available, allowing playback to start before
//! the entire file is downloaded.
//!
//! # Design
//!
@@ -20,10 +23,20 @@
//!
//! Communication uses `Mutex` + `Condvar` for blocking synchronization.
use std::collections::VecDeque;
use std::io::{Error as IoError, ErrorKind, Read, Result as IoResult, Seek, SeekFrom};
use std::sync::{Arc, Condvar, Mutex};
use std::time::Duration;
use symphonia::core::io::MediaSource;
use rodio::Source;
use symphonia::core::audio::SampleBuffer;
use symphonia::core::codecs::{Decoder, DecoderOptions};
use symphonia::core::errors::Error as SymphoniaError;
use symphonia::core::formats::{FormatOptions, FormatReader};
use symphonia::core::io::{MediaSource, MediaSourceStream};
use symphonia::core::meta::MetadataOptions;
use symphonia::core::probe::Hint;
use symphonia::default::{get_codecs, get_probe};
/// Configuration for the streaming buffer
#[derive(Debug, Clone)]
@@ -37,8 +50,10 @@ pub struct StreamingConfig {
impl Default for StreamingConfig {
fn default() -> Self {
Self {
// 2MB default - enough for format headers and some audio data
initial_buffer_bytes: 2 * 1024 * 1024,
// 512KB default - enough for format headers and ~2-5 seconds of audio
// This allows playback to start quickly while still having enough
// buffer to handle network jitter
initial_buffer_bytes: 512 * 1024,
// 100MB max buffer
max_buffer_bytes: 100 * 1024 * 1024,
}
@@ -51,12 +66,22 @@ impl StreamingConfig {
/// For Hi-Res FLAC at 192kHz/24bit stereo, bitrate is roughly 9.2 Mbps
/// We estimate ~1MB per second as a conservative approximation
pub fn from_seconds(seconds: u8) -> Self {
let bytes = (seconds as usize) * 1024 * 1024;
// Minimum 256KB to ensure format detection works
let bytes = ((seconds as usize) * 1024 * 1024).max(256 * 1024);
Self {
initial_buffer_bytes: bytes,
max_buffer_bytes: 100 * 1024 * 1024,
}
}
/// Create a minimal config for fastest startup
/// Uses smallest buffer that still allows format detection (~256KB)
pub fn fast_start() -> Self {
Self {
initial_buffer_bytes: 256 * 1024,
max_buffer_bytes: 100 * 1024 * 1024,
}
}
}
/// Internal state shared between reader and writer
@@ -401,6 +426,223 @@ impl BufferWriter {
}
}
// =============================================================================
// IncrementalStreamingSource - A rodio Source that decodes on-demand
// =============================================================================
/// A rodio Source that decodes audio packets incrementally from a BufferedMediaSource.
///
/// This allows playback to start immediately after the initial buffer is filled,
/// while the rest of the file continues downloading in the background.
///
/// The source maintains an internal queue of decoded samples and decodes more
/// packets on-demand as samples are consumed.
pub struct IncrementalStreamingSource {
/// Sample rate of the audio
sample_rate: u32,
/// Number of channels
channels: u16,
/// Queue of decoded samples ready to play
sample_queue: VecDeque<i16>,
/// The format reader (demuxer)
format: Box<dyn FormatReader>,
/// The audio decoder
decoder: Box<dyn Decoder>,
/// Track ID we're decoding
track_id: u32,
/// Whether we've reached end of stream
finished: bool,
/// Number of packets decoded (for stats)
packets_decoded: u64,
/// Reference to the buffered source (for cache retrieval after playback)
buffered_source: Arc<BufferedMediaSource>,
}
impl IncrementalStreamingSource {
/// Create a new incremental streaming source.
///
/// This initializes the symphonia decoder and prepares for incremental decoding.
/// The BufferedMediaSource should already have its initial buffer filled.
///
/// Returns the source along with detected sample_rate and channels.
pub fn new(
buffered_source: Arc<BufferedMediaSource>,
) -> Result<Self, String> {
// Create a reader from the buffered source
let reader = buffered_source.create_reader();
let media_source = Box::new(reader) as Box<dyn MediaSource>;
let mss = MediaSourceStream::new(media_source, Default::default());
let mut hint = Hint::new();
hint.with_extension("flac"); // Most Qobuz Hi-Res is FLAC
let format_opts = FormatOptions {
enable_gapless: true,
..Default::default()
};
let metadata_opts: MetadataOptions = Default::default();
let probed = get_probe()
.format(&hint, mss, &format_opts, &metadata_opts)
.map_err(|err| format!("Symphonia probe failed for streaming: {}", err))?;
let track = probed
.format
.default_track()
.ok_or_else(|| "Symphonia: no supported audio tracks in stream".to_string())?;
let track_id = track.id;
let codec_params = track.codec_params.clone();
// Extract sample rate and channels from codec params
let sample_rate = codec_params
.sample_rate
.ok_or_else(|| "No sample rate in codec params".to_string())?;
let channels = codec_params
.channels
.map(|c| c.count() as u16)
.unwrap_or(2);
let decoder = get_codecs()
.make(&codec_params, &DecoderOptions::default())
.map_err(|err| format!("Symphonia decoder init failed for streaming: {}", err))?;
log::info!(
"IncrementalStreamingSource initialized: {}Hz, {} channels",
sample_rate,
channels
);
Ok(Self {
sample_rate,
channels,
sample_queue: VecDeque::with_capacity(sample_rate as usize * channels as usize), // ~1s buffer
format: probed.format,
decoder,
track_id,
finished: false,
packets_decoded: 0,
buffered_source,
})
}
/// Get the sample rate
pub fn get_sample_rate(&self) -> u32 {
self.sample_rate
}
/// Get the number of channels
pub fn get_channels(&self) -> u16 {
self.channels
}
/// Get reference to the buffered source for cache retrieval
pub fn buffered_source(&self) -> &Arc<BufferedMediaSource> {
&self.buffered_source
}
/// Decode more packets to fill the sample queue.
///
/// This is called when the sample queue is running low.
/// It will decode packets until the queue has at least `min_samples` or EOF is reached.
fn decode_more(&mut self, min_samples: usize) {
if self.finished {
return;
}
while self.sample_queue.len() < min_samples {
let packet = match self.format.next_packet() {
Ok(packet) => packet,
Err(SymphoniaError::IoError(ref e)) if e.kind() == std::io::ErrorKind::WouldBlock => {
// Not enough data buffered yet - wait briefly and retry
// This happens when playback catches up with download
std::thread::sleep(Duration::from_millis(5));
continue;
}
Err(SymphoniaError::IoError(_)) => {
// EOF or other IO error
log::info!(
"IncrementalStreamingSource: EOF reached after {} packets",
self.packets_decoded
);
self.finished = true;
return;
}
Err(err) => {
log::error!("Symphonia read error in stream: {}", err);
self.finished = true;
return;
}
};
if packet.track_id() != self.track_id {
continue;
}
match self.decoder.decode(&packet) {
Ok(audio_buf) => {
let spec = *audio_buf.spec();
let mut sample_buf = SampleBuffer::<i16>::new(audio_buf.frames() as u64, spec);
sample_buf.copy_interleaved_ref(audio_buf);
// Add samples to queue
self.sample_queue.extend(sample_buf.samples().iter().copied());
self.packets_decoded += 1;
}
Err(SymphoniaError::DecodeError(e)) => {
log::warn!("Decode error (skipping packet): {}", e);
continue;
}
Err(SymphoniaError::ResetRequired) => {
self.decoder.reset();
continue;
}
Err(err) => {
log::error!("Symphonia decode error: {}", err);
self.finished = true;
return;
}
}
}
}
}
impl Source for IncrementalStreamingSource {
fn current_frame_len(&self) -> Option<usize> {
// We don't know frame boundaries in the queue
None
}
fn channels(&self) -> u16 {
self.channels
}
fn sample_rate(&self) -> u32 {
self.sample_rate
}
fn total_duration(&self) -> Option<Duration> {
// We don't know total duration until download completes
// Could estimate from content-length if available
None
}
}
impl Iterator for IncrementalStreamingSource {
type Item = i16;
fn next(&mut self) -> Option<Self::Item> {
// If queue is running low, decode more
// Keep at least 0.5 seconds of audio buffered
let min_buffer = (self.sample_rate as usize * self.channels as usize) / 2;
if self.sample_queue.len() < min_buffer {
self.decode_more(min_buffer);
}
self.sample_queue.pop_front()
}
}
#[cfg(test)]
mod tests {
use super::*;