python-aaronia 0.11.1__tar.gz → 0.11.2__tar.gz

{python_aaronia-0.11.1 → python_aaronia-0.11.2}/CHANGELOG.md

@@ -4,6 +4,48 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [v0.11.2] - 2026-09-11
+
+### Added
+- **`capture_sample_rate_hz()`** on `SpectranSource`, the rate counterpart of
+  `capture_frequency_hz()`. It describes the samples a read just returned, not
+  the newest rate the background reader has seen, so a consumer that resamples
+  or sizes an FFT from it agrees with the block in its hands.
+
+### Fixed
+- **A read no longer spans a sample-rate change.** The retune boundary rule
+  from 0.11.0 covered frequency only, so a rate change could land mid-block —
+  with the returned samples labelled at whichever rate the reader had reached
+  by then. Reads now stop at a rate change too, holding the rest for the next
+  call, and queued samples keep the rate they were captured at.
+- **The HTTP read timeout is a budget for the whole block, not per receive.**
+  A read asking for a large block against a slow stream could wait the full
+  timeout repeatedly and take far longer than the caller allowed.
+- **File tuning setters no longer rewrite the recording's metadata.**
+  `set_center_frequency_hz`, `set_sample_rate_hz` and `set_reference_level_dbm`
+  overwrote the config on a file source, so the playback then described itself
+  by what was asked for rather than by what was recorded.
+
+### Fixed (futuresdr source)
+- **The buffer pool is bounded by bytes, not by a fixed count.** It held 256
+  buffers of `block_size` regardless of size — 256 MiB at a 1 Mi-sample block.
+  Depth is now derived from `block_size` against a 64 MiB ceiling, and a
+  `block_size` past that ceiling is rejected at `start()` instead of consuming
+  the memory.
+- **A refused channel override is no longer retried forever.** A retune the
+  device rejected slept 100 ms and tried the same frequency again, indefinitely.
+  The rejected frequency is now remembered and skipped until the override
+  changes. A retune failure on the *commanded* frequency, which has no such
+  fallback, propagates rather than spinning.
+- **A parked viewer keeps receiving after its dwell expires.** Reads for an
+  override channel were budgeted from the hop deadline, which is already in the
+  past once parked — so the read budget was zero and the viewer starved.
+- **Packets carry the metadata of the samples in them.** They reported the
+  commanded frequency and the source's current rate; they now carry the
+  captured pair, and samples whose frequency cannot be confirmed are dropped
+  rather than mislabelled.
+- **Returning a buffer to a full pool cannot block the pump.**
+
 ## [v0.11.1] - 2026-09-10
 
 ### Fixed

{python_aaronia-0.11.1 → python_aaronia-0.11.2}/Cargo.lock

