sounddiff 0.1.0__py3-none-any.whl

sounddiff/__init__.py

@@ -0,0 +1,3 @@
+"""sounddiff: structured audio comparison for producers and developers."""
+
+__version__ = "0.1.0"

sounddiff/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running sounddiff as `python -m sounddiff`."""
+
+from sounddiff.cli import main
+
+main()

sounddiff/cli.py

@@ -0,0 +1,79 @@
+"""CLI entry point for sounddiff."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from sounddiff import __version__
+from sounddiff.core import diff
+from sounddiff.report import render
+from sounddiff.types import OutputFormat
+
+
+@click.command()
+@click.argument("file_a", type=click.Path(exists=True))
+@click.argument("file_b", type=click.Path(exists=True))
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["terminal", "json", "html"]),
+    default="terminal",
+    help="Output format.",
+)
+@click.option(
+    "-o",
+    "--output",
+    "output_path",
+    type=click.Path(),
+    default=None,
+    help="Write output to a file (useful with --format html).",
+)
+@click.option(
+    "--verbose",
+    is_flag=True,
+    default=False,
+    help="Show additional detail.",
+)
+@click.option(
+    "--no-color",
+    is_flag=True,
+    default=False,
+    help="Disable colored terminal output.",
+)
+@click.version_option(version=__version__, prog_name="sounddiff")
+def main(
+    file_a: str,
+    file_b: str,
+    output_format: str,
+    output_path: str | None,
+    verbose: bool,
+    no_color: bool,
+) -> None:
+    """Compare two audio files and report what changed.
+
+    sounddiff FILE_A FILE_B
+
+    Compares FILE_A (reference) against FILE_B (comparison) and reports
+    differences in loudness, spectral content, timing, and potential issues.
+    """
+    try:
+        result = diff(file_a, file_b)
+    except FileNotFoundError as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+    except ValueError as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+    except RuntimeError as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+    fmt = OutputFormat(output_format)
+    output = render(result, fmt, output_path, no_color=no_color)
+
+    if output_path and fmt == OutputFormat.HTML:
+        click.echo(f"Report written to {output_path}")
+    else:
+        click.echo(output)

sounddiff/core.py

