MCP Audio Tweaker

A Model Context Protocol (MCP) server for batch audio processing and optimization using FFmpeg. This package provides parameter-based audio modifications including sample rate conversion, bitrate adjustment, volume control, channel configuration, and audio effects.

Features

• 🎵 Comprehensive Audio Processing: Sample rate conversion, bitrate adjustment, volume control, channel configuration
• 🔧 FFmpeg Integration: Leverages FFmpeg for robust, cross-platform audio processing
• 📦 Batch Processing: Process multiple audio files concurrently with queue management
• 🎯 Preset System: Predefined configurations for common use cases (game audio, voice processing, music mastering)
• 🎮 Game Audio Optimized: Special presets for mobile, desktop, and console game development
• 🤖 ElevenLabs Integration: Optimized preset for ElevenLabs AI voice output
• 🔍 MCP Compatible: Full integration with Claude Desktop and other MCP clients
• ⚡ Concurrent Processing: Efficient queue-based processing for large batch operations
• 📊 Detailed Reporting: Comprehensive processing results and error handling

MCP Tools

process_audio_file

Process a single audio file with custom operations.

Parameters:

• inputFile (string): Path to input audio file
• outputFile (string): Path for output file
• operations (object): Audio processing operations
• overwrite (boolean): Whether to overwrite existing files

Example:

{
  "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

Process multiple audio files in a directory.

Parameters:

• inputDirectory (string): Directory containing input files
• outputDirectory (string): Directory for processed files
• filePattern (string): Glob pattern for file matching
• operations (object): Audio processing operations
• overwrite (boolean): Whether to overwrite existing files

apply_preset

Apply predefined audio processing preset.

Parameters:

• inputFile (string): Path to input audio file
• outputFile (string): Path for output file
• preset (string): Preset name to apply
• overwrite (boolean): Whether to overwrite existing files

Available Presets:

• game-audio-mobile: Optimized for mobile games
• game-audio-desktop: High-quality for desktop games
• game-audio-console: Premium quality for consoles
• elevenLabs-optimize: Optimizes ElevenLabs AI voice output
• voice-processing: General voice and dialogue processing
• music-mastering: High-quality music mastering
• sfx-optimization: Sound effects and ambient audio

list_presets

List all available presets with descriptions.

Parameters:

• category (string, optional): Filter by category (game, voice, music, effects)

get_queue_status

Get current status of the audio processing queue.

Audio Operations

Volume Operations

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

Format Operations

{
  "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)
  }
}

Effects Operations

{
  "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
    }
  }
}

Workflow Integration

Game Development Workflow

1. Generate AI Voice with ElevenLabs
2. Optimize with MCP Audio Tweaker: Apply elevenLabs-optimize preset
3. Platform-specific Processing: Use game-audio-mobile, game-audio-desktop, or game-audio-console presets
4. Integration: Import optimized audio into game engine

Music Production Workflow

1. Record/Import Audio
2. Master with Audio Tweaker: Apply music-mastering preset
3. Platform Optimization: Create platform-specific versions
4. Distribution: Export in required formats

Error Handling

The package provides comprehensive error handling with specific error codes:

• FILE_NOT_FOUND: Input file does not exist
• FFMPEG_NOT_FOUND: FFmpeg not installed or not in PATH
• INVALID_PARAMETERS: Processing parameters validation failed
• OUTPUT_WRITE_FAILED: Cannot write to output location
• PROCESSING_FAILED: FFmpeg processing failed
• PRESET_NOT_FOUND: Requested preset does not exist

Performance

• Concurrent Processing: Default 2 concurrent operations (configurable)
• Queue Management: Efficient processing queue with pause/resume capabilities
• Memory Efficient: Streams audio data without loading entire files into memory
• Cross-platform: Optimized for Windows, macOS, and Linux

Supported Formats

Input Formats: MP3, WAV, OGG, FLAC, M4A, AAC Output Formats: MP3, WAV, OGG, FLAC, M4A, AAC

Development

Building from Source

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

Running Tests

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

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

Complete Documentation

This README provides a quick overview. For comprehensive documentation:

🚀 Getting Started

• Installation Guide: Complete setup instructions
• Quick Start Tutorial: Get running in 15 minutes
• API Reference: Complete API documentation

🔧 Support & Troubleshooting

• Troubleshooting Guide: Common issues and solutions
• Contributing Guide: How to contribute to the project

Support

• Issues: GitHub Issues
• Documentation: README
• Community: Discussions

Installation

npm install -g mcp-audio-tweaker

Prerequisites

• Node.js 18.0.0 or higher
• FFmpeg installed and available in system PATH

Installing 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

Quick Start

MCP Integration with Claude Desktop

Add to your Claude Desktop configuration:

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

Standalone Usage

Check system requirements:

mcp-audio-tweaker --standalone check

Process a single file:

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

Batch process with preset:

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

List available presets:

mcp-audio-tweaker --standalone presets

Claude Desktop Usage Examples

Optimize ElevenLabs Voice Output

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

Batch Process Game Audio

@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/

Custom Voice Processing

@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

Check Audio Processing Status

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

Configuration

Environment Variables

• AUDIO_TWEAKER_LOG_LEVEL: Set logging level (debug, info, warn, error)
• FFMPEG_PATH: Custom FFmpeg binary path (optional)

Advanced Configuration

The package supports advanced FFmpeg configurations through direct parameter passing. See the FFmpeg documentation for additional options.

License

MIT License - see LICENSE file for details.