AudacityMCP

AudacityMCP

Edição de áudio com IA no Audacity através do Model Context Protocol

Início Rápido • Por que AudacityMCP? • Pipelines • Referência de Ferramentas • Solução de Problemas

O AudacityMCP conecta qualquer assistente de IA compatível com MCP ao Audacity, dando a ele controle total sobre a edição de áudio por meio de 144 ferramentas que abrangem efeitos, limpeza, masterização, transcrição e muito mais. Converse com seu assistente de IA e ele edita seu áudio em tempo real.

Sem nuvem. Sem chaves de API para processamento de áudio. Tudo roda localmente através da interface de pipe nomeado do Audacity.

Se isso for útil para você, uma estrela ajuda outras pessoas a encontrar o projeto — esse é todo o orçamento de marketing deste projeto. Quer ajudar a mantê-lo? Clique no selo Sponsor no topo.

Demonstração

Compatibilidade: O AudacityMCP funciona com Audacity 3.x. O Audacity 4 removeu o mod-script-pipe — a interface de script que este servidor utiliza — e não oferece substituto, então o AudacityMCP não consegue controlar o Audacity 4.

Usando o Audacity 4? Existe um projeto complementar: Audacity4-MCP — 159 ferramentas sobre uma ponte TCP JSON-RPC, cobrindo edição, seleção, rótulos, efeitos destrutivos e em tempo real, e controle de parâmetros VST3 ao vivo.

Está em alfa inicial, e vale ser claro sobre a configuração: como o Audacity 4 ainda não tem interface de controle remoto, ele precisa de um fork complementar do Audacity 4 compilado a partir do código-fonte (Visual Studio, Qt 6.10, CMake, Ninja). Isso o coloca em território de desenvolvedor por enquanto, em vez de uso geral. Os mantenedores do Audacity confirmaram que uma interface oficial de comando e MCP está planejada assim que a migração interna for concluída; quando isso acontecer, o fork não deve ser mais necessário.

Funciona Com

O AudacityMCP funciona com qualquer cliente de IA que suporte o Model Context Protocol:

• Claude Desktop — aplicativo de desktop da Anthropic
• Claude Code — agente de CLI
• Cursor — editor de código com IA e suporte a MCP
• Qualquer outro cliente compatível com MCP

Início Rápido

1. Obtenha o AudacityMCP

Opção A: Clique no botão verde Code acima → Download ZIP → extraia para uma pasta

Opção B: Clone com git:

git clone https://github.com/xDarkzx/Audacity-MCP.git

2. Execute o instalador (configura todo o resto automaticamente)

Windows: clique duas vezes em install.bat no Explorador de Arquivos, ou — se você já estiver em um terminal da etapa git clone acima — continue na mesma janela do PowerShell/Command Prompt:

cd Audacity-MCP
.\install.bat

macOS / Linux:

cd Audacity-MCP
bash install.sh

O instalador faz 3 coisas: instala o audacity-mcp desta pasta local (a que você acabou de baixar/clonar — sem busca no PyPI ou GitHub), habilita o mod-script-pipe no Audacity, e configura o Claude Desktop — sem necessidade de edição manual de JSON. Ele pede confirmação antes de tocar em qualquer arquivo de configuração, explica exatamente o que vai fazer primeiro, e sempre faz backup de um arquivo existente antes de alterá-lo. Quer ver tudo o que ele faria sem mudar nada? Adicione --dry-run: .\install.bat --dry-run / bash install.sh --dry-run.

Nota: install.bat/install.sh devem ser executados de dentro desta pasta — eles só instalam o código que está ao lado deles, não baixam nada por conta própria.

{
  "mcpServers": {
    "audacity": {
      "command": "audacity-mcp"
    }
  }
}

3. Comece a editar

Abra o Audacity, carregue algum áudio e converse com sua IA:

