Instalar o AudioSR pelo GitHub: como executá-lo localmente

September 16, 2026

O AudioSR é um modelo de super-resolução de áudio de código aberto. Ele gera os detalhes de alta frequência ausentes em fala, música e efeitos sonoros para produzir áudio a 48 kHz. Você pode instalá-lo pelo repositório oficial no GitHub ou usar o AudioSR online com o Neural Analog.

Para instalar localmente, clone o repositório, crie um ambiente Python 3.10 com uv, instale uma versão compatível do PyTorch e o AudioSR e execute python -m audiosr em um arquivo WAV curto. Os passos abaixo explicam cada comando.

Como funciona o AudioSR? Entenda a arquitetura

O AudioSR converte a gravação em um espectrograma mel, usa um modelo de difusão latente para estimar os detalhes de alta frequência ausentes e transforma o resultado em uma forma de onda com um vocoder. O pós-processamento então recoloca as frequências baixas originais da fonte no lugar das geradas. O resultado é uma reconstrução plausível, não uma recuperação exata do áudio perdido, e não é apenas ruído adicionado.

Onde você pode executar o AudioSR?

O Neural Analog processa separadamente as informações de centro e diferença do áudio estéreo. Você também pode definir a frequência de corte a partir da qual o AudioSR começa a regenerar detalhes. Um corte mais baixo muda mais o som, enquanto um corte mais alto preenche apenas a região mais aguda.

Requisitos do AudioSR: Python, memória da GPU e espaço em disco

O AudioSR é um modelo pesado, principalmente para músicas completas. O checkpoint básico oficial ocupa cerca de 6,2 GB em disco, e a inferência precisa de mais memória do que os pesos armazenados. Uma GPU NVIDIA com bastante memória ajuda, mas o tamanho do checkpoint não é um valor mínimo de VRAM: a duração do trecho e a implementação também afetam o uso de memória. O README oficial não publica um requisito mínimo de GPU.

Entradas longas podem esgotar a memória da GPU. Comece com um trecho curto e depois processe gravações mais longas em segmentos menores.

Prepare estas dependências antes de começar:

• Python em um ambiente isolado. O exemplo do projeto original usa Python 3.9. Este guia usa Python 3.10, que funciona com as versões antigas do NumPy exigidas pelo AudioSR. Um ambiente virtual mantém esses pacotes separados do Python do sistema.
• Git e uv. Instale Git e uv para baixar o código-fonte e gerenciar o ambiente Python.
• PyTorch e um driver de GPU adequado. Usuários de NVIDIA precisam de uma versão do PyTorch compatível com CUDA. Combine as versões do PyTorch, TorchAudio e TorchVision usando a tabela oficial de instalação.
• FFmpeg, incluindo ffprobe. O código original de gravação de arquivos usa esses comandos. Instale-os pelas opções de download do FFmpeg e deixe-os disponíveis no terminal.
• Espaço livre em disco e conexão à internet. Reserve espaço para o ambiente, os pesos baixados, os arquivos de entrada e as saídas. O primeiro carregamento do modelo baixa seu checkpoint.

O código original de seleção de dispositivo reconhece CUDA, Apple MPS e CPU. O processamento por CPU pode ser muito lento. O reconhecimento do MPS na verificação do dispositivo não garante que todas as dependências e operações funcionem em todos os Macs.

Como instalar o AudioSR pelo GitHub

1. Baixe o repositório oficial e crie um ambiente Python

Execute estes comandos em um terminal:

git clone https://github.com/haoheliu/versatile_audio_super_resolution.git
cd versatile_audio_super_resolution
uv venv --python 3.10

Ative o ambiente no Linux ou macOS:

source .venv/bin/activate

No Windows PowerShell, use este comando de ativação:

.venv\Scripts\Activate.ps1

2. Instale dependências compatíveis e o AudioSR

O AudioSR tem restrições de dependências antigas, incluindo NumPy 1.23.5 ou anterior e Transformers 4.30.2. Instalar as versões mais recentes de Python e PyTorch pode causar erros de compatibilidade. Os requisitos do pacote e o ambiente de referência do projeto são bons pontos de partida.

