AudacityMCP

AudacityMCP

Edición de audio impulsada por IA en Audacity mediante el Protocolo de Contexto de Modelos

Inicio rápido • ¿Por qué AudacityMCP? • Pipelines • Referencia de herramientas • Solución de problemas

AudacityMCP conecta cualquier asistente de IA compatible con MCP a Audacity, dándole control total sobre la edición de audio mediante 144 herramientas que abarcan efectos, limpieza, masterización, transcripción y más. Habla con tu asistente de IA y este edita tu audio en tiempo real.

Sin nube. Sin claves API para el procesamiento de audio. Todo se ejecuta localmente a través de la interfaz de tubería con nombre de Audacity.

Si esto te resulta útil, una estrella ayuda a que otros lo encuentren — ese es todo el presupuesto de marketing de este proyecto. ¿Quieres ayudar a mantenerlo? Haz clic en la insignia Sponsor arriba.

Compatibilidad: AudacityMCP actualmente funciona solo con Audacity 3.x. Audacity 4.x aún no es compatible — esperamos añadir soporte en el futuro.

Funciona con

AudacityMCP funciona con cualquier cliente de IA que admita el Protocolo de Contexto de Modelos:

• Claude Desktop — la aplicación de escritorio de Anthropic
• Claude Code — agente CLI
• Cursor — editor de código con IA compatible con MCP
• Cualquier otro cliente compatible con MCP

Inicio rápido

1. Obtén AudacityMCP

Opción A: Haz clic en el botón verde Code arriba → Download ZIP → extrae a una carpeta

Opción B: Clona con git:

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

2. Ejecuta el instalador (configura todo lo demás automáticamente)

Windows: haz doble clic en install.bat en el Explorador de archivos, o — si ya estás en una terminal desde el paso git clone anterior — simplemente continúa en la misma ventana de PowerShell/Command Prompt:

cd Audacity-MCP
.\install.bat

macOS / Linux:

cd Audacity-MCP
bash install.sh

El instalador hace 3 cosas: instala audacity-mcp desde esta carpeta local (la que acabas de descargar/clonar — sin descargas de PyPI ni GitHub), habilita mod-script-pipe en Audacity, y configura Claude Desktop — sin necesidad de editar JSON manualmente. Pide confirmación antes de tocar cualquiera de los archivos de configuración, explica exactamente lo que va a hacer primero, y siempre hace una copia de seguridad de un archivo existente antes de modificarlo. ¿Quieres ver todo lo que haría sin cambiar nada? Añade --dry-run: .\install.bat --dry-run / bash install.sh --dry-run.

Nota: install.bat/install.sh deben ejecutarse desde dentro de esta carpeta — solo instalan el código que está justo a su lado, no descargan nada por sí mismos.

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

3. Empieza a editar

Abre Audacity, carga algo de audio y luego habla con tu 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"

Audacity debe estar abierto primero. AudacityMCP se comunica a través de la tubería con nombre de Audacity — no puede iniciar Audacity por ti.

Consulta la Guía de instalación completa para una configuración detallada en todas las plataformas y clientes MCP.

¿Por qué AudacityMCP?

Sin AudacityMCP: Navegas manualmente por los menús, ajustas los parámetros de efectos de oído, aplicas efectos uno a la vez, consultas las especificaciones ACX y repites hasta que suene bien.

Con AudacityMCP: Describes lo que quieres en lenguaje natural y la IA se encarga del resto — eligiendo los efectos correctos, estableciendo parámetros estándar de la industria y encadenando operaciones.

AudacityMCP es especialmente útil para:

• Podcasters que quieren un sonido profesional y consistente sin conocimientos de ingeniería de audio
• Músicos que necesitan masterización rápida con ajustes apropiados para el género
• Creadores de contenido que trabajan con entrevistas, voces en off o grabaciones de campo
• Cualquiera que prefiera describir lo que quiere en lugar de hacer clic por los menús

¿Qué puede hacer?

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

Características

144 herramientas en 11 categorías

Pipelines

AudacityMCP incluye 9 pipelines de un clic para tareas de audio comunes. Cada pipeline está diseñado para ser seguro con audio mal grabado — nunca aumentará tu audio de forma peligrosa. Los pipelines limpian y mejoran tu audio, y luego puedes ajustar manualmente el volumen si es necesario.

Cómo funcionan los pipelines

