audio-super-resolution 0.1.0__tar.gz

audio_super_resolution-0.1.0/.dockerignore

@@ -0,0 +1,10 @@
+.git
+.github
+.pixi
+.pytest_cache
+.ruff_cache
+dist
+build
+*.egg-info
+__pycache__
+*.pyc

audio_super_resolution-0.1.0/.gitattributes

@@ -0,0 +1,7 @@
+* text=auto
+*.md text eol=lf
+*.py text eol=lf
+*.toml text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.lock text eol=lf

audio_super_resolution-0.1.0/.github/ISSUE_TEMPLATE/BUG_REPORT.yml

@@ -0,0 +1,58 @@
+name: Bug report
+description: Report a problem with the CLI, Python API, packaging, or backend behavior
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the bug
+      description: Provide a concise description of what failed and what you expected.
+      placeholder: What happened?
+    validations:
+      required: true
+  - type: checkboxes
+    id: searched
+    attributes:
+      label: Existing issues
+      description: Please search existing issues before filing a new report.
+      options:
+        - label: I have searched and found no existing issue for this problem.
+          required: true
+  - type: textarea
+    id: command
+    attributes:
+      label: Command or code
+      description: Paste the exact command or minimal Python snippet that reproduces the issue.
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs
+      description: Include the full error output or stack trace.
+      render: shell
+  - type: textarea
+    id: system
+    attributes:
+      label: System information
+      description: Run `audio-super-res --env-info` and paste the output here.
+      render: shell
+    validations:
+      required: true
+  - type: dropdown
+    id: backend
+    attributes:
+      label: Backend
+      options:
+        - sinc-resample
+        - audiosr
+        - other / not sure
+    validations:
+      required: true
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Add any other useful information here.

audio_super_resolution-0.1.0/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml

@@ -0,0 +1,37 @@
+name: Feature request
+description: Suggest an enhancement or new backend
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or use case
+      description: Describe the workflow or limitation this feature should address.
+      placeholder: I want to...
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Describe the behavior, API, or CLI you would like.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Note any workaround or alternative backend you considered.
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - CLI
+        - Python API
+        - backend
+        - packaging
+        - documentation
+        - testing
+        - other

audio_super_resolution-0.1.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5

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

@@ -0,0 +1,19 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: prefix-dev/setup-pixi@v0.9.6
+        with:
+          pixi-version: v0.63.2
+      - run: pixi run lint
+      - run: pixi run test

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

@@ -0,0 +1,24 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: prefix-dev/setup-pixi@v0.9.6
+        with:
+          pixi-version: v0.63.2
+      - run: pixi run lint
+      - run: pixi run test
+      - run: pixi run build
+      - uses: pypa/gh-action-pypi-publish@release/v1

audio_super_resolution-0.1.0/.github/workflows/security.yml

@@ -0,0 +1,21 @@
+name: Security
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  codeql:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: github/codeql-action/init@v4
+        with:
+          languages: python
+      - uses: github/codeql-action/analyze@v4

audio_super_resolution-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.pixi/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.coverage
+coverage.xml
+.DS_Store

audio_super_resolution-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows semantic versioning once published to PyPI.
+
+## 0.1.0
+
+- Added the initial Pixi-managed Python package.
+- Added `audio-super-res` and `audiosr` CLI entry points.
+- Added single-file and recursive directory batch processing.
+- Added explicit chunked processing with overlap crossfading for long files.
+- Added backend selection with the baseline `sinc-resample` backend.
+- Added inference configuration for device, precision, chunking, seed, and model cache path.
+- Added audio quality checks for sample rate, duration drift, clipping, and peak level.
+- Added standalone JSON quality report export through `--quality-report-json`.
+- Added examples for single-file enhancement, batch processing, and quality checks.
+- Added the optional `audiosr` backend wrapper for AudioSR latent diffusion inference.
+- Added an environment-gated real AudioSR integration test.
+- Added backend availability metadata and JSON output for `--list-backends`.
+- Added model catalog output through `--list-models`.
+- Added JSON manifests for dry-run plans and completed enhancement runs.
+- Added manifest regression comparison through `--compare-manifests`.
+- Added optional low-pass preprocessing for model-backed enhancement runs.
+- Added managed weight manifests, local cache verification, and explicit Hugging Face download plumbing.
+- Added LavaSR-compatible managed weight metadata while keeping self-contained LavaSR inference marked as pending.
+- Added PyPI Trusted Publishing / GitHub OIDC release workflow configuration.
+- Added release dry-run notes, a Colab plan, and sample JSON artifacts.
+- Added GitHub issue templates, Dependabot configuration, CodeQL security workflow, and architecture/test documentation.

