audio-validation 0.1.2__py3-none-any.whl

audio_validation/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.2'
+__version_tuple__ = version_tuple = (0, 1, 2)
+
+__commit_id__ = commit_id = None

audio_validation/audio_features.py

@@ -0,0 +1,430 @@
+"""Classes for keeping audio features and utilities to compute them from raw samples."""
+
+import logging
+import os
+import threading
+from dataclasses import dataclass
+from typing import Any, Callable, Optional, Union
+
+import numpy as np
+import pytest
+from _pytest.python_api import ApproxBase
+from matplotlib import pyplot as plt
+from scipy.fftpack import rfft, rfftfreq
+from scipy.signal import find_peaks
+from scipy.io import wavfile
+
+logger = logging.getLogger(__name__)
+save_plot_lock = threading.Lock()
+
+
+# pylint:disable=too-many-instance-attributes, too-many-locals, too-many-positional-arguments
+# pylint:disable=too-many-arguments
+@dataclass
+class ChannelFeatures:
+    """Holds calculated audio quantities for a single captured channel.
+
+    This is the per-channel building block used by :class:`AudioFeatures`.
+    Every field describes one audio channel extracted from a multi-channel capture.
+
+    :cvar samples: 1-D single-channel numpy sample array.
+    :cvar detected: ``True`` when all expected frequencies were found in the FFT.
+    :cvar failed_peaks: List of frequency strings (Hz) that did not match any
+        expected frequency; ``None`` when FFT detection was not requested.
+    :cvar peak_frequencies: 1-D array of detected FFT peak frequencies in Hz;
+        ``None`` when FFT detection was not requested.
+    :cvar peak_amplitudes: 1-D array of normalised amplitudes at each detected
+        peak; ``None`` when FFT detection was not requested.
+    :cvar rms: Root-mean-square value of the channel samples.
+    :cvar max: Maximum sample value.
+    :cvar min: Minimum sample value.
+    :cvar dbs: Level in dBFS (placeholder, populated as ``-90.0`` by default).
+    :cvar mean: Arithmetic mean of the channel samples.
+    :cvar start_audio_offset_s: Time in seconds from the start of the capture at
+        which the signal was first detected as varying; ``-1`` if the channel is
+        entirely silent.
+    """
+
+    samples: np.ndarray  # 1-D single-channel array
+    detected: bool = False
+    failed_peaks: list = None
+    peak_frequencies: list = None
+    peak_amplitudes: list = None
+    rms: float = 0
+    max: float = 0
+    min: float = 0
+    dbs: float = 0
+    mean: float = 0
+    start_audio_offset_s: int = -1
+
+    @staticmethod
+    def _compute(
+        samples: np.ndarray,
+        sample_rate: int = 48000,
+        expected_frequencies: list = None,
+        tolerance: Union[int, float] = None,
+        freq_checker: Callable = None,
+        start_audio_offset_s: Optional[float] = None,
+    ) -> "ChannelFeatures":
+        """Compute all audio features from a 1-D single-channel sample array.
+
+        Basic statistics (rms, max, min, mean) are always computed.
+        FFT-based frequency detection is performed only when all three of
+        *expected_frequencies*, *tolerance*, and *freq_checker* are provided.
+
+        :param samples: 1-D array of samples for a single channel.
+        :param sample_rate: Sample rate of the audio in Hz.
+        :param expected_frequencies: List of expected frequencies in Hz
+            (e.g. ``[400, 800]``); pass ``None`` to skip FFT detection.
+        :param tolerance: Absolute frequency tolerance in Hz.
+        :param freq_checker: Aggregation callable — typically built-in ``all``
+            or ``any``.
+        :param start_audio_offset_s: Pre-computed onset offset in seconds to
+            store directly, bypassing the internal
+            :func:`get_audio_start_offset` call.  Pass this when the caller has
+            already trimmed the samples (e.g. ``skip_latency=True`` in
+            :meth:`AudioFeatures.compute`) so that the stored offset reflects
+            the original capture position rather than a near-zero residual.
+        :return: Fully populated :class:`ChannelFeatures` instance.
+        """
+        samples_float = samples.astype(np.float64)
+        rms_val = round(np.sqrt(np.mean(samples_float**2)), 2)
+        max_val = float(np.max(samples))
+        min_val = float(np.min(samples))
+        mean_val = float(np.mean(samples))
+        if start_audio_offset_s is None:
+            start_audio_offset_s = get_audio_start_offset(samples, sample_rate)
+
+        detected = False
+        failed_peaks = None
+        peak_frequencies = None
+        peak_amplitudes = None
+
+        if (
+            expected_frequencies is not None
+            and tolerance is not None
+            and freq_checker is not None
+        ):
+            expected_freq_approx = _calculate_approx_values(
+                expected_frequencies, tolerance
+            )
+            peak_frequencies, peak_amplitudes = ChannelFeatures._calculate_ffts(
+                samples, sample_rate
+            )
+            checks = []
+            failed_peaks = []
+
+            for exp_approx in expected_freq_approx:
+                checks.append(any(pf == exp_approx for pf in peak_frequencies))
+
+            for peak_freq in peak_frequencies:
+                if peak_freq not in expected_freq_approx:
+                    failed_peaks.append(str(int(peak_freq)))
+            detected = freq_checker(checks)
+
+        return ChannelFeatures(
+            samples=samples,
+            detected=detected,
+            failed_peaks=failed_peaks,
+            peak_frequencies=peak_frequencies,
+            peak_amplitudes=peak_amplitudes,
+            rms=rms_val,
+            max=max_val,
+            min=min_val,
+            dbs=-90.0,
+            mean=mean_val,
+            start_audio_offset_s=start_audio_offset_s,
+        )
+
+    @staticmethod
+    def from_wav(
+        filepath: str, channel: int = 0, skip_first: int = 0
+    ) -> "ChannelFeatures":
+        """Build :class:`ChannelFeatures` from a single channel of a WAV file.
+
+        :param filepath: Path to the WAV file.
+        :param channel: Channel to analyse (0-based index).
+        :param skip_first: Number of samples to discard from the start.
+        :return: :class:`ChannelFeatures` with basic statistics; ``detected``
+            is ``False``.
+        """
+        _, data = wavfile.read(filepath)
+        samples = data[:, channel] if data.ndim > 1 else data
+        samples = samples[skip_first:]
+        return ChannelFeatures._compute(samples=samples)
+
+    @staticmethod
+    def _calculate_ffts(samples, sample_rate=48000, **find_peaks_kwargs):
+        """Calculate RFFT peaks from a 1-D sample array.
+
+        :param samples: 1-D array of samples for a single channel.
+        :param sample_rate: Sample rate in Hz.
+        :param find_peaks_kwargs: Forwarded to :func:`scipy.signal.find_peaks`;
+            defaults are ``prominence=0.03, height=0.3``.
+        :return: Tuple ``(frequencies, amplitudes)`` — two 1-D arrays of
+            detected peak frequencies (Hz) and their normalised amplitudes.
+        """
+        default_kwargs = {"prominence": 0.03, "height": 0.3}
+        kwargs = default_kwargs | find_peaks_kwargs
+
+        y_amplitudes = np.abs(rfft(samples))
+        y_amplitudes /= np.max(y_amplitudes)
+        x_frequencies = rfftfreq(samples.size, 1 / sample_rate)
+        p_idx, _ = find_peaks(y_amplitudes, **kwargs)
+
+        return x_frequencies[p_idx], y_amplitudes[p_idx]
+
+
+@dataclass
+class AudioFeatures:
+    """Full multi-channel audio capture result.
+
+    Combines the raw multi-channel sample array with a per-channel list of
+    :class:`ChannelFeatures` computed from those samples.
+
+    :cvar samples: 2-D numpy array of shape ``(n_samples, n_channels)`` — the
+        native sounddevice / interleaved layout as returned by ``record_audio``.
+    :cvar channel_features: One :class:`ChannelFeatures` per channel in
+        channel-index order.  Each entry may have been computed from a trimmed
+        slice of the corresponding column in ``samples`` (e.g. when
+        *skip_first* or *skip_latency* is used in :meth:`compute`).
+    """
+
+    samples: np.ndarray  # (n_samples, n_channels)
+    channel_features: list
+
+    def __len__(self) -> int:
+        """Return the number of channels."""
+        return len(self.channel_features)
+
+    def __getitem__(self, channel: int) -> ChannelFeatures:
+        """Return the :class:`ChannelFeatures` for *channel* (0-based index).
+
+        :param channel: 0-based channel index.
+        :return: :class:`ChannelFeatures` for the requested channel.
+        """
+        return self.channel_features[channel]
+
+    @staticmethod
+    def compute(
+        samples: np.ndarray,
+        sample_rate: int = 48000,
+        expected_frequencies: list = None,
+        tolerance: Union[int, float] = None,
+        freq_checker: Callable = None,
+        skip_first: int = 0,
+        skip_latency: bool = False,
+    ) -> "AudioFeatures":
+        """Build :class:`AudioFeatures` from a multi-channel sample array.
+
+        Computes :class:`ChannelFeatures` for every channel in *samples*.
+        FFT-based frequency detection is performed only when
+        *expected_frequencies*, *tolerance*, and *freq_checker* are all given.
+
+        :param samples: 2-D array of shape ``(n_samples, n_channels)`` — the
+            native sounddevice / interleaved layout.
+        :param sample_rate: Sample rate in Hz.
+        :param expected_frequencies: Per-channel expected frequencies indexed by
+            channel position, e.g. ``[[400], [800]]``; pass ``None`` to skip
+            FFT detection.
+        :param tolerance: Absolute frequency tolerance in Hz.
+        :param freq_checker: Aggregation callable — typically built-in ``all``
+            or ``any``.
+        :param skip_first: Samples to discard from the front of each channel
+            (ignored when *skip_latency* is ``True``).
+        :param skip_latency: When ``True``, auto-detect the signal start and
+            trim the silent prefix instead of using *skip_first*.
+        :return: :class:`AudioFeatures` with ``samples`` and
+            ``channel_features`` populated.
+        """
+        n_channels = samples.shape[1] if samples.ndim > 1 else 1
+        channel_features: list[ChannelFeatures] = []
+
+        for ch in range(n_channels):
+            ch_samples = samples[:, ch] if samples.ndim > 1 else samples
+
+            pre_trim_offset_s: Optional[float] = None
+            if skip_latency:
+                pre_trim_offset_s = get_audio_start_offset(ch_samples, sample_rate)
+                if pre_trim_offset_s >= 0:
+                    ch_samples = ch_samples[int(pre_trim_offset_s * sample_rate) :]
+                else:
+                    logger.debug(
+                        "skip_latency: channel %d is entirely silent, no trimming.", ch
+                    )
+            elif skip_first > 0:
+                ch_samples = ch_samples[skip_first:]
+
+            ch_freqs = (
+                expected_frequencies[ch] if expected_frequencies is not None else None
+            )
+            ch_features = ChannelFeatures._compute(  # pylint: disable=protected-access
+                samples=ch_samples,
+                sample_rate=sample_rate,
+                expected_frequencies=ch_freqs,
+                tolerance=tolerance,
+                freq_checker=freq_checker,
+                start_audio_offset_s=pre_trim_offset_s,
+            )
+            channel_features.append(ch_features)
+
+        return AudioFeatures(samples=samples, channel_features=channel_features)
+
+    @staticmethod
+    def from_wav(
+        filepath: str, channels: int = 1, skip_first: int = 0
+    ) -> "AudioFeatures":
+        """Build :class:`AudioFeatures` from a WAV file (no FFT detection).
+
+        :param filepath: Path to the WAV file.
+        :param channels: Number of channels to load (first *channels* tracks).
+        :param skip_first: Samples to discard from the front of every channel.
+        :return: :class:`AudioFeatures` with basic statistics per channel;
+            ``detected`` is ``False`` on every :class:`ChannelFeatures`.
+        """
+        _, data = wavfile.read(filepath)
+        if data.ndim == 1:
+            data = data.reshape(-1, 1)
+
+        wav_samples = data[:, :channels]
+        if skip_first:
+            wav_samples = wav_samples[skip_first:]
+        return AudioFeatures.compute(samples=wav_samples)
+
+
+def _calculate_approx_values(
+    frequencies: list[int], tolerance: int | float
+) -> list[ApproxBase]:
+    """Return pytest.approx wrappers for each frequency ± tolerance.
+
+    :param frequencies: List of frequency values in Hz to wrap in
+        :func:`pytest.approx`.
+    :param tolerance: Absolute tolerance applied symmetrically to each
+        frequency.
+    :return: List of :class:`~_pytest.python_api.ApproxBase` objects, one per
+        input frequency.
+    """
+    expected_freq_approx = list(
+        map(lambda x: pytest.approx(x, abs=tolerance), frequencies)
+    )
+    return expected_freq_approx
+
+
+def draw_plots(
+    audio: "AudioFeatures",
+    path: str,
+    chunk_size: int = 1024,
+) -> None:
+    """Draw time-domain and FFT plots for all channels and save to *path*.
+
+    Produces a grid of ``(n_channels, 2)`` subplots: the left column shows the
+    time-domain waveform and the right column shows the detected FFT peaks.
+
+    :param audio: :class:`AudioFeatures` containing per-channel features.
+    :param path: Destination file path including extension
+        (e.g. ``"output.png"``).
+    :param chunk_size: Number of samples shown on the time-domain axis.
+    """
+    n = len(audio.channel_features)
+    with save_plot_lock:
+        fig, axes = plt.subplots(n, 2, figsize=(18, 5 * n), squeeze=False)
+        for ch, feat in enumerate(audio.channel_features):
+            n_show = min(len(feat.samples), chunk_size * 10)
+
+            ax_time = axes[ch][0]
+            ax_time.plot(feat.samples[:n_show])
+            ax_time.set_title(f"Audio CH{ch}")
+            ax_time.set_xlabel(f"First {n_show} samples")
+            ax_time.set_ylabel("Amplitude")
+
+            ax_fft = axes[ch][1]
+            if feat.peak_frequencies is not None and len(feat.peak_frequencies):
+                ax_fft.plot(feat.peak_frequencies, feat.peak_amplitudes, "x")
+                ax_fft.vlines(feat.peak_frequencies, 0, feat.peak_amplitudes)
+            ax_fft.set_title(f"RFFT CH{ch}")
+            ax_fft.set_xlabel("Frequency [Hz]")
+            ax_fft.set_ylabel("Power")
+            ax_fft.ticklabel_format(useOffset=False)
+
+        plt.tight_layout()
+        if dirname := os.path.dirname(path):
+            os.makedirs(dirname, exist_ok=True)
+        plt.savefig(path)
+        plt.close(fig)
+
+
+def save_to_wave(
+    audio: "AudioFeatures",
+    path: str,
+    samplerate: int = 48000,
+    dtype: str = "float32",
+) -> None:
+    """Save all channels to a single multi-channel WAV file.
+
+    Uses ``audio.samples`` (the original unprocessed 2-D capture array) so
+    that the full, untrimmed data is written regardless of any *skip_first* /
+    *skip_latency* trimming applied during feature computation.
+
+    :param audio: :class:`AudioFeatures` whose ``samples`` array is written.
+    :param path: Destination WAV file path.
+    :param samplerate: Sample rate in Hz.
+    :param dtype: Numpy dtype string matching the original capture format.
+    """
+    if dirname := os.path.dirname(path):
+        os.makedirs(dirname, exist_ok=True)
+    # audio.samples shape: (n_samples, n_channels) — already interleaved, write directly
+    wavfile.write(path, samplerate, audio.samples.astype(dtype))
+
+
+def get_audio_start_offset(
+    samples: np.ndarray[Any], sample_rate: int, threshold: int = 100
+) -> int | float:
+    """Calculate the time (in seconds) when the audio starts varying.
+
+    :param samples: Numpy array of audio samples.
+    :param sample_rate: Sample rate of the audio in Hz.
+    :param threshold: Standard-deviation threshold used to detect signal
+        activity.
+    :return: Time in seconds (relative to the start of *samples*) at which
+        the signal first becomes active (std > *threshold*); ``-1`` if the
+        signal never varies.
+    """
+    window = 100
+    signal_evaluation = detect_if_signal_changes(
+        samples, window_size=window, threshold=threshold
+    )
+    first_index_where_started = np.where(signal_evaluation)[0]
+    if first_index_where_started.size:
+        idx = first_index_where_started[0] * window
+        time_where_started = idx / sample_rate
+    else:
+        time_where_started = -1
+    return time_where_started
+
+
+def detect_if_signal_changes(
+    samples: np.ndarray[Any], window_size=100, threshold=50
+) -> np.ndarray[np.bool]:
+    """Detect whether the signal is varying within successive windows.
+
+    Divides *samples* into non-overlapping windows of *window_size* and
+    computes the standard deviation of each window.  A window is marked as
+    active when its standard deviation exceeds *threshold*.
+
+    :param samples: Numpy array of audio samples.
+    :param window_size: Number of samples per evaluation window.
+    :param threshold: Standard-deviation threshold above which the signal is
+        considered as varying.
+    :return: Boolean array of length ``(len(samples) // window_size) - 1``
+        indicating activity in each window.
+    """
+    n_windows = len(samples) // window_size
+    if n_windows < 2:
+        # Not enough samples to fill even two windows — treat as non-varying (silent).
+        return np.zeros(0, dtype=bool)
+    result = np.zeros(n_windows - 1, dtype=bool)
+    for i, _ in enumerate(result):
+        window = samples[i * window_size : (i + 1) * window_size]
+        if abs(np.std(window)) > threshold:
+            result[i] = True
+    return result