"Clean up this podcast recording"
"Master this track for Spotify, it's EDM"
"Transcribe this and add labels at each sentence"
"Add reverb with a large room, then export as FLAC"

O Audacity deve estar aberto primeiro. O AudacityMCP se comunica através do pipe nomeado do Audacity — ele não pode iniciar o Audacity por você.

Veja o Guia de Instalação completo para configuração detalhada em todas as plataformas e clientes MCP.

Por que AudacityMCP?

Sem AudacityMCP: Você navega manualmente pelos menus, ajusta parâmetros de efeitos de ouvido, aplica efeitos um de cada vez, consulta especificações ACX e repete até soar bem.

Com AudacityMCP: Você descreve o que quer em inglês simples e a IA cuida do resto — escolhendo os efeitos certos, definindo parâmetros padrão da indústria e encadeando operações.

O AudacityMCP é especialmente útil para:

• Podcasters que querem som consistente e profissional sem conhecimento de engenharia de áudio
• Músicos que precisam de masterização rápida com configurações adequadas ao gênero
• Criadores de conteúdo que trabalham com entrevistas, narrações ou gravações de campo
• Qualquer pessoa que prefira descrever o que quer em vez de clicar em menus

O Que Ele Pode Fazer?

You:  "Clean up this podcast recording"
AI:   Runs auto_cleanup_podcast → HPF 80Hz → noise reduction → compression → safe loudness check

You:  "Master this track for Spotify, it's EDM"
AI:   Runs auto_master_music style=edm → HPF 30Hz → click removal → compression 2.5:1 → bass +2dB → loudness check

You:  "This is a noisy live recording, fix it up"
AI:   Runs auto_cleanup_live → HPF 100Hz → click removal → noise reduction 18dB → compression 5:1

You:  "Transcribe this interview and add labels"
AI:   Runs transcribe_to_labels → faster-whisper transcription → Audacity labels at each timestamp

You:  "Add reverb to the vocals, then export as FLAC"
AI:   select region → reverb effect → export to FLAC

Recursos

144 Ferramentas em 11 Categorias

Pipelines

O AudacityMCP inclui 9 pipelines de um clique para tarefas comuns de áudio. Cada pipeline é projetado para ser seguro para áudio mal gravado — ele nunca aumentará seu áudio de forma perigosa. Os pipelines limpam e melhoram seu áudio, e então você pode ajustar manualmente o volume depois, se necessário.

Como os Pipelines Funcionam

1. Você diz à IA o que quer (ex.: "limpe este podcast")
2. A IA escolhe o pipeline certo e o inicia
3. O pipeline roda em segundo plano — você recebe um job_id de volta
4. Consulte com check_pipeline_status a cada 15-30 segundos para monitorar o progresso
5. Quando terminar, um popup aparece no Audacity

Regra de segurança: Os pipelines apenas reduzem picos se estiverem muito altos. Eles nunca aumentam o volume. Se você quiser atingir um alvo específico de LUFS (ex.: -14 para o Spotify), peça à IA para executar loudness_normalize depois de verificar se os resultados estão bons.

Referência de Pipelines

auto_analyze_audio — Analisar antes de processar

Mede seu áudio e recomenda o melhor pipeline. Execute isto primeiro se não tiver certeza do que fazer.

You: "Analyze this audio"
→ Returns: peak level, noise floor, clipping status, recommended pipeline

auto_cleanup_audio — Limpeza segura apenas

Limpa ruídos e artefatos sem alterar o volume de forma alguma. Use quando os níveis já estiverem bons.

You: "Just clean up the noise, don't change the volume"
→ DC offset removal → HPF 80Hz → noise reduction → click removal (optional)

auto_cleanup_podcast — Podcast / narração

Processamento profissional de transmissão para fala.

You: "Clean up this podcast recording"
→ DC offset → HPF 80Hz → noise reduction 12dB → compression 3:1 → safe loudness check

auto_audiobook_mastering — Audiolivro (ACX/Audible)

