audio-validation 0.3.2__tar.gz → 0.3.4__tar.gz

{audio_validation-0.3.2 → audio_validation-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: audio_validation
-Version: 0.3.2
+Version: 0.3.4
 Summary: Tools for validating audio data, including feature extraction and visualization.
 Maintainer-email: Hubert Stepniewski <hubert.stepniewski@int2code.com>, Marcin Tomiczek <marcin.tomiczek@int2code.com>, Piotr Sznapka <piotr.sznapka@int2code.com>
 License: MIT License

{audio_validation-0.3.2 → audio_validation-0.3.4}/RELEASE_NOTES.md

@@ -1,3 +1,11 @@
+### 0.3.4
+
+[PATCH] Add non-blocking chunk validation skip to transition conditions.
+
+### 0.3.3
+
+[PATCH] Add absolute timestamps in audio chunks.
+
 ### 0.3.2
 
 [PATCH] Add warmup chunks, improve failure reporting.

{audio_validation-0.3.2 → audio_validation-0.3.4}/src/audio_validation/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.2'
-__version_tuple__ = version_tuple = (0, 3, 2)
+__version__ = version = '0.3.4'
+__version_tuple__ = version_tuple = (0, 3, 4)
 
-__commit_id__ = commit_id = 'ge32c5a61b'
+__commit_id__ = commit_id = 'gc5b840998'

{audio_validation-0.3.2 → audio_validation-0.3.4}/src/audio_validation/continous_validation/models.py

@@ -5,12 +5,15 @@ short-lived (only referenced by the bounded retention buffer).
 """
 
 from dataclasses import dataclass, field
+from datetime import datetime
 from textwrap import indent
 from typing import List, Optional
 
 import numpy as np
 import pandas as pd
 
+WALL_CLOCK_UNKNOWN = "-"
+
 
 def format_timestamp(seconds: float) -> str:
     """Render *seconds* since capture start as ``HH:MM:SS.mmm``.
@@ -28,6 +31,18 @@ def format_timestamp(seconds: float) -> str:
     return f"{hours:02d}:{minutes:02d}:{secs:02d}.{millis:03d}"
 
 
+def format_wall_clock(timestamp: Optional[datetime]) -> str:
+    """Render an absolute chunk timestamp as ``YYYY-MM-DD HH:MM:SS.mmm``.
+
+    :param timestamp: Absolute chunk time, or ``None`` when not recorded.
+    :return: Millisecond-precision timestamp, or ``"-"`` when *timestamp* is
+        ``None``.
+    """
+    if timestamp is None:
+        return WALL_CLOCK_UNKNOWN
+    return timestamp.strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
+
+
 @dataclass
 class RawChunk:
     """One contiguous captured block, tagged with its position in the run.
@@ -36,12 +51,15 @@ class RawChunk:
     :ivar start_s: Start time in seconds relative to capture start.
     :ivar end_s: End time in seconds relative to capture start.
     :ivar samples: 2-D array ``(n_samples, channels)``.
+    :ivar start_timestamp: Absolute wall-clock time of the chunk's first sample,
+        or ``None`` when the capture start time is unknown.
     """
 
     index: int
     start_s: float
     end_s: float
     samples: np.ndarray
+    start_timestamp: Optional[datetime] = None
 
 
 @dataclass
@@ -63,6 +81,8 @@ class ChunkMetrics:
     :ivar reason: Single-line failure summary, suited to a table column.
     :ivar detail: Multiline failure report with the per-check channel tables;
         never put this in a DataFrame cell, log it separately.
+    :ivar start_timestamp: Absolute wall-clock time of the chunk's first sample,
+        or ``None`` when the capture start time is unknown.
     """
 
     index: int
@@ -72,6 +92,7 @@ class ChunkMetrics:
     reason: str
     detail: str = ""
     channels: List[ChannelMetric] = field(default_factory=list)
+    start_timestamp: Optional[datetime] = None
 
 
 @dataclass
@@ -124,7 +145,8 @@ class ValidationResult:  # pylint: disable=too-many-instance-attributes
         multiline table crammed into one cell wrecks the table layout.
 
         ``start``/``end`` are rendered as ``HH:MM:SS.mmm`` offsets from capture
-        start rather than raw seconds.
+        start rather than raw seconds; ``timestamp`` is the absolute wall-clock
+        time of the chunk's first sample, for lining chunks up with DUT logs.
         """
         rows = []
         for metric in self.metrics:
@@ -132,6 +154,7 @@ class ValidationResult:  # pylint: disable=too-many-instance-attributes
                 rows.append(
                     {
                         "index": metric.index,
+                        "timestamp": format_wall_clock(metric.start_timestamp),
                         "start": format_timestamp(metric.start_s),
                         "end": format_timestamp(metric.end_s),
                         "ch": ch_idx,

{audio_validation-0.3.2 → audio_validation-0.3.4}/src/audio_validation/continous_validation/validator.py

@@ -19,7 +19,7 @@ import threading
 from concurrent.futures import CancelledError, Future, ThreadPoolExecutor
 from concurrent.futures import wait as futures_wait
 from dataclasses import dataclass, replace
-import time
+from datetime import datetime, timedelta
 from typing import Callable, List, Optional
 
 from scipy.io import wavfile
@@ -149,6 +149,11 @@ class ContinuousAudioValidator:  # pylint: disable=too-many-instance-attributes
         self._error: Optional[str] = None
 
         self._captured_time_s = 0.0
+        self._capture_started_at: Optional[datetime] = None
+        self._chunks_read = 0
+        self._skip_from_index = 0
+        self._skip_until_index: Optional[int] = None
+        self._pending_criteria: Optional[AudioCriteria] = None
         self._consec_fail = 0
         self._stop_requested = False
         self._play_stopped = False
@@ -180,19 +185,57 @@ class ContinuousAudioValidator:  # pylint: disable=too-many-instance-attributes
         empty_criteria = AudioCriteria()  # no check is performed
         self.update_criteria(empty_criteria)
 
+    def skip_chunks(
+        self, skip_chunks: int, criteria: Optional[AudioCriteria] = None
+    ) -> int:
+        """Leave the next *skip_chunks* chunks unevaluated, then swap criteria.
+
+        **Returns immediately** — the caller keeps the audio timeline running and
+        is free to disturb the DUT (install a network delay, power-cycle, change
+        volume, ...) *inside* the skip window it just opened. The window and the
+        criteria swap are honoured by the analysis worker, keyed on chunk index,
+        so a queue backlog cannot shift them.
+
+        :param skip_chunks: Number of chunks to leave unevaluated. ``0`` skips
+            nothing and applies *criteria* to the next analysed chunk.
+        :param criteria: Criteria to activate once the window has passed.
+            ``None`` keeps the active criteria (skip only).
+        :return: Index of the first chunk that will be evaluated again.
+        """
+        with self._state_lock:
+            # The chunk being captured right now is ``_chunks_read``; the change
+            # the caller is about to make lands inside it, so it is skipped too.
+            first_skipped = self._chunks_read
+            skip_until = first_skipped + max(skip_chunks, 0)
+            if self._skip_until_index is not None:
+                # Extending an open window: keep its (earlier) lower bound.
+                first_skipped = self._skip_from_index
+                skip_until = max(skip_until, self._skip_until_index)
+            self._skip_from_index = first_skipped
+            self._skip_until_index = skip_until
+            if criteria is not None:
+                self._pending_criteria = criteria
+        swap = "; criteria swapped afterwards" if criteria is not None else ""
+        if skip_until > first_skipped:
+            logger.info(
+                "Skipping checks for chunks %d-%d%s",
+                first_skipped,
+                skip_until - 1,
+                swap,
+            )
+        else:
+            logger.info("Skipping no chunks%s", swap)
+        return skip_until
+
     def skip_check_and_update_criteria(
         self, skip_chunks: int, criteria: AudioCriteria
     ) -> None:
-        """Set the active criteria to an empty one, effectively skipping checks.
+        """Skip given number of chunks and then set the new criteria. Thread-safe.
 
-        Then update the criteria to the provided one after a short delay.
-        This is useful for skipping checks during a known transient event.
+        :param skip_chunks: Number of chunks to leave unevaluated.
+        :param criteria: Criteria to activate once the window has passed.
         """
-        self.set_empty_criteria()
-        time.sleep(
-            skip_chunks * self._cfg.chunk_s
-        )  # skip the specified number of chunks
-        self.update_criteria(criteria)
+        self.skip_chunks(skip_chunks, criteria)
 
     def snapshot_metrics(self) -> List[ChunkMetrics]:
         """Return a copy of the metrics timeline collected so far."""
@@ -258,6 +301,17 @@ class ContinuousAudioValidator:  # pylint: disable=too-many-instance-attributes
             except Exception:  # pylint: disable=broad-except
                 logger.exception("recorder.stop_capture() raised")
 
+    def _chunk_timestamp(self, chunk_start_s: float) -> Optional[datetime]:
+        """Return the absolute time of a chunk starting *chunk_start_s* into the run.
+        Chunk timestamps are derived from capture start plus the sample-count offset,
+
+        :param chunk_start_s: Chunk start offset from capture start, in seconds.
+        :return: Wall-clock chunk start, or ``None`` before capture started.
+        """
+        if self._capture_started_at is None:
+            return None
+        return self._capture_started_at + timedelta(seconds=chunk_start_s)
+
     def _read_chunks(self) -> None:
         """
         Read chunks from the recorder and put them into the queue.
@@ -266,6 +320,7 @@ class ContinuousAudioValidator:  # pylint: disable=too-many-instance-attributes
         total_samples = 0
         try:
             self._recorder.start_capture()
+            self._capture_started_at = datetime.now()
             while not self._stop.is_set() and not self._abort.is_set():
 
                 if (
@@ -293,9 +348,17 @@ class ContinuousAudioValidator:  # pylint: disable=too-many-instance-attributes
                 chunk_end_s = total_samples / self._sample_rate
                 self._captured_time_s = chunk_end_s
                 self._enqueue_chunk(
-                    RawChunk(chunk_idx, chunk_start_s, chunk_end_s, chunk)
+                    RawChunk(
+                        chunk_idx,
+                        chunk_start_s,
+                        chunk_end_s,
+                        chunk,
+                        self._chunk_timestamp(chunk_start_s),
+                    )
                 )
                 chunk_idx += 1
+                with self._state_lock:
+                    self._chunks_read = chunk_idx
         except Exception as exc:  # pylint: disable=broad-except
             with self._state_lock:
                 self._error = f"{type(exc).__name__}: {exc}"
@@ -330,15 +393,48 @@ class ContinuousAudioValidator:  # pylint: disable=too-many-instance-attributes
         finally:
             self._abort.set()
 
-    def _validate_chunk_features(self, chunk: RawChunk) -> None:
-        """Compute features for *chunk*, evaluate criteria, and arm on failure.
+    def _criteria_for_chunk(self, chunk_index: int) -> tuple[AudioCriteria, bool]:
+        """Resolve the criteria to use for *chunk_index* and whether to skip it.
+
+        Closes a :meth:`skip_chunks` window and applies its deferred criteria as
+        soon as a chunk from beyond the window arrives.
+
+        The window is bounded on both sides: chunks already queued when
+        :meth:`skip_chunks` was called before the caller's change, so they are
+        still evaluated against the criteria that were active while they were
+        captured.
 
-        Warm-up chunks still get their features computed and recorded — they
-        belong in the metrics table and the WAV — but no check is run against
-        them, so they can neither fail the run nor break a failing streak.
+        :param chunk_index: Index of the chunk about to be analysed.
+        :return: Tuple of the active criteria and whether the chunk is inside a
+            skip window (features computed, no checks run).
         """
+        applied = False
         with self._state_lock:
+            if self._skip_until_index is None:
+                return self._criteria, False
+            if chunk_index < self._skip_until_index:
+                return self._criteria, chunk_index >= self._skip_from_index
+            self._skip_until_index = None
+            if self._pending_criteria is not None:
+                self._criteria = self._pending_criteria
+                self._pending_criteria = None
+                applied = True
             criteria = self._criteria
+        if applied:
+            logger.info(
+                "Skip window over, new criteria active from chunk %d", chunk_index
+            )
+        return criteria, False
+
+    def _validate_chunk_features(self, chunk: RawChunk) -> None:
+        """Compute features for *chunk*, evaluate criteria, and arm on failure.
+
+        Warm-up chunks and chunks inside a :meth:`skip_chunks` window still get
+        their features computed and recorded — they belong in the metrics table
+        and the WAV — but no check is run against them, so they can neither fail
+        the run nor break a failing streak.
+        """
+        criteria, skipped = self._criteria_for_chunk(chunk.index)
 
         use_fft = criteria.expected_frequencies is not None
         features = AudioFeatures.compute(
@@ -351,14 +447,23 @@ class ContinuousAudioValidator:  # pylint: disable=too-many-instance-attributes
             activity_threshold=criteria.silence_rms_threshold,
         )
         warmup = chunk.index < self._cfg.warmup_chunks
-        verdict = ChunkVerdict() if warmup else evaluate_chunk(features, criteria)
+        if warmup:
+            not_evaluated = "warm-up (not evaluated)"
+        elif skipped:
+            not_evaluated = "skipped (criteria transition)"
+        else:
+            not_evaluated = ""
+        verdict = (
+            ChunkVerdict() if not_evaluated else evaluate_chunk(features, criteria)
+        )
 
         metric = ChunkMetrics(
             index=chunk.index,
             start_s=chunk.start_s,
             end_s=chunk.end_s,
+            start_timestamp=chunk.start_timestamp,
             ok=verdict.ok,
-            reason="warm-up (not evaluated)" if warmup else verdict.summary,
+            reason=not_evaluated or verdict.summary,
             detail=verdict.detail,
             channels=[
                 ChannelMetric(

{audio_validation-0.3.2 → audio_validation-0.3.4}/src/audio_validation.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: audio_validation
-Version: 0.3.2
+Version: 0.3.4
 Summary: Tools for validating audio data, including feature extraction and visualization.
 Maintainer-email: Hubert Stepniewski <hubert.stepniewski@int2code.com>, Marcin Tomiczek <marcin.tomiczek@int2code.com>, Piotr Sznapka <piotr.sznapka@int2code.com>
 License: MIT License

{audio_validation-0.3.2 → audio_validation-0.3.4}/src/audio_validation.egg-info/scm_file_list.json

@@ -1,38 +1,38 @@
 {
   "files": [
-    "tox.ini",
-    "requirements.txt",
-    "requirements-test.txt",
-    "requirements-dev.txt",
-    "pyproject.toml",
+    ".github/workflows/code_checker.yml",
+    ".github/workflows/publish_to_pypi.yml",
+    ".github/workflows/unit_tests.yml",
+    ".gitignore",
     ".pylint_ignore",
     "LICENSE",
-    "RELEASE_NOTES.md",
     "README.md",
-    ".gitignore",
-    ".github/workflows/code_checker.yml",
-    ".github/workflows/unit_tests.yml",
-    ".github/workflows/publish_to_pypi.yml",
-    "tests/__init__.py",
-    "tests/test_template.py",
+    "RELEASE_NOTES.md",
+    "_ci/is_dev_version.sh",
+    "docs/Makefile",
+    "docs/conf.py",
+    "docs/contribute.rst",
+    "docs/index.rst",
+    "docs/installation.rst",
+    "docs/release_notes.rst",
+    "docs/requirements.txt",
+    "docs/tutorials/index.rst",
+    "pyproject.toml",
+    "requirements-dev.txt",
+    "requirements-test.txt",
+    "requirements.txt",
     "src/audio_validation/__init__.py",
     "src/audio_validation/audio_features.py",
     "src/audio_validation/audio_verification.py",
-    "src/audio_validation/utils/audio_generation.py",
     "src/audio_validation/continous_validation/criteria.py",
+    "src/audio_validation/continous_validation/models.py",
     "src/audio_validation/continous_validation/plots.py",
-    "src/audio_validation/continous_validation/validator.py",
     "src/audio_validation/continous_validation/recorder.py",
     "src/audio_validation/continous_validation/retention.py",
-    "src/audio_validation/continous_validation/models.py",
-    "docs/requirements.txt",
-    "docs/index.rst",
-    "docs/conf.py",
-    "docs/release_notes.rst",
-    "docs/Makefile",
-    "docs/contribute.rst",
-    "docs/installation.rst",
-    "docs/tutorials/index.rst",
-    "_ci/is_dev_version.sh"
+    "src/audio_validation/continous_validation/validator.py",
+    "src/audio_validation/utils/audio_generation.py",
+    "tests/__init__.py",
+    "tests/test_template.py",
+    "tox.ini"
   ]
 }

audio_validation-0.3.4/src/audio_validation.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.3.4",
+  "distance": 0,
+  "node": "gc5b840998cee69b55769a7f8f90667191a0749af",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-08-12"
+}

audio_validation-0.3.2/src/audio_validation.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "0.3.2",
-  "distance": 0,
-  "node": "ge32c5a61ba2f0d187518620dd508fd43f8e2e24f",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-08-06"
-}