audio_validation/audio_verification.py

@@ -0,0 +1,567 @@
+"""Methods for validating captured audio against a reference WAV,
+with detailed mismatch analysis and artefact generation.
+"""
+
+import logging
+import os
+import threading
+import wave
+
+import numpy as np
+import pandas as pd
+from matplotlib import pyplot as plt
+
+logger = logging.getLogger(__name__)
+save_plot_lock = threading.Lock()
+
+
+def _find_mismatches(
+    diff: np.ndarray,
+    merge_gap: int = 16,
+) -> list[tuple[int, int]]:
+    """Return non-zero diff regions as ``(start, end)`` pairs.
+
+    Regions separated by at most *merge_gap* zero samples are merged.
+
+    :param diff: 1-D int64 difference array
+    :param merge_gap: max gap in samples to merge into one run
+    :return: list of ``(start, end)`` pairs (inclusive, 0-based)
+    """
+    mismatch_indexes = np.nonzero(diff)[0]
+    if len(mismatch_indexes) == 0:
+        return []
+    mismatches: list[tuple[int, int]] = []
+    mismatch_start = int(mismatch_indexes[0])
+    last_mismatch = int(mismatch_indexes[0])
+    for idx in mismatch_indexes[1:]:
+        idx = int(idx)
+        if idx - last_mismatch > merge_gap:
+            mismatches.append((mismatch_start, last_mismatch))
+            mismatch_start = idx
+        last_mismatch = idx
+    mismatches.append((mismatch_start, last_mismatch))
+    return mismatches
+
+
+# pylint: disable=too-many-arguments,too-many-positional-arguments
+def _find_best_resync_lag(
+    reference: np.ndarray,
+    detected: np.ndarray,
+    ref_mismatch: int,
+    det_mismatch: int,
+    max_offset_search: int,
+    resync_verify_window: int,
+) -> tuple[int, float]:
+    """Return the lag with the highest bit-exact match ratio at a mismatch point.
+
+    Tries all integer lags in ``-max_offset_search … +max_offset_search``.
+
+    :param reference: full 1-D reference array
+    :param detected: full 1-D detected array
+    :param ref_mismatch: absolute mismatch index in *reference*
+    :param det_mismatch: absolute mismatch index in *detected*
+    :param max_offset_search: maximum ±offset to try
+    :param resync_verify_window: verification window length in samples
+    :return: ``(best_lag, best_ratio)``
+    """
+    best_lag = 0
+    best_ratio = 0.0
+    for lag in range(-max_offset_search, max_offset_search + 1):
+        ref_start = ref_mismatch + max(0, -lag)
+        det_start = det_mismatch + max(0, lag)
+        window = min(
+            resync_verify_window,
+            len(reference) - ref_start,
+            len(detected) - det_start,
+        )
+        if window < resync_verify_window // 2:
+            continue
+        ratio = (
+            float(
+                np.sum(
+                    reference[ref_start : ref_start + window].astype(np.int64)
+                    == detected[det_start : det_start + window].astype(np.int64)
+                )
+            )
+            / window
+        )
+        if ratio > best_ratio:
+            best_ratio = ratio
+            best_lag = lag
+    return best_lag, best_ratio
+
+
+# pylint: disable=too-many-arguments,too-many-positional-arguments,too-many-locals
+def _segment_compare(
+    reference: np.ndarray,
+    detected: np.ndarray,
+    max_offset_search: int = 64,
+    resync_verify_window: int = 256,
+    min_match_ratio: float = 0.95,
+    max_iterations: int = 128,
+) -> tuple[list[tuple[int, int]], int]:
+    """Compare arrays with automatic re-alignment after sample insertion/deletion glitches.
+
+    A plain diff permanently phase-shifts after one inserted/deleted sample.
+    This function re-aligns at each such event and reports only truly bad samples.
+
+    Algorithm (up to *max_iterations*):
+
+    1. Find first non-zero position in the remaining diff.
+    2. Score candidate lags via :func:`_find_best_resync_lag`.
+    3. High ratio + non-zero lag → timing glitch: record and re-align.
+    4. Otherwise → data error: record run via :func:`_find_mismatches` and advance.
+
+    :param reference: 1-D reference array (post initial-lag alignment)
+    :param detected: 1-D detected array (post initial-lag alignment)
+    :param max_offset_search: maximum ±offset to try at each mismatch
+    :param resync_verify_window: samples used to score each candidate offset
+    :param min_match_ratio: minimum match fraction to accept a re-sync
+    :param max_iterations: safety cap on iterations
+    :return: ``(mismatches, cumulative_lag)``
+    """
+    ref_pos = 0
+    det_pos = 0
+    mismatches: list[tuple[int, int]] = []
+
+    for _ in range(max_iterations):
+        if ref_pos >= len(reference) or det_pos >= len(detected):
+            break
+
+        remaining = min(len(reference) - ref_pos, len(detected) - det_pos)
+        diff_rem = detected[det_pos : det_pos + remaining].astype(np.int64) - reference[
+            ref_pos : ref_pos + remaining
+        ].astype(np.int64)
+        mismatch_indexes = np.nonzero(diff_rem)[0]
+        if len(mismatch_indexes) == 0:
+            break
+
+        local_mismatch = int(mismatch_indexes[0])
+        abs_ref_mismatch = ref_pos + local_mismatch
+        abs_det_mismatch = det_pos + local_mismatch
+
+        best_lag, best_ratio = _find_best_resync_lag(
+            reference,
+            detected,
+            abs_ref_mismatch,
+            abs_det_mismatch,
+            max_offset_search,
+            resync_verify_window,
+        )
+
+        if best_ratio >= min_match_ratio and best_lag != 0:
+            mismatches.append((abs_ref_mismatch, abs_ref_mismatch + abs(best_lag) - 1))
+            if best_lag > 0:
+                # insertion in detected → advance detected
+                ref_pos = abs_ref_mismatch
+                det_pos = abs_det_mismatch + best_lag
+            else:
+                # deletion in detected → advance reference
+                ref_pos = abs_ref_mismatch + abs(best_lag)
+                det_pos = abs_det_mismatch
+        else:
+            # Data error or no clean re-sync — record run and advance past it.
+            first_mismatch = _find_mismatches(diff_rem[local_mismatch:], merge_gap=16)
+            if first_mismatch:
+                _, mismatch_end_local = first_mismatch[0]
+                mismatches.append(
+                    (
+                        ref_pos + local_mismatch,
+                        ref_pos + local_mismatch + mismatch_end_local,
+                    )
+                )
+                advance = local_mismatch + mismatch_end_local + 1
+                ref_pos += advance
+                det_pos += advance
+            else:
+                # Fallback: report all remaining
+                mismatches.append((abs_ref_mismatch, ref_pos + remaining - 1))
+                break
+
+    return mismatches, det_pos - ref_pos  # cumulative timing drift
+
+
+def _align_channel_samples(
+    ref_samples: np.ndarray,
+    det_samples: np.ndarray,
+    channel: int,
+) -> tuple[np.ndarray, np.ndarray, int]:
+    """Trim *det_samples* so both arrays share the same signal onset.
+
+    :param ref_samples: 1-D reference channel samples
+    :param det_samples: 1-D detected channel samples
+    :param channel: channel index (error messages only)
+    :return: ``(ref_aligned, det_aligned, signal_offset)``
+    :raises ValueError: if either channel is completely silent
+    :raises RuntimeError: if detected starts before reference (negative latency)
+    """
+    ref_nz = np.nonzero(ref_samples)[0]
+    det_nz = np.nonzero(det_samples)[0]
+
+    if len(ref_nz) == 0 or len(det_nz) == 0:
+        raise ValueError(f"Channel {channel} is completely silent.")
+
+    ref_start = int(ref_nz[0])
+    det_start = int(det_nz[0])
+    signal_offset = det_start - ref_start
+
+    if signal_offset < 0:
+        raise RuntimeError(
+            f"[Ch {channel}] Detected signal starts {abs(signal_offset)} samples "
+            f"BEFORE the reference (ref_start={ref_start}, det_start={det_start}). "
+            f"Negative latency is physically impossible — check that detected_data "
+        )
+
+    if signal_offset > 0:
+        det_aligned = det_samples[signal_offset:]
+        ref_aligned = ref_samples[: len(det_aligned)]
+    else:
+        det_aligned = det_samples
+        ref_aligned = ref_samples
+
+    min_len = min(len(det_aligned), len(ref_aligned))
+    return ref_aligned[:min_len], det_aligned[:min_len], signal_offset
+
+
+def _compute_mismatch_stats(
+    ref_aligned: np.ndarray,
+    det_aligned: np.ndarray,
+    mismatches: list[tuple[int, int]],
+) -> tuple[int, int, int, str]:
+    """Return ``(total_samples, max_abs_diff, n_runs, run_description)`` for mismatch runs.
+
+    :param ref_aligned: 1-D aligned reference samples
+    :param det_aligned: 1-D aligned detected samples
+    :param mismatches: list of ``(start, end)`` pairs
+    :return: ``(total_mismatch_samples, max_abs_diff, n_runs, run_description)``
+    """
+    n_runs = len(mismatches)
+    total_mismatch_samples = sum(end - start + 1 for start, end in mismatches)
+    max_abs_diff = max(
+        int(
+            np.max(
+                np.abs(
+                    det_aligned[s : e + 1].astype(np.int64)
+                    - ref_aligned[s : e + 1].astype(np.int64)
+                )
+            )
+        )
+        for s, e in mismatches
+    )
+    run_description = (
+        "1 continuous mismatch region"
+        if n_runs == 1
+        else f"{n_runs} separate mismatch regions"
+    )
+    return total_mismatch_samples, max_abs_diff, n_runs, run_description
+
+
+def _save_mismatch_plot(
+    ref_aligned: np.ndarray,
+    det_aligned: np.ndarray,
+    start: int,
+    end: int,
+    run_idx: int,
+    total_runs: int,
+    channel: int,
+    artifacts_dir: str,
+    max_plot_samples: int = 4096,
+    context_samples: int = 256,
+) -> str:
+    """Save a PNG with reference (top) and detected (bottom) subplots for one mismatch run.
+
+    The x-axis is capped at *max_plot_samples* for readability.
+
+    :param ref_aligned: 1-D reference array (post-alignment)
+    :param det_aligned: 1-D detected array (post-alignment)
+    :param start: mismatch start index (inclusive)
+    :param end: mismatch end index (inclusive)
+    :param run_idx: 1-based run index
+    :param total_runs: total mismatch run count
+    :param channel: channel index
+    :param artifacts_dir: output directory
+    :param max_plot_samples: max samples to render
+    :param context_samples: samples prepended/appended around the mismatch
+    :return: path of the saved PNG
+    """
+    ctx_start = max(0, start - context_samples)
+    ctx_end = min(len(ref_aligned), end + context_samples + 1)
+    if ctx_end - ctx_start > max_plot_samples:
+        ctx_end = ctx_start + max_plot_samples
+
+    x = np.arange(ctx_start, ctx_end)
+    ref_slice = ref_aligned[ctx_start:ctx_end]
+    det_slice = det_aligned[ctx_start:ctx_end]
+
+    span_start = max(start, ctx_start)
+    span_end = min(end, ctx_end - 1)
+    run_len = end - start + 1
+    truncated = (ctx_end - ctx_start) >= max_plot_samples
+
+    title_suffix = f"mismatch {run_idx}/{total_runs}  |  {run_len} bad samples" + (
+        "  [plot truncated to first samples]" if truncated else ""
+    )
+
+    with save_plot_lock:
+        fig, axes = plt.subplots(2, 1, figsize=(14, 6), sharex=True)
+
+        axes[0].plot(x, ref_slice, color="steelblue", linewidth=0.8, label="reference")
+        if span_end >= span_start:
+            axes[0].axvspan(
+                span_start, span_end, alpha=0.25, color="red", label="mismatch"
+            )
+        axes[0].set_title(f"Ch {channel} – Reference  ({title_suffix})")
+        axes[0].set_ylabel("Amplitude")
+        axes[0].legend(loc="upper right", fontsize=8)
+
+        axes[1].plot(x, det_slice, color="darkorange", linewidth=0.8, label="detected")
+        if span_end >= span_start:
+            axes[1].axvspan(
+                span_start, span_end, alpha=0.25, color="red", label="mismatch"
+            )
+        axes[1].set_title(f"Ch {channel} – Detected  ({title_suffix})")
+        axes[1].set_ylabel("Amplitude")
+        axes[1].set_xlabel("Sample index (post-alignment)")
+        axes[1].legend(loc="upper right", fontsize=8)
+
+        plt.tight_layout()
+        png_path = os.path.join(
+            artifacts_dir, f"null_test_ch{channel}_mismatch{run_idx:02d}.png"
+        )
+        plt.savefig(png_path, dpi=100)
+        plt.close(fig)
+
+    logger.info("Saved mismatch plot: %s", png_path)
+    return png_path
+
+
+def _save_mismatch_wav(
+    ref_aligned: np.ndarray,
+    det_aligned: np.ndarray,
+    start: int,
+    end: int,
+    run_idx: int,
+    channel: int,
+    artifacts_dir: str,
+    sample_rate: int,
+    dtype: str,
+    context_samples: int = 256,
+) -> str:
+    """Save a 2-channel WAV clip for one mismatch run (reference=L, detected=R).
+
+    :param ref_aligned: 1-D reference array (post-alignment)
+    :param det_aligned: 1-D detected array (post-alignment)
+    :param start: mismatch start index (inclusive)
+    :param end: mismatch end index (inclusive)
+    :param run_idx: 1-based run index
+    :param channel: channel index
+    :param artifacts_dir: output directory
+    :param sample_rate: sample rate in Hz
+    :param dtype: numpy dtype string (e.g. ``"int16"``)
+    :param context_samples: samples prepended/appended around the mismatch
+    :return: path of the saved WAV
+    """
+    wav_start = max(0, start - context_samples)
+    wav_end = min(len(ref_aligned), end + context_samples + 1)
+    ref_wav = ref_aligned[wav_start:wav_end].reshape(-1, 1)
+    det_wav = det_aligned[wav_start:wav_end].reshape(-1, 1)
+    stacked = np.hstack([ref_wav, det_wav])  # 2-ch: ref=L, detected=R
+    wav_path = os.path.join(
+        artifacts_dir, f"null_test_ch{channel}_mismatch{run_idx:02d}.wav"
+    )
+    with wave.open(wav_path, "wb") as wf:  # pylint: disable=no-member
+        wf.setnchannels(2)  # type: ignore[attr-defined]  # pylint: disable=no-member
+        wf.setframerate(sample_rate)  # type: ignore[attr-defined]  # pylint: disable=no-member
+        wf.setsampwidth(np.dtype(dtype).itemsize)  # type: ignore[attr-defined]  # pylint: disable=no-member
+        wf.writeframes(stacked.astype(dtype).tobytes())  # type: ignore[attr-defined]  # pylint: disable=no-member
+    logger.info("Saved mismatch WAV: %s", wav_path)
+    return wav_path
+
+
+def _save_mismatch_artifacts(
+    ref_aligned: np.ndarray,
+    det_aligned: np.ndarray,
+    mismatches: list[tuple[int, int]],
+    channel: int,
+    artifacts_dir: str,
+    max_plot_samples: int = 4096,
+    context_samples: int = 256,
+) -> list[str]:
+    """Save a PNG per mismatch run and (when >1 run) a WAV per run.
+
+    :param ref_aligned: 1-D reference array (post-alignment)
+    :param det_aligned: 1-D detected array (post-alignment)
+    :param mismatches: list of ``(start, end)`` run pairs
+    :param channel: channel index
+    :param artifacts_dir: output directory
+    :param max_plot_samples: max samples per plot
+    :param context_samples: guard-band around each run
+    :return: list of created file paths
+    """
+    os.makedirs(artifacts_dir, exist_ok=True)
+    saved: list[str] = []
+    total_runs = len(mismatches)
+
+    for run_idx, (mismatch_start, mismatch_end) in enumerate(mismatches, start=1):
+        png_path = _save_mismatch_plot(
+            ref_aligned=ref_aligned,
+            det_aligned=det_aligned,
+            start=mismatch_start,
+            end=mismatch_end,
+            run_idx=run_idx,
+            total_runs=total_runs,
+            channel=channel,
+            artifacts_dir=artifacts_dir,
+            max_plot_samples=max_plot_samples,
+            context_samples=context_samples,
+        )
+        saved.append(png_path)
+    return saved
+
+
+def _build_null_test_table(rows: list[dict]) -> str:
+    """Format per-channel null-test results as a table string for pytest assert messages.
+
+    :param rows: per-channel result dicts produced by :func:`validate_audio_data`
+    :return: newline-prefixed table string
+    """
+    df = pd.DataFrame(rows).set_index("ch")
+    return "\n" + df.to_string(justify="left")
+
+
+# pylint: disable=too-many-arguments,too-many-positional-arguments,too-many-locals
+def validate_audio_perfect(
+    detected_data: np.ndarray,
+    reference_data: np.ndarray,
+    samplerate: int,
+    artifacts_dir: str = "test_artifacts",
+    broadcast_reference_ch0: bool = False,
+) -> tuple[bool, str]:
+    """Null-test every channel after aligning detected audio to the reference.
+
+    Alignment is based on signal onset per channel. A channel passes when every
+    aligned sample difference is exactly zero (bit-perfect). Timing-only drift
+    (sample insertions/deletions) is resolved by :func:`_segment_compare` and
+    does not cause a failure on its own.
+
+    On failure, artefacts are written to *artifacts_dir*:
+
+    * PNG per mismatch run (reference + detected subplots, highlighted region).
+    * WAV per mismatch run (ref=L, det=R) — only when there are multiple runs.
+
+    :param detected_data: capture array from ``record_audio``, shape ``(n_samples, channels)``
+    :param reference_data: WAV array from ``play_audio``, shape ``(n_frames, channels)``
+    :param samplerate: sample rate in Hz
+    :param artifacts_dir: directory for failure PNGs and WAVs
+    :param broadcast_reference_ch0: compare all detected channels against reference ch 0
+    :return: ``(True, table)`` on pass, ``(False, table)`` on failure —
+        table has one row per channel
+    """
+    if detected_data.ndim != 2:
+        raise ValueError(
+            f"detected_data must be 2-D (n_samples, channels), got shape {detected_data.shape}."
+        )
+    if reference_data.ndim != 2:
+        raise ValueError(
+            f"reference_data must be 2-D (n_frames, channels), got shape {reference_data.shape}."
+        )
+
+    reference_channels = reference_data.shape[1]
+    detected_channels = detected_data.shape[1]
+
+    if not broadcast_reference_ch0 and reference_channels != detected_channels:
+        return (
+            False,
+            f"Channel count mismatch: detected has {detected_channels} ch, "
+            f"reference has {reference_channels} ch. "
+            f"Use broadcast_reference_ch0=True to compare all against ch 0.",
+        )
+
+    channel_rows: list[dict] = []
+
+    for channel in range(detected_channels):
+        ref_ch_idx = 0 if broadcast_reference_ch0 else channel
+        ref_samples = reference_data[:, ref_ch_idx]
+        det_samples = detected_data[:, channel]
+
+        row: dict = {
+            "ch": channel,
+            "status": "?",
+            "audio_offset": "-",
+            "correct_samples": 0,
+            "incorrect_samples": 0,
+            "glitch_count": 0,
+            "artifacts_path": "-",
+        }
+
+        try:
+            ref_aligned, det_aligned, signal_offset = _align_channel_samples(
+                ref_samples, det_samples, channel
+            )
+        except ValueError:
+            row["status"] = "SILENT"
+            channel_rows.append(row)
+            continue
+
+        row["audio_offset"] = f"{signal_offset / samplerate:.3f}s ({signal_offset})"
+
+        if len(ref_aligned) == 0:
+            row["status"] = "NO_OVERLAP"
+            channel_rows.append(row)
+            continue
+
+        row["correct_samples"] = len(ref_aligned)
+
+        diff = det_aligned.astype(np.int64) - ref_aligned.astype(np.int64)
+        if int(np.count_nonzero(diff)) == 0:
+            row["status"] = "PASS"
+            channel_rows.append(row)
+            logger.info(
+                "Channel %d: PASSED (%d aligned samples).", channel, len(ref_aligned)
+            )
+            continue
+
+        mismatches, timing_drift = _segment_compare(ref_aligned, det_aligned)
+
+        if not mismatches:
+            row["status"] = "PASS"
+            channel_rows.append(row)
+            logger.info(
+                "Channel %d: PASSED (timing drift only, %+d samples).",
+                channel,
+                timing_drift,
+            )
+            continue
+
+        total_mismatch_samples, _, n_runs, run_description = _compute_mismatch_stats(
+            ref_aligned, det_aligned, mismatches
+        )
+        row.update(
+            {
+                "status": "FAIL",
+                "correct_samples": len(ref_aligned) - total_mismatch_samples,
+                "incorrect_samples": total_mismatch_samples,
+                "glitch_count": n_runs,
+            }
+        )
+
+        logger.warning(
+            "[Ch %d] FAILED — %s. Saving artefacts to '%s'.",
+            channel,
+            run_description,
+            artifacts_dir,
+        )
+        _save_mismatch_artifacts(
+            ref_aligned=ref_aligned,
+            det_aligned=det_aligned,
+            mismatches=mismatches,
+            channel=channel,
+            artifacts_dir=artifacts_dir,
+        )
+        row["artifacts_path"] = artifacts_dir
+
+        channel_rows.append(row)
+
+    passed = all(r["status"] == "PASS" for r in channel_rows)
+    table = _build_null_test_table(channel_rows)
+    return passed, table

