Local Sound Library

A fast, zero-dependency web app to search, audition, star, and trim a local library of sound effects — plus a built-in MCP server so AI agents can search your sounds too.

It's a single Python file (sound_browser.py) with no dependencies beyond Python 3. Point it at a folder full of sound packs and it serves a browser UI at http://127.0.0.1:8000, streaming audio straight from disk. Everything is local — it binds to 127.0.0.1 only and never modifies your files.

Built and tested against the Sonniss GDC Game Audio Bundles. The sound packs themselves are not included in this repository (they're gigabytes of third-party audio and are git-ignored) — bring your own.

Features

• Search across file name, pack, and bundle — instant, as you type.
• Filters: bundle, pack, length range (seconds), and starred only.
• Sortable columns (name, pack, time, format, size).
• Player with hover-prefetch and next-track preload for near-instant playback, seek bar, prev/next, loop, volume, and an Autoplay next toggle.
• Star / favourite sounds — persisted on disk, keyed by file path so they survive rescans and browser-cache clears.
• Waveform trimming ✂ — mark in/out points on a server-rendered waveform, preview the selection, and download just that region as a lossless WAV (bit-exact, original format preserved).
• Open containing folder with the file selected in your OS file manager.
• Large-file highlighting — files over 50 MB show their size in orange.
• Refresh Library — rescan the folders for newly added sounds without a restart.
• MCP server for AI agents — see AGENT_README.md.
• Reads .wav (with duration/format parsing) plus .mp3 .flac .ogg .aiff .m4a and more.

Requirements

• Python 3.8+ (developed on 3.14). No packages to install.
• Windows, macOS, or Linux. (The "open folder" action reveals the file in Explorer on Windows / Finder on macOS; on Linux it opens the containing folder.)

Quick start

Windows: double-click Start Sound Library.bat. It finds Python, starts the server, and opens your browser automatically.

Any OS:

python sound_browser.py

Then open http://127.0.0.1:8000 (it opens automatically). Press Ctrl+C in the terminal to stop.

Useful flags:

python sound_browser.py --port 9000     # choose a port
python sound_browser.py --no-browser    # don't auto-open the browser
python sound_browser.py --root PATH     # scan a different sound folder
python sound_browser.py --mcp           # run as an MCP server (see AGENT_README.md)

Adding your own sounds

Put your sound-pack folders next to sound_browser.py (any nesting is fine — it scans recursively). Then click Refresh Library in the UI, or restart. WAV header parsing is cached in .sound_browser_cache.json, so rescans are fast.

Keyboard shortcuts

Key	Action
Space	Play / pause
← / →	Previous / next
L	Loop
S	Star the current sound
✂ / I / O	Toggle trim mode / set in / set out
R	Refresh library
/	Focus the search box

For AI agents (MCP)

The same program runs as a Model Context Protocol server over stdio:

python sound_browser.py --mcp

It exposes search_sounds, get_sound_info, list_packs, and get_library_stats. Full setup and tool reference is in AGENT_README.md.

How it works

• One file, standard library only: http.server for the web/API + audio streaming (with HTTP range support for seeking), manual RIFF/WAV parsing for duration, waveform peaks, and lossless cuts.
• The library is indexed on startup (and on Refresh); each sound is referenced by an internal id, so the browser can never request arbitrary paths.
• Read-only with respect to your audio — trimming streams a freshly-built WAV from the source bytes and never touches the originals.

Notes

• Local only: the server listens on 127.0.0.1. Nothing is uploaded anywhere.
• The sound packs are intentionally excluded from version control via .gitignore.