Skip to main content
LoopHaven

A local-first API, CLI and MCP server for Looperman.

Search loops and acapella previews with real filters, get clean JSON, and pull the file you picked — from your terminal or from an AI agent.

Python tests FastAPI MCP License

Unofficial project. LoopHaven is not affiliated with, endorsed by, or supported by Looperman. It reads public pages and your own session, at human pace. It does not redistribute audio and does not bypass quotas. Read DISCLAIMER.md before using it.


Why this exists

Looperman hosts a huge community sample library and has no public API. Every "scraper" out there stops at "here is some HTML". LoopHaven does three things differently:

  1. It speaks the site's own filter vocabulary. Genre, category, key, time signature, tempo range, date window, sort order — resolved from the real advanced-search form, not guessed from URL slugs. Ask for F#m, Bb or 4/4 and it maps them to what the site actually submits.
  2. It is honest about what it returns. total is null past page 1, because Looperman stops counting. When the quota is hit you get a 429, not a silent MP3 renamed to .wav.
  3. It plugs into a DAW workflow and into agents. One HTTP API, a haven CLI, and an optional MCP server so Claude, Cursor or any MCP client can search and fetch material on your behalf.

Quickstart

git clone https://github.com/mohamed-amine-ben-mallessa/loop-haven.git
cd loop-haven
python -m pip install -e ".[mcp]"

# 1. start the local API
python -m uvicorn loophaven.api.app:app --host 127.0.0.1 --port 8000

# 2. search (public previews need no account)
curl "http://127.0.0.1:8000/api/search?genre=Trap&bpm=140&limit=2"

A real response, trimmed:

{
  "success": true,
  "count": 2,
  "looperman_url": "https://www.looperman.com/loops?gid=54&ftempo=140&ttempo=140&order=date&dir=d",
  "resolved": { "genre": { "id": 54, "label": "Trap" } },
  "loops": [
    {
      "id": "436799",
      "title": "Lil Uzi Vert Arp Type Loop",
      "bpm": 140,
      "genre": "Trap",
      "key": "Cm",
      "author": "NiemiroMTS",
      "duration_seconds": 13,
      "mp3_url": "https://www.looperman.com/media/loops/8513679/looperman-l-8513679-0436799-...mp3",
      "url": "https://www.looperman.com/loops/detail/436799/..."
    }
  ]
}

Interactive docs are at http://127.0.0.1:8000/docs.

CLI

The CLI talks to the local API, so start the server first.

# find material
haven search --genre Trap --bpm 140 --key Cm --limit 4
haven search --kind acapellas --genre "Boom Bap" --bpm 86 --mf 1 --json

# check what a download will give you (free: does not spend quota)
curl "http://127.0.0.1:8000/api/download/info/loop/436799"

# log in with your own account, then download (WAV for loops, MP3 for acapellas)
haven login
curl -OJ "http://127.0.0.1:8000/api/download/audio/loop/436799"

# audition a preview, toggle a favourite
haven play --id 436799
haven fav --hash <favorite_hash> --type loop

haven login prompts locally and never stores your password. The session cookie is persisted so a server restart does not log you out.

API

Method Route What it does
GET /api/health status + whether a session is open
GET /api/filters full vocabularies (genres, categories, keys, sorts…)
GET /api/search loop search with real filters
GET /api/acapellas/search acapella search + licence wording
GET /api/loop/{id} one loop, parsed from JSON-LD
GET /api/acapellas/{id} one acapella + usage terms
GET /api/download/info/{kind}/{id} what you would get, without spending quota
GET /api/download/audio/{kind}/{id} the actual file
POST /api/download/zip personal ZIP of 2–4 loops
POST /api/auth/login open a Looperman session
GET /api/auth/status session state (never the email)
POST /api/favorites/toggle toggle a favourite (needs login)
GET /api/stream/preview stream a public MP3 preview
GET /api/download/proxy same-origin proxy for previews

Full parameter reference: docs/API.md · Filter tables: docs/FILTERS.md · How the site's internals were mapped: docs/REVERSE-ENGINEERING.md.

MCP