audio_validation/utils/audio_generation.py

@@ -0,0 +1,168 @@
+"""Audio waveform generation and file output.
+
+This module provides utilities for generating various waveform types and saving them
+as multi-channel WAV files. Supports the following waveform shapes:
+
+- Sine wave: pure sinusoidal oscillation at specified frequency
+- Square wave: binary waveform oscillating between +1 and -1
+- Sawtooth wave: linearly increasing periodic waveform
+- White noise: uniformly distributed random noise
+- Pink noise: frequency-weighted noise with reduced high-frequency content
+
+Generated audio can be multi-channel, with selective activation of specific channels
+and configurable amplitude, sample rate, and duration. Output is saved as 32-bit
+PCM WAV files suitable for audio playback and analysis.
+"""
+
+import logging
+import wave
+from typing import Literal, List
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+def _encode_pcm(data: np.ndarray, resolution_bits: int) -> bytes:
+    """Encode float32 audio data to raw PCM bytes.
+
+    :param data: float32 array of shape ``(n_samples, n_channels)``
+    :param resolution_bits: bit depth – 16, 24, or 32
+    :return: raw PCM bytes
+    :raises ValueError: if *resolution_bits* is not supported
+    """
+    if resolution_bits == 16:
+        max_val = np.iinfo(np.int16).max
+        return (data * max_val).astype(np.int16).tobytes()
+    if resolution_bits == 24:
+        max_val = 2**23 - 1
+        pcm = (data * max_val).astype(np.int32)
+        raw = pcm.tobytes()
+        return bytes(b for i, b in enumerate(raw) if i % 4 != 3)
+    if resolution_bits == 32:
+        max_val = np.iinfo(np.int32).max
+        return (data * max_val).astype(np.int32).tobytes()
+    raise ValueError(
+        f"Unsupported resolution_bits: {resolution_bits}. Supported values are 16, 24 and 32."
+    )
+
+
+# pylint:disable=too-many-arguments, too-many-positional-arguments, too-many-locals, too-many-branches
+def generate_wave_file(
+    shape: Literal["sine", "square", "sawtooth", "white_noise", "pink_noise"],
+    freq_list: List[float] = None,
+    sample_rate: int = 48000,
+    duration=10.0,
+    num_channels: int = 24,
+    active_channels=None,
+    amplitude: float = 0.05,
+    resolution_bits: int = 16,
+    output_dir: str = "generated_signal.wav",
+):
+    """Generate a multi-channel waveform and save it as a WAV file.
+
+    Creates a multi-channel audio file with one or more active channels containing
+    the specified waveform. Inactive channels contain silence (zeros). The function
+    generates the waveform based on shape, frequency, duration, and other parameters,
+    then encodes it as 32-bit PCM and saves to a WAV file.
+
+    :param shape: type of waveform to generate
+    :param freq_list: fundamental frequency in Hz for each channel
+    :param sample_rate: audio sample rate in Hz
+    :param duration: duration of the generated audio in seconds
+    :param num_channels: total number of channels in the output file
+    :param active_channels: list of channel indices to populate with signal;
+                           if None, defaults to [0, 1, 2, 3]
+    :param amplitude: signal amplitude as a fraction of maximum (range: 0.0-1.0)
+    :param output_dir: path to output WAV file
+
+    :raises ValueError: if shape is not a supported waveform type
+
+    Note:
+        - Active channels must be within valid range [0, num_channels)
+        - Inactive channels contain silence
+        - Output is 32-bit PCM mono samples, saved as multi-channel WAV
+    """
+
+    logger.info(
+        "Generating audio file with %s shape, freq %f Hz, amplitude %.2f, %d sample rate,"
+        " %d duration, %d channels, %s active channels and %d bits audio resolution.",
+        shape,
+        freq_list,
+        amplitude,
+        sample_rate,
+        duration,
+        num_channels,
+        active_channels,
+        resolution_bits,
+    )
+    if active_channels is None:
+        active_channels = [0, 1, 2, 3]
+
+    if freq_list is None:
+        freq_list = [400]
+
+    if len(freq_list) != len(active_channels):
+        raise ValueError("Length of freq list must match length of active_channels")
+
+    n_samples = int(sample_rate * duration)
+    t = np.linspace(0, duration, n_samples)
+    data = np.zeros((n_samples, num_channels), dtype=np.float32)
+
+    for i, ch in enumerate(active_channels):
+        if 0 <= ch < num_channels:
+            current_freq = freq_list[i]
+
+            if shape == "sine":
+                signal = np.sin(2 * np.pi * current_freq * t)
+            elif shape == "square":
+                signal = np.sign(np.sin(2 * np.pi * current_freq * t))
+            elif shape == "sawtooth":
+                signal = 2 * (t * current_freq - np.floor(0.5 + t * current_freq))
+            elif shape == "white_noise":
+                signal = np.random.uniform(-1.0, 1.0, size=n_samples)
+            elif shape == "pink_noise":
+                num_rows = 16
+                array = np.random.randn(num_rows, n_samples)
+                array = np.cumsum(array, axis=1)
+                weights = 2.0 ** (-np.arange(num_rows))
+                signal = np.dot(weights, array)
+                signal /= np.max(np.abs(signal))
+            else:
+                raise ValueError(f"Unsupported shape: {shape}.")
+
+            signal = (signal * amplitude).astype(np.float32)
+            data[:, ch] = signal
+
+    raw_frames = _encode_pcm(data, resolution_bits)
+
+    # pylint:disable=no-member
+    with wave.open(output_dir, "wb") as wf:
+        wf.setnchannels(num_channels)
+        wf.setsampwidth(
+            resolution_bits // 8
+        )  # Pass resolution in bytes to set the sample width
+        wf.setframerate(sample_rate)
+        wf.writeframes(raw_frames)
+
+
+if __name__ == "__main__":
+    START_HZ = 100
+    STEP_HZ = 0
+    CHANNELS = 2
+    RESOLUTION_BITS = 16
+
+    generate_wave_file(
+        shape="sine",
+        freq_list=[START_HZ + i * STEP_HZ for i in range(CHANNELS)],
+        sample_rate=48000,
+        duration=10,
+        num_channels=CHANNELS,
+        active_channels=list(range(CHANNELS)),
+        amplitude=0.05,
+        resolution_bits=RESOLUTION_BITS,
+        output_dir=(
+            f"{CHANNELS}ch_{RESOLUTION_BITS}bit_freqs"
+            f"_start_{START_HZ}hz_step_{STEP_HZ}hz.wav"
+        ),
+    )