audio_super_resolution-0.1.0/Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.12-slim
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libsndfile1 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+
+RUN pip install --no-cache-dir .
+
+WORKDIR /workdir
+
+ENTRYPOINT ["audio-super-res"]

audio_super_resolution-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SiTinc
+
+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_super_resolution-0.1.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: audio-super-resolution
+Version: 0.1.0
+Summary: Easy to use audio super-resolution and bandwidth extension from CLI or as a Python package.
+Project-URL: Homepage, https://github.com/Tinnci/python-audio-super-resolution
+Project-URL: Repository, https://github.com/Tinnci/python-audio-super-resolution
+Project-URL: Documentation, https://github.com/Tinnci/python-audio-super-resolution/blob/main/README.md
+Project-URL: Issues, https://github.com/Tinnci/python-audio-super-resolution/issues
+Author: SiTinc
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audio,audiosr,bandwidth-extension,music,speech,super-resolution
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.23.5
+Requires-Dist: scipy>=1.11
+Requires-Dist: soundfile>=0.12
+Requires-Dist: tqdm>=4.66
+Provides-Extra: audiosr
+Requires-Dist: audiosr==0.0.7; extra == 'audiosr'
+Provides-Extra: download
+Requires-Dist: huggingface-hub>=0.24; extra == 'download'
+Provides-Extra: lavasr
+Requires-Dist: pyyaml>=6; extra == 'lavasr'
+Requires-Dist: torch>=2; extra == 'lavasr'
+Provides-Extra: weights
+Requires-Dist: safetensors>=0.4; extra == 'weights'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# Audio Super Resolution
+
+[![PyPI version](https://badge.fury.io/py/audio-super-resolution.svg)](https://badge.fury.io/py/audio-super-resolution)
+[![CI](https://github.com/Tinnci/python-audio-super-resolution/actions/workflows/ci.yml/badge.svg)](https://github.com/Tinnci/python-audio-super-resolution/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+</div>
+
+Audio Super Resolution is a Python CLI and library for audio super-resolution and bandwidth extension. It ships with a deterministic `sinc-resample` baseline, optional external AudioSR support, and managed metadata for self-contained model backends.
+
+The baseline package stays lightweight: normal inference is offline, model downloads are explicit, and heavyweight model dependencies live behind optional extras.
+
+## Features
+
+- CLI and Python API for single files, directory batches, dry runs, and recursive path-preserving output.
+- Pluggable backend registry with `sinc-resample`, optional `audiosr`, and LavaSR-compatible managed weight metadata.
+- Shared inference config for device, precision, chunking, preprocessing, seeds, and model cache paths.
+- JSON run manifests, manifest comparison, and quality reports for regression workflows.
+- Explicit local weight resolution with multi-file manifests, size/SHA256 checks, and opt-in Hugging Face downloads.
+- Pixi tasks for repeatable test, lint, format, and build commands.
+
+## Installation
+
+Install from GitHub:
+
+```sh
+pip install git+https://github.com/Tinnci/python-audio-super-resolution.git
+```
+
+For local development:
+
+```sh
+git clone https://github.com/Tinnci/python-audio-super-resolution.git
+cd python-audio-super-resolution
+pixi install
+```
+
+Optional extras:
+
+| Extra | Purpose |
+| --- | --- |
+| `audiosr` | External AudioSR wrapper. Use Python 3.10 because upstream dependencies are older. |
+| `download` | Hugging Face model weight downloads. |
+| `weights` | Optional safetensors loading helpers. |
+| `lavasr` | LavaSR-compatible runtime dependencies. Inference is not implemented yet. |
+
+Example:
+
+```sh
+pip install "audio-super-resolution[lavasr,download] @ git+https://github.com/Tinnci/python-audio-super-resolution.git"
+```
+
+## CLI Quick Start
+
+Enhance one file:
+
+```sh
+audio-super-res input.wav output.wav --target-sr 48000
+```
+
+If `output.wav` is omitted, the CLI writes next to the input as `input-sr48000.wav`.
+
+Batch process a directory:
+
+```sh
+audio-super-res ./low-res-audio ./enhanced-audio --recursive --target-sr 48000
+```
+
+Preview or record a run:
+
+```sh
+audio-super-res ./low-res-audio ./enhanced-audio --recursive --dry-run --manifest plan.json
+audio-super-res ./low-res-audio ./enhanced-audio --recursive --manifest run.json
+audio-super-res --compare-manifests expected.json actual.json
+```
+
+List backends and models:
+
+```sh
+audio-super-res --list-backends
+audio-super-res --list-models --list-format json
+```
+
+Run post-write quality checks:
+
+```sh
+audio-super-res input.wav output.wav --quality-report --fail-on-quality-issue
+audio-super-res input.wav output.wav --quality-report-json quality.json
+```
+
+The shorter `audiosr` command is also available as an alias for `audio-super-res`.
+
+## Models And Weights
+
+Current backend status:
+
+| Backend | Status |
+| --- | --- |
+| `sinc-resample` | Default deterministic baseline. |
+| `audiosr` | Optional external package backend; upstream package owns its checkpoint behavior. |
+| `lavasr-compat` | LavaSR v2 BWE download and verification are wired; self-contained inference is pending. |
+
+Managed downloads are explicit. Normal enhancement only uses local verified files unless `--download-weights` is set:
+
+```sh
+audio-super-res --backend lavasr-compat --download-weights --prepare-model-cache
+audio-super-res --backend lavasr-compat --verify-weights
+```
+
+Use an existing manifest:
+
+```sh
+audio-super-res input.wav output.wav \
+  --backend lavasr-compat \
+  --target-sr 48000 \
+  --weights-manifest C:\path\to\lavasr-v2-bwe\manifest.json
+```
+
+Run the optional external AudioSR backend:
+
+```sh
+audio-super-res input.wav output.wav \
+  --backend audiosr \
+  --target-sr 48000 \
+  --model-name basic \
+  --device auto
+```
+
+## Python API
+
+```python
+from audio_super_resolution import AudioSuperResolver
+
+resolver = AudioSuperResolver(target_sr=48000)
+result = resolver.enhance("input.wav", "output.wav")
+
+print(result.output_path)
+print(result.sample_rate)
+```
+
+Batch planning and manifests:
+
+```python
+from audio_super_resolution import InferenceConfig, build_manifest, plan_enhancements
+
+jobs = plan_enhancements("low-res-audio", "enhanced-audio", recursive=True)
+manifest = build_manifest("dry-run", jobs, InferenceConfig(), backend="sinc-resample", target_sample_rate=48000)
+```
+
+Managed weights:
+
+```python
+from audio_super_resolution import InferenceConfig, download_model_weights, resolve_model_weights, verify_model_weights
+
+download_model_weights("lavasr-v2-bwe")
+verified = verify_model_weights("lavasr-v2-bwe")
+weights = resolve_model_weights("lavasr-v2-bwe", InferenceConfig(model_cache_dir=verified.root_dir.parent))
+model_path = weights.path_for("enhancer_v2/pytorch_model.bin")
+```
+
+## Development
+
+```sh
+pixi run test
+pixi run lint
+pixi run format
+pixi run build
+```
+
+Run optional real AudioSR integration only when model inference and upstream checkpoint handling are intended:
+
+```sh
+set AUDIO_SUPER_RESOLUTION_RUN_AUDIOSR_INTEGRATION=1
+pixi run pytest tests/test_audiosr_integration.py
+```
+
+## Docker
+
+```sh
+docker build -t audio-super-resolution .
+docker run --rm -v "%cd%":/workdir audio-super-resolution input.wav output.wav --target-sr 48000
+```
+
+On Unix-like shells, use `-v "$PWD":/workdir`.
+
+## Project Docs
+
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): package layers, backend contract, and weight-management boundaries.
+- [ROADMAP.md](ROADMAP.md): current status and next implementation work.
+- [docs/RELEASE.md](docs/RELEASE.md): release checklist and publishing notes.
+- [tests/README.md](tests/README.md): default and optional test strategy.
+- [examples/](examples/): Python examples and sample JSON artifacts.
+
+## Requirements
+
+- Python 3.10 or newer
+- Pixi for development
+- libsndfile-compatible audio files for the default reader/writer
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
+
+## Credits
+
+Inspired by the project structure and user experience of [python-audio-separator](https://github.com/nomadkaraoke/python-audio-separator).