{
  "mcpServers": {
    "loophaven": {
      "command": "loophaven-mcp",
      "env": { "LOOPHAVEN_API": "http://127.0.0.1:8000" }
    }
  }
}

Tools: search_loops, search_acapellas, get_acapella_detail, get_preview_url, export_loop_zip, toggle_favorite. The agent sees JSON, never HTML.

There is also a ready-made skill in skills/loop-haven/SKILL.md that teaches an agent the etiquette: preview before download, respect the licence label, never bulk-scrape.

How the filters work

Looperman's advanced search posts a form; the ids below are the real ones, read from the form itself.

Filter Parameter Example
Genre genre → gid Trap (54), Hip Hop (7), Phonk (70)
Category category → cid Piano (21), Drum (1), Vocal (6)
Key key → mkey Am, F#m → fsm, Bb → am
Tempo bpm or ftempo/ttempo bpm=140 → exact; ftempo=90&ttempo=110
Time signature tsig 4/4 → 4x4
Date window when 1=24 h, 2=7 d, 3=30 d, 4=60 d
Sort order + dir downloads/d, date/d
Keywords keyword → keys +funky -techno

Labels, ids and slugs are all accepted; unknown values return 422 with suggestions instead of an empty result page. Call /api/filters for the whole vocabulary — 69 genres, 40 categories, 24 keys.

Honest limitations

  • This is a wrapper, not an API. If Looperman changes its HTML, parsing breaks. That is the whole reason the reverse-engineering notes are in the repo.
  • total is null after page 1. Looperman caps the displayed count at 5,000 and stops showing it on later pages. LoopHaven reports that instead of inventing a number.
  • Downloads need your account and are quota-limited. One account per person. A 429 means wait, not retry harder. Nothing here is designed to evade it.
  • Acapellas have no WAV. Wherever the site serves MP3, the API says MP3 in Content-Type and a .mp3 filename.
  • The browser UI at / is a French prototype. The API, CLI and docs are in English; that page has not been translated yet.
  • Local single-user only. There is no API authentication. Do not expose it to the internet as-is.

LoopHaven is MIT-licensed code. The loops and acapellas it helps you find are not covered by that licence: they belong to their creators and are offered under Looperman's terms. Looperman is a trademark of its owner. This project is independent and unaffiliated.

What the project does, on purpose:

  • one query at a time, like a browser, with pauses;
  • no bulk harvesting, no mirroring of the catalogue;
  • no re-hosting of audio — the repo ships zero .mp3/.wav;
  • quotas and account limits are respected, never worked around.

If you are from Looperman and want something changed, open an issue — it will be handled quickly. See DISCLAIMER.md.

Contributing

Bug reports, parser fixtures and doc translations are the most useful things right now. See CONTRIBUTING.md and the good first issues.

python -m pip install -e ".[dev]"
python -m pytest tests/unit -q

Licence

MIT — take it, fork it, ship it. A star keeps the crate warm.

Metadata

Release files for loophaven 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for loophaven 0.1.0
File Size Uploaded Provenance Actions
loophaven-0.1.0.tar.gz 40.4 kB Without provenance Details for loophaven-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for loophaven 0.1.0
File Interpreter ABI Platform Actions
loophaven-0.1.0-py3-none-any.whl Python 3 none any Details for loophaven-0.1.0-py3-none-any.whl

Total release size: 79.2 kB

Release files / loophaven-0.1.0.tar.gz

Download URL loophaven-0.1.0.tar.gz
Size 40.4 kB
Tags Source
SHA-256 checksum
How to use checksums
23286de6d57e5fe92841f546db90b9021c12ab262109e392b9af7b9540c64e15
BLAKE2b-256 checksum
How to use checksums
1679f6f102c763d26dabe0f2fc73099a96f0504d4cd2a1021059b64352534ff9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.10

Release files / loophaven-0.1.0-py3-none-any.whl

Download URL loophaven-0.1.0-py3-none-any.whl
Size 38.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8c1ea56a15bad8024a4dc3b24f9576dd51862fbcf8e05a5c3c05f387f429780f
BLAKE2b-256 checksum
How to use checksums
dcbef608d684477a07a0641d1fc4454dfa40403e5b3cc94fd2169550e9ff8c1d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.10

Security for loophaven 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page