@@ -0,0 +1,66 @@
+"""Core orchestration: run the full comparison pipeline."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from sounddiff.detection import compare_detection
+from sounddiff.formats import load_audio
+from sounddiff.loudness import compare_loudness
+from sounddiff.spectral import compare_spectral
+from sounddiff.temporal import compare_temporal
+from sounddiff.types import DiffResult, MetadataComparison
+
+
+def diff(
+    path_a: str | Path,
+    path_b: str | Path,
+) -> DiffResult:
+    """Compare two audio files and return a structured diff.
+
+    Args:
+        path_a: Path to the first (reference) audio file.
+        path_b: Path to the second (comparison) audio file.
+
+    Returns:
+        DiffResult containing all analysis results.
+
+    Raises:
+        FileNotFoundError: If either file does not exist.
+        ValueError: If either file format is unsupported.
+    """
+    data_a, meta_a = load_audio(path_a)
+    data_b, meta_b = load_audio(path_b)
+
+    metadata = MetadataComparison(file_a=meta_a, file_b=meta_b)
+
+    warnings: list[str] = []
+    if not metadata.same_sample_rate:
+        warnings.append(
+            f"Sample rate mismatch: {meta_a.sample_rate} Hz vs {meta_b.sample_rate} Hz. "
+            "Comparison accuracy may be reduced."
+        )
+    if not metadata.same_channels:
+        warnings.append(
+            f"Channel count mismatch: {meta_a.channels} vs {meta_b.channels}. "
+            "Comparison will use mixed-to-mono signals where needed."
+        )
+
+    loudness = compare_loudness(data_a, data_b, meta_a.sample_rate, meta_b.sample_rate)
+    spectral = compare_spectral(data_a, data_b, meta_a.sample_rate, meta_b.sample_rate)
+    temporal = compare_temporal(data_a, data_b, meta_a.sample_rate)
+
+    file_a_name = Path(meta_a.path).name
+    file_b_name = Path(meta_b.path).name
+    detection = compare_detection(
+        data_a, data_b, meta_a.sample_rate, meta_b.sample_rate, file_a_name, file_b_name
+    )
+
+    return DiffResult(
+        metadata=metadata,
+        loudness=loudness,
+        spectral=spectral,
+        temporal=temporal,
+        detection=detection,
+        warnings=warnings,
+    )

sounddiff/detection.py

@@ -0,0 +1,164 @@
+"""Detection: clipping and silence analysis."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from sounddiff.types import ClipEvent, DetectionResult, SilenceRegion
+
+
+def detect_clipping(
+    data: np.ndarray,
+    sample_rate: int,
+    file_label: str,
+    threshold: float = 0.99,
+    min_consecutive: int = 2,
+) -> list[ClipEvent]:
+    """Detect clipping events in an audio signal.
+
+    Clipping is defined as consecutive samples at or above the threshold.
+
+    Args:
+        data: Audio signal, shape (frames, channels).
+        sample_rate: Sample rate in Hz.
+        file_label: Label for this file (used in output).
+        threshold: Amplitude threshold for clipping detection.
+        min_consecutive: Minimum consecutive samples to count as clipping.
+
+    Returns:
+        List of ClipEvent objects.
+    """
+    clips: list[ClipEvent] = []
+
+    for channel in range(data.shape[1]):
+        channel_data = np.abs(data[:, channel])
+        is_clipping = channel_data >= threshold
+
+        # Find runs of consecutive clipping samples
+        changes = np.diff(is_clipping.astype(int))
+        starts = np.where(changes == 1)[0] + 1
+        ends = np.where(changes == -1)[0] + 1
+
+        # Handle edge cases
+        if is_clipping[0]:
+            starts = np.concatenate([[0], starts])
+        if is_clipping[-1]:
+            ends = np.concatenate([ends, [len(channel_data)]])
+
+        for start, end in zip(starts, ends, strict=True):
+            count = end - start
+            if count >= min_consecutive:
+                timestamp = start / sample_rate
+                clips.append(
+                    ClipEvent(
+                        file_label=file_label,
+                        timestamp=round(timestamp, 3),
+                        channel=channel,
+                        sample_count=int(count),
+                    )
+                )
+
+    return clips
+
+
+def detect_silence(
+    data: np.ndarray,
+    sample_rate: int,
+    file_label: str,
+    threshold_db: float = -60.0,
+    min_duration: float = 0.1,
+) -> list[SilenceRegion]:
+    """Detect regions of silence in an audio signal.
+
+    Silence is defined as RMS energy below the threshold for at least min_duration.
+
+    Args:
+        data: Audio signal, shape (frames, channels).
+        sample_rate: Sample rate in Hz.
+        file_label: Label for this file (used in output).
+        threshold_db: RMS threshold in dB for silence.
+        min_duration: Minimum duration in seconds for a silence region.
+
+    Returns:
+        List of SilenceRegion objects.
+    """
+    # Mix to mono for silence detection
+    mono = np.mean(data, axis=1)
+
+    # Compute RMS in short windows
+    window_size = int(0.01 * sample_rate)  # 10ms windows
+    if window_size == 0:
+        return []
+
+    threshold_linear = 10 ** (threshold_db / 20.0)
+    min_samples = int(min_duration * sample_rate)
+
+    # Compute per-window RMS
+    n_windows = len(mono) // window_size
+    if n_windows == 0:
+        return []
+
+    truncated = mono[: n_windows * window_size].reshape(n_windows, window_size)
+    rms_values = np.sqrt(np.mean(truncated**2, axis=1))
+    is_silent = rms_values < threshold_linear
+
+    # Find runs of silence
+    regions: list[SilenceRegion] = []
+    changes = np.diff(is_silent.astype(int))
+    starts = np.where(changes == 1)[0] + 1
+    ends = np.where(changes == -1)[0] + 1
+
+    if is_silent[0]:
+        starts = np.concatenate([[0], starts])
+    if is_silent[-1]:
+        ends = np.concatenate([ends, [n_windows]])
+
+    for start, end in zip(starts, ends, strict=True):
+        sample_start = start * window_size
+        sample_end = end * window_size
+        duration_samples = sample_end - sample_start
+
+        if duration_samples >= min_samples:
+            regions.append(
+                SilenceRegion(
+                    file_label=file_label,
+                    start_time=round(sample_start / sample_rate, 3),
+                    end_time=round(sample_end / sample_rate, 3),
+                )
+            )
+
+    return regions
+
+
+def compare_detection(
+    data_a: np.ndarray,
+    data_b: np.ndarray,
+    sample_rate_a: int,
+    sample_rate_b: int,
+    file_a_name: str,
+    file_b_name: str,
+) -> DetectionResult:
+    """Run clipping and silence detection on both files.
+
+    Args:
+        data_a: First audio signal.
+        data_b: Second audio signal.
+        sample_rate_a: Sample rate of first signal.
+        sample_rate_b: Sample rate of second signal.
+        file_a_name: Display name for first file.
+        file_b_name: Display name for second file.
+
+    Returns:
+        DetectionResult with clips and silence regions.
+    """
+    clips_a = detect_clipping(data_a, sample_rate_a, file_a_name)
+    clips_b = detect_clipping(data_b, sample_rate_b, file_b_name)
+
+    silence_a = detect_silence(data_a, sample_rate_a, file_a_name)
+    silence_b = detect_silence(data_b, sample_rate_b, file_b_name)
+
+    return DetectionResult(
+        clips=clips_a + clips_b,
+        silence_regions_a=silence_a,
+        silence_regions_b=silence_b,
+    )

