# MCP Audio Inspector

[![npm version](https://badge.fury.io/js/mcp-audio-inspector.svg)](https://badge.fury.io/js/mcp-audio-inspector)
[![npm downloads](https://img.shields.io/npm/dm/mcp-audio-inspector.svg)](https://www.npmjs.com/package/mcp-audio-inspector)
[![license](https://img.shields.io/npm/l/mcp-audio-inspector.svg)](https://github.com/DeveloperZo/mcp-audio-inspector/blob/main/LICENSE)

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

```bash
npm install -g mcp-audio-inspector
```

Or use with npx:
```bash
npx mcp-audio-inspector
```

## Usage

### MCP Server Mode (Claude Desktop)

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "audio-inspector": {
      "command": "npx",
      "args": ["-y", "mcp-audio-inspector"],
      "env": {}
    }
  }
}
```

### Standalone CLI Mode

Analyze a single file:
```bash
npx mcp-audio-inspector --standalone path/to/audio.mp3
```

Batch analyze a directory:
```bash
npx mcp-audio-inspector --batch path/to/audio/directory
```

Save output to file:
```bash
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 file
- `includeGameAnalysis` (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 files
- `recursive` (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:

```json
{
  "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](../docs/installation-guide.md)**: Complete setup instructions
- **[Quick Start Tutorial](../docs/tutorials/quick-start.md)**: Get running in 15 minutes
- **[API Reference](../docs/api-reference.md)**: Complete API documentation

### 🎮 Workflows & Tutorials
- **[Game Audio Workflow](../docs/tutorials/game-audio-workflow.md)**: Complete game development pipeline
- **[ElevenLabs Integration](../docs/tutorials/elevenlabs-integration.md)**: AI voice processing workflow
- **[Batch Processing Guide](../docs/tutorials/batch-processing.md)**: Efficient mass audio processing

### 🔧 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.

## Contributing

Contributions welcome! Please read our [Contributing Guide](../docs/contributing.md) and submit pull requests to our GitHub repository.

## Support

- **Issues**: [GitHub Issues](https://github.com/DeveloperZo/mcp-audio-inspector/issues)
- **Documentation**: [README](https://github.com/DeveloperZo/mcp-audio-inspector#readme)
- **Community**: [Discussions](https://github.com/DeveloperZo/mcp-audio-inspector/discussions)