Atende aos requisitos ACX para distribuição de audiolivros.

You: "Master this for ACX / Audible"
→ DC offset → HPF 80Hz → noise reduction 12dB → compression 2.5:1 → safe loudness check → peak cap -3dB

auto_cleanup_interview — Entrevista / diálogo

Toque leve para conversas — preserva a dinâmica natural.

You: "Clean up this interview recording"
→ DC offset → HPF 80Hz → noise reduction 8dB → compression 2.5:1 → safe loudness check

auto_cleanup_vocal — Canto / vocal de estúdio

Ajustado para gravações vocais com EQ de presença para clareza.

You: "Process this vocal recording"
→ DC offset → HPF 100Hz → noise reduction 10dB → compression 3:1 → presence EQ (+3dB treble, -1dB bass) → safe loudness check

auto_cleanup_live — Gravação ao vivo / campo / com ruído

Limpeza agressiva para ambientes ruidosos. Os primeiros 0,5s devem ser ruído ambiente para a criação de perfil.

You: "This is a noisy live recording, clean it up"
→ DC offset → HPF 100Hz → click removal → noise reduction 18dB → compression 5:1 → safe loudness check

auto_master_music — Masterização de música

Masterização ajustada por gênero com 6 predefinições: edm, hiphop, rock, pop, classical, acoustic.

You: "Master this hip-hop track"
→ HPF 30Hz → click removal → compression 2:1 → bass +3dB treble +1dB → safe loudness check

You: "Master this for a classical album"
→ HPF 30Hz → click removal → compression 1.3:1 (very gentle) → no EQ → safe loudness check

auto_lofi_effect — Lo-fi / vintage criativo

Aplique um som lo-fi quente e vintage. Predefinições: light, medium, heavy.

You: "Give this a lo-fi vibe"
→ HPF → LPF (muffled highs) → bass/treble warmth → compression 2:1 → safe loudness check

Após um Pipeline: Ajustando o Volume

Os pipelines intencionalmente não alteram o volume (eles apenas reduzem se os picos estiverem estourando). Para atingir um alvo de streaming:

You: "Now normalize this to -14 LUFS for Spotify"
→ AI uses loudness_normalize tool with lufs_level=-14

You: "Normalize to -16 LUFS for podcast"
→ AI uses loudness_normalize tool with lufs_level=-16

Por que não fazer isso automaticamente? A normalização LUFS pode aumentar áudio silencioso/mal gravado em 10-20 dB, o que o estoura. Ao separar a limpeza do volume, você pode verificar os resultados antes da etapa final de volume.

Transcrição Local (Experimental)

Este recurso é experimental e requer configuração separada. Todo o resto funciona sem ele.

Desenvolvido por faster-whisper — funciona totalmente offline, seu áudio nunca sai da sua máquina:

• 5 tamanhos de modelo: tiny, base, small, medium, large-v3
• Transcreva o áudio completo ou apenas uma seleção
• Exporte como legendas SRT, VTT ou texto simples
• Adicione automaticamente rótulos do Audacity em cada segmento falado
• Detecção de idioma ou especifique 99+ idiomas

Configuração necessária antes do primeiro uso: Veja Configuração de Transcrição para etapas de instalação.

Quer aceleração por GPU (10-20x mais rápida)? Execute audacity-mcp-setup-gpu — ou baixe setup_gpu.bat/setup_gpu.sh e clique duas vezes/execute se preferir não usar um terminal. Detecta sua GPU, instala o necessário e verifica se realmente funciona. Apenas GPUs NVIDIA (gráficos AMD/Intel e macOS não são suportados pelo backend de transcrição — qualquer placa NVIDIA funciona, GeForce não é um requisito, apenas ter uma GPU NVIDIA é suficiente). Sem GPU NVIDIA? A CPU funciona bem, apenas mais lenta em arquivos longos.

