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

Prerequisites

• Node.js 18.0.0 or higher

• FFmpeg installed and available in system PATH

Installing FFmpeg

Windows:

macOS:

Linux:

Quick Start

MCP Integration with Claude Desktop

Add to your Claude Desktop configuration:

Standalone Usage

Check system requirements:

Process a single file:

Batch process with preset:

List available 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:

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

Format Operations

Effects Operations

Claude Desktop Usage Examples

Optimize ElevenLabs Voice Output

Batch Process Game Audio

Custom Voice Processing

Check Audio Processing Status

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

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

Running Tests

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

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