{"id":50909934,"url":"https://github.com/icedmoca/beatmaper","last_synced_at":"2026-06-16T09:02:36.265Z","repository":{"id":358162595,"uuid":"1240251136","full_name":"icedmoca/beatmaper","owner":"icedmoca","description":"Beatmaper turns any song (MP3/WAV/OGG) into a playable Beat Saber map.","archived":false,"fork":false,"pushed_at":"2026-05-16T02:14:18.000Z","size":162,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-16T03:41:32.632Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/icedmoca.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-15T23:33:08.000Z","updated_at":"2026-05-16T02:14:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/icedmoca/beatmaper","commit_stats":null,"previous_names":["icedmoca/beatmaper"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/icedmoca/beatmaper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icedmoca%2Fbeatmaper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icedmoca%2Fbeatmaper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icedmoca%2Fbeatmaper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icedmoca%2Fbeatmaper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/icedmoca","download_url":"https://codeload.github.com/icedmoca/beatmaper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icedmoca%2Fbeatmaper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34398408,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-16T09:02:35.409Z","updated_at":"2026-06-16T09:02:36.260Z","avatar_url":"https://github.com/icedmoca.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Beatmaper\n\n\u003e Beatmaper is a local web app that turns an uploaded audio file into a Beat Saber custom map ZIP. It includes:\n\n[![Hugging Face Dataset](https://img.shields.io/badge/HuggingFace-BeatMapMaker-yellow?logo=huggingface\u0026logoColor=white)](https://huggingface.co/datasets/icedmoca/beatmapmaker)\n\n\n- A React/Vite frontend.\n- A FastAPI Python backend.\n- Audio analysis for tempo, beat peaks, bass peaks, vocal/mid peaks, and high-frequency accents.\n- A learned ranked-pattern model trained from ranked Beat Saber maps.\n- Multiple generation modes: Normal, Fun, Overkill, and Direct Instrument Mode.\n- A Three.js preview that simulates blocks moving toward sabers in sync with the generated song audio.\n- Exported Beat Saber map files: `Info.dat`, `ExpertStandard.dat`, and `song.egg`.\n\nThis project is designed to run locally on your own computer. It does not require an online API once dependencies are installed.\n\n## What the app does\n\nWhen you upload a song:\n\n1. The backend receives the audio file.\n2. If the file is not already WAV, the backend uses **ffmpeg** to convert it to WAV for analysis.\n3. The backend analyzes the waveform and extracts:\n   - overall beats/onsets,\n   - bass events,\n   - vocal/mid-range events,\n   - high-frequency accent events,\n   - estimated BPM,\n   - section intensity.\n4. The generator creates Beat Saber notes using both:\n   - direct audio events from the song,\n   - learned note-pattern tendencies from ranked Beat Saber maps.\n5. The backend converts the song to **song.egg**, which is an Ogg/Vorbis audio file with the `.egg` extension used by Beat Saber maps.\n6. The backend writes a Beat Saber map folder and ZIP.\n7. The frontend shows the generated stats and a Three.js gameplay preview.\n8. You can download the generated ZIP and put it into your Beat Saber custom levels folder.\n\n## Important limitation\n\nThis is an **experimental** generator. It can create valid Beat Saber-style files, but it is not guaranteed to make perfect human-authored maps. Beat Saber mapping is artistic and technical. You should still test maps in-game and refine them if you want polished results.\n\nThe current generator tries to be readable by default in **Normal** mode, then lets you increase complexity through **Fun** and **Overkill** settings.\n\n---\n\nSource: [github.com/icedmoca/beatmaper](https://github.com/icedmoca/beatmaper)\n\n## Quick start\n\n### One command (paste in Terminal)\n\n**macOS, Linux, or [Git Bash](https://git-scm.com/downloads) on Windows** — clones/updates the app under `~/beatmaper` and runs **`npm start`** (install + Hugging Face models + **TUI** to pick browser or Electron):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/icedmoca/beatmaper/main/install.sh | bash\n```\n\nThe installer reopens your **keyboard** as stdin for `npm start` (via `/dev/tty`), so the **1 / 2 / 0** menu still works when the script is piped from `curl`—otherwise stdin would be the script stream and the menu would exit immediately.\n\nOptional: install somewhere else (directory must be empty or already this repo):\n\n```bash\nexport BEATMAPER_DIR=\"$HOME/code/beatmaper\"\ncurl -fsSL https://raw.githubusercontent.com/icedmoca/beatmaper/main/install.sh | bash\n```\n\nIf you already cloned the repo, you can run the same script from any directory (it detects a checkout in the current folder) or:\n\n```bash\nbash install.sh\n```\n\n---\n\nYou need:\n\n- [Node.js](https://nodejs.org/) (LTS includes `npm`)\n- [Python](https://www.python.org/) **3.10+** with `pip`\n- [**ffmpeg**](https://ffmpeg.org/) on your `PATH` (used to decode/convert audio)\n\nThe first time you run **`npm start`**, it creates a **local `.venv`**, then runs **`pip install -r requirements.txt`** inside it when FastAPI / uvicorn are missing (PEP 668 / “externally managed” systems like Arch are handled this way). You can still install manually anytime:\n\n```bash\npip install -r requirements.txt\n```\n\nOn Windows, if `python3` is missing, use `py -3 -m pip install -r requirements.txt`. The dev scripts try `python3`, then `python`, then `py -3`.\n\nIf you prefer not to use `install.sh`, clone and start manually:\n\n```bash\ngit clone https://github.com/icedmoca/beatmaper.git \u0026\u0026 cd beatmaper \u0026\u0026 npm start\n```\n\nIf you already cloned into `beatmaper`:\n\n```bash\ncd beatmaper \u0026\u0026 npm start\n```\n\n`npm start` runs `npm install`, installs Python API dependencies into **`.venv`** when needed, downloads the **Hugging Face** dataset [`icedmoca/beatmapmaker`](https://huggingface.co/datasets/icedmoca/beatmapmaker) into `models/` (skipped if files are already there), then shows a short **terminal menu**: pick **local website** (Vite in the browser) or **Electron** (desktop). **Both options start the FastAPI backend** on [http://127.0.0.1:8008](http://127.0.0.1:8008) together with the UI, so uploads work. Follow the URL or window it starts.\n\nTo re-download model files (for example after a dataset update): `npm run fetch-dataset`. Override repo/revision with `BEATMAPER_HF_DATASET` and `BEATMAPER_HF_REV`. Force refresh: `BEATMAPER_FORCE_DATASET=1 npm run fetch-dataset`.\n\n| Command | What it does |\n|--------|----------------|\n| `npm run fetch-dataset` | Download / refresh `models/` from Hugging Face (`icedmoca/beatmapmaker`) |\n| `npm run backend:dev` | FastAPI only at [http://127.0.0.1:8008](http://127.0.0.1:8008) (uses `scripts/run-backend.mjs` to pick `python3` / `python` / `py -3`) |\n| `npm run dev` | **Vite + FastAPI** (browser UI + API for uploads) |\n| `npm run electron:dev` | **Vite + FastAPI + Electron** (desktop) |\n\n## Build\n\n```bash\nnpm run build\n```\n\nPreview the production build:\n\n```bash\nnpm run preview\n```\n\n## Python backend and map models\n\nThe FastAPI server under `backend/` reads **derived** JSON under `models/` (spacing profile, pattern model, `brain/dataset_brain.json`). Those files are **not** committed to Git; a fresh clone gets them automatically from Hugging Face when you run **`npm start`** (dataset [`icedmoca/beatmapmaker`](https://huggingface.co/datasets/icedmoca/beatmapmaker)) or anytime via **`npm run fetch-dataset`**.\n\nTo rebuild from your own ranked map zips (that you have the rights to use) instead of HF:\n\n1. Drop `*.zip` archives into `data/ranked_zips/`, or set `BEATMAPER_RANKED_ZIPS` to a folder of zips.\n2. Run `python3 analyze_ranked_spacing.py` then `python3 train_ranked_patterns.py` (after `pip install -r requirements.txt` in a venv if you use one).\n\nDetails: `data/README.md`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficedmoca%2Fbeatmaper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ficedmoca%2Fbeatmaper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficedmoca%2Fbeatmaper/lists"}