audio_validation-0.1.2.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: audio_validation
+Version: 0.1.2
+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
+        
+        Copyright (c) 2026 int2code
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+Requires-Dist: pandas
+Requires-Dist: pytest
+Provides-Extra: test
+Requires-Dist: coverage; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-html; extra == "test"
+Provides-Extra: dev
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-html; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: tox; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: coverage; extra == "docs"
+Requires-Dist: pytest; extra == "docs"
+Requires-Dist: pytest-cov; extra == "docs"
+Requires-Dist: pytest-html; extra == "docs"
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Requires-Dist: sphinxcontrib-programoutput; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Dynamic: license-file
+
+# audio_validation
+
+A Python library for validating and analysing audio data, including feature extraction, bit-exact verification against a reference, and waveform generation utilities.
+
+## Features
+
+- **Feature extraction** — compute RMS, peak/min/max, mean, FFT-based frequency detection, and per-channel audio onset offset for multi-channel captures.
+- **Audio verification** — validate a captured audio stream against a reference WAV file with drift-tolerant re-synchronisation, detailed mismatch reporting, and automatic artefact generation (PNG plots and WAV snippets).
+- **Waveform generation** — generate multi-channel WAV files with configurable waveforms: sine, square, sawtooth, white noise, and pink noise; supports 16-, 24-, and 32-bit PCM output.
+
+## Requirements
+
+- Python ≥ 3.11
+- See [requirements.txt](requirements.txt) for runtime dependencies (`numpy`, `scipy`, `sounddevice`, `pymodbus`, …).
+
+## Installation
+
+```bash
+pip install audio_validation
+```
+
+Or, for development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+### Feature extraction
+
+```python
+from audio_validation.audio_features import AudioFeatures
+
+features = AudioFeatures.compute(
+    samples=raw_samples,           # numpy array, shape (n_samples, n_channels)
+    sample_rate=48000,
+    expected_frequencies=[400, 800],
+    tolerance=50,
+)
+
+for ch_idx, ch in enumerate(features.channels):
+    print(f"Ch {ch_idx}: detected={ch.detected}, rms={ch.rms:.4f}, peaks={ch.peak_frequencies}")
+```
+
+### Audio verification
+
+```python
+from audio_validation.audio_verification import verify_audio
+
+results = verify_audio(
+    reference_path="reference.wav",
+    detected_samples=captured_array,
+    sample_rate=48000,
+    artifacts_dir="test_artifacts/",
+)
+```
+
+### Waveform generation
+
+```python
+from audio_validation.utils.audio_generation import generate_wave_file
+
+generate_wave_file(
+    shape="sine",
+    freq_list=[1000.0],
+    sample_rate=48000,
+    duration=5.0,
+    num_channels=2,
+    active_channels=[0, 1],
+    amplitude=0.05,
+    resolution_bits=16,
+    output_dir="output.wav",
+)
+```
+
+## Maintainers
+
+- Hubert Stepniewski — hubert.stepniewski@int2code.com
+- Marcin Tomiczek — marcin.tomiczek@int2code.com
+- Piotr Sznapka — piotr.sznapka@int2code.com
+
+## License
+
+See [LICENSE](LICENSE).

