AudioSR GitHub Install Guide: How to Run AudioSR Locally
AudioSR is an open-source audio super-resolution model. It generates missing high-frequency detail in speech, music, and sound effects to produce 48 kHz audio. You can install it from the official GitHub repository or run AudioSR online with Neural Analog.
To install it locally, clone the repository, create a Python 3.10 environment with uv, install a compatible PyTorch build and AudioSR, then run python -m audiosr on a short WAV file. The steps below cover each command.
How Does AudioSR Work? Architecture Explained
How AudioSR reconstructs missing high frequencies
The input mel spectrogram conditions latent diffusion to estimate a fuller-bandwidth mel spectrogram. The input's lower mel bands replace the generated ones before the vocoder; its lower STFT bands replace the generated ones after the vocoder. The model generates plausible missing detail, rather than recovering an exact lost recording.

Original figure: AudioSR.
AudioSR converts the recording into a mel spectrogram, uses a latent diffusion model to estimate the missing high-frequency detail, and turns the result back into a waveform with a vocoder. Postprocessing then puts the source's original lower frequencies back in place of the generated ones. The result is a plausible reconstruction, not an exact recovery of lost audio, and it is not just added noise.
Where Can You Run AudioSR?
| Option | Best fit | Setup and tradeoff |
|---|---|---|
| Neural Analog AudioSR Online (recommended) | Stereo restoration with mid/side processing and a customizable frequency cutoff | Upload, preview, and export online. No Python installation or local GPU needed. |
| Official GitHub repo | Local experiments and Python scripts | Install dependencies, download weights, and supply the compute. |
| AudioSR Colab notebook | Experiments using Google's cloud GPUs | Open the community notebook and follow its instructions in your browser. |
| Hugging Face Space | A quick browser demo | Community deployment; availability and GPU quotas can change. |
| AudioSR on Replicate | Hosted predictions and API integration | Usage-based billing; no local model installation. |
Neural Analog processes the center and side information of stereo audio separately. You can also set the cutoff frequency where AudioSR starts regenerating detail. A lower cutoff changes more of the sound, while a higher cutoff only fills the top end.
AudioSR Requirements: Python, GPU Memory, and Disk Space
AudioSR is a heavy model, especially for full songs. The official basic checkpoint is about 6.2 GB on disk, and inference needs more memory than the stored weights. A large NVIDIA GPU helps, but the checkpoint size is not a minimum VRAM figure: clip length and implementation also affect memory use. The official README does not publish a minimum GPU requirement.
Long inputs can exhaust GPU memory. Start with a short clip, then process longer recordings in smaller chunks.
Prepare these dependencies before starting:
- Python in an isolated environment. The upstream example uses Python 3.9. This guide uses Python 3.10, which works with the older NumPy versions AudioSR requires. A virtual environment keeps these packages out of your system Python.
- Git and uv. Install Git and uv to download the source and manage the Python environment.
- PyTorch and an appropriate GPU driver. NVIDIA users need a CUDA-compatible PyTorch build. Match the PyTorch, TorchAudio, and TorchVision versions using the official installation matrix.
- FFmpeg, including ffprobe. The upstream file-saving code uses these commands. Install them through the FFmpeg download options and make them available in your terminal.
- Free disk space and an internet connection. Allow space for the environment, downloaded model weights, input files, and outputs. The first model load downloads its checkpoint.
The upstream device selection code recognizes CUDA, Apple MPS, and CPU. CPU processing can be very slow. MPS support in the device check does not guarantee that every dependency and operation works on every Mac.
How to Install AudioSR from GitHub
1. Download the Official Repo and Create a Python Environment
Run these commands in a terminal:
git clone https://github.com/haoheliu/versatile_audio_super_resolution.git
cd versatile_audio_super_resolution
uv venv --python 3.10
Activate the environment on Linux or macOS:
source .venv/bin/activate
On Windows PowerShell, use this activation command instead:
.venv\Scripts\Activate.ps1
2. Install Compatible Dependencies and AudioSR
AudioSR has older dependency constraints, including NumPy 1.23.5 or earlier and Transformers 4.30.2. Installing the newest Python and PyTorch versions can cause compatibility errors. The project's package requirements and reference environment are useful starting points.
For example, the reference environment pairs PyTorch 2.0.1, TorchAudio 2.0.2, and TorchVision 0.15.2. On Linux or Windows with a suitable NVIDIA driver, install that CUDA 11.7 combination, then the checked-out AudioSR source:
uv pip install torch==2.0.1 torchaudio==2.0.2 torchvision==0.15.2 --index-url https://download.pytorch.org/whl/cu117
uv pip install .
python -m audiosr --help
The CUDA command is for NVIDIA systems. Use the matching macOS or CPU instructions in the PyTorch matrix for those devices. These are legacy dependency versions, so keep this environment separate from other Python projects.
If you only need the published package, the official README also documents audiosr==0.0.7. That release and GitHub's current main branch can have different features, so check python -m audiosr --help for the version you installed.
3. Check That Python Can See Your GPU
Run this check inside the activated environment on an NVIDIA machine:
python -c "import torch; print('CUDA available:', torch.cuda.is_available())"
ffmpeg -version
ffprobe -version
If CUDA is unavailable, fix the driver or PyTorch installation before starting a long job. Adding -d cuda to AudioSR cannot make an unavailable GPU work.
AudioSR Command-Line Usage: Start with a Short WAV
Use a short mono WAV for the first run. The upstream audio loader recommends 5.12-second inputs and warns about quality beyond 10.24 seconds. A full song makes setup and memory problems harder to diagnose.
Put input.wav in the repository directory, then run:
python -m audiosr -i input.wav -s output --model_name basic -d cuda --ddim_steps 50 --seed 42
The command-line implementation saves 48 kHz WAV output in a timestamped folder under output. Use basic for general audio or speech for spoken recordings. The seed controls the generated variation; comparing a few seeds can help you choose a better result.
If generation finishes but saving raises numpy.ndarray has no attribute cpu, use the Python example below to write the output directly. In the GitHub source checked for this guide, inference returns a NumPy array but the file-saving function expects a tensor. That is an upstream output-type mismatch, not a GPU memory error.
Current GitHub code also exposes chunking for longer files:
python -m audiosr -i input.wav -s output --model_name basic -d cuda --ddim_steps 50 --chunking --chunk_duration 5 --overlap_duration 1
Chunking processes smaller sections and blends their overlaps. It lowers memory use, but adds joins you need to check by ear. These flags are version-specific, and the upstream chunked path mixes stereo input down to mono, so keep the original stereo file.
How to Use AudioSR from Python
Use the Python API to call AudioSR from your own script. The example below runs a short mono file, trims padding to the input duration, and writes a 48 kHz WAV. Save it as run_audiosr.py in the repository directory.
import numpy as np
import soundfile as sf
import torch
from audiosr import build_model, super_resolution
model = build_model(model_name="basic", device="cuda")
waveform = super_resolution(
model,
"input.wav",
seed=42,
ddim_steps=50,
guidance_scale=3.5,
)
if isinstance(waveform, torch.Tensor):
waveform = waveform.detach().cpu().numpy()
audio = np.asarray(waveform)[0, 0]
input_info = sf.info("input.wav")
output_samples = round(input_info.frames * 48000 / input_info.samplerate)
sf.write("output.wav", audio[:output_samples], 48000, subtype="PCM_24")
python run_audiosr.py
The Python pipeline loads the model once, so a batch-processing script can reuse it. In Neural Analog, batch processing runs one restoration across many files without a script. Set the number of sampling steps explicitly, because the Python API and CLI may use different defaults.
How to Run AudioSR in Google Colab
Google Colab lets you run AudioSR on Google's cloud hardware. Open the community AudioSR Colab notebook and follow its instructions to load your audio, run the model, and save the result. The notebook runs in your browser, so you need no Python installation or GPU on your computer.
The notebook is a community adaptation of AudioSR. Its source is available on GitHub.
Where Can You Download AudioSR Model Weights?
Download the AudioSR model weights on Hugging Face.
AudioSR Model Details: Architecture, Training, and History
Who Created AudioSR?
AudioSR is a generative audio super-resolution model by Haohe Liu, Ke Chen, Qiao Tian, Wenwu Wang, and Mark D. Plumbley. It predicts missing high frequencies in speech, music, and sound effects and produces 48 kHz audio. The AudioSR research page includes the paper and listening examples. The work first appeared as a September 2023 preprint and was published at ICASSP 2024.
AudioSR generates plausible detail. It cannot recover an exact copy of a lost studio master. Converting an MP3 to a 48 kHz WAV does not perform this reconstruction at all. For that distinction, see the guide to upscaling MP3 files to WAV.
Audio Upscaling, Resampling, and Bandwidth Are Different
Resampling changes how many samples represent each second of audio. Audio upscaling, or super-resolution, tries to estimate frequency content that the recording no longer contains. For example, resampling an 8 kHz recording to 48 kHz gives it more samples, but does not by itself restore sounds above its original 4 kHz frequency limit.
AudioSR targets input bandwidths from 2 to 16 kHz and generates output with a 24 kHz bandwidth at a 48 kHz sample rate, according to the official project description. Bandwidth describes the frequency range; sample rate describes samples per second. A file labeled 48 kHz can still have a narrow bandwidth because of earlier compression or filtering. Many AI-generated songs are like this, which is why Suno songs often sound muffled.
Was AudioSR the First Audio Upscaling Model?
AudioSR was not the first neural audio upscaler. Kuleshov, Enam, and Ermon published Audio Super Resolution using Neural Networks in 2017, and diffusion-based speech upscaling also came before AudioSR.
Its contribution is narrower. The AudioSR paper presents it as the first system covering the general audible domain: music, speech, and sound effects. It combines that breadth with flexible input bandwidth rather than introducing audio super-resolution itself.
From the Input Recording to a 48 kHz Waveform
AudioSR combines a variational autoencoder (VAE), a conditional latent diffusion model, and a neural vocoder. Each component handles a stage of the reconstruction:
| Stage | What happens | Why it matters |
|---|---|---|
| Audio representation | The input becomes a mel spectrogram: a map of sound energy across time and frequency. | The model works with patterns of frequency content. |
| VAE encoding | An encoder compresses the spectrogram into a smaller representation called a latent. | Diffusion operates on fewer values than a full spectrogram. |
| Conditional diffusion | A Transformer U-Net iteratively refines a noisy latent, guided by the low-resolution input latent. | The recording guides the generated detail; no text prompt is needed. |
| Decoding and vocoder | The VAE decodes a higher-resolution mel spectrogram. A HiFi-GAN-based vocoder turns it into a waveform. | A spectrogram must be converted back into audible samples. |
| Frequency replacement | Lower-frequency information from the input replaces corresponding generated bands. | Existing information helps constrain changes to the recording. |
The published model configuration specifies a 256-band mel representation, a VAE, and a U-Net with spatial transformers. It concatenates the input's encoded low-pass features with the diffusion latent. This is audio-conditioned generation, even though some inherited CLI descriptions mention text.
What Do Sampling Steps and Guidance Control?
Sampling steps control how many iterations the model spends refining its generated representation. AudioSR uses a DDIM sampler. Guidance controls how strongly the input conditioning steers generation. It is not an EQ amount, and a higher value does not guarantee higher quality. The inference implementation applies sampling, decoding, frequency replacement, and waveform normalization in sequence.
More sampling steps and longer recordings take more processing time. AudioSR is intended for offline processing, and actual speed depends on your GPU and settings. Reducing ddim_steps speeds up generation, but does not reliably solve GPU memory errors.
How Was AudioSR Trained?
The paper's training section describes approximately 7,000 hours from MUSDB18-HQ, MoisesDB, MedleyDB, Freesound, and OpenSLR speech data. Low-pass filters with varied cutoffs create degraded inputs paired with fuller-bandwidth targets. The diffusion model uses a cosine noise schedule, velocity prediction, and classifier-free guidance. The vocoder is based on HiFi-GAN with a multi-resolution discriminator.
Real recordings can differ from these training examples. The authors explain that irregular frequency cutoffs, heavy noise, and reverb can reduce quality. MP3 compression can leave gaps near the cutoff. Low-pass filtering before inference can help, but a cutoff set too low removes useful detail. For reverberant recordings, removing the reverb before upscaling can give the model a cleaner input.
You do not need to train these components to run AudioSR. The installation workflow loads pretrained weights.
Why Does AudioSR Use Postprocessing?
The generated audio should retain useful information that already exists in the source. AudioSR replaces lower bands twice: in the estimated mel spectrogram before the vocoder, and in the short-time Fourier transform (STFT) representation of the resulting waveform. The replacement code estimates a cutoff and adjusts the reconstructed output.
Stereo recordings and full songs need a pipeline that handles channels, chunks, and reconstruction. The default repository workflow produces mono audio: the standard loader takes the first input channel, while the chunked pipeline downmixes stereo to mono. Preserving stereo requires additional channel handling, such as the community notebook's separate processing of left and right channels.
Reconstruction needs a listening check. The community pipeline notes warn that excessive overlap can cause phase cancellations. Compare the result at similar loudness and check the regenerated highs, chunk joins, duration, and stereo image. Frequency replacement helps preserve the source, but does not guarantee an unchanged lower band or clean joins.
AudioSR Troubleshooting FAQ
Is AudioSR on PyPI?
Yes. The official README installs audiosr==0.0.7 with pip, or the latest code straight from GitHub. The GitHub main branch has features, such as chunking, that the PyPI release may lack.
How much GPU memory does AudioSR need?
The README gives no minimum. The basic checkpoint alone is about 6.2 GB on disk, and memory use grows with clip length. Start with a clip of about 5 seconds, then use chunking for longer files.
Why does AudioSR fail with numpy.ndarray has no attribute cpu?
Inference finished, but the save step expects a PyTorch tensor and receives a NumPy array. Use the Python script above, which writes the output with soundfile.
Why is my AudioSR output mono?
The default loader reads only the first channel, and the chunked path mixes stereo down to mono. Process the left and right channels separately, or use AudioSR Online, which processes the mid and side channels for you.
Is the AudioSR training code available?
Yes. The README changelog for December 31, 2024 links the training code, which the author describes as for reference only and not carefully organized.
Run AudioSR with Neural Analog Instead of Managing the Setup
To skip the local setup, open AudioSR Online, upload a file or import a supported music link, and adjust the restoration settings. Public Udio links work too, even though Udio has turned off downloads. You can choose a frequency cutoff, preview the processed result, and export audio from the same interface.
Neural Analog handles the model processing online, so you can use a computer without a large GPU and skip Python installation, checkpoint downloads, and notebook maintenance. You still need to listen critically, because a hosted workflow does not remove the model's quality limitations. After restoration, follow the audio improvement guide for the next steps. For AI-generated music, fixing AI song audio quality covers stem repair and mastering after upscaling.
You can also compare AudioSR with newer audio upscaling models available on Neural Analog, including UniverSR and FlashSR. Their model cards explain how each one works, and the FAQ sums up how UniverSR differs from AudioSR. For a worked example, see all 203 RPG Maker 2000 sound effects restored to 48 kHz with UniverSR. Run them on the same recording and compare the previews to pick the best result.