Como separar stems de áudio com Python: Demucs, API e pipeline completo (2026) · StemSplit

Separar stems de áudio em Python parece complicado. Não é — desde que você escolha o método certo para o seu caso.

Neste guia você vai ver dois métodos funcionais com código copiável: um que roda localmente com Demucs, e outro que usa uma API REST se você não quer lidar com GPU e dependências pesadas. No final tem uma tabela comparando SDR (qualidade) e tempo de processamento para você decidir qual usar no seu projeto.

O que você vai aprender

✅ O que é separação de stems e como o HTDemucs funciona por baixo dos panos
✅ Como instalar e rodar o Demucs localmente com Python (Linux, macOS, Windows)
✅ Como usar uma API REST para separar stems sem GPU local em ~5 linhas de Python
✅ Demucs vs Spleeter em 2026: qual entrega melhor SDR e por quê o Spleeter ficou pra trás
✅ Casos de uso reais: Discord bots, karaokê, prática musical, remixes

Pré-requisitos

Para o Método 1 (Demucs local):

pip install demucs torch torchaudio

Para o Método 2 (API):

pip install requests python-dotenv

O que é separação de stems e como a IA faz isso?

Resposta curta: um modelo de deep learning aprende a separar as frequências de cada instrumento ouvindo milhares de músicas com stems já isolados, e depois aplica isso a qualquer faixa nova.

O modelo que vamos usar é o HTDemucs (Hybrid Transformer Demucs), desenvolvido pela Meta AI. Ele combina um encoder convolucional no domínio do tempo com um Transformer no domínio da frequência — daí o "Hybrid". O resultado é uma separação com SDR médio de 9,0 dB em vocais, contra 6,8 dB do Spleeter no mesmo benchmark. Se você quiser ver o paper completo, está em arxiv.org/abs/2211.00028 — "Hybrid Transformers for Music Source Separation".

O modelo separa a música em 4 stems:

vocals — vocais isolados
drums — bateria
bass — baixo
other — tudo que sobrou (guitarra, teclado, etc.)

O repositório oficial do Demucs fica em github.com/facebookresearch/demucs — 8k+ stars, ativamente mantido.

Método 1: API REST — sem GPU, sem dependências pesadas

Melhor para: protótipos, apps web, automações, quando você não tem GPU disponível ou não quer gerenciar um ambiente Python pesado.

O separador de stems online do StemSplit expõe o HTDemucs via API REST. O fluxo é assíncrono: você envia o arquivo, pega um job_id, e consulta o status até o job terminar.

import os
import time
import requests
from dotenv import load_dotenv

load_dotenv()

API_KEY  = os.environ["STEMSPLIT_API_KEY"]
API_BASE = "https://api.stemsplit.io/v1"
HEADERS  = {"Authorization": f"Bearer {API_KEY}"}

def separate_stems(audio_path: str) -> dict:
    # 1. Enviar o arquivo
    with open(audio_path, "rb") as f:
        res = requests.post(
            f"{API_BASE}/jobs",
            headers=HEADERS,
            files={"file": (os.path.basename(audio_path), f, "audio/mpeg")},
        )
    res.raise_for_status()
    job_id = res.json()["job_id"]
    print(f"Job criado: {job_id}")

    # 2. Aguardar o resultado (polling a cada 5s)
    while True:
        status = requests.get(f"{API_BASE}/jobs/{job_id}", headers=HEADERS).json()
        if status["status"] == "done":
            return status["stems"]   # dict: {"vocals": url, "drums": url, ...}
        if status["status"] == "failed":
            raise RuntimeError(f"Job falhou: {status.get('error')}")
        print(f"  aguardando... ({status['status']})")
        time.sleep(5)

if __name__ == "__main__":
    stems = separate_stems("minha_musica.mp3")
    for stem, url in stems.items():
        print(f"{stem}: {url}")

Coloque sua chave de API no .env:

STEMSPLIT_API_KEY=sua_chave_aqui

Você consegue uma chave grátis (5 minutos de processamento, sem cartão) direto na documentação da API em stemsplit.io/developers/docs.

Tempo médio: ~35–45 segundos para uma faixa de 3 minutos rodando em GPU dedicada no servidor.

Método 2: Demucs local — controle total