O script diz que funcionou, mas a transcrição ainda está lenta/na CPU? Isso significa que o Claude Desktop está iniciando audacity-mcp a partir de um Python diferente do que o script acabou de verificar — veja a correção (uma edição manual de configuração, cinco minutos).

O que há de novo — v0.1.3

32 novas ferramentas (99 → 131), correções de ajuste de pipeline e testado ao vivo contra o Audacity.

• Novos efeitos: Reverse, Invert, Repair, AutoDuck, NotchFilter, VocalReduction, AdjustableFade, StudioFadeOut, CrossfadeClips, CrossfadeTracks, ClipFix, SlidingStretch, Tremolo
• Nova edição: Split (no lugar), SplitCut, SplitDelete, Disjoin + split antigo renomeado → edit_split_new
• Novas faixas: StereoToMono, MixAndRenderToNew, MuteAll, UnmuteAll, Resample, AlignEndToEnd, AddLabelTrack
• Nova seleção: CursorToTrackStart/End, CursorToProjectStart/End, SelectCursorToTrackEnd
• Novo projeto: EditMetadata, ImportMIDI
• Novos rótulos: RegularIntervalLabels
• Correções de pipeline: Limite de pico ACX -3.0→-3.5dB, NR ao vivo 18→12dB, comp de podcast 10ms/1s→30ms/200ms, liberação de entrevista 1s→200ms
• Correção de bug: effect_repair agora usa timeout longo (o Audacity mostra popup em seleção inválida)
• Validação: Adicionadas verificações de intervalo ausentes em AutoDuck, VocalReduction, SlidingStretch, Resample

Solução de Problemas

mod-script-pipe Não Habilitado

O instalador habilita isso automaticamente, mas se não funcionou (por exemplo, o Audacity nunca foi aberto antes), habilite manualmente:

1. Abra o Audacity
2. Vá em Editar → Preferências (Windows/Linux) ou Audacity → Preferências (macOS)
3. Clique em Módulos na barra lateral esquerda
4. Defina mod-script-pipe como Habilitado
5. Clique em OK e reinicie o Audacity

Problemas de Conexão

Problemas de Pipeline

Dicas de Qualidade de Áudio

Problemas Gerais

Arquitetura

┌──────────────┐     stdio      ┌──────────────┐   named pipe   ┌──────────────┐
│  MCP Client  │◄──────────────►│ AudacityMCP  │◄──────────────►│   Audacity   │
│(AI assistant)│    (JSON-RPC)  │   FastMCP    │  (commands)    │              │
└──────────────┘                └──────────────┘                └──────────────┘
                                       │
                                       ├── audacity_mcp/main.py          (entry point)
                                       ├── audacity_mcp/audacity_client.py (pipe I/O)
                                       ├── audacity_mcp/tool_registry.py  (auto-loader)
                                       └── audacity_mcp/tools/            (11 modules)

Decisões de Design Principais

• Pipes nomeados, não TCP — IPC direto para o mod-script-pipe do Audacity. Sem exposição de rede, sem conflitos de porta.
• Zero exec/eval — Cada operação mapeia para um handler estático com validação de entrada. Sem execução de código arbitrário.
• Multiplataforma — Windows usa API Win32 via ctypes, Unix usa E/S de arquivo padrão.
• Assíncrono em todo lugar — Todos os handlers de ferramentas são async. E/S de pipe bloqueante é executada em um pool de execução com timeouts configuráveis.
• Pipelines seguros — Os pipelines medem o áudio antes de tomar decisões de volume. Eles apenas reduzem, nunca aumentam.
• Registro dinâmico de ferramentas — Coloque um módulo em audacity_mcp/tools/, exporte uma função register(mcp), e ele é descoberto automaticamente.

Estrutura do Projeto

