sounddiff 0.1.0__tar.gz

sounddiff-0.1.0/.coderabbit.yaml

@@ -0,0 +1,72 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+# sounddiff — Python CLI for structured audio comparison
+inheritance: true
+
+reviews:
+  request_changes_workflow: true
+  profile: assertive
+  pre_merge_checks:
+    docstrings:
+      mode: "off"
+    title:
+      mode: warning
+    description:
+      mode: warning
+  path_filters:
+    - "!CLAUDE.md"
+    - "!docs/**"
+    - "!.coderabbit.yaml"
+    - "!scripts/**"
+  path_instructions:
+    - path: "src/sounddiff/**/*.py"
+      instructions: |
+        sounddiff is a Python 3.10+ CLI tool for structured audio comparison.
+        Uses numpy, scipy, pyloudnorm for DSP. Click for CLI. Rich for terminal output.
+        mypy strict mode. Ruff for linting and formatting.
+
+        Review priorities (highest to lowest):
+        1. Correctness of DSP algorithms (loudness, spectral, correlation math)
+        2. Type safety (all public functions must have complete type annotations)
+        3. Edge cases in audio processing (empty signals, mono/stereo, different sample rates)
+        4. Performance issues with measurable impact on large audio files
+        5. Error handling (clear messages for file not found, unsupported format, corrupt audio)
+
+        Known patterns, DO NOT flag:
+        - `from __future__ import annotations` at top of every module (PEP 604 unions on 3.10)
+        - `np.ndarray` without generic parameters (numpy typing is limited)
+        - `pyloudnorm` and `soundfile` are untyped (ignore_missing_imports in mypy config)
+        - Frozen dataclasses for all result types (immutability is intentional)
+        - Properties on frozen dataclasses for computed deltas (avoids storing derived values)
+
+        Do NOT flag:
+        - Missing docstrings on private functions (underscore-prefixed)
+        - Import ordering (ruff handles this)
+        - Line length (ruff formatter handles this)
+    - path: "src/sounddiff/cli.py"
+      instructions: |
+        CLI entry point using Click. Review for:
+        - Clear error messages for all failure modes
+        - Correct exit codes (0 success, 1 for errors)
+        - No unhandled exceptions reaching the user
+    - path: "src/sounddiff/{loudness,spectral,temporal,detection}.py"
+      instructions: |
+        Core DSP modules. Review with extra care for:
+        - Mathematical correctness (dB conversions, RMS calculations, correlation)
+        - Handling of edge cases (silence, single-sample files, DC offset)
+        - Numerical stability (division by zero, log of zero)
+        - Consistent units (always dB, Hz, seconds — never raw sample counts in output)
+    - path: "tests/**/*.py"
+      instructions: |
+        Test suite using pytest and hypothesis. Review for:
+        - Test isolation (no shared mutable state between tests)
+        - Meaningful assertions (not just "doesn't crash")
+        - Edge case coverage (empty input, mono, extreme values)
+        - Deterministic test audio generation (fixed seeds, no randomness without rng fixture)
+
+  tools:
+    ruff:
+      enabled: true
+
+knowledge_base:
+  web_search:
+    enabled: false

sounddiff-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,8 @@
+# Default owners for everything
+* @claudesystemblueio
+
+# Core audio analysis
+src/sounddiff/loudness.py @claudesystemblueio
+src/sounddiff/spectral.py @claudesystemblueio
+src/sounddiff/temporal.py @claudesystemblueio
+src/sounddiff/detection.py @claudesystemblueio

sounddiff-0.1.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [systemblueteam]

sounddiff-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,62 @@
+name: Bug Report
+description: Report a bug in sounddiff
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: A clear description of the bug.
+      placeholder: When I run sounddiff on two WAV files...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What did you expect?
+      description: What should have happened instead.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Minimal steps to reproduce the issue.
+      placeholder: |
+        1. Run `sounddiff a.wav b.wav`
+        2. See error...
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: sounddiff version
+      description: Output of `sounddiff --version`
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      description: Output of `python --version`
+      placeholder: "3.12.0"
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - macOS
+        - Linux
+        - Windows
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: audio
+    attributes:
+      label: Audio file details
+      description: Format, sample rate, channels, duration of the files involved (if relevant).

sounddiff-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

sounddiff-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,35 @@
+name: Feature Request
+description: Suggest a new feature for sounddiff
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the use case or workflow this feature would improve.
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How do you think this should work? CLI interface, output format, etc.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any other approaches you've thought about.
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Audio analysis
+        - CLI / UX
+        - Output formats
+        - Performance
+        - Documentation
+        - Other

sounddiff-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## What changed
+
+<!-- Brief description of the changes -->
+
+## Why
+
+<!-- Motivation: what problem does this solve? -->
+
+## How to verify
+
+<!-- Steps to test this change -->
+
+## Closes
+
+<!-- Closes #issue_number -->

sounddiff-0.1.0/.github/SECURITY.md

