MCP Audio Tweaker

Processamento e otimização de áudio em lote usando FFmpeg. Modifique taxa de amostragem, bitrate, volume, canais e aplique efeitos.

GitHub

Experimente este MCPPatrocinado

Documentação

MCP Audio Tweaker

Um servidor Model Context Protocol (MCP) para processamento e otimização de áudio em lote usando FFmpeg. Este pacote fornece modificações de áudio baseadas em parâmetros, incluindo conversão de taxa de amostragem, ajuste de bitrate, controle de volume, configuração de canais e efeitos de áudio.

Recursos

🎵 Processamento de Áudio Abrangente: Conversão de taxa de amostragem, ajuste de bitrate, controle de volume, configuração de canais
🔧 Integração com FFmpeg: Utiliza FFmpeg para processamento de áudio robusto e multiplataforma
📦 Processamento em Lote: Processa múltiplos arquivos de áudio simultaneamente com gerenciamento de fila
🎯 Sistema de Presets: Configurações predefinidas para casos de uso comuns (áudio de jogos, processamento de voz, masterização de música)
🎮 Otimizado para Áudio de Jogos: Presets especiais para desenvolvimento de jogos mobile, desktop e console
🤖 Integração com ElevenLabs: Preset otimizado para saída de voz IA da ElevenLabs
🔍 Compatível com MCP: Integração completa com Claude Desktop e outros clientes MCP
⚡ Processamento Concorrente: Processamento eficiente baseado em fila para operações em lote grandes
📊 Relatórios Detalhados: Resultados abrangentes de processamento e tratamento de erros

Instalação

npm install -g mcp-audio-tweaker

Pré-requisitos

Node.js 18.0.0 ou superior
FFmpeg instalado e disponível no PATH do sistema

Instalando FFmpeg

Windows:

# Using Chocolatey
choco install ffmpeg

# Using winget
winget install FFmpeg

macOS:

# Using Homebrew
brew install ffmpeg

Linux:

# Ubuntu/Debian
sudo apt update && sudo apt install ffmpeg

# CentOS/RHEL
sudo yum install ffmpeg

Início Rápido

Integração MCP com Claude Desktop

Adicione à sua configuração do Claude Desktop:

{
  "mcpServers": {
    "audio-tweaker": {
      "command": "npx",
      "args": ["-y", "mcp-audio-tweaker"],
      "env": {
        "AUDIO_TWEAKER_LOG_LEVEL": "info"
      }
    }
  }
}

Uso Independente

Verifique os requisitos do sistema:

mcp-audio-tweaker --standalone check

Processe um único arquivo:

mcp-audio-tweaker --standalone process \
  --input input.wav \
  --output output.mp3 \
  --volume -3 \
  --sample-rate 44100 \
  --bitrate 192 \
  --normalize

Processamento em lote com preset:

mcp-audio-tweaker --standalone batch \
  --input-dir ./audio/raw \
  --output-dir ./audio/processed \
  --preset game-audio-mobile

Liste os presets disponíveis:

mcp-audio-tweaker --standalone presets

Ferramentas MCP

process_audio_file

Processa um único arquivo de áudio com operações personalizadas.

Parâmetros:

inputFile (string): Caminho para o arquivo de áudio de entrada
outputFile (string): Caminho para o arquivo de saída
operations (objeto): Operações de processamento de áudio
overwrite (booleano): Se deve sobrescrever arquivos existentes

Exemplo:

{
  "inputFile": "/path/to/input.wav",
  "outputFile": "/path/to/output.mp3",
  "operations": {
    "volume": {
      "adjust": -3,
      "normalize": true,
      "targetLUFS": -20
    },
    "format": {
      "sampleRate": 44100,
      "bitrate": 192,
      "channels": 2,
      "codec": "mp3"
    },
    "effects": {
      "fadeIn": 0.1,
      "fadeOut": 0.2
    }
  }
}

batch_process_audio

Processa múltiplos arquivos de áudio em um diretório.

Parâmetros:

inputDirectory (string): Diretório contendo os arquivos de entrada
outputDirectory (string): Diretório para os arquivos processados
filePattern (string): Padrão glob para correspondência de arquivos
operations (objeto): Operações de processamento de áudio
overwrite (booleano): Se deve sobrescrever arquivos existentes

apply_preset

Aplica um preset de processamento de áudio predefinido.

Parâmetros:

inputFile (string): Caminho para o arquivo de áudio de entrada
outputFile (string): Caminho para o arquivo de saída
preset (string): Nome do preset a ser aplicado
overwrite (booleano): Se deve sobrescrever arquivos existentes

Presets Disponíveis:

game-audio-mobile: Otimizado para jogos mobile
game-audio-desktop: Alta qualidade para jogos desktop
game-audio-console: Qualidade premium para consoles
elevenLabs-optimize: Otimiza a saída de voz IA da ElevenLabs
voice-processing: Processamento geral de voz e diálogo
music-mastering: Masterização de música de alta qualidade
sfx-optimization: Efeitos sonoros e áudio ambiente

list_presets

Lista todos os presets disponíveis com descrições.

Parâmetros:

category (string, opcional): Filtrar por categoria (game, voice, music, effects)

get_queue_status