Melhor para: quando você precisa processar muitos arquivos em batch, quer privacidade total, ou já tem uma GPU disponível.

Instalação

# Requer Python 3.8+
pip install demucs

# Verificar se instalou corretamente
python -m demucs --help

Atenção Windows: se você tiver problemas com o ffmpeg, instale separadamente:
winget install Gyan.FFmpeg

Uso via linha de comando (mais simples)

# Separa stems e salva em ./separated/htdemucs/<nome_da_musica>/
python -m demucs --mp3 minha_musica.mp3

# Para usar o modelo de 6 stems (drums, bass, guitar, piano, vocals, other):
python -m demucs -n htdemucs_6s minha_musica.mp3

Uso via Python (integração em pipelines)

import subprocess
from pathlib import Path

def separate_local(audio_path: str, output_dir: str = "separated") -> Path:
    """
    Roda o HTDemucs localmente e retorna o diretório com os stems.
    """
    result = subprocess.run(
        [
            "python", "-m", "demucs",
            "--out", output_dir,
            "--mp3",                # salva como mp3 (menor tamanho)
            audio_path,
        ],
        capture_output=True,
        text=True,
    )
    if result.returncode != 0:
        raise RuntimeError(f"Demucs falhou:\n{result.stderr}")

    # O Demucs salva em: output_dir/htdemucs/<nome_sem_extensao>/
    song_name = Path(audio_path).stem
    stems_dir = Path(output_dir) / "htdemucs" / song_name
    return stems_dir

if __name__ == "__main__":
    stems_dir = separate_local("minha_musica.mp3")
    for stem in stems_dir.glob("*.mp3"):
        print(f"{stem.name}: {stem.stat().st_size / 1024:.1f} KB")

Tempo médio: ~3–5 minutos por faixa na CPU, ~40–60 segundos em GPU moderna (RTX 3070+).

Demucs vs Spleeter: qual usar em 2026?

Resposta curta: Demucs. O Spleeter não recebe atualizações significativas desde 2022 e perde em qualidade em praticamente todos os benchmarks modernos.

Métrica	HTDemucs	Spleeter 2stems
SDR vocais	9,0 dB	6,8 dB
SDR acompanhamento	13,2 dB	11,5 dB
Última atualização ativa	2024	2022
GPU necessária (local)	Sim (recomendada)	Sim (recomendada)
Modelos de 4+ stems	Sim	Sim (4stems)
Instalação	`pip install demucs`	`pip install spleeter`

Nota sobre SDR: Signal-to-Distortion Ratio — quanto maior, melhor a separação. Diferença de 2+ dB é perceptível ao ouvido.

Para um benchmark com 6 ferramentas e código Python completo, incluindo métricas de latência e custo por minuto, vale conferir esse artigo no dev.to que cobre o benchmark completo com mir_eval.

Casos de uso reais

Discord bots de música: o padrão mais comum é aceitar um upload de áudio no bot, passar para a API (sem precisar de GPU no servidor), e devolver os stems como links. Publicamos um tutorial completo de como construir esse bot em Python no dev.to.

Karaokê e prática musical: isolar o instrumental de qualquer música para cantar por cima, ou remover um instrumento específico para praticar. O separador de stems do StemSplit faz isso direto no browser sem precisar de código.

Remixes e produção musical: beatmakers usando stems de referência para estudar arranjos, criar samples ou fazer mashups. O HTDemucs preserva bem as frequências originais, o que é crítico para esse caso.

Pipelines de MIR (Music Information Retrieval): stems isolados como entrada para modelos de transcrição, detecção de BPM/tom, ou classificação de gênero — a qualidade da separação impacta diretamente o resultado dos modelos downstream.

Conclusão

Para a maioria dos projetos em Python, o caminho mais rápido é:

Prototipando: use a API REST (5 linhas de código, zero configuração, modelo HTDemucs no servidor)
Em produção com volume: avalie o custo da API vs rodar Demucs localmente com GPU

O código completo dos dois métodos está acima — é só copiar e adaptar. Se você quiser ver benchmarks mais detalhados com SDR medido em Python usando mir_eval, temos uma versão completa em inglês com benchmarks de SDR no Hashnode que cobre isso com mais profundidade.

Qualquer dúvida ou caso de uso específico, comenta aqui.