@@ -0,0 +1,33 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+|---------|--------------------|
+| 0.1.x   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it responsibly.
+
+**Do not open a public issue.**
+
+Email security concerns to **dev@systemblue.io** with:
+
+1. Description of the vulnerability
+2. Steps to reproduce
+3. Potential impact
+4. Suggested fix (if any)
+
+We will acknowledge receipt within 48 hours and provide a timeline for a fix. Security patches are prioritized over all other work.
+
+## Scope
+
+sounddiff processes audio files from disk. Relevant security concerns include:
+
+- Path traversal in file handling
+- Denial of service via malformed audio files
+- Dependency vulnerabilities
+- Secret leakage in CI/CD
+
+We run [gitleaks](https://github.com/gitleaks/gitleaks) in CI and as a pre-commit hook to prevent accidental secret commits.

sounddiff-0.1.0/.github/labeler.yml

@@ -0,0 +1,23 @@
+audio-core:
+  - changed-files:
+      - any-glob-to-any-file:
+          - src/sounddiff/loudness.py
+          - src/sounddiff/spectral.py
+          - src/sounddiff/temporal.py
+          - src/sounddiff/detection.py
+
+cli:
+  - changed-files:
+      - any-glob-to-any-file:
+          - src/sounddiff/cli.py
+
+docs:
+  - changed-files:
+      - any-glob-to-any-file:
+          - docs/**
+          - "*.md"
+
+tests:
+  - changed-files:
+      - any-glob-to-any-file:
+          - tests/**

sounddiff-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Ruff lint
+        run: ruff check .
+      - name: Ruff format
+        run: ruff format --check .
+      - name: mypy
+        run: mypy src
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y libsndfile1
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Generate test audio
+        run: python scripts/generate_test_audio.py
+      - name: Run tests
+        run: pytest --cov=sounddiff --cov-report=xml
+      - name: Upload coverage
+        if: matrix.python-version == '3.13'
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml
+          fail_ci_if_error: false

sounddiff-0.1.0/.github/workflows/labeler.yml

@@ -0,0 +1,17 @@
+name: Labeler
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/labeler@v5
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}

sounddiff-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,55 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install build tools
+        run: pip install build
+      - name: Build sdist and wheel
+        run: python -m build
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

sounddiff-0.1.0/.github/workflows/sentry.yml

@@ -0,0 +1,23 @@
+name: Sentry Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  sentry-release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Create Sentry Release
+        uses: getsentry/action-release@v3
+        env:
+          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
+          SENTRY_ORG: ${{ secrets.SENTRY_ORG }}
+          SENTRY_PROJECT: sounddiff
+        with:
+          environment: production
+          version: ${{ github.ref_name }}

sounddiff-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+
+# Distribution
+*.whl
+*.tar.gz
+
+# Generated test audio
+tests/fixtures/*.wav
+tests/fixtures/*.flac
+
+# Environment
+.env
+.env.*

sounddiff-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.14.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [types-click]
+        args: [--config-file=pyproject.toml]
+        pass_filenames: false
+        entry: mypy src
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.22.0
+    hooks:
+      - id: gitleaks

sounddiff-0.1.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-26
+
+### Added
+
+- Integrated LUFS comparison (ITU-R BS.1770 via pyloudnorm)
+- True peak measurement (dBTP)
+- Loudness range (LRA) comparison per EBU R128
+- Spectral band energy comparison (low/mid/high, configurable bands)
+- Waveform cross-correlation for segment similarity scoring
+- Segment change detection: added, removed, shifted, or changed sections
+- Clipping detection with timestamp, channel, and sample count
+- Silence detection with configurable threshold and minimum duration
+- Audio file loading via soundfile (WAV, FLAC, OGG, AIFF)
+- CLI with click: `sounddiff <file1> <file2>`
+- Terminal output with rich (colored, grouped by category)
+- JSON output for scripts and CI pipelines
+- HTML report output (self-contained, jinja2 templates)
+- `--no-color` flag for plain terminal output
+- `--version` flag
+- Sample rate mismatch warnings
+- Duration difference display in metadata section
+- Test suite with 60 tests (pytest + hypothesis)
+- CI pipeline (Python 3.10, 3.13 on Ubuntu)
+- Documentation (install, usage, API reference, architecture)
+
+### Fixed
+
+- Terminal output no longer prints twice
+- Spectral band delta no longer shows absurd values for near-zero energy bands
+
+[0.1.0]: https://github.com/systemblueteam/sounddiff/releases/tag/v0.1.0

sounddiff-0.1.0/CLAUDE.md

@@ -0,0 +1,50 @@
+# sounddiff
+
+Structured audio comparison CLI. Python 3.10+, src layout, hatchling build.
+
+## Build & Test
+
+```sh
+pip install -e ".[dev]"
+python scripts/generate_test_audio.py
+pytest
+ruff check . && ruff format --check . && mypy src
+```
+
+## Architecture
+
+```
+src/sounddiff/
+  types.py       # Dataclasses for all results
+  formats.py     # Audio I/O via soundfile
+  loudness.py    # LUFS, true peak, LRA (pyloudnorm)
+  spectral.py    # Band energy comparison (numpy FFT)
+  temporal.py    # Cross-correlation, segment detection
+  detection.py   # Clipping, silence detection
+  core.py        # Pipeline orchestration
+  cli.py         # Click CLI entry point
+  report.py      # Output formatters (terminal/JSON/HTML)
+```
+
+## Conventions
+
+- **Ruff** for linting and formatting. No black, isort, or flake8.
+- **mypy strict mode.** Type hints everywhere.
+- **Google-style docstrings** on all public functions.
+- **Conventional commits.** `feat:`, `fix:`, `docs:`, `test:`, `chore:`, `refactor:`.
+- **One concern per PR.** Small, focused diffs. Squash merge.
+- **pytest + hypothesis** for testing. Property-based tests for DSP functions.
+- **Test audio is generated, not committed.** Run `scripts/generate_test_audio.py`.
+- **No `# type: ignore` without a comment.**
+
+## Key dependencies
+
+| Package | Purpose |
+|---------|---------|
+| soundfile | Audio I/O (wav, flac, ogg, aiff) |
+| numpy | Array math, FFT, correlation |
+| scipy | Signal processing, filtering |
+| pyloudnorm | ITU-R BS.1770 LUFS measurement |
+| click | CLI framework |
+| rich | Terminal formatting |
+| jinja2 | HTML report templates |

sounddiff-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,41 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers at dev@systemblue.io. All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.0, available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.

sounddiff-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing to sounddiff
+
+Contributions are welcome. This guide covers everything you need to get set up and submit a pull request.
+
+## Development setup
+
+1. Fork and clone the repo
+2. Create a virtual environment: `python -m venv .venv && source .venv/bin/activate`
+3. Install dev dependencies: `pip install -e ".[dev]"`
+4. Install pre-commit hooks: `pre-commit install`
+5. Generate test audio fixtures: `python scripts/generate_test_audio.py`
+6. Run the test suite: `pytest`
+
+If all tests pass, your environment is ready.
+
+## Finding work
+
+The [issue board](https://github.com/systemblueteam/sounddiff/issues) is organized by milestone. Issues labeled [`good first issue`](https://github.com/systemblueteam/sounddiff/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) are scoped for newcomers and include enough context to get started without deep DSP knowledge.
+
+If you want to work on something, leave a comment on the issue so nobody duplicates effort. If you have an idea that isn't on the board, open an issue first so we can align on scope before you write code.
+
+## Development workflow
+
+1. Create a branch from `main`: `git checkout -b feat/42-your-description`
+2. Make your changes and write tests for new behavior
+3. Run the full check: `ruff check . && ruff format --check . && mypy src && pytest`
+4. Commit using [conventional commits](https://www.conventionalcommits.org/): `feat: add stereo field analysis`
+5. Push your branch and open a PR against `main`
+
+## Pull request guidelines
+
+- **One concern per PR.** Keep diffs focused and reviewable.
+- **Reference the issue** in your PR body: `Closes #42`
+- **CI must pass** before review. The pipeline runs ruff, mypy, and pytest across Python 3.10-3.13 on Linux and macOS.
+- **[CodeRabbit](https://coderabbit.ai) reviews every PR automatically.** Address its feedback or explain your reasoning if you disagree.
+- Maintainers will review within a few days. If a week goes by without a response, ping us in the PR.
+
+## Code standards
+
+**Formatting and linting** are handled by [ruff](https://docs.astral.sh/ruff/). Pre-commit hooks run automatically, so you don't need to think about formatting manually.
+
+**Type annotations** are required on all public functions. [mypy](https://mypy.readthedocs.io/) runs in strict mode.
+
+**Docstrings** follow [Google style](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) on public functions. Private functions (underscore-prefixed) don't require them.
+
+**No `# type: ignore`** without a comment explaining why.
+
+## Testing
+
+Every new feature needs tests. Every bug fix needs a regression test.
+
+We use [pytest](https://docs.pytest.org/) for the test suite and [hypothesis](https://hypothesis.readthedocs.io/) for property-based testing on DSP functions. Test audio is generated deterministically by `scripts/generate_test_audio.py` and is not committed to the repo. This keeps the repo lightweight and tests reproducible.
+
+If you're unsure how to test something, ask in the issue. We'd rather help you write a good test than skip testing.
+
+## Conventions
+
+### Branch naming
+
+Include the issue number when there is one:
+
+- `feat/42-segment-detection`
+- `fix/17-clipping-threshold`
+- `docs/8-usage-guide`
+- `chore/12-ci-update`
+
+### Commit messages
+
+```text
+feat: add spectral band comparison
+fix: handle mono files in loudness calculation
+docs: add installation guide
+test: add property tests for temporal alignment
+chore: update CI to Python 3.13
+refactor: extract segment detection into its own module
+```
+
+## Questions
+
+Open an [issue](https://github.com/systemblueteam/sounddiff/issues). We're happy to help with anything from setup problems to architecture questions.