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 experimental lavasr-compat.
• Shared inference config for device, precision, chunking, preprocessing, seeds, and model cache paths.
• Import-light accelerator and runtime-provider metadata for CPU/CUDA/ROCm/XPU/MPS/DirectML planning.
• JSON run manifests, manifest comparison, and quality reports for regression workflows.
• Optional benchmark JSON reports for local accelerator/runtime validation.
• Explicit local weight resolution with multi-file manifests, size/SHA256 checks, and opt-in Hugging Face downloads.
• Pixi tasks for repeatable lint, format, typecheck, test, build, and package validation commands.

Installation

Install from PyPI:

uv pip install audio-super-resolution

Install optional model/runtime extras only when needed. For example, LavaSR-compatible inference with managed Hugging Face downloads uses:

uv pip install "audio-super-resolution[lavasr,download]"

Install the unreleased repository version from GitHub:

uv pip install "audio-super-resolution @ git+https://github.com/Tinnci/python-audio-super-resolution.git"

GitHub installs can include extras:

uv pip install "audio-super-resolution[lavasr,download] @ git+https://github.com/Tinnci/python-audio-super-resolution.git"

For local development:

git clone https://github.com/Tinnci/python-audio-super-resolution.git
cd python-audio-super-resolution
pixi install

Optional extras:

CLI Quick Start

Enhance one file:

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:

audio-super-res ./low-res-audio ./enhanced-audio --recursive --target-sr 48000

Preview or record a run:

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

Run a lightweight backend eval over clean references:

audio-super-res eval run --dataset evalsets/speech_clean_48k --backend sinc-resample --work-dir runs/sinc-work --output runs/sinc.json
audio-super-res eval compare runs/sinc.json runs/lavasr.json --output runs/comparison.json

List backends and models:

audio-super-res --list-backends
audio-super-res --list-models --list-format json

Run post-write quality checks:

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
audio-super-res input.wav output.wav --benchmark-json benchmark.json

The shorter audiosr command is also available as an alias for audio-super-res.

Models And Weights

Current backend status:

Use audio-super-res --list-models --list-format json for machine-readable comparison metadata, including task/domain, input and target sample rates, implementation family, I/O capabilities, accelerator and runtime-provider declarations, weight source/size/license, validation evidence, recommended use, and known limitations.

Accelerator install paths, device=auto behavior, runtime-provider selection, and gated benchmark guidance live in docs/ACCELERATORS.md.

Future model candidates are tracked in the speech and general-audio reviews linked from docs/README.md. Candidate entries are not supported backends until they pass admission and validation.

Managed downloads are explicit. Normal enhancement only uses local verified files unless --download-weights is set:

audio-super-res --backend lavasr-compat --download-weights --prepare-model-cache
audio-super-res --backend lavasr-compat --verify-weights

Use an existing manifest:

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:

audio-super-res input.wav output.wav \
  --backend audiosr \
  --target-sr 48000 \
  --model-name basic \
  --device auto

Python API

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:

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:

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

pixi run lint
pixi run format-check
pixi run typecheck
pixi run test
pixi run build
pixi run metadata-check
pixi run wheel-check

Run optional real AudioSR integration only when model inference and upstream checkpoint handling are intended:

set AUDIO_SUPER_RESOLUTION_RUN_AUDIOSR_INTEGRATION=1
pixi run pytest tests/test_audiosr_integration.py

Real LavaSR weight download and torch smoke tests are also gated; see tests/README.md.

Docker

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/README.md: documentation map and ownership rules.
• docs/ARCHITECTURE.md: package layers, backend contract, and weight-management boundaries.
• docs/ACCELERATORS.md: accelerator install strategy, runtime providers, and validation matrix.
• docs/EVALUATION.md: eval/regression, golden compatibility, metrics, and manifests.
• docs/BACKEND_CANDIDATES.md: candidate evidence and implementation blockers.
• docs/RELEASE.md: merge, package, and release checklist.
• ROADMAP.md: prioritized next work and completed milestone summary.
• CHANGELOG.md: release history and unreleased changes.
• tests/README.md: default and optional test strategy.
• examples/: Python examples and sample JSON artifacts.

Requirements

• Python 3.10 or newer
• Pixi 0.70 or newer for development; the committed pixi.lock uses lock-file version 7.
• libsndfile-compatible audio files for the default reader/writer

License

This project is licensed under the MIT License. See LICENSE for details.

Credits

Inspired by the project structure and user experience of python-audio-separator.