1. Le dices a la IA lo que quieres (por ejemplo, "limpia este podcast")
2. La IA elige el pipeline correcto y lo inicia
3. El pipeline se ejecuta en segundo plano — recibes un job_id de vuelta
4. Consulta con check_pipeline_status cada 15-30 segundos para monitorear el progreso
5. Cuando termine, aparece una ventana emergente en Audacity

Regla de seguridad: Los pipelines solo reducen los picos si están demasiado altos. Nunca aumentan el volumen. Si quieres alcanzar un objetivo LUFS específico (por ejemplo, -14 para Spotify), pide a la IA que ejecute loudness_normalize después de verificar que los resultados se ven bien.

Referencia de pipelines

auto_analyze_audio — Analizar antes de procesar

Mide tu audio y recomienda el mejor pipeline. Ejecuta esto primero si no estás seguro de qué hacer.

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

auto_cleanup_audio — Limpieza segura solamente

Limpia ruido y artefactos sin cambiar el volumen en absoluto. Úsalo cuando los niveles ya estén bien.

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 / voz en off

Procesamiento profesional de radiodifusión para voz hablada.

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

auto_audiobook_mastering — Audiolibro (ACX/Audible)

Apunta a los requisitos ACX para distribución de audiolibros.

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 ligero para conversaciones — preserva la 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 / voz de estudio

Ajustado para grabaciones vocales con EQ de presencia para claridad.

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 — Grabación en vivo / campo / ruidosa

Limpieza agresiva para entornos ruidosos. Los primeros 0.5s deben ser ruido ambiental para el perfilado.

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 — Masterización musical

Masterización ajustada por género con 6 ajustes preestablecidos: 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 creativo / vintage

Aplica un sonido lo-fi cálido y vintage. Ajustes preestablecidos: light, medium, heavy.

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

Después de un pipeline: Ajustar el volumen

Los pipelines dejan el volumen intacto a propósito (solo reducen si los picos están recortando). Para alcanzar un objetivo 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 qué no hacer esto automáticamente? La normalización LUFS puede aumentar audio silencioso o mal grabado en 10-20 dB, lo que lo estropea. Al separar la limpieza del volumen, puedes verificar los resultados antes del paso final de volumen.

Transcripción local (Experimental)

Esta característica es experimental y requiere configuración adicional. Todo lo demás funciona sin ella.

Powered by faster-whisper — funciona completamente sin conexión, tu audio nunca sale de tu máquina:

• 5 tamaños de modelo: tiny, base, small, medium, large-v3
• Transcribe audio completo o solo una selección
• Exporta como subtítulos SRT, VTT o texto plano
• Añade automáticamente etiquetas de Audacity en cada segmento hablado
• Detección de idioma o especifica más de 99 idiomas

Configuración requerida antes del primer uso: Consulta Configuración de Transcripción para los pasos de instalación.

¿Quieres aceleración por GPU (10-20x más rápida)? Ejecuta audacity-mcp-setup-gpu — o descarga setup_gpu.bat/setup_gpu.sh y haz doble clic/ejecútalo si prefieres no usar una terminal. Detecta tu GPU, instala lo necesario y verifica que realmente funciona. Solo GPUs NVIDIA (las gráficas AMD/Intel y macOS no son compatibles con el backend de transcripción en absoluto — cualquier tarjeta NVIDIA funciona, GeForce no es un requisito, solo tener una GPU NVIDIA). ¿Sin GPU NVIDIA? La CPU funciona bien, solo más lenta en archivos largos.

¿El script dice que funcionó pero la transcripción sigue lenta/en CPU? Eso significa que Claude Desktop está lanzando audacity-mcp desde un Python diferente al que el script acaba de verificar — consulta la solución (una edición manual de configuración, cinco minutos).

Novedades — v0.1.3

32 nuevas herramientas (99 → 131), ajustes de corrección de pipelines y probado en vivo contra Audacity.