sounddiff/formats.py

@@ -0,0 +1,100 @@
+"""Audio file loading and format detection."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np  # noqa: TC002 (used at runtime in return type)
+import soundfile as sf
+
+from sounddiff.types import AudioMetadata
+
+# Formats supported natively via libsndfile
+NATIVE_FORMATS = {".wav", ".flac", ".ogg", ".aiff", ".aif"}
+
+# Formats that require ffmpeg
+FFMPEG_FORMATS = {".mp3", ".aac", ".m4a", ".wma", ".opus"}
+
+
+def load_audio(path: str | Path) -> tuple[np.ndarray, AudioMetadata]:
+    """Load an audio file and return the signal and metadata.
+
+    Args:
+        path: Path to the audio file.
+
+    Returns:
+        Tuple of (audio signal as float64 ndarray, metadata).
+        Signal is always 2D: (frames, channels). Mono files get shape (frames, 1).
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        ValueError: If the format is unsupported or requires ffmpeg.
+        RuntimeError: If the file cannot be read.
+    """
+    filepath = Path(path)
+
+    if not filepath.exists():
+        raise FileNotFoundError(f"File not found: {filepath}")
+
+    suffix = filepath.suffix.lower()
+
+    if suffix in FFMPEG_FORMATS:
+        raise ValueError(
+            f"Format '{suffix}' requires ffmpeg, which is not installed or not supported yet. "
+            f"Supported formats without ffmpeg: {', '.join(sorted(NATIVE_FORMATS))}"
+        )
+
+    if suffix not in NATIVE_FORMATS:
+        raise ValueError(
+            f"Unsupported audio format: '{suffix}'. "
+            f"Supported: {', '.join(sorted(NATIVE_FORMATS | FFMPEG_FORMATS))}"
+        )
+
+    try:
+        info = sf.info(str(filepath))
+    except RuntimeError as e:
+        raise RuntimeError(f"Cannot read audio file: {filepath} ({e})") from e
+
+    data, sample_rate = sf.read(str(filepath), dtype="float64", always_2d=True)
+
+    metadata = AudioMetadata(
+        path=str(filepath),
+        duration=len(data) / sample_rate,
+        sample_rate=sample_rate,
+        channels=data.shape[1],
+        bit_depth=_subtype_to_bits(info.subtype),
+        format_name=info.format,
+        frames=len(data),
+    )
+
+    return data, metadata
+
+
+def _subtype_to_bits(subtype: str) -> int | None:
+    """Convert soundfile subtype string to bit depth."""
+    mapping: dict[str, int] = {
+        "PCM_16": 16,
+        "PCM_24": 24,
+        "PCM_32": 32,
+        "PCM_S8": 8,
+        "PCM_U8": 8,
+        "FLOAT": 32,
+        "DOUBLE": 64,
+    }
+    return mapping.get(subtype)
+
+
+def format_duration(seconds: float) -> str:
+    """Format a duration in seconds as M:SS.mmm."""
+    minutes = int(seconds // 60)
+    secs = seconds % 60
+    return f"{minutes}:{secs:06.3f}"
+
+
+def format_channels(n: int) -> str:
+    """Format channel count as a human-readable string."""
+    if n == 1:
+        return "mono"
+    if n == 2:
+        return "stereo"
+    return f"{n}ch"

sounddiff/loudness.py

@@ -0,0 +1,98 @@
+"""Loudness analysis: integrated LUFS, true peak, loudness range."""
+
+from __future__ import annotations
+
+import numpy as np
+import pyloudnorm as pyln
+
+from sounddiff.types import LoudnessComparison, LoudnessResult
+
+
+def measure_loudness(data: np.ndarray, sample_rate: int) -> LoudnessResult:
+    """Measure loudness metrics for an audio signal.
+
+    Args:
+        data: Audio signal, shape (frames, channels).
+        sample_rate: Sample rate in Hz.
+
+    Returns:
+        LoudnessResult with LUFS, true peak, and loudness range.
+    """
+    meter = pyln.Meter(sample_rate)
+
+    # pyloudnorm expects (samples, channels) which is what we have
+    lufs = meter.integrated_loudness(data)
+
+    # True peak: find the maximum absolute sample value across all channels,
+    # convert to dBTP. This is a simplified true peak (sample peak).
+    # Full ITU-R BS.1770 true peak requires 4x oversampling, but sample peak
+    # is a reasonable approximation for comparison purposes.
+    peak_linear = np.max(np.abs(data))
+    true_peak_dbtp = 20 * np.log10(peak_linear) if peak_linear > 0 else -np.inf
+
+    # Loudness range (LRA): difference between the 95th and 10th percentile
+    # of short-term loudness measurements
+    lra = _compute_loudness_range(data, sample_rate)
+
+    return LoudnessResult(
+        lufs=round(lufs, 1),
+        true_peak_dbtp=round(float(true_peak_dbtp), 1),
+        loudness_range=round(lra, 1),
+    )
+
+
+def compare_loudness(
+    data_a: np.ndarray,
+    data_b: np.ndarray,
+    sample_rate_a: int,
+    sample_rate_b: int,
+) -> LoudnessComparison:
+    """Compare loudness between two audio signals.
+
+    Args:
+        data_a: First audio signal.
+        data_b: Second audio signal.
+        sample_rate_a: Sample rate of first signal.
+        sample_rate_b: Sample rate of second signal.
+
+    Returns:
+        LoudnessComparison with measurements for both files.
+    """
+    result_a = measure_loudness(data_a, sample_rate_a)
+    result_b = measure_loudness(data_b, sample_rate_b)
+    return LoudnessComparison(file_a=result_a, file_b=result_b)
+
+
+def _compute_loudness_range(data: np.ndarray, sample_rate: int) -> float:
+    """Compute loudness range (LRA) using short-term loudness measurements.
+
+    Uses 3-second windows with 2-second overlap per EBU R128.
+    """
+    window_size = int(3.0 * sample_rate)
+    hop_size = int(1.0 * sample_rate)  # 2s overlap = 1s hop
+    meter = pyln.Meter(sample_rate)
+
+    if len(data) < window_size:
+        return 0.0
+
+    short_term_levels: list[float] = []
+    for start in range(0, len(data) - window_size + 1, hop_size):
+        window = data[start : start + window_size]
+        level = meter.integrated_loudness(window)
+        if np.isfinite(level):
+            short_term_levels.append(level)
+
+    if len(short_term_levels) < 2:
+        return 0.0
+
+    levels = np.array(short_term_levels)
+
+    # Gate: exclude windows below absolute threshold (-70 LUFS)
+    levels = levels[levels > -70.0]
+    if len(levels) < 2:
+        return 0.0
+
+    # LRA: difference between 95th and 10th percentiles
+    p95 = float(np.percentile(levels, 95))
+    p10 = float(np.percentile(levels, 10))
+    return max(0.0, p95 - p10)