slm_open_api_package 0.2.12__tar.gz → 0.2.14__tar.gz

{slm_open_api_package-0.2.12 → slm_open_api_package-0.2.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: slm_open_api_package
-Version: 0.2.12
+Version: 0.2.14
 Summary: Add your description here
 Author: Sofus Vingaard
 Author-email: Sofus Vingaard <sofus.krebsvingaard@hbkworld.com>
@@ -82,6 +82,8 @@ except KeyboardInterrupt:
 
 JSON and CSV publish complete snapshots in a background worker, at most once per second while new data arrives, rather than rewriting the file for every sample. They retain records in memory and preserve their existing layouts; full-history snapshot costs still grow with recording length. Construct `JsonDataHandler(path, snapshot_interval=2.0)` or `CsvDataHandler(path, snapshot_interval=2.0)` and attach it with `setDataHandler()` to use a different interval. `close()` waits for the worker and saves all remaining records; background write failures are reported on subsequent updates or during the final flush. WAV still appends each audio chunk without buffering the recording in memory. `stopStream()` stops the measurement, closes saving handlers, and removes the device stream. Measurement saving formats are `"csv"` and `"json"`; audio uses `"wav"`. File extensions are added automatically.
 
+If snapshot replacement raises `PermissionError` (for example, Windows prevents replacing a CSV open in Excel), the worker warns once per failure episode, continues buffering records, and retries at the next snapshot interval. Close the program holding the output file open, or correct its permissions, to allow saving to resume. A lock still present at `close()` raises an error; unsaved records only remain in memory while the process is alive. Other write failures remain fatal to snapshot saving. `stopStream()` still attempts device cleanup if closing the saving handler fails.
+
 ## Multiple Sequences
 
 Based on [example_multi.py](src/slm_api/example_multi.py), use `mode="multi"` for several enabled broadband sequences in a single stream:
@@ -161,6 +163,8 @@ except KeyboardInterrupt:
 
 The matching `flac` form uses `SequenceIdEnums.FLACSignal.value` and `mode="flac"`. Audio setup is enabled by the handler. The SLM can take a few seconds to initialize audio recording when its quality setting changes.
 
+For GUI plots, check the read-only `streamer.audio_ready` property in the plot's timer callback before reading `DataBuffer`. It becomes `True` after the first nonempty decoded audio has been written to the buffer, without requiring a custom `DataHandler` or event. It resets when the streaming session starts, when a stop is requested, and when the session exits. This is a startup gate, not a full-window availability check or a detector for stalled streams. Keep running the GUI event loop while waiting for audio.
+
 WAV saving appends decoded mono samples as recording happens, updating the file header after each chunk so the file is readable before shutdown. Saving happens after decoding and calibration to pascals. Samples are divided by the fixed full-scale pressure `calibrationFactor * (2**23 - 1)` and saved as `PCM_24`, not peak-normalized per chunk. The filename includes `_fullscale-<value>Pa.wav`. To recover pressure values, multiply floating-point samples read from the WAV by that full-scale value (within 24-bit quantization accuracy). Samples outside the calibrated range produce a clipping warning; this scaling cannot repair upstream clipping. MP3 uses the decoded sample rate; the current FLAC decoder uses 65536 Hz. JSON and CSV saving are rejected for audio modes, and WAV saving is rejected for measurement modes. Run `uv sync` to install the `soundfile` dependency used for progressive WAV writing.
 
 To attach the handler directly, use `WavDataHandler("saved_data/audio", sample_rate=65536, full_scale_pa=calibrationFactor * (2**23 - 1))` from `slm_api.helpers.data_handler`, using the device's actual calibration factor. You can instead supply `sample_rate` and `full_scale_pa` to `handle()`; the stream supplies both automatically. Call `close()` when finished. Use a separate WAV handler and output path for each device. Existing float32 pressure WAVs are unchanged; this format applies to new recordings.

{slm_open_api_package-0.2.12 → slm_open_api_package-0.2.14}/README.md

@@ -60,6 +60,8 @@ except KeyboardInterrupt:
 
 JSON and CSV publish complete snapshots in a background worker, at most once per second while new data arrives, rather than rewriting the file for every sample. They retain records in memory and preserve their existing layouts; full-history snapshot costs still grow with recording length. Construct `JsonDataHandler(path, snapshot_interval=2.0)` or `CsvDataHandler(path, snapshot_interval=2.0)` and attach it with `setDataHandler()` to use a different interval. `close()` waits for the worker and saves all remaining records; background write failures are reported on subsequent updates or during the final flush. WAV still appends each audio chunk without buffering the recording in memory. `stopStream()` stops the measurement, closes saving handlers, and removes the device stream. Measurement saving formats are `"csv"` and `"json"`; audio uses `"wav"`. File extensions are added automatically.
 
+If snapshot replacement raises `PermissionError` (for example, Windows prevents replacing a CSV open in Excel), the worker warns once per failure episode, continues buffering records, and retries at the next snapshot interval. Close the program holding the output file open, or correct its permissions, to allow saving to resume. A lock still present at `close()` raises an error; unsaved records only remain in memory while the process is alive. Other write failures remain fatal to snapshot saving. `stopStream()` still attempts device cleanup if closing the saving handler fails.
+
 ## Multiple Sequences
 
 Based on [example_multi.py](src/slm_api/example_multi.py), use `mode="multi"` for several enabled broadband sequences in a single stream:
@@ -139,6 +141,8 @@ except KeyboardInterrupt:
 
 The matching `flac` form uses `SequenceIdEnums.FLACSignal.value` and `mode="flac"`. Audio setup is enabled by the handler. The SLM can take a few seconds to initialize audio recording when its quality setting changes.
 
+For GUI plots, check the read-only `streamer.audio_ready` property in the plot's timer callback before reading `DataBuffer`. It becomes `True` after the first nonempty decoded audio has been written to the buffer, without requiring a custom `DataHandler` or event. It resets when the streaming session starts, when a stop is requested, and when the session exits. This is a startup gate, not a full-window availability check or a detector for stalled streams. Keep running the GUI event loop while waiting for audio.
+
 WAV saving appends decoded mono samples as recording happens, updating the file header after each chunk so the file is readable before shutdown. Saving happens after decoding and calibration to pascals. Samples are divided by the fixed full-scale pressure `calibrationFactor * (2**23 - 1)` and saved as `PCM_24`, not peak-normalized per chunk. The filename includes `_fullscale-<value>Pa.wav`. To recover pressure values, multiply floating-point samples read from the WAV by that full-scale value (within 24-bit quantization accuracy). Samples outside the calibrated range produce a clipping warning; this scaling cannot repair upstream clipping. MP3 uses the decoded sample rate; the current FLAC decoder uses 65536 Hz. JSON and CSV saving are rejected for audio modes, and WAV saving is rejected for measurement modes. Run `uv sync` to install the `soundfile` dependency used for progressive WAV writing.
 
 To attach the handler directly, use `WavDataHandler("saved_data/audio", sample_rate=65536, full_scale_pa=calibrationFactor * (2**23 - 1))` from `slm_api.helpers.data_handler`, using the device's actual calibration factor. You can instead supply `sample_rate` and `full_scale_pa` to `handle()`; the stream supplies both automatically. Call `close()` when finished. Use a separate WAV handler and output path for each device. Existing float32 pressure WAVs are unchanged; this format applies to new recordings.

{slm_open_api_package-0.2.12 → slm_open_api_package-0.2.14}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "slm_open_api_package"
-version = "0.2.12"
+version = "0.2.14"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.12"

{slm_open_api_package-0.2.12 → slm_open_api_package-0.2.14}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "slm_open_api_package"
-version = "0.2.12"
+version = "0.2.14"
 description = "Add your description here"
 readme = "README.md"
 authors = [

{slm_open_api_package-0.2.12 → slm_open_api_package-0.2.14}/src/slm_api/fast_log_example.py

@@ -53,8 +53,8 @@ FAST_LOGGING_INTERVAL_MS = FastLogInterval.interval_1000ms.value
 SEQUENCE_ID = SequenceIdEnums.FastLAF.value
 
 class PrintDataHandler(DataHandler):
-    def handle(self, timestamp, name, local, value, unit, **data):
-        print(f"{timestamp} {name} ({local}):  {value:7.2f} {unit}")
+    def handle(self, timestamp, name, local, value, **data):
+        print(f"{timestamp} {name} ({local}):  {value:7.2f}")
 
 
 
@@ -170,7 +170,7 @@ if __name__ == "__main__":
                                       sequenceID = SEQUENCE_ID, 
                                       mode="fast_logging",
                                       fast_logging_interval=FAST_LOGGING_INTERVAL_MS,
-                                      saving="json",
+                                      saving="csv",
                                       saving_path=f"./saved_data/{filename}",
                                       time=True)
         streamer.setDataHandler(PrintDataHandler())

{slm_open_api_package-0.2.12 → slm_open_api_package-0.2.14}/src/slm_api/helpers/data_handler.py

@@ -53,7 +53,10 @@ class _BufferedFileDataHandler(DataHandler):
             if self._closed:
                 return
             if self._write_error is not None:
-                raise RuntimeError("Background snapshot saving failed") from self._write_error
+                raise RuntimeError(
+                    f"Background snapshot saving failed for {self._path}: "
+                    f"{type(self._write_error).__name__}: {self._write_error}"
+                ) from self._write_error
             if "values" in data:
                 data["values"] = [float(v) for v in data["values"]]
             elif "samples" in data:
@@ -67,9 +70,20 @@ class _BufferedFileDataHandler(DataHandler):
                 self._worker.start()
 
     def _run_snapshots(self):
+        permission_error_reported = False
         while not self._stop_event.wait(self._snapshot_interval):
             try:
                 self._flush_snapshot()
+                permission_error_reported = False
+            except PermissionError as error:
+                if not permission_error_reported:
+                    warnings.warn(
+                        f"Cannot replace snapshot {self._path}: {error}. "
+                        "Close any program holding the file open. Records remain "
+                        "buffered in memory and saving will retry automatically.",
+                        RuntimeWarning,
+                    )
+                    permission_error_reported = True
             except Exception as error:
                 with self._lock:
                     self._write_error = error
@@ -110,8 +124,14 @@ class _BufferedFileDataHandler(DataHandler):
             self._closed = True
             self._stop_event.set()
             worker = self._worker
+
         if worker is not None:
-            worker.join()
+            worker.join(timeout=5.0)
+            if worker.is_alive():
+                raise TimeoutError(
+                    f"Snapshot writer did not stop: {self._path}"
+                )
+
         self._flush_snapshot()
 
     def _group_records(self, records=None):

{slm_open_api_package-0.2.12 → slm_open_api_package-0.2.14}/src/slm_api/helpers/stream_handlers.py

@@ -221,6 +221,7 @@ class WebXiStreamHandler(stream.StreamHandler):
         self.time = time
         self.screen_record = self.mode == "screen_record"
         self.image_bytes = None
+        self._audio_ready = threading.Event()
         self.fast_logging_interval = fast_logging_interval
         self.max_input = 15.6263 / np.sqrt(2)
         self._saving_handler = None
@@ -237,6 +238,22 @@ class WebXiStreamHandler(stream.StreamHandler):
             self.tmpFileSM = TmpfileStateMachine()
         self.streamInit()
 
+    @property
+    def audio_ready(self):
+        """Whether nonempty decoded audio has reached the buffer in this session."""
+        return self._audio_ready.is_set()
+
+    async def runStream(self):
+        self._audio_ready.clear()
+        try:
+            await super().runStream()
+        finally:
+            self._audio_ready.clear()
+
+    def request_stop(self):
+        super().request_stop()
+        self._audio_ready.clear()
+
     def setDataHandler(self, data_handler):
         """Attach a DataHandler (see data_handler.py) before calling startStream().
         Without one, WebXiStreamHandler stays silent and does nothing with decoded values.
@@ -263,6 +280,10 @@ class WebXiStreamHandler(stream.StreamHandler):
             raise ValueError(
                 "FLAC and MP3 streams must be saved as WAV, not JSON or CSV."
             )
+        if (self.mp3 or self.flac) and self.time == True:
+                    raise ValueError(
+                        "Time is not supported for flac and mp3."
+                    )
         if self.mp3 or self.flac:
             quality_setting = "AudioRecordingListenQuality" if self.mp3 else "AudioRecordingAnalysisQuality"
             response = https_requests.put(self.host, f"/WebXi/Applications/SLM/setup/{quality_setting}", json=1)
@@ -421,7 +442,7 @@ class WebXiStreamHandler(stream.StreamHandler):
         unit = self.sequence.get("Unit", "dB re 20uPa")
         for sample_index, value in enumerate(samples):
             timestamp = self._time_prefix(start + sample_index * self.fast_logging_interval_s)
-            self._handle_data(timestamp=timestamp, name=name, local=local, value=value, unit=unit)
+            self._handle_data(timestamp=timestamp, name=name, local=local, value=value)
 
     def _msg_func_screen_record(self, message):
         package = webxi_stream.WebxiStream.from_bytes(message)
@@ -447,7 +468,11 @@ class WebXiStreamHandler(stream.StreamHandler):
                 else:
                     decoded = flac2samples.decode(block, self.calibrationFactor)
                     sample_rate = 2 ** 16
+                if len(decoded) == 0:
+                    continue
                 DataBuffer.append(decoded)
+                if not self._stop_requested:
+                    self._audio_ready.set()
                 self._handle_data(
                     samples=decoded, sample_rate=sample_rate,
                     full_scale_pa=self.calibrationFactor * (2 ** 23 - 1),
@@ -457,6 +482,8 @@ class WebXiStreamHandler(stream.StreamHandler):
                 print(f"TotalTime: {total}")
 
     def stopStream(self):
-        if self.data_handler is not None and hasattr(self.data_handler, "close"):
-            self.data_handler.close()
-        super().stopStream()
+        try:
+            if self.data_handler is not None and hasattr(self.data_handler, "close"):
+                self.data_handler.close()
+        finally:
+            super().stopStream()