Por exemplo, o ambiente de referência combina PyTorch 2.0.1, TorchAudio 2.0.2 e TorchVision 0.15.2. No Linux ou Windows com um driver NVIDIA adequado, instale essa combinação para CUDA 11.7 e depois o código-fonte do AudioSR que você baixou:

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

O comando CUDA é para sistemas NVIDIA. Para macOS ou CPU, use as instruções correspondentes na tabela do PyTorch. Essas são versões antigas das dependências, então mantenha esse ambiente separado de outros projetos Python.

Se você precisa apenas do pacote publicado, o README oficial também documenta audiosr==0.0.7. Essa versão e a branch main atual do GitHub podem ter recursos diferentes, então confira python -m audiosr --help para a versão instalada.

3. Confira se o Python reconhece sua GPU

Execute esta verificação no ambiente ativado em uma máquina NVIDIA:

python -c "import torch; print('CUDA available:', torch.cuda.is_available())"
ffmpeg -version
ffprobe -version

Se o CUDA estiver indisponível, corrija a instalação do driver ou do PyTorch antes de iniciar um processamento longo. Adicionar -d cuda ao AudioSR não faz uma GPU indisponível funcionar.

AudioSR pela linha de comando: comece com um WAV curto

Use um WAV mono curto na primeira execução. O carregador de áudio original recomenda entradas de 5,12 segundos e alerta sobre a qualidade acima de 10,24 segundos. Uma música completa dificulta o diagnóstico de problemas de configuração e memória.

Coloque input.wav no diretório do repositório e execute:

python -m audiosr -i input.wav -s output --model_name basic -d cuda --ddim_steps 50 --seed 42

A implementação da linha de comando salva um WAV a 48 kHz em uma pasta com marca de data e hora dentro de output. Use basic para áudio geral ou speech para gravações de fala. A semente controla as variações geradas; comparar algumas sementes pode ajudar a escolher um resultado melhor.

Se a geração terminar, mas ao salvar aparecer numpy.ndarray has no attribute cpu, use o exemplo Python abaixo para gravar a saída diretamente. No código-fonte do GitHub verificado para este guia, a inferência retorna um array NumPy, mas a função de gravação espera um tensor. É uma incompatibilidade de tipo de saída no projeto original, não um erro de memória da GPU.

O código atual do GitHub também oferece processamento por segmentos para arquivos mais longos:

python -m audiosr -i input.wav -s output --model_name basic -d cuda --ddim_steps 50 --chunking --chunk_duration 5 --overlap_duration 1

Esse processamento trata seções menores e mistura suas sobreposições. Ele reduz o uso de memória, mas acrescenta junções que você precisa conferir de ouvido. Esses parâmetros dependem da versão, e o processamento por segmentos original mistura a entrada estéreo em mono, então preserve o arquivo estéreo original.

Como usar o AudioSR pelo Python

Use a API Python para chamar o AudioSR no seu próprio script. O exemplo abaixo processa um arquivo mono curto, remove o preenchimento extra até a duração da entrada e grava um WAV a 48 kHz. Salve como run_audiosr.py no diretório do repositório.

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

O pipeline Python carrega o modelo uma única vez, então um script de processamento em lote pode reutilizá-lo. No Neural Analog, o processamento em lote aplica uma restauração a vários arquivos sem script. Defina explicitamente o número de passos de amostragem, porque a API Python e a CLI podem usar valores padrão diferentes.

Como executar o AudioSR no Google Colab

O Google Colab permite executar o AudioSR no hardware do Google na nuvem. Abra o notebook AudioSR Colab da comunidade e siga as instruções para carregar o áudio, executar o modelo e salvar o resultado. O notebook roda no navegador, então você não precisa instalar Python nem ter uma GPU no computador.

O notebook é uma adaptação do AudioSR feita pela comunidade. Seu código-fonte está disponível no GitHub.

Onde baixar os pesos do modelo AudioSR?

Baixe os pesos do modelo AudioSR no Hugging Face.

Detalhes do modelo AudioSR: arquitetura, treinamento e história

Quem criou o AudioSR?

