{
  "markdown": "# 🎵 Gemini Audio MCP\n\n[![Institutional Grade](https://img.shields.io/badge/Quality-Institutional--Grade-blue.svg)](https://github.com/mcp-servers/gemini-audio-mcp)\n[![Gemini 2.5](https://img.shields.io/badge/Model-Gemini%202.5%20Live-orange.svg)](https://ai.google.dev/)\n[![Lyria 3](https://img.shields.io/badge/Engine-Lyria%203%20Pro-purple.svg)](https://deepmind.google/technologies/lyria/)\n\n**Gemini Audio MCP** is a high-performance Model Context Protocol (MCP) server engineered for professional-grade audio synthesis. It leverages the **Gemini 2.5 Multimodal Live API** and Google DeepMind's **Lyria 3** models to deliver high-fidelity environmental soundscapes, musical compositions, and expressive narration on-demand.\n\n---\n\n## 🛠 Prerequisites\n\nBefore deploying the server, ensure your environment meets the following technical requirements:\n\n### 1. FFmpeg (Core Processing Engine)\nRequired for high-performance audio encoding, decoding, and transcoding.\n- **macOS**: `brew install ffmpeg`\n- **Windows**: `winget install ffmpeg` or download from [ffmpeg.org](https://ffmpeg.org/).\n- **Linux (Ubuntu/Debian)**: `sudo apt update && sudo apt install ffmpeg`\n\n### 2. Rust Toolchain (Compilation)\nRequired to build the server from source.\n- Install via [rustup.rs](https://rustup.rs/): `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`\n\n### 3. Node.js & NPM (Runtime)\nRequired if using the pre-compiled NPM package.\n- Version: `node >= 18.0.0`\n\n---\n\n## 🚀 Installation & Deployment\n\n### Global Installation (via NPX)\nThe fastest way to integrate the server into your MCP client (e.g., Claude Desktop).\n```json\n{\n  \"mcpServers\": {\n    \"gemini-audio\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"gemini-audio-mcp\"],\n      \"env\": {\n        \"GEMINI_API_KEY\": \"YOUR_SECURE_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n### Manual Build (Optimized)\nFor maximum performance, build the Rust binary locally:\n1.  **Clone & Build**:\n    ```bash\n    git clone https://github.com/mcp-servers/gemini-audio-mcp.git\n    cd gemini-audio-mcp\n    cargo build --release\n    ```\n2.  **Locate Binary**: The optimized binary will be in `./target/release/gemini-audio-mcp`.\n\n---\n\n## 🔑 API Key Management\n\nThe server requires a valid Google AI Studio API key.\n1.  Obtain your key from [Google AI Studio](https://aistudio.google.com/).\n2.  **Security Best Practice**: Never hardcode keys. Inject the key via the `GEMINI_API_KEY` environment variable.\n3.  **Tier Note**: Access to Lyria 3 (Pro/Clip) models typically requires a **Paid Tier** or specific preview access in Google AI Studio.\n\n---\n\n## 🎮 Tool Usage Guide\n\n### 1. Environmental Generation (`generate_soundscape`)\nSynthesizes immersive, vocal-free ambient textures.\n```json\n{\n  \"name\": \"generate_soundscape\",\n  \"arguments\": {\n    \"prompt\": \"Deep underwater abyss, low-frequency whale songs, rhythmic air bubbles rising, muffled aquatic pressure.\",\n    \"duration\": 60,\n    \"quality\": \"high\",\n    \"auto_play\": true\n  }\n}\n```\n\n### 2. Professional Music (`generate_music`)\nGenerates structural compositions with optional vocal control.\n```json\n{\n  \"name\": \"generate_music\",\n  \"arguments\": {\n    \"prompt\": \"Melancholic solo cello in a vast cathedral with 5-second decay reverb.\",\n    \"bpm\": 72,\n    \"song_key\": \"D minor\",\n    \"intensity\": 4\n  }\n}\n```\n\n### 3. Expressive Voice (`generate_voice`)\nNarration and character dialogue using Gemini 2.5 Native Audio.\n```json\n{\n  \"name\": \"generate_voice\",\n  \"arguments\": {\n    \"text\": \"The artifacts are stable, but the rift remains open.\",\n    \"voice_direction\": \"Gravelly, urgent, whispered\"\n  }\n}\n```\n\n### 4. Dynamic Evolution (`transition_soundscape`)\nCrossfades two distinct environments for seamless scene transitions.\n```json\n{\n  \"name\": \"transition_soundscape\",\n  \"arguments\": {\n    \"from_prompt\": \"Quiet library silence.\",\n    \"to_prompt\": \"Sudden heavy rain on a tin roof.\",\n    \"transition_duration\": 8\n  }\n}\n```\n\n---\n\n## ⚙️ Advanced Parameters\n\n| Parameter | Type | Description |\n| :--- | :--- | :--- |\n| `seed` | `Integer` | Ensures deterministic, reproducible audio outputs. |\n| `image_path` | `String` | **Multimodal**: Uses a local image to guide the acoustic mood (e.g., resonance). |\n| `bpm` | `Number` | Explicitly sets the rhythmic tempo (essential for music). |\n| `intensity` | `Number` | 1-10 scale controlling dynamic range and complexity. |\n| `guidance` | `Number` | 0.0-6.0 scale for prompt adherence (Lyria models). |\n| `duration` | `Number` | Target length in seconds. Triggers the **Seamless Looping Engine**. |\n\n---\n\n## 🔬 Architecture Overview\n\nGemini Audio MCP employs a unique **Hybrid Engine Strategy**:\n- **WebSocket Loop**: Connects to Gemini 2.5 Live for low-latency, interactive voice and foley tasks.\n- **REST Pipeline**: Interfaces with Lyria 3 Pro for high-fidelity musical synthesis.\n- **PCM Processing**: An internal Rust-based loop (`decode -> crossfade -> loop -> encode`) ensures that short clips are transformed into seamless, infinite soundscapes without audible clicks.\n\n---\n\n## 🧪 Troubleshooting\n\n### FFmpeg Errors\n- **\"FFmpeg not found\"**: Ensure `ffmpeg` is in your system PATH. Run `ffmpeg -version` in your terminal to verify.\n- **Transcoding Failures**: Check if you have the necessary codecs (e.g., `libmp3lame` for MP3). Most standard FFmpeg installations include these.\n\n### API Issues\n- **429 Rate Limit**: The server implements a semaphore to limit concurrency, but ensure your API tier supports the requested model.\n- **Empty Audio Output**: Verify your `GEMINI_API_KEY` is correct and that your account has access to the requested model (especially `lyria-3-pro-preview`).\n\n---\n\n## 📄 License\nLicensed under the **MIT License**. Engineered with precision by the MCP community.\n",
  "bytes": 5723,
  "sha": "861a0d4824efa20dee4ec9d8453b84e9777c8d43b38e717ef9a019d882694d48",
  "repo_slug": "jxoesneon/gemini-audio-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jxoesneon_gemini_audio_mcp_b3aeee13/readme"
}