Obtém o status atual da fila de processamento de áudio.

Operações de Áudio

Operações de Volume

{
  "volume": {
    "adjust": -3,          // Volume adjustment in dB (-60 to +20)
    "normalize": true,     // Apply loudness normalization
    "targetLUFS": -23      // Target LUFS for normalization
  }
}

Operações de Formato

{
  "format": {
    "sampleRate": 44100,   // Sample rate (8000, 16000, 22050, 44100, 48000, 96000, 192000)
    "bitrate": 192,        // Bitrate in kbps (64-320)
    "channels": 2,         // Channel count (1, 2, 6, 8)
    "codec": "mp3"         // Codec (pcm, mp3, aac, vorbis, flac)
  }
}

Operações de Efeitos

{
  "effects": {
    "fadeIn": 0.1,         // Fade in duration in seconds
    "fadeOut": 0.2,        // Fade out duration in seconds
    "trim": {              // Trim audio
      "start": 1.0,        // Start time in seconds
      "end": 30.0          // End time in seconds
    },
    "loop": {              // Loop audio
      "enabled": true,
      "count": 3           // Number of loops
    }
  }
}

Exemplos de Uso com Claude Desktop

Otimizar Saída de Voz ElevenLabs

@audio-tweaker Apply the elevenLabs-optimize preset to the file /audio/voice-output.wav and save it as /audio/optimized-voice.mp3

Processar Áudio de Jogos em Lote

@audio-tweaker Process all WAV files in /game-assets/audio/raw/ using the game-audio-mobile preset and save them to /game-assets/audio/mobile/

Processamento Personalizado de Voz

@audio-tweaker Process /recordings/dialogue.wav with the following operations: normalize audio to -20 LUFS, convert to 22kHz mono MP3 at 128kbps, add 0.05s fade in and 0.1s fade out, and save as /processed/dialogue.mp3

Verificar Status do Processamento de Áudio

@audio-tweaker What's the current status of the audio processing queue?

Integração de Fluxo de Trabalho

Fluxo de Trabalho de Desenvolvimento de Jogos

Gerar Voz IA com ElevenLabs
Otimizar com MCP Audio Tweaker: Aplicar preset elevenLabs-optimize
Processamento Específico por Plataforma: Usar presets game-audio-mobile, game-audio-desktop ou game-audio-console
Integração: Importar áudio otimizado para o motor do jogo

Fluxo de Trabalho de Produção Musical

Gravar/Importar Áudio
Masterizar com Audio Tweaker: Aplicar preset music-mastering
Otimização por Plataforma: Criar versões específicas por plataforma
Distribuição: Exportar nos formatos necessários

Configuração

Variáveis de Ambiente

AUDIO_TWEAKER_LOG_LEVEL: Define o nível de registro (debug, info, warn, error)
FFMPEG_PATH: Caminho personalizado do binário FFmpeg (opcional)

Configuração Avançada

O pacote suporta configurações avançadas do FFmpeg através de passagem direta de parâmetros. Consulte a documentação do FFmpeg para opções adicionais.

Tratamento de Erros

O pacote fornece tratamento abrangente de erros com códigos de erro específicos:

FILE_NOT_FOUND: O arquivo de entrada não existe
FFMPEG_NOT_FOUND: FFmpeg não instalado ou não está no PATH
INVALID_PARAMETERS: Falha na validação dos parâmetros de processamento
OUTPUT_WRITE_FAILED: Não é possível gravar no local de saída
PROCESSING_FAILED: Falha no processamento do FFmpeg
PRESET_NOT_FOUND: O preset solicitado não existe

Desempenho

Processamento Concorrente: Padrão de 2 operações concorrentes (configurável)
Gerenciamento de Fila: Fila de processamento eficiente com recursos de pausa/retomada
Eficiência de Memória: Transmite dados de áudio sem carregar arquivos inteiros na memória
Multiplataforma: Otimizado para Windows, macOS e Linux

Formatos Suportados

Formatos de Entrada: MP3, WAV, OGG, FLAC, M4A, AAC Formatos de Saída: MP3, WAV, OGG, FLAC, M4A, AAC

Desenvolvimento

Compilando a partir do Código Fonte

git clone https://github.com/your-org/mcp-audio-tweaker.git
cd mcp-audio-tweaker
npm install
npm run build

Executando Testes

npm test
npm run test:coverage
npm run test:ffmpeg

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade
Faça suas alterações
Adicione testes para novas funcionalidades
Envie um pull request

Documentação Completa

Este README fornece uma visão geral rápida. Para documentação abrangente:

🚀 Começando

Guia de Instalação: Instruções completas de configuração
Tutorial de Início Rápido: Comece a usar em 15 minutos
Referência da API: Documentação completa da API

🔧 Suporte e Solução de Problemas

Guia de Solução de Problemas: Problemas comuns e soluções
Guia de Contribuição: Como contribuir com o projeto

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

Suporte

Problemas: GitHub Issues
Documentação: README
Comunidade: Discussões

Agradecimentos

Construído com FFmpeg para processamento de áudio
Usa Model Context Protocol para integração com Claude Desktop
Projetado para o fluxo de trabalho de áudio de jogos Infinity Cube