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

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

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

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?

Workflow Integration

Game Development Workflow

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

Music Production Workflow

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

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.

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

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
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

License

MIT License - see LICENSE file for details.

Support

Issues: GitHub Issues
Documentation: README
Community: Discussions

Acknowledgments

Built with FFmpeg for audio processing
Uses Model Context Protocol for Claude Desktop integration
Designed for Infinity Cube game audio workflow

Server	Summary	Actions
Asset Price MCP Server	English \| 中文 \| 日本語	View
Bazi MCP		View
Monzo	A Model Context Protocol (MCP) server that provides access to your Monzo banking data through a Clau...	View
Phone Carrier Detector	一个用于检测中国手机号码运营商和归属地的 MCP (Model Context Protocol) 服务器。	View
Drand		View
Gaggiuino MCP		View