MCP Audio Inspector
A Model Context Protocol (MCP) server for comprehensive audio file analysis and metadata extraction, designed specifically for game audio development workflows.
Features
- Comprehensive Metadata Extraction: Uses music-metadata library for detailed audio analysis
- FFprobe Fallback: Handles exotic and corrupted formats through FFprobe
- Game Audio Analysis: Specialized analysis for game development use cases
- Batch Processing: Analyze entire directories of audio files
- MCP Integration: Seamless integration with Claude Desktop
- Cross-Platform: Works on Windows, macOS, and Linux
Installation
npm install -g mcp-audio-inspector
Or use with npx:
npx mcp-audio-inspector
Usage
MCP Server Mode (Claude Desktop)
Add to your Claude Desktop configuration:
{
"mcpServers": {
"audio-inspector": {
"command": "npx",
"args": ["-y", "mcp-audio-inspector"],
"env": {}
}
}
}
Standalone CLI Mode
Analyze a single file:
npx mcp-audio-inspector --standalone path/to/audio.mp3
Batch analyze a directory:
npx mcp-audio-inspector --batch path/to/audio/directory
Save output to file:
npx mcp-audio-inspector --standalone audio.wav --output analysis.json
Supported Formats
Primary Support (music-metadata):
- MP3, WAV, FLAC, OGG, M4A, AAC, WMA, AIFF, AU, WebM, Opus, APE, MP4
Extended Support (FFprobe fallback):
- Any format supported by FFmpeg
MCP Tools
analyze_audio_file
Analyze a single audio file and extract comprehensive metadata.
Parameters:
filePath(string, required): Path to the audio fileincludeGameAnalysis(boolean, optional): Include game-specific analysis (default: true)
analyze_audio_batch
Analyze all audio files in a directory.
Parameters:
directoryPath(string, required): Path to directory containing audio filesrecursive(boolean, optional): Search subdirectories recursively (default: false)includeGameAnalysis(boolean, optional): Include game-specific analysis (default: true)
get_supported_formats
Get list of supported audio formats.
Output Schema
The tool returns comprehensive metadata including:
{
"file": {
"path": "string",
"name": "string",
"size": "number",
"modified": "ISO date string"
},
"format": {
"container": "string",
"codec": "string",
"lossless": "boolean",
"duration": "number",
"bitrate": "number",
"sampleRate": "number",
"channels": "number",
"bitsPerSample": "number"
},
"tags": {
"title": "string",
"artist": "string",
"album": "string",
"year": "number",
"genre": "string",
"track": "number",
"comment": "string"
},
"gameAudio": {
"suitableForLoop": "boolean",
"recommendedCompressionFormat": "string",
"estimatedMemoryUsage": "number",
"platformOptimizations": {
"mobile": "string",
"desktop": "string",
"console": "string"
},
"compressionRatio": "number",
"gameDevNotes": "string"
}
}
Game Audio Analysis
The inspector includes specialized analysis for game development:
- Loop Suitability: Determines if audio is suitable for looping
- Compression Recommendations: Suggests optimal compression formats
- Memory Usage Estimation: Calculates uncompressed memory requirements
- Platform Optimizations: Platform-specific optimization suggestions
- Game Development Notes: Actionable recommendations for game audio
Requirements
- Node.js 18+
- FFmpeg/FFprobe (for fallback support)
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
🎮 Workflows & Tutorials
- Game Audio Workflow: Complete game development pipeline
- ElevenLabs Integration: AI voice processing workflow
- Batch Processing Guide: Efficient mass audio processing
🔧 Support & Troubleshooting
- Troubleshooting Guide: Common issues and solutions
- Contributing Guide: How to contribute to the project
License
MIT License - see LICENSE file for details.
Contributing
Contributions welcome! Please read our Contributing Guide and submit pull requests to our GitHub repository.
Support
- Issues: GitHub Issues
- Documentation: README
- Community: Discussions