Beat Saber map checker, one-click fixer, cropper and generator. Web UI, VR mode, MCP.
462
Check, fix and generate Beat Saber custom levels from your own music.
Give it a song or an existing map and it writes a map folder into your CustomLevels
directory. It builds all five Standard difficulties, finds impossible swings, broken parity
and empty stretches in existing maps, and adds atmospheric lighting learned from the maps you
already have installed. It uses vanilla features only: no Chroma, Noodle Extensions or
Vivify. Every change is reviewed by you in the browser first, and fixes go into a new sibling
folder so the original map is never touched.
Source, issues and full documentation: https://github.com/Levia-Labs/saber-tooth
<map> [saber-tooth] with all five Standard difficulties. Scan and Fix run in batches, save as they go and resume after a cancel, timeout or error.[saber-tooth] copy..bplist export and sync URLs that PlaylistManager refreshes on its own./vr, with a host helper that detects the headset; desktop, VR and mobile layouts.



CustomLevels.The service needs beat-analyser next to it. Save this as docker-compose.yml:
services:
app:
image: levialabs/sabertooth:latest
ports: ["127.0.0.1:8100:8100"]
environment:
LEVELS_DIR: /levels
DATA_DIR: /data
ANALYSER_URL: http://beat-analyser:8000
ANALYSER_UPLOADS: /analyser
PUID: 1000
PGID: 1000
volumes:
- "/path/to/Beat Saber_Data/CustomLevels:/levels"
- analyser-uploads:/analyser:ro
- saber-data:/data
depends_on:
beat-analyser:
condition: service_healthy
beat-analyser:
image: levialabs/beat-analyser:latest
volumes: ["analyser-uploads:/app/uploads"]
read_only: true
tmpfs: ["/tmp"]
healthcheck:
test:
- CMD
- python
- -c
- import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/folders', timeout=4)
interval: 10s
timeout: 5s
retries: 6
start_period: 20s
volumes:
analyser-uploads:
saber-data:
Then run docker compose up -d and open http://127.0.0.1:8100.
For HTTPS with a self-signed certificate, add SABER_TLS: "1" to the environment block and open https://127.0.0.1:8100, accepting the browser warning. The pair is generated once into /data/tls; SABER_TLS_HOSTS adds names, SABER_TLS_CERT and SABER_TLS_KEY use your own pair. HSTS is never sent.
The container starts as root only to apply PUID and PGID, then drops to that user. It
never changes ownership of /levels: on Linux, the mounted levels folder must be writable by
the PUID user.
The source repository has the full docker-compose.yml with the optional settings, including
the Playlists folder.
| Mount | Purpose |
|---|---|
/levels | Your CustomLevels folder. Maps are read here and new folders written |
/data | Service state: scan results, proposals, caches, learned lightshows |
/analyser | beat-analyser's uploads volume, mounted read-only to read its output |
/playlists | Optional. Beat Saber Playlists folder for .bplist export |
| Variable | Default | Meaning |
|---|---|---|
LEVELS_DIR | /levels | Where the service reads and writes maps |
DATA_DIR | /data | Where the service keeps its own state |
ANALYSER_URL | http://beat-analyser:8000 | Base URL of the beat-analyser service |
ANALYSER_UPLOADS | /analyser | Where beat-analyser's output volume is mounted |
ANALYSER_CONCURRENCY | 1 | Analyser requests in flight at once, shared by all job workers |
PLAYLISTS_DIR | unset | Playlists folder; setting it enables the .bplist export |
MAX_UPLOAD_MB | 200 | Largest audio upload |
SABER_ALLOWED_HOSTS | empty | Extra Host names accepted besides 127.0.0.1, localhost and [::1] |
SABER_TRUSTED_PROXY_IPS | empty | Comma list of single proxy addresses whose X-Forwarded-* headers are trusted |
PUID, PGID | 1000 | User and group the service runs as |
VR_AGENT_URL | unset | VR headset helper; compose default http://host.docker.internal:8101/status |
SABER_BIND | 127.0.0.1 | Host address of the published port (compose); 0.0.0.0 opens it to the LAN |
Warning: with SABER_BIND=0.0.0.0 anyone on the network can fix, crop, download and permanently delete map folders, because the service has no login. Also set SABER_ALLOWED_HOSTS to the names the headset uses, and set SABER_BIND back to 127.0.0.1 when done. See VR mode.
MAX_UPLOAD_MB and YT_MAX_MINUTES (default 20) also apply to the beat-analyser container.
The REST API lives under /api. Routes that start work answer {"job": "<id>"}; poll
GET /api/jobs/{id} until status is done or failed.
| Method | Path | Does |
|---|---|---|
| GET | /api/health | {"status": "ok"}, the container health check |
| GET | /api/maps | One page of the library, with search, sort and filters |
| POST | /api/maps/{id}/scan | Check one map |
| POST | /api/maps/{id}/fix | One-click fix, written to a new <name> [saber-tooth] folder |
| POST | /api/generate | New map from a YouTube URL or an uploaded audio file |
| GET | /api/maps/{id}/proposals | Proposed changes for a map, with before and after excerpts |
| POST | /api/maps/{id}/apply | Write the approved proposals into a new sibling folder |
| POST | /api/lightshow/learn | Learn lightshow styles from the installed maps |
| GET | /api/beatsaver/search | Search BeatSaver |
| POST | /api/beatsaver/download | Install up to 100 BeatSaver maps as new folders |
Errors are JSON: {"error": "..."}. The route list is longer than this table; see the
API reference.
Agents can connect over MCP (Streamable HTTP) at /mcp:
claude mcp add --transport http saber-tooth http://127.0.0.1:8100/mcp
Tools: list_maps, get_proposals, scan_map, job_status, approve_proposal,
reject_proposal, apply_map, generate_from_youtube, learn_lightshows, map_timeline,
crop_map, beatsaver_search and beatsaver_download. Details are in the
MCP section.
The API has no authentication. Publish the port on 127.0.0.1 (as above) unless the service
sits behind something that authenticates. Requests with a Host outside the allowlist get
403, and state-changing requests whose Origin does not match are refused. Behind a TLS
proxy, set SABER_ALLOWED_HOSTS and SABER_TRUSTED_PROXY_IPS. Fixes are written to a new
folder and the original map is never changed.
| Tag | What it is |
|---|---|
1.5.0 | The 1.5.0 release |
latest | The same build as 1.5.0 |
1.4.0 | The 1.4.0 release, kept |
1.3.0 | The 1.3.0 release, kept |
1.2.0 | The 1.2.0 release, kept |
1.1.0 | The 1.1.0 release, kept |
1.0.0 | The 1.0.0 release, kept |
MIT.
Content type
Image
Digest
sha256:ed6d3ff5d…
Size
259 MB
Last updated
11 days ago
docker pull levialabs/sabertooth