O AudioSR é um modelo generativo de super-resolução de áudio criado por Haohe Liu, Ke Chen, Qiao Tian, Wenwu Wang e Mark D. Plumbley. Ele prevê as frequências altas ausentes em fala, música e efeitos sonoros e produz áudio a 48 kHz. A página de pesquisa do AudioSR inclui o artigo e exemplos para ouvir. O trabalho apareceu primeiro como preprint em setembro de 2023 e foi publicado na ICASSP 2024.

O AudioSR gera detalhes plausíveis. Ele não consegue recuperar uma cópia exata de um master de estúdio perdido. Converter um MP3 em WAV de 48 kHz não realiza essa reconstrução. Para entender a diferença, veja o guia de restauração de arquivos MP3 para WAV.

Restauração, reamostragem e largura de banda são diferentes

A reamostragem muda quantas amostras representam cada segundo de áudio. A restauração de áudio, ou super-resolução, tenta estimar o conteúdo de frequências que a gravação já não contém. Por exemplo, reamostrar uma gravação de 8 kHz para 48 kHz cria mais amostras, mas não restaura por si só os sons acima do limite de frequência original de 4 kHz.

O AudioSR trabalha com larguras de banda de entrada de 2 a 16 kHz e gera uma saída com largura de banda de 24 kHz a uma taxa de amostragem de 48 kHz, segundo a descrição oficial do projeto. A largura de banda descreve a faixa de frequências; a taxa de amostragem descreve as amostras por segundo. Um arquivo identificado como 48 kHz ainda pode ter uma largura de banda estreita por causa de compressão ou filtragem anteriores. Muitas músicas geradas por IA são assim, e é por isso que músicas do Suno costumam soar abafadas.

O AudioSR foi o primeiro modelo de restauração de áudio?

O AudioSR não foi o primeiro modelo neural de super-resolução de áudio. Kuleshov, Enam e Ermon publicaram Super-resolução de áudio usando redes neurais em 2017, e a super-resolução de fala baseada em difusão também veio antes do AudioSR.

Sua contribuição é mais específica. O artigo do AudioSR o apresenta como o primeiro sistema que cobre o domínio audível geral: música, fala e efeitos sonoros. Ele combina essa abrangência com uma largura de banda de entrada flexível, sem ter introduzido a super-resolução de áudio em si.

Da gravação de entrada a uma forma de onda de 48 kHz

O AudioSR combina um autoencoder variacional (VAE), um modelo de difusão latente condicional e um vocoder neural. Cada componente cuida de uma etapa da reconstrução:

A configuração publicada do modelo especifica uma representação mel de 256 bandas, um VAE e um U-Net com transformers espaciais. Ela concatena as características passa-baixas codificadas da entrada com o latente de difusão. É geração condicionada por áudio, embora algumas descrições herdadas da CLI mencionem texto.

O que os passos de amostragem e a orientação controlam?

Os passos de amostragem controlam quantas iterações o modelo dedica a refinar a representação gerada. O AudioSR usa um amostrador DDIM. A orientação controla a força com que o condicionamento da entrada direciona a geração. Ela não é uma quantidade de EQ, e um valor mais alto não garante maior qualidade. A implementação da inferência aplica amostragem, decodificação, substituição de frequências e normalização da forma de onda em sequência.

Mais passos de amostragem e gravações mais longas exigem mais tempo de processamento. O AudioSR foi feito para processamento fora de tempo real, e a velocidade depende da sua GPU e das configurações. Reduzir ddim_steps acelera a geração, mas não resolve de forma confiável os erros de memória da GPU.

Como o AudioSR foi treinado?

A seção de treinamento do artigo descreve aproximadamente 7.000 horas de MUSDB18-HQ, MoisesDB, MedleyDB, Freesound e dados de fala do OpenSLR. Filtros passa-baixas com cortes variados criam entradas degradadas pareadas com alvos de largura de banda maior. O modelo de difusão usa uma programação de ruído cossenoidal, predição de velocidade e orientação sem classificador. O vocoder é baseado em HiFi-GAN com um discriminador multirresolução.

Gravações reais podem diferir desses exemplos de treinamento. Os autores explicam que cortes de frequência irregulares, ruído intenso e reverberação podem reduzir a qualidade. A compressão MP3 pode deixar lacunas perto do corte. A filtragem passa-baixas antes da inferência pode ajudar, mas um corte baixo demais remove detalhes úteis. Para gravações reverberantes, remover a reverberação antes da restauração pode oferecer uma entrada mais limpa ao modelo.

