{
  "markdown": "# Audio File MCP App\n\nAn [MCP App](https://blog.modelcontextprotocol.io/posts/2026-01-26-mcp-apps/)\nfor playing and inspecting local audio files in an MCP host.\n\n![Audio File MCP App running in Claude Desktop](https://raw.githubusercontent.com/counterpoint-studio/audio-file-mcp-app/main/docs/screenshot.png)\n\nRenders an in-conversation UI with playback, metadata, loudness, a\nspectrogram, and an optional annotation-lane timeline.\n\nFile metadata, loudness statistics, the current playhead position, any\nselected region, and the annotation lanes active at the playhead are also\nexposed back to the model, so follow-up tasks can refer to what the user is\nactually hearing and looking at.\n\n## Features\n\n- **Global loudness metrics** computed to EBU R128: Integrated Loudness\n  (LUFS), Loudness Range (LRA), True Peak (dBTP), Sample Peak, and RMS.\n- **Instantaneous loudness metrics** while playing or hovering: Momentary\n  (400 ms) and Short-Term (3 s) LUFS, plus sample-peak and RMS at the\n  cursor position.\n- **Waveform colouring** by spectral centroid — each waveform slice is\n  shaded along a tonal ramp using a low/mid/high band-energy ratio, so\n  bright/dark regions read at a glance as bright/dark sound.\n- **Reassigned spectrogram** with log-frequency bins (20 Hz floor) and an\n  Inferno colour scale; time-frequency reassignment sharpens transients\n  and tonal partials beyond what a plain STFT shows.\n- **Looping region selection.** Drag on the timeline to mark a region;\n  playback loops over it, and the region's start/end are passed back to\n  the model alongside the file's loudness and playhead state.\n- **Annotation-lane timeline.** Supply timeline annotations and the widget\n  draws a stack of thin labelled lanes between the waveform and spectrogram,\n  aligned to the audio's own timeline. Each lane carries time spans, an\n  optional colour, and an optional envelope that fades span opacity along the\n  lane. Hovering a span reveals its label, and the lanes active at the\n  playhead — plus those starting, ending, or active within a selected region\n  — are reported back to the model.\n\n## Install\n\nThe server runs locally over stdio. Every install path below configures the\nsame command: `npx -y @counterpoint-studio/audio-file-mcp-app`.\n\n### Claude Desktop\n\nEasiest: grab the latest `.mcpb` from the\n[Releases page](https://github.com/counterpoint-studio/audio-file-mcp-app/releases/latest)\nand double-click it. Claude Desktop has Node bundled, so no extra runtime\nis needed.\n\nOr add the server by hand to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"audio-file\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@counterpoint-studio/audio-file-mcp-app\"]\n    }\n  }\n}\n```\n\n### Codex Desktop\n\n1. Go to Settings -> MCP Servers\n2. Add Server\n3. Name: `audiofile-mcp-app`\n4. Command to launch: `npx`\n5. Arguments `-y` and `@counterpoint-studio/audio-file-mcp-app`\n\n\n### VS Code (Copilot, Agent mode)\n\n[![Install in VS Code](https://img.shields.io/badge/Install%20in-VS%20Code-007ACC?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=audio-file&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40counterpoint-studio%2Faudio-file-mcp-app%22%5D%7D)\n\nOr add to `.vscode/mcp.json` (workspace) or your user `mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"audio-file\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@counterpoint-studio/audio-file-mcp-app\"]\n    }\n  }\n}\n```\n\n### Goose\n\nPaste this deep link into your browser (Goose Desktop must be installed; the\ncustom URI scheme can't be a real link in a GitHub README):\n\n```\ngoose://extension?id=audio-file&name=Audio%20File%20MCP%20App&cmd=npx&arg=-y&arg=%40counterpoint-studio%2Faudio-file-mcp-app\n```\n\nOr run `goose configure` → **Add Extension** → **Command-line Extension** and\nenter `npx -y @counterpoint-studio/audio-file-mcp-app`.\n\n### MCP Inspector\n\n```bash\nnpx @modelcontextprotocol/inspector npx -y @counterpoint-studio/audio-file-mcp-app\n```\n\n## Usage\n\nAsk the host to show you a local audio file by its absolute path. For\nexample:\n\n> \"Show me `/Users/me/Music/track.wav`\"\n\nThe host calls the `display_audio_file` tool, which renders the in-app UI\nwith waveform, spectrogram, loudness metrics, and playback transport.\n\n### Annotation lanes\n\n`display_audio_file` accepts an optional `annotations` object describing lanes\nto draw on the timeline (or an `annotationsPath` pointing at a JSON file with\nthe same `{ \"lanes\": [...] }` shape — handy for large payloads):\n\n```json\n{\n  \"annotations\": {\n    \"lanes\": [\n      {\n        \"label\": \"Delay tails\",\n        \"color\": \"#e6007e\",\n        \"spans\": [{ \"start\": 8, \"end\": 24 }],\n        \"envelope\": [\n          { \"time\": 8, \"value\": 0 },\n          { \"time\": 24, \"value\": 1 }\n        ]\n      }\n    ]\n  }\n}\n```\n\nTimes are in seconds on the audio's own timeline. `label`, `color`, and\n`envelope` are optional; a lane with an envelope fades its span opacity along\nthe envelope curve, and uncoloured lanes use a light-accent fill. Overlapping\nspans in a lane are truncated at the next span's start so rows never overlap.\nThe model can author annotations to point out sections, mark events, or\nvisualise an analysis it just ran.\n\n## Client compatibility\n\nTested and known to work in:\n\n- **Claude Desktop** — Chat, Cowork, and Code\n- **Codex Desktop**\n- **Visual Studio Code**\n- **Goose**\n- **MCP Inspector**\n\n## Development\n\n```bash\npnpm install\npnpm run build:dsp   # emsdk required; see WASM-BUILD.md\npnpm run serve       # runs the server with tsx, no compile step\npnpm test\n```\n\n`pnpm run build:dist` produces the publishable layout under `dist/`\n(`dist/mcp-app.html` + `dist/server/`).\n\n## Releasing\n\n```bash\npnpm version <bump>          # bumps every version string (package.json, server.json,\n                             # mcpb/manifest.json, src/server/app.ts) + commits + tags\npnpm publish --access public # publishes to npm, then the MCP Registry (postpublish)\npnpm run build:mcpb          # produces dist/audio-file-mcp-app-<version>.mcpb\ngh release create v<version> dist/*.mcpb # attaches the bundle to a GitHub release\n```\n\nThe MCP Registry step runs `mcp-publisher publish` automatically after\n`pnpm publish`. It needs a valid login — if it fails with an auth error, run\n`mcp-publisher login github` and then `mcp-publisher publish` by hand.\n`mcp-publisher` is a Go binary; install it via `brew install mcp-publisher`\nor per the [registry quickstart](https://modelcontextprotocol.io/registry/quickstart).\n\n## License\n\nISC © Counterpoint Studio OÜ\n",
  "bytes": 6598,
  "sha": "ad4a6e043d52c2fae48d43c5ddd40235ff750c39ea957aedde36baff45767aa2",
  "repo_slug": "counterpoint-studio/audio-file-mcp-app",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_counterpoint_studio_audio_file_8e9d3ffa/readme"
}