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 fileoutputFile(string): Path for output fileoperations(object): Audio processing operationsoverwrite(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 filesoutputDirectory(string): Directory for processed filesfilePattern(string): Glob pattern for file matchingoperations(object): Audio processing operationsoverwrite(boolean): Whether to overwrite existing files
apply_preset
Apply predefined audio processing preset.
Parameters:
inputFile(string): Path to input audio fileoutputFile(string): Path for output filepreset(string): Preset name to applyoverwrite(boolean): Whether to overwrite existing files
Available Presets:
game-audio-mobile: Optimized for mobile gamesgame-audio-desktop: High-quality for desktop gamesgame-audio-console: Premium quality for consoleselevenLabs-optimize: Optimizes ElevenLabs AI voice outputvoice-processing: General voice and dialogue processingmusic-mastering: High-quality music masteringsfx-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-optimizepreset - Platform-specific Processing: Use
game-audio-mobile,game-audio-desktop, orgame-audio-consolepresets - Integration: Import optimized audio into game engine
Music Production Workflow
- Record/Import Audio
- Master with Audio Tweaker: Apply
music-masteringpreset - 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 existFFMPEG_NOT_FOUND: FFmpeg not installed or not in PATHINVALID_PARAMETERS: Processing parameters validation failedOUTPUT_WRITE_FAILED: Cannot write to output locationPROCESSING_FAILED: FFmpeg processing failedPRESET_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