AudacityMCP/
├── audacity_mcp/
│   ├── main.py                 # FastMCP server entry point
│   ├── audacity_client.py      # Cross-platform named pipe client
│   ├── tool_registry.py        # Auto-discovers and registers tool modules
│   └── tools/
│       ├── analysis_tools.py   # Audio analysis (contrast, spectrum, beats)
│       ├── cleanup_tools.py    # Noise reduction, mastering, 9 pipelines
│       ├── edit_tools.py       # Cut, copy, paste, split, join, trim
│       ├── effects_tools.py    # Reverb, echo, pitch, EQ, filters
│       ├── generate_tools.py   # Tone, noise, chirp, DTMF generation
│       ├── label_tools.py      # Label management
│       ├── project_tools.py    # Project/file operations
│       ├── selection_tools.py  # Selection and cursor control
│       ├── track_tools.py      # Track management
│       ├── transcription_tools.py  # Whisper-based transcription
│       └── transport_tools.py  # Playback and recording control
├── audacity_mcp_shared/
│   ├── constants.py            # Pipe paths, timeouts, allowed formats
│   ├── error_codes.py          # Typed error codes (pipe/command/validation)
│   └── pipe_protocol.py        # Command formatting and response parsing
├── tests/                      # 60 tests
├── docs/
│   ├── INSTALLATION.md         # Detailed setup guide
│   └── TOOLS.md                # Complete tool reference
└── pyproject.toml

Desenvolvimento

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -x -q

# Run lint (real bugs + security patterns, not style/formatting)
ruff check .

Adicionando Novas Ferramentas

1. Crie um módulo em audacity_mcp/tools/ (ou adicione a um existente)
2. Exporte uma função register(mcp: FastMCP)
3. Defina suas ferramentas com decoradores @mcp.tool()
4. Pronto — o registro de ferramentas descobre automaticamente na inicialização

# audacity_mcp/tools/my_tools.py
from mcp.server.fastmcp import FastMCP
from audacity_mcp_shared.error_codes import AudacityMCPError, ErrorCode


def register(mcp: FastMCP):
    from audacity_mcp.main import client

    @mcp.tool()
    async def my_custom_effect(intensity: float = 0.5) -> dict:
        """Apply my custom effect to the selected audio."""
        if not 0 <= intensity <= 1:
            raise AudacityMCPError(ErrorCode.VALUE_OUT_OF_RANGE, "intensity must be 0-1")
        return await client.execute_long("MyEffect", Intensity=intensity)

Veja CONTRIBUTING.md para diretrizes completas.

Comunidade

Transformar isso em uma ferramenta que todo usuário do Audacity usa requer mais do que uma pessoa. Se você está usando o AudacityMCP — mesmo apenas experimentando — venha participar do Discord: compartilhe o que construiu, relate o que está quebrado, sugira o que está faltando, ou apenas converse com outras pessoas que fazem edição de áudio com IA. Comunidades crescem quando uma pessoa conta a outra que isso existe, então se você conhece alguém que se beneficiaria disso, envie o link.

Suporte

Se o AudacityMCP economizou seu tempo ou ajudou com seus projetos de áudio, considere patrocinar:

Seu apoio ajuda a manter este projeto mantido e gratuito para todos.

Documentação

• Guia de Instalação — Configuração detalhada para Windows, macOS, Linux
• Referência de Ferramentas — Referência completa para todas as 144 ferramentas com parâmetros e intervalos
• Edição Baseada em Transcrição — Guia de fluxo de trabalho para podcasts, entrevistas e palestras (edição orientada por rótulos)
• Contribuindo — Como adicionar ferramentas e contribuir
• Changelog — Histórico de versões e notas de lançamento

Agradecimentos

Agradecimentos aos seguintes por bugs relatados, ideias e feedback que melhoraram este projeto:

• @Harsha-Jay-S — diagnosticou o bug effect_change_pitch/effect_change_speed (#15) com prova medida contra o Audacity real, identificando a causa raiz exata.

Licença

Apache License 2.0 — veja LICENSE para detalhes.

Construído por Daniel Hodgetts • 𝕏 @daehonz1