• Nuevos efectos: Reverse, Invert, Repair, AutoDuck, NotchFilter, VocalReduction, AdjustableFade, StudioFadeOut, CrossfadeClips, CrossfadeTracks, ClipFix, SlidingStretch, Tremolo
• Nueva edición: Split (en su lugar), SplitCut, SplitDelete, Disjoin + antiguo split renombrado → edit_split_new
• Nuevas pistas: StereoToMono, MixAndRenderToNew, MuteAll, UnmuteAll, Resample, AlignEndToEnd, AddLabelTrack
• Nueva selección: CursorToTrackStart/End, CursorToProjectStart/End, SelectCursorToTrackEnd
• Nuevo proyecto: EditMetadata, ImportMIDI
• Nuevas etiquetas: RegularIntervalLabels
• Correcciones de pipeline: límite de pico ACX -3.0→-3.5dB, NR en vivo 18→12dB, compresión de podcast 10ms/1s→30ms/200ms, release de entrevista 1s→200ms
• Corrección de errores: effect_repair ahora usa un tiempo de espera largo (Audacity muestra un popup en selección inválida)
• Validación: Se añadieron comprobaciones de rango faltantes en AutoDuck, VocalReduction, SlidingStretch, Resample

Solución de problemas

mod-script-pipe No Habilitado

El instalador habilita esto automáticamente, pero si no funcionó (por ejemplo, Audacity nunca se abrió antes), habilítalo manualmente:

1. Abre Audacity
2. Ve a Editar → Preferencias (Windows/Linux) o Audacity → Preferencias (macOS)
3. Haz clic en Módulos en la barra lateral izquierda
4. Configura mod-script-pipe en Habilitado
5. Haz clic en Aceptar y reinicia Audacity

Problemas de conexión

Problemas de pipeline

Consejos de calidad de audio

Problemas generales

Arquitectura

┌──────────────┐     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)

Decisiones clave de diseño

• Pipes con nombre, no TCP — IPC directo al mod-script-pipe de Audacity. Sin exposición a la red, sin conflictos de puertos.
• Cero exec/eval — Cada operación se asigna a un manejador estático con validación de entrada. Sin ejecución de código arbitrario.
• Multiplataforma — Windows usa la API Win32 a través de ctypes, Unix usa E/S de archivos estándar.
• Asíncrono en todo — Todos los manejadores de herramientas son async. La E/S de pipe bloqueante se ejecuta en un grupo de ejecutores con tiempos de espera configurables.
• Pipelines seguros — Los pipelines miden el audio antes de tomar decisiones de sonoridad. Solo reducen, nunca aumentan.
• Registro dinámico de herramientas — Coloca un módulo en audacity_mcp/tools/, exporta una función register(mcp), y se descubre automáticamente.

Estructura del proyecto

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

Desarrollo

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

# Run tests
pytest tests/ -x -q

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

Añadir nuevas herramientas

1. Crea un módulo en audacity_mcp/tools/ (o añade a uno existente)
2. Exporta una función register(mcp: FastMCP)
3. Define tus herramientas con decoradores @mcp.tool()
4. Eso es todo — el registro de herramientas lo descubre automáticamente al inicio

# 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)

Consulta CONTRIBUTING.md para las pautas completas.

Comunidad

Convertir esto en una herramienta que todo usuario de Audacity use requiere más de una persona. Si estás usando AudacityMCP — incluso solo probándolo — únete al Discord: comparte lo que construiste, reporta lo que está roto, sugiere lo que falta, o simplemente pasa el rato con otras personas que hacen edición de audio impulsada por IA. Las comunidades crecen cuando una persona le cuenta a otra que esto existe, así que si conoces a alguien que le sacaría provecho, envíale el enlace.

Soporte

Si AudacityMCP te ha ahorrado tiempo o ayudado con tus proyectos de audio, considera patrocinar:

Tu apoyo ayuda a mantener este proyecto mantenido y gratuito para todos.

Documentación

• Guía de Instalación — Configuración detallada para Windows, macOS, Linux
• Referencia de Herramientas — Referencia completa de las 144 herramientas con parámetros y rangos
• Edición Basada en Transcripciones — Guía de flujo de trabajo para podcasts, entrevistas y conferencias (edición impulsada por etiquetas)
• Contribuir — Cómo añadir herramientas y contribuir
• Registro de Cambios — Historial de versiones y notas de lanzamiento

Agradecimientos

Gracias a los siguientes por errores reportados, ideas y comentarios que mejoraron este proyecto:

• @Harsha-Jay-S — diagnosticó el error de effect_change_pitch/effect_change_speed (#15) con prueba medida contra Audacity real, señalando la causa raíz exacta.

Licencia

Apache License 2.0 — consulta LICENSE para más detalles.

Construido por Daniel Hodgetts • 𝕏 @daehonz1