Você não precisa treinar esses componentes para executar o AudioSR. O processo de instalação carrega pesos pré-treinados.

Por que o AudioSR usa pós-processamento?

O áudio gerado deve preservar as informações úteis que já existem na fonte. O AudioSR substitui as bandas baixas duas vezes: no espectrograma mel estimado antes do vocoder e na representação por transformada de Fourier de tempo curto (STFT) da forma de onda resultante. O código de substituição estima um corte e ajusta a saída reconstruída.

Gravações estéreo e músicas completas precisam de um pipeline que cuide de canais, segmentos e reconstrução. O processo padrão do repositório produz áudio mono: o carregador padrão pega o primeiro canal de entrada, enquanto o pipeline por segmentos mistura o estéreo em mono. Preservar o estéreo exige tratamento adicional dos canais, como o processamento separado de esquerda e direita do notebook da comunidade.

A reconstrução precisa ser conferida de ouvido. As notas do pipeline da comunidade alertam que uma sobreposição excessiva pode causar cancelamentos de fase. Compare o resultado em volumes semelhantes e confira os agudos regenerados, as junções dos segmentos, a duração e a imagem estéreo. A substituição de frequências ajuda a preservar a fonte, mas não garante uma banda baixa sem alterações nem junções limpas.

Perguntas frequentes sobre erros do AudioSR

O AudioSR está no PyPI?

Sim. O README oficial instala audiosr==0.0.7 com pip ou o código mais recente direto do GitHub. A branch main do GitHub tem recursos, como o processamento por segmentos, que podem não estar na versão do PyPI.

De quanta memória de GPU o AudioSR precisa?

O README não informa um mínimo. Só o checkpoint básico ocupa cerca de 6,2 GB em disco, e o uso de memória aumenta com a duração do trecho. Comece com um trecho de cerca de 5 segundos e use segmentos para arquivos mais longos.

Por que o AudioSR falha com numpy.ndarray has no attribute cpu?

A inferência terminou, mas a etapa de gravação espera um tensor PyTorch e recebe um array NumPy. Use o script Python acima, que grava a saída com soundfile.

Por que a saída do meu AudioSR é mono?

O carregador padrão lê apenas o primeiro canal, e o processamento por segmentos mistura o estéreo em mono. Processe os canais esquerdo e direito separadamente ou use o AudioSR Online, que processa os canais de centro e diferença para você.

O código de treinamento do AudioSR está disponível?

Sim. O histórico de alterações do README de 31 de dezembro de 2024 tem um link para o código de treinamento, que o autor descreve como apenas para referência e não cuidadosamente organizado.

Execute o AudioSR com o Neural Analog sem gerenciar a instalação

Para evitar a configuração local, abra o AudioSR Online, envie um arquivo ou importe um link musical compatível e ajuste a restauração. Para o Udio, salve ou grave o áudio primeiro e depois envie o arquivo. Você pode escolher uma frequência de corte, ouvir uma prévia do resultado processado e exportar o áudio pela mesma interface.

O Neural Analog cuida do processamento do modelo online, então você pode usar um computador sem uma GPU grande e evitar a instalação do Python, os downloads dos checkpoints e a manutenção de notebooks. Você ainda precisa ouvir com atenção crítica, porque um processo hospedado não elimina as limitações de qualidade do modelo. Depois da restauração, siga o guia de melhoria de áudio para os próximos passos. Para música gerada por IA, corrigir a qualidade do áudio de músicas de IA explica a recuperação dos stems e a masterização após a restauração.

Você também pode comparar o AudioSR com modelos de restauração de áudio mais recentes disponíveis no Neural Analog, incluindo UniverSR e FlashSR. As fichas dos modelos explicam como cada um funciona, e a FAQ resume como o UniverSR difere do AudioSR. Para um exemplo completo, veja todos os 203 efeitos sonoros do RPG Maker 2000 restaurados a 48 kHz com UniverSR. Execute os modelos na mesma gravação e compare as prévias para escolher o melhor resultado.