MCP Audio Tweaker

# 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 ```bash npm install -g mcp-audio-tweaker ``` ### Prerequisites - Node.js 18.0.0 or higher - FFmpeg installed and available in system PATH #### Installing FFmpeg **Windows:** ```bash # Using Chocolatey choco install ffmpeg # Using winget winget install FFmpeg ``` **macOS:** ```bash # Using Homebrew brew install ffmpeg ``` **Linux:** ```bash # 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: ```json { "mcpServers": { "audio-tweaker": { "command": "npx", "args": ["-y", "mcp-audio-tweaker"], "env": { "AUDIO_TWEAKER_LOG_LEVEL": "info" } } } } ``` ### Standalone Usage Check system requirements: ```bash mcp-audio-tweaker --standalone check ``` Process a single file: ```bash mcp-audio-tweaker --standalone process \ --input input.wav \ --output output.mp3 \ --volume -3 \ --sample-rate 44100 \ --bitrate 192 \ --normalize ``` Batch process with preset: ```bash mcp-audio-tweaker --standalone batch \ --input-dir ./audio/raw \ --output-dir ./audio/processed \ --preset game-audio-mobile ``` List available presets: ```bash 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:** ```json { "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 ```json { "volume": { "adjust": -3, // Volume adjustment in dB (-60 to +20) "normalize": true, // Apply loudness normalization "targetLUFS": -23 // Target LUFS for normalization } } ``` ### Format Operations ```json { "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 ```json { "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 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 ```bash git clone https://github.com/your-org/mcp-audio-tweaker.git cd mcp-audio-tweaker npm install npm run build ``` ### Running Tests ```bash 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](/docs/installation-guide.md)**: Complete setup instructions - **[Quick Start Tutorial](/docs/quick-start.md)**: Get running in 15 minutes - **[API Reference](/docs/api-reference.md)**: Complete API documentation ### 🔧 Support & Troubleshooting - **[Troubleshooting Guide](/docs/troubleshooting.md)**: Common issues and solutions - **[Contributing Guide](/docs/contributing.md)**: How to contribute to the project ## License MIT License - see [LICENSE](LICENSE) file for details. ## Support - **Issues**: [GitHub Issues](https://github.com/DeveloperZo/mcp-audio-tweaker/issues) - **Documentation**: [README](https://github.com/DeveloperZo/mcp-audio-tweaker#readme) - **Community**: [Discussions](https://github.com/DeveloperZo/mcp-audio-tweaker/discussions) ## Acknowledgments - Built with [FFmpeg](https://ffmpeg.org/) for audio processing - Uses [Model Context Protocol](https://github.com/modelcontextprotocol) for Claude Desktop integration - Designed for [Infinity Cube](https://github.com/your-org/infinity-cube) game audio workflow