@@ -3092,7 +3092,7 @@ dependencies = [
 
 [[package]]
 name = "python-aaronia"
-version = "0.11.1"
+version = "0.11.2"
 dependencies = [
  "arrow",
  "num-complex",
@@ -3621,7 +3621,7 @@ checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 
 [[package]]
 name = "sdr-aaronia-rs"
-version = "0.11.1"
+version = "0.11.2"
 dependencies = [
  "anyhow",
  "bitflags 2.13.1",

{python_aaronia-0.11.1 → python_aaronia-0.11.2}/Cargo.toml

@@ -2,7 +2,7 @@
 name = "sdr-aaronia-rs"
 description = "Unified Rust interface for Aaronia Spectran Spectrum Analyzers / SDRs, featuring Python bindings, a SoapySDR plugin, HTTP streaming, and native SDK support."
 license = "GPL-3.0-or-later"
-version = "0.11.1"
+version = "0.11.2"
 edition = "2024"
 repository = "https://github.com/isaacbentley/sdr-aaronia-rs"
 readme = "README.md"

{python_aaronia-0.11.1 → python_aaronia-0.11.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aaronia
-Version: 0.11.1
+Version: 0.11.2
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)

{python_aaronia-0.11.1 → python_aaronia-0.11.2}/README.md

@@ -93,6 +93,8 @@ tokio = { version = "1.43", features = ["rt-multi-thread", "macros"] }
 # sdr-aaronia-rs = { version = "0.8", features = ["native-sdk", "futuresdr"] }
 ```
 
+HTTP reads use one timeout budget for the entire requested block and return partial data at a timeout, frequency change, sample-rate change, or detected gap. `capture_frequency_hz()` and `capture_sample_rate_hz()` describe the returned samples even when newer packets are queued. File tuning setters preserve the recording's metadata.
+
 ## Quickstart
 
 Set the RF parameters and read:

{python_aaronia-0.11.1 → python_aaronia-0.11.2}/python-aaronia/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "python-aaronia"
-version = "0.11.1"
+version = "0.11.2"
 edition = "2024"
 description = "Python bindings for sdr-aaronia-rs (Aaronia SPECTRAN V6 SDR source)"
 license = "GPL-3.0-or-later"

{python_aaronia-0.11.1 → python_aaronia-0.11.2}/src/sdr_source_impl.rs

@@ -129,13 +129,41 @@ const EMPTY_READ_BAILOUT: u32 = 16;
 /// should see EOF rather than be silently fed an empty channel.
 const READ_ERROR_BAILOUT: u32 = 5;
 
+fn accepted_override(requested: Option<f64>, rejected: Option<u64>) -> Option<f64> {
+    requested.filter(|f| f.is_finite() && *f > 0.0 && rejected != Some(f.to_bits()))
+}
+
+fn read_budget(parked: bool, deadline: Instant) -> Duration {
+    if parked {
+        Duration::from_millis(50)
+    } else {
+        deadline.saturating_duration_since(Instant::now())
+    }
+}
+
+fn packet_frequency(captured_hz: f64, commanded_hz: f64) -> Option<f64> {
+    if captured_hz > 0.0 {
+        ((captured_hz - commanded_hz).abs() <= STALE_TOLERANCE_HZ).then_some(captured_hz)
+    } else {
+        Some(commanded_hz)
+    }
+}
+
 impl SdrSource for SpectranSdrSource {
     fn start(
         self: Box<Self>,
         config: SourceConfig,
         advice: Arc<dyn DwellAdvice>,
     ) -> Result<SdrHandle, SdrError> {
-        let (tx, receiver) = channel::bounded::<IqPacket>(1024);
+        let block_size = self.block_size.max(1024);
+        if block_size > 8 * 1024 * 1024 {
+            return Err(SdrError::BadConfig(
+                "block_size exceeds the 64 MiB sample-buffer limit".into(),
+            ));
+        }
+        let pool_depth =
+            (64 * 1024 * 1024 / (block_size * std::mem::size_of::<Complex32>())).clamp(1, 64);
+        let (tx, receiver) = channel::bounded::<IqPacket>(pool_depth);
         let stop_flag = Arc::new(AtomicBool::new(false));
         let stop_thread = stop_flag.clone();
 
@@ -243,12 +271,9 @@ impl SdrSource for SpectranSdrSource {
                     let hopping =
                         !channels_hz.is_empty() && !matches!(backend, SpectranBackend::File(_));
 
-                    let (pool_tx, pool_rx) = channel::bounded::<Vec<Complex32>>(256);
-                    for _ in 0..256 {
-                        let _ = pool_tx.send(Vec::with_capacity(block_size));
-                    }
+                    let (pool_tx, pool_rx) = channel::bounded::<Vec<Complex32>>(pool_depth);
 
-                    if hopping {
+                    let pump_result = if hopping {
                         info!(
                             "Aaronia hop mode: {} channels, dwell {:?}-{:?} (adaptive={})",
                             channels_hz.len(),
@@ -268,7 +293,6 @@ impl SdrSource for SpectranSdrSource {
                             &pool_tx,
                         )
                         .await
-                        .map_err(|e| Error::Config(e.to_string()))?;
                     } else {
                         single_channel_pump(
                             &mut source,
@@ -281,11 +305,10 @@ impl SdrSource for SpectranSdrSource {
                             &pool_tx,
                         )
                         .await
-                        .map_err(|e| Error::Config(e.to_string()))?;
-                    }
+                    };
 
                     let _ = source.stop_streaming().await;
-                    Ok::<_, Error>(())
+                    pump_result
                 })?;
                             Ok(())
                         })() {
@@ -340,13 +363,23 @@ async fn single_channel_pump(
 ) -> Result<()> {
     let mut empty_reads = 0u32;
     let mut current_freq = center_frequency_hz;
+    let file_playback = source.source_info().source_type == SourceType::File;
+    let mut rejected_override = None;
     while !stop_thread.load(Ordering::SeqCst) {
-        let target = advice.channel_override().unwrap_or(center_frequency_hz);
+        let requested = if file_playback {
+            None
+        } else {
+            accepted_override(advice.channel_override(), rejected_override)
+        };
+        let target = requested.unwrap_or(center_frequency_hz);
         if (target - current_freq).abs() > 1.0 {
             if let Err(e) = source.set_center_frequency_hz(target).await {
                 warn!("Aaronia retune to {:.3} MHz failed: {e}", target / 1e6);
-                tokio::time::sleep(Duration::from_millis(100)).await;
-                continue;
+                if requested.is_some() {
+                    rejected_override = Some(target.to_bits());
+                    continue;
+                }
+                return Err(e);
             }
             current_freq = target;
             drain_during_settle(source, block_size, RETUNE_SETTLE).await;
@@ -357,8 +390,12 @@ async fn single_channel_pump(
             .unwrap_or_else(|_| Vec::with_capacity(block_size));
         raw_buffer.clear();
 
-        let n = match source.read_samples(&mut raw_buffer, block_size).await {
+        let n = match source
+            .read_samples_deadline(&mut raw_buffer, block_size, Duration::from_millis(50))
+            .await
+        {
             Ok(v) => v,
+            Err(Error::Io(ref e)) if e.kind() == std::io::ErrorKind::TimedOut => continue,
             Err(e) => {
                 warn!("Aaronia read_samples error: {e} — stopping");
                 break;
@@ -374,13 +411,19 @@ async fn single_channel_pump(
             continue;
         }
         empty_reads = 0;
+        let Some(packet_center) = packet_frequency(source.capture_frequency_hz(), current_freq)
+        else {
+            raw_buffer.clear();
+            let _ = pool_tx.try_send(raw_buffer);
+            continue;
+        };
         // The rate is read per packet: on HTTP the rate the device actually
         // streams is only known once packets flow, and may not be the one
         // asked for (it snaps to the decimation ladder).
         let pkt = IqPacket {
             samples: crate::sdr_source::PooledIqBuffer::new_pooled(raw_buffer, pool_tx.clone()),
-            center_frequency_hz: current_freq,
-            sample_rate_hz: source.sample_rate_hz() as f32,
+            center_frequency_hz: packet_center,
+            sample_rate_hz: source.capture_sample_rate_hz() as f32,
             overrun: source.take_overrun(),
         };
         if tx.send(pkt).is_err() {
@@ -426,12 +469,13 @@ async fn hop_pump(
     // by contrast is per-hop on purpose: a quiet channel isn't a
     // dead source, and hopping is the cure.
     let mut read_errors = 0u32;
+    let mut rejected_override = None;
     while !stop_thread.load(Ordering::SeqCst) {
         // A live `/video` viewer wants a specific channel: park there,
         // bypassing the hop list, until the override changes or clears.
         // `channel_idx` only advances on a genuine hop below, so hopping
         // resumes exactly where it left off once the viewer disconnects.
-        let override_freq = advice.channel_override();
+        let override_freq = accepted_override(advice.channel_override(), rejected_override);
         let channel = override_freq.unwrap_or_else(|| {
             let c = channels_hz[channel_idx];
             channel_idx = (channel_idx + 1) % channels_hz.len();
@@ -444,6 +488,10 @@ async fn hop_pump(
         if channel != current_channel {
             if let Err(e) = source.set_center_frequency_hz(channel).await {
                 warn!("Aaronia retune to {:.3} MHz failed: {e}", channel / 1e6);
+                if override_freq.is_some() {
+                    rejected_override = Some(channel.to_bits());
+                    continue;
+                }
                 consecutive_retune_failures += 1;
                 if consecutive_retune_failures >= READ_ERROR_BAILOUT {
                     return Err(Error::Config(format!(
@@ -473,22 +521,10 @@ async fn hop_pump(
             if stop_thread.load(Ordering::SeqCst) {
                 break;
             }
-            let still_overridden = advice.channel_override() == Some(channel);
-            if override_freq.is_some() {
-                // Parked here for live view: hold regardless of the dwell
-                // deadline, but break out the moment the viewer's channel
-                // changes or they disconnect so the outer loop can retune
-                // or resume hopping.
-                if !still_overridden {
-                    break;
-                }
-            } else if still_overridden {
-                // A viewer just requested this exact channel while we were
-                // still mid-hop-dwell here — break out now (rather than
-                // waiting for the normal dwell deadline) so the next outer
-                // iteration parks on it promptly.
+            if accepted_override(advice.channel_override(), rejected_override) != override_freq {
                 break;
-            } else if Instant::now() >= deadline {
+            }
+            if override_freq.is_none() && Instant::now() >= deadline {
                 break;
             }
 
@@ -506,7 +542,7 @@ async fn hop_pump(
             // channel stays open instead of closing. Returning whatever
             // arrived by the deadline keeps the hop cadence intact, and
             // the `n == 0` branch below already handles an empty read.
-            let remaining = deadline.saturating_duration_since(Instant::now());
+            let remaining = read_budget(override_freq.is_some(), deadline);
             let n = match source
                 .read_samples_deadline(&mut raw_buffer, block_size, remaining)
                 .await
@@ -553,24 +589,20 @@ async fn hop_pump(
             // that carry no per-packet frequency (file, native SDK), so
             // those fall back to the commanded channel.
             let captured_hz = source.capture_frequency_hz();
-            if captured_hz > 0.0 && (captured_hz - channel).abs() > STALE_TOLERANCE_HZ {
+            let Some(packet_center) = packet_frequency(captured_hz, channel) else {
                 // Pre-retune samples. Discard rather than mislabel them;
                 // the settle is short and the next read is clean. Hand
                 // the buffer back to the pool by the same route a
                 // delivered packet takes — dropping it here would shrink
                 // the pool by one on every hop.
                 raw_buffer.clear();
-                let _ = pool_tx.send(raw_buffer);
+                let _ = pool_tx.try_send(raw_buffer);
                 continue;
-            }
+            };
             let pkt = IqPacket {
                 samples: crate::sdr_source::PooledIqBuffer::new_pooled(raw_buffer, pool_tx.clone()),
-                center_frequency_hz: if captured_hz > 0.0 {
-                    captured_hz
-                } else {
-                    channel
-                },
-                sample_rate_hz: source.sample_rate_hz() as f32,
+                center_frequency_hz: packet_center,
+                sample_rate_hz: source.capture_sample_rate_hz() as f32,
                 overrun: source.take_overrun(),
             };
             if tx.send(pkt).is_err() {
@@ -612,3 +644,31 @@ async fn drain_during_settle(
         }
     }
 }
+
+#[cfg(test)]
+mod review_regressions {
+    use super::*;
+    #[test]
+    fn parked_reads_continue_after_the_original_dwell_expires() {
+        let expired = Instant::now() - Duration::from_secs(1);
+        assert!(!read_budget(true, expired).is_zero());
+        assert!(read_budget(false, expired).is_zero());
+    }
+    #[test]
+    fn single_channel_packets_reject_stale_frequency_metadata() {
+        assert_eq!(packet_frequency(433e6, 915e6), None);
+        assert_eq!(packet_frequency(915e6 - 500.0, 915e6), Some(915e6 - 500.0));
+        assert_eq!(packet_frequency(0.0, 915e6), Some(915e6));
+    }
+    #[test]
+    fn override_can_move_to_another_channel_or_clear() {
+        assert_ne!(None, accepted_override(Some(915e6), None));
+        assert_ne!(Some(915e6), accepted_override(Some(433e6), None));
+        assert_ne!(Some(915e6), accepted_override(None, None));
+        assert_eq!(None, accepted_override(Some(f64::NAN), None));
+        assert_eq!(
+            None,
+            accepted_override(Some(915e6), Some(915e6_f64.to_bits()))
+        );
+    }
+}

{python_aaronia-0.11.1 → python_aaronia-0.11.2}/src/unified_source.rs

@@ -421,6 +421,7 @@ pub struct SpectranSource {
     /// Capture frequency of whatever is sitting in `sample_buffer`, so a
     /// leftover tail is never merged into a read at another frequency.
     sample_buffer_freq_hz: f64,
+    sample_buffer_rate_hz: f64,
     /// Whether the stashed samples in `sample_buffer` begin immediately
     /// after a break in the stream.
     ///
@@ -436,6 +437,7 @@ pub struct SpectranSource {
     /// what the stream itself reported, not what was requested. Read it
     /// with [`SpectranSource::capture_frequency_hz`].
     last_read_frequency_hz: f64,
+    last_read_sample_rate_hz: f64,
 
     // Source-specific implementations
     #[cfg(all(
@@ -462,7 +464,7 @@ pub struct SpectranSource {
     /// task's `DropDetector` observed a timestamp gap ending at (or
     /// before) that chunk — see `pending_overrun`.
     #[allow(clippy::type_complexity)]
-    http_receiver: Option<tokio::sync::mpsc::Receiver<(Vec<Complex32>, bool, u64, i64, f64)>>,
+    http_receiver: Option<tokio::sync::mpsc::Receiver<(Vec<Complex32>, bool, u64, i64, f64, f64)>>,
     /// Background task draining the HTTP `/stream` connection. Held so it
     /// can be aborted on `stop_streaming` / drop — otherwise it lingers
     /// parked on `next().await` (holding the open connection, so the
@@ -585,8 +587,10 @@ impl SpectranSource {
             source_type: SourceType::Http, // Will be updated during detection
             sample_buffer: VecDeque::new(),
             sample_buffer_freq_hz: 0.0,
+            sample_buffer_rate_hz: 0.0,
             sample_buffer_after_gap: false,
             last_read_frequency_hz: 0.0,
+            last_read_sample_rate_hz: 0.0,
 
             #[cfg(all(
                 feature = "native-sdk",
@@ -1006,6 +1010,7 @@ impl SpectranSource {
                                         cumulative_drops,
                                         timestamp_ns,
                                         packet_center_hz,
+                                        packet.sdr_config.sample_rate_hz,
                                     ))
                                     .await
                                     .is_err()
@@ -1329,12 +1334,11 @@ impl SpectranSource {
     /// runtime should do the same, or call it from a plain thread.
     /// Append up to `max_samples` samples, giving up at `timeout`.
     ///
-    /// A read never spans a retune. When the capture frequency changes
-    /// part-way through, the samples captured before it are returned and
-    /// the rest are held for the next call, so one read is always
-    /// describable by a single frequency —
-    /// [`Self::capture_frequency_hz`]. Expect a short read around a
-    /// retune; that was already possible on a timeout.
+    /// A read never spans a frequency or sample-rate change. Samples
+    /// captured before the change are returned and the rest are held for
+    /// the next call. [`Self::capture_frequency_hz`] and
+    /// [`Self::capture_sample_rate_hz`] describe the returned samples.
+    /// Expect a short read at either boundary, as on a timeout.
     pub async fn read_samples_deadline(
         &mut self,
         buffer: &mut Vec<Complex32>,
@@ -1371,11 +1375,23 @@ impl SpectranSource {
                 } else {
                     0.0
                 };
+                let mut batch_rate_hz = if from_buffer > 0 {
+                    self.sample_buffer_rate_hz
+                } else {
+                    0.0
+                };
                 let mut collected = from_buffer;
                 while collected < max_samples {
                     let recv = tokio::time::timeout_at(deadline, receiver.recv()).await;
                     match recv {
-                        Ok(Some((mut new_samples, dropped, cum_drops, ts_ns, pkt_freq_hz))) => {
+                        Ok(Some((
+                            mut new_samples,
+                            dropped,
+                            cum_drops,
+                            ts_ns,
+                            pkt_freq_hz,
+                            pkt_rate_hz,
+                        ))) => {
                             if dropped {
                                 if collected > 0 {
                                     // Put the gap on a boundary rather
@@ -1388,6 +1404,7 @@ impl SpectranSource {
                                     // its state between reads.
                                     self.sample_buffer.extend(new_samples);
                                     self.sample_buffer_freq_hz = pkt_freq_hz;
+                                    self.sample_buffer_rate_hz = pkt_rate_hz;
                                     self.sample_buffer_after_gap = true;
                                     self.cumulative_drops = cum_drops;
                                     self.last_timestamp_ns = ts_ns;
@@ -1400,24 +1417,29 @@ impl SpectranSource {
                             }
                             self.cumulative_drops = cum_drops;
                             self.last_timestamp_ns = ts_ns;
-                            // A retune landed mid-read. Stash the whole
-                            // packet with its own frequency and return
+                            // A frequency or rate change landed mid-read. Stash
+                            // the packet with its own metadata and return
                             // what we have: mixing the two would produce
                             // a buffer that is partly stale and wholly
                             // mislabelled, which is the failure this
                             // frequency tag exists to prevent.
                             if collected > 0
-                                && pkt_freq_hz > 0.0
-                                && batch_freq_hz > 0.0
-                                && (pkt_freq_hz - batch_freq_hz).abs() > 1.0
+                                && ((pkt_freq_hz > 0.0
+                                    && batch_freq_hz > 0.0
+                                    && (pkt_freq_hz - batch_freq_hz).abs() > 1.0)
+                                    || pkt_rate_hz != batch_rate_hz)
                             {
                                 self.sample_buffer.extend(new_samples);
                                 self.sample_buffer_freq_hz = pkt_freq_hz;
+                                self.sample_buffer_rate_hz = pkt_rate_hz;
                                 break;
                             }
                             if batch_freq_hz == 0.0 {
                                 batch_freq_hz = pkt_freq_hz;
                             }
+                            if batch_rate_hz == 0.0 {
+                                batch_rate_hz = pkt_rate_hz;
+                            }
                             let needed = max_samples - collected;
                             if new_samples.len() <= needed {
                                 collected += new_samples.len();
@@ -1427,6 +1449,7 @@ impl SpectranSource {
                                 buffer.extend(new_samples.drain(0..needed));
                                 self.sample_buffer.extend(new_samples);
                                 self.sample_buffer_freq_hz = batch_freq_hz;
+                                self.sample_buffer_rate_hz = batch_rate_hz;
                             }
                         }
                         Ok(None) => {
@@ -1452,6 +1475,9 @@ impl SpectranSource {
                 if batch_freq_hz > 0.0 {
                     self.last_read_frequency_hz = batch_freq_hz;
                 }
+                if collected > 0 {
+                    self.last_read_sample_rate_hz = batch_rate_hz;
+                }
                 Ok(buffer.len() - start_len)
             }
             #[cfg(all(
@@ -1491,7 +1517,7 @@ impl SpectranSource {
                     }
                 }
             }
-            _ => self.read_samples(buffer, max_samples).await,
+            _ => Box::pin(self.read_samples(buffer, max_samples)).await,
         }
     }
 
@@ -1525,128 +1551,8 @@ impl SpectranSource {
             )))]
             SourceType::NativeSdk => Err(Error::Config("Native SDK not available".to_string())),
             SourceType::Http => {
-                let start_len = buffer.len();
-                // Read before the `&mut self` borrow of `http_receiver`.
-                let read_timeout = self.config.read_timeout;
-                let receiver = self
-                    .http_receiver
-                    .as_mut()
-                    .ok_or_else(|| Error::Config("HTTP receiver not initialized".to_string()))?;
-
-                // 1. Drain from internal buffer first
-                let from_buffer = self.sample_buffer.len().min(max_samples);
-                if from_buffer > 0 {
-                    buffer.extend(self.sample_buffer.drain(0..from_buffer));
-                    // These samples were stashed because they follow a
-                    // gap; this is the read that begins with them, so
-                    // this is the read that must be told.
-                    if self.sample_buffer_after_gap {
-                        self.pending_overrun = true;
-                        self.sample_buffer_after_gap = false;
-                    }
-                }
-
-                // 2. If we need more, receive from channel
-                let mut batch_freq_hz = if from_buffer > 0 {
-                    self.sample_buffer_freq_hz
-                } else {
-                    0.0
-                };
-                let mut collected = from_buffer;
-                while collected < max_samples {
-                    // If buffer is empty, try to receive more samples from the channel
-                    match tokio::time::timeout(read_timeout, receiver.recv()).await {
-                        Ok(Some((mut new_samples, dropped, cum_drops, ts_ns, pkt_freq_hz))) => {
-                            if dropped {
-                                if collected > 0 {
-                                    // Put the gap on a boundary rather
-                                    // than inside this block: stash the
-                                    // post-gap chunk and let the next
-                                    // read start with it, carrying the
-                                    // flag. Same shape as the retune
-                                    // boundary below, for the same
-                                    // reason — a consumer can only reset
-                                    // its state between reads.
-                                    self.sample_buffer.extend(new_samples);
-                                    self.sample_buffer_freq_hz = pkt_freq_hz;
-                                    self.sample_buffer_after_gap = true;
-                                    self.cumulative_drops = cum_drops;
-                                    self.last_timestamp_ns = ts_ns;
-                                    break;
-                                }
-                                // Nothing collected yet, so this chunk
-                                // opens the block and the gap really is
-                                // immediately before it.
-                                self.pending_overrun = true;
-                            }
-                            self.cumulative_drops = cum_drops;
-                            self.last_timestamp_ns = ts_ns;
-                            // See `read_samples_deadline`: a read never
-                            // spans a retune.
-                            if collected > 0
-                                && pkt_freq_hz > 0.0
-                                && batch_freq_hz > 0.0
-                                && (pkt_freq_hz - batch_freq_hz).abs() > 1.0
-                            {
-                                self.sample_buffer.extend(new_samples);
-                                self.sample_buffer_freq_hz = pkt_freq_hz;
-                                break;
-                            }
-                            if batch_freq_hz == 0.0 {
-                                batch_freq_hz = pkt_freq_hz;
-                            }
-                            let needed = max_samples - collected;
-                            if new_samples.len() <= needed {
-                                collected += new_samples.len();
-                                buffer.append(&mut new_samples);
-                            } else {
-                                collected += needed;
-                                buffer.extend(new_samples.drain(0..needed));
-                                // `sample_buffer` is a VecDeque, so it can't
-                                // accept `Vec::append` — extend from the
-                                // remainder instead.
-                                self.sample_buffer.extend(new_samples);
-                                self.sample_buffer_freq_hz = batch_freq_hz;
-                            }
-                        }
-                        Ok(None) => {
-                            // Reader task gone (server closed the stream or
-                            // the parser gave up). Returning Ok(0) forever
-                            // here made every consumer spin on a dead
-                            // stream with no way to distinguish "no data
-                            // yet" from "stream is dead" — surface it.
-                            if collected == 0 {
-                                return Err(Error::StreamClosed(
-                                    "HTTP sample stream closed (reader task ended)".to_string(),
-                                ));
-                            }
-                            break;
-                        }
-                        Err(_) => {
-                            // Samples already moved into `buffer` are not
-                            // put back, so a timeout after a partial block
-                            // returns that block, as `read_samples_deadline`
-                            // does. Erroring here lost everything collected
-                            // so far without flagging a gap.
-                            if collected > 0 {
-                                warn!(
-                                    "Timeout waiting for HTTP samples; returning {} of {} requested",
-                                    collected, max_samples
-                                );
-                                break;
-                            }
-                            error!("Timeout waiting for HTTP samples.");
-                            return Err(Error::Io(std::io::Error::new(
-                                std::io::ErrorKind::TimedOut,
-                                "Timeout waiting for HTTP samples",
-                            )));
-                        }
-                    }
-                }
-                if batch_freq_hz > 0.0 {
-                    self.last_read_frequency_hz = batch_freq_hz;
-                }
-                Ok(buffer.len() - start_len)
+                self.read_samples_deadline(buffer, max_samples, self.config.read_timeout)
+                    .await
             }
             SourceType::File => {
                 if let Some(ref mut source) = self.file_source {
@@ -1703,6 +1609,18 @@ impl SpectranSource {
         self.last_read_frequency_hz
     }
 
+    /// Sample rate of the most recently returned samples. HTTP reads keep
+    /// this metadata with queued samples and stop at a rate change, even
+    /// when the background reader has already observed a newer rate.
+    /// Other backends, or HTTP packets without a rate, use `sample_rate_hz`.
+    pub fn capture_sample_rate_hz(&self) -> f64 {
+        if self.last_read_sample_rate_hz.is_finite() && self.last_read_sample_rate_hz > 0.0 {
+            self.last_read_sample_rate_hz
+        } else {
+            self.sample_rate_hz()
+        }
+    }
+
     /// Number of timestamp gaps the drop detector has seen since the
     /// source was created: one per gap event, however many samples it
     /// spanned.
@@ -1904,6 +1822,9 @@ impl SpectranSource {
     ///   meaningless. Hopping orchestrators shouldn't drive a file backend,
     ///   but the no-op keeps the abstraction tidy.
     pub async fn set_center_frequency_hz(&mut self, hz: f64) -> Result<()> {
+        if self.source_type == SourceType::File {
+            return Ok(());
+        }
         match self.source_type {
             #[cfg(all(
                 feature = "native-sdk",
@@ -1966,6 +1887,9 @@ impl SpectranSource {
 
     /// Update the IQ sample rate of the running source.
     pub async fn set_sample_rate_hz(&mut self, hz: f64) -> Result<()> {
+        if self.source_type == SourceType::File {
+            return Ok(());
+        }
         // Enforce the IQ-mode constraint at runtime exactly as the
         // builder does at construction: without this, an out-of-range
         // runtime rate was shipped to the server unchecked, the request
@@ -2030,6 +1954,9 @@ impl SpectranSource {
 
     /// Update the reference level (in dBm) of the running source.
     pub async fn set_reference_level_dbm(&mut self, dbm: f64) -> Result<()> {
+        if self.source_type == SourceType::File {
+            return Ok(());
+        }
         match self.source_type {
             #[cfg(all(
                 feature = "native-sdk",
@@ -2791,8 +2718,10 @@ mod tests {
             source_type: SourceType::Http, // Will be updated
             sample_buffer: VecDeque::new(),
             sample_buffer_freq_hz: 0.0,
+            sample_buffer_rate_hz: 0.0,
             sample_buffer_after_gap: false,
             last_read_frequency_hz: 0.0,
+            last_read_sample_rate_hz: 0.0,
             #[cfg(all(
                 feature = "native-sdk",
                 any(target_os = "windows", target_os = "linux")
@@ -2875,8 +2804,10 @@ mod tests {
             source_type: SourceType::Http,
             sample_buffer: VecDeque::new(),
             sample_buffer_freq_hz: 0.0,
+            sample_buffer_rate_hz: 0.0,
             sample_buffer_after_gap: false,
             last_read_frequency_hz: 0.0,
+            last_read_sample_rate_hz: 0.0,
             #[cfg(all(
                 feature = "native-sdk",
                 any(target_os = "windows", target_os = "linux")
@@ -2911,8 +2842,10 @@ mod tests {
             source_type: SourceType::File,
             sample_buffer: VecDeque::new(),
             sample_buffer_freq_hz: 0.0,
+            sample_buffer_rate_hz: 0.0,
             sample_buffer_after_gap: false,
             last_read_frequency_hz: 0.0,
+            last_read_sample_rate_hz: 0.0,
             #[cfg(all(
                 feature = "native-sdk",
                 any(target_os = "windows", target_os = "linux")
@@ -2949,8 +2882,10 @@ mod tests {
             source_type: SourceType::NativeSdk,
             sample_buffer: VecDeque::new(),
             sample_buffer_freq_hz: 0.0,
+            sample_buffer_rate_hz: 0.0,
             sample_buffer_after_gap: false,
             last_read_frequency_hz: 0.0,
+            last_read_sample_rate_hz: 0.0,
             #[cfg(all(
                 feature = "native-sdk",
                 any(target_os = "windows", target_os = "linux")
@@ -3144,15 +3079,17 @@ mod tests {
     /// tests. Factored out because three of them build the same thing
     /// and a new field otherwise has to be added in every copy.
     fn http_test_source(
-        chunk_rx: tokio::sync::mpsc::Receiver<(Vec<Complex32>, bool, u64, i64, f64)>,
+        chunk_rx: tokio::sync::mpsc::Receiver<(Vec<Complex32>, bool, u64, i64, f64, f64)>,
     ) -> SpectranSource {
         SpectranSource {
             config: SpectranConfig::default(),
             source_type: SourceType::Http,
             sample_buffer: VecDeque::new(),
             sample_buffer_freq_hz: 0.0,
+            sample_buffer_rate_hz: 0.0,
             sample_buffer_after_gap: false,
             last_read_frequency_hz: 0.0,
+            last_read_sample_rate_hz: 0.0,
             #[cfg(all(
                 feature = "native-sdk",
                 any(target_os = "windows", target_os = "linux")
@@ -3173,6 +3110,88 @@ mod tests {
         }
     }
 
+    #[tokio::test]
+    async fn queued_samples_keep_their_rate_and_reads_stop_at_rate_changes() {
+        let (tx, rx) = tokio::sync::mpsc::channel(4);
+        let mut source = http_test_source(rx);
+        // The producer has already seen 2 MS/s while 1 MS/s data is queued.
+        source.http_rate_bits = Some(Arc::new(std::sync::atomic::AtomicU64::new(
+            2e6_f64.to_bits(),
+        )));
+        tx.send((vec![Complex32::new(1.0, 0.0); 2], false, 0, 1, 915e6, 1e6))
+            .await
+            .unwrap();
+        tx.send((vec![Complex32::new(2.0, 0.0); 3], false, 0, 2, 915e6, 2e6))
+            .await
+            .unwrap();
+        drop(tx);
+        let mut buffer = Vec::new();
+        assert_eq!(source.read_samples(&mut buffer, 10).await.unwrap(), 2);
+        assert_eq!(source.capture_sample_rate_hz(), 1e6);
+        assert!(buffer.iter().all(|s| s.re == 1.0));
+        buffer.clear();
+        assert_eq!(source.read_samples(&mut buffer, 2).await.unwrap(), 2);
+        assert_eq!(source.capture_sample_rate_hz(), 2e6);
+        buffer.clear();
+        assert_eq!(source.read_samples(&mut buffer, 10).await.unwrap(), 1);
+        assert_eq!(source.capture_sample_rate_hz(), 2e6);
+        assert_eq!(buffer[0].re, 2.0);
+    }
+
+    #[tokio::test]
+    async fn read_timeout_is_a_budget_for_the_whole_block() {
+        let (tx, rx) = tokio::sync::mpsc::channel(4);
+        let mut source = http_test_source(rx);
+        source.config.read_timeout = Duration::from_millis(80);
+        tx.send((vec![Complex32::new(1.0, 0.0)], false, 0, 1, 915e6, 1e6))
+            .await
+            .unwrap();
+        let feeder = tokio::spawn(async move {
+            loop {
+                tokio::time::sleep(Duration::from_millis(20)).await;
+                if tx
+                    .send((vec![Complex32::new(2.0, 0.0)], false, 0, 2, 915e6, 1e6))
+                    .await
+                    .is_err()
+                {
+                    break;
+                }
+            }
+        });
+        let mut buffer = Vec::new();
+        let result = tokio::time::timeout(
+            Duration::from_millis(400),
+            source.read_samples(&mut buffer, 100),
+        )
+        .await;
+        feeder.abort();
+        let count = result
+            .expect("each new packet restarted the timeout")
+            .unwrap();
+        assert!((1..100).contains(&count));
+        assert_eq!(buffer.len(), count);
+    }
+
+    #[tokio::test]
+    async fn file_setters_do_not_rewrite_recording_metadata() {
+        let (_tx, rx) = tokio::sync::mpsc::channel(1);
+        let mut source = http_test_source(rx);
+        source.source_type = SourceType::File;
+        let before = source.config.clone();
+        source.set_center_frequency_hz(915e6).await.unwrap();
+        source.set_sample_rate_hz(1e6).await.unwrap();
+        source.set_reference_level_dbm(-10.0).await.unwrap();
+        assert_eq!(
+            source.config.center_frequency_hz,
+            before.center_frequency_hz
+        );
+        assert_eq!(source.config.sample_rate_hz, before.sample_rate_hz);
+        assert_eq!(
+            source.config.reference_level_dbm,
+            before.reference_level_dbm
+        );
+    }
+
     /// A gap must land on a read boundary, not inside a block.
     ///
     /// Assembly used to note a dropped chunk and keep concatenating, so
@@ -3190,15 +3209,15 @@ mod tests {
         // dropped chunk. All the same frequency, so only the gap can
         // split them.
         chunk_tx
-            .send((vec![Complex32::new(1.0, 0.0)], false, 0, 1, 915e6))
+            .send((vec![Complex32::new(1.0, 0.0)], false, 0, 1, 915e6, 1e6))
             .await
             .expect("channel open");
         chunk_tx
-            .send((vec![Complex32::new(2.0, 0.0)], false, 0, 2, 915e6))
+            .send((vec![Complex32::new(2.0, 0.0)], false, 0, 2, 915e6, 1e6))
             .await
             .expect("channel open");
         chunk_tx
-            .send((vec![Complex32::new(3.0, 0.0)], true, 1, 3, 915e6))
+            .send((vec![Complex32::new(3.0, 0.0)], true, 1, 3, 915e6, 1e6))
             .await
             .expect("channel open");
         drop(chunk_tx);
@@ -3236,7 +3255,7 @@ mod tests {
         let (chunk_tx, chunk_rx) = tokio::sync::mpsc::channel(4);
         let mut source = http_test_source(chunk_rx);
         chunk_tx
-            .send((vec![Complex32::new(9.0, 0.0)], true, 1, 1, 915e6))
+            .send((vec![Complex32::new(9.0, 0.0)], true, 1, 1, 915e6, 1e6))
             .await
             .expect("channel open");
         drop(chunk_tx);
@@ -3258,11 +3277,11 @@ mod tests {
 
         // Two chunks either side of a retune, queued before any read.
         chunk_tx
-            .send((vec![Complex32::new(1.0, 0.0)], false, 0, 1, 915e6))
+            .send((vec![Complex32::new(1.0, 0.0)], false, 0, 1, 915e6, 1e6))
             .await
             .expect("channel open");
         chunk_tx
-            .send((vec![Complex32::new(2.0, 0.0)], false, 0, 2, 2_400e6))
+            .send((vec![Complex32::new(2.0, 0.0)], false, 0, 2, 2_400e6, 1e6))
             .await
             .expect("channel open");
         drop(chunk_tx);
@@ -3303,11 +3322,25 @@ mod tests {
         assert!(!source.take_overrun(), "no chunk received yet");
 
         chunk_tx
-            .send((vec![Complex32::new(1.0, 0.0)], false, 0, 123456789, 915e6))
+            .send((
+                vec![Complex32::new(1.0, 0.0)],
+                false,
+                0,
+                123456789,
+                915e6,
+                1e6,
+            ))
             .await
             .expect("channel open");
         chunk_tx
-            .send((vec![Complex32::new(2.0, 0.0)], true, 1, 123456790, 915e6))
+            .send((
+                vec![Complex32::new(2.0, 0.0)],
+                true,
+                1,
+                123456790,
+                915e6,
+                1e6,
+            ))
             .await
             .expect("channel open");
         drop(chunk_tx);