audio_validation-0.1.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+audio_validation/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+audio_validation/_version.py,sha256=Q6ScJXlkBsUI-cazSvpYPMyIVUB-Vd0R3pq3_rM1wmI,520
+audio_validation/audio_features.py,sha256=Saf9v7agorOy5Mw5eEGdlRfkZAuUkihMUMMMR-vOAT0,17466
+audio_validation/audio_verification.py,sha256=wLihZDo1Qj0iOwHNCYHkXeYlsZwdywD_yMWFr9Bm_jM,20714
+audio_validation/utils/audio_generation.py,sha256=1-SxE3FKyp4A1nt_BNmeggUh4ReDy2_y7EVpo4owWP8,6210
+audio_validation-0.1.2.dist-info/licenses/LICENSE,sha256=e9JsLl_zrw1-Gs4lwFc1MMu71eiUUvxJhsX6DDRlOZQ,1065
+audio_validation-0.1.2.dist-info/METADATA,sha256=WAdq3ClwZE6-JY1n95cAfY8uhaKPa4HvlcmzDFfmPcM,4935
+audio_validation-0.1.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+audio_validation-0.1.2.dist-info/top_level.txt,sha256=4x0c2_XfHaGP84D8ehLRf_wD3lT12oDaU4adXTJkgTU,17
+audio_validation-0.1.2.dist-info/RECORD,,

audio_validation-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

audio_validation-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 int2code
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

audio_validation-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+audio_validation