README: lead with requirements and Docker, refresh for the editor #36

2026-10-15T17:05:59-07:00

dejima-agent commented

2026-10-15 17:05:59 -07:00

Summary generated by LLM agent

Refreshes the README for how songtrace is used now, ahead of publishing more widely, and fixes a sheet bug the new screenshot exposed.

README

The old README described "a CLI and minimal web UI" and told people to finish their charts in Yass or USDX. The new one is organised around running it with Docker and working in the web UI:

Intro: the repository description, then what it does and its eight stages in plain terms.
Requirements, up front:
- an NVIDIA GPU with CUDA: developed on a 12 GB card, Demucs alone takes about 3.7 GB, alignment holds a whole stretch of singing at once, and cards under 12 GB and CPU mode are untested
- Docker with the NVIDIA Container Toolkit
- your own Whisper server, since songtrace doesn't include one
- disk space for model weights and per-song working files
Quick start (Docker): includes mounting a game's song folder as output_dir, so finished songs land straight in the collection.
Reviewing and editing, then Rebuilding: the sheet, line breaks, the GRID bar, edits surviving rebuilds, REBUILD ALL FROM….
Reference sections: Configuration, Sharing the GPU, YouTube download failures, then Command line, now near the end, and Development.

It's about a fifth shorter than before despite the new Requirements section.

config.example.toml no longer sets creator = "brad", which every new user would have copied into their charts' #CREATOR. It's now a commented-out placeholder, and the code's default stays songtrace. The example Whisper host is now whisper.example, a reserved example name.

Screenshot

docs/images/webui.png now shows the note sheet. scripts/screenshot_webui.py seeds the featured song with syllables, a chart (for the beat grid and GRID bar), a pitch track with vibrato (for the curve) and a line break, and always scrolls to the review. Before, it gave every note the syllable "~" and wrote no chart.

Sheet fix: far line breaks

Since #35, the sheet widened its view to show the breaks either side of a line. Before an instrumental passage the break sits mid-gap, and in the screenshot's song that was about 15s away, which crushed the line's notes into a corner with their syllables piled on top of each other. The view now grows at most 3s past the line to show a break. A break further off is pinned to the edge, labelled "↵ →" or "← ↵" toward where it lies, and can still be dragged inward.

Checked in Chromium on a song with a 20s gap between lines: the notes kept a normal width (71px each), the break showed pinned on both lines, and dragging it inward saved it at 5.25s, marked as moved. No script errors.

Testing

Full suite passes, except test_version (needs the package installed). The two torch tests are left to CI, since this sandbox's torch install was lost in a restart.
21 Node tests pass.

**Summary generated by LLM agent** Refreshes the README for how songtrace is used now, ahead of publishing more widely, and fixes a sheet bug the new screenshot exposed. ## README The old README described "a CLI and minimal web UI" and told people to finish their charts in Yass or USDX. The new one is organised around running it with Docker and working in the web UI: - **Intro:** the repository description, then what it does and its eight stages in plain terms. - **Requirements, up front:** - an NVIDIA GPU with CUDA: developed on a 12 GB card, Demucs alone takes about 3.7 GB, alignment holds a whole stretch of singing at once, and cards under 12 GB and CPU mode are untested - Docker with the NVIDIA Container Toolkit - your own Whisper server, since songtrace doesn't include one - disk space for model weights and per-song working files - **Quick start (Docker):** includes mounting a game's song folder as `output_dir`, so finished songs land straight in the collection. - **Reviewing and editing, then Rebuilding:** the sheet, line breaks, the GRID bar, edits surviving rebuilds, REBUILD ALL FROM…. - **Reference sections:** Configuration, Sharing the GPU, YouTube download failures, then Command line, now near the end, and Development. It's about a fifth shorter than before despite the new Requirements section. `config.example.toml` no longer sets `creator = "brad"`, which every new user would have copied into their charts' `#CREATOR`. It's now a commented-out placeholder, and the code's default stays `songtrace`. The example Whisper host is now `whisper.example`, a reserved example name. ## Screenshot `docs/images/webui.png` now shows the note sheet. `scripts/screenshot_webui.py` seeds the featured song with syllables, a chart (for the beat grid and GRID bar), a pitch track with vibrato (for the curve) and a line break, and always scrolls to the review. Before, it gave every note the syllable "~" and wrote no chart. ## Sheet fix: far line breaks Since #35, the sheet widened its view to show the breaks either side of a line. Before an instrumental passage the break sits mid-gap, and in the screenshot's song that was about 15s away, which crushed the line's notes into a corner with their syllables piled on top of each other. The view now grows at most 3s past the line to show a break. A break further off is pinned to the edge, labelled "↵ →" or "← ↵" toward where it lies, and can still be dragged inward. Checked in Chromium on a song with a 20s gap between lines: the notes kept a normal width (71px each), the break showed pinned on both lines, and dragging it inward saved it at 5.25s, marked as moved. No script errors. ## Testing - Full suite passes, except `test_version` (needs the package installed). The two torch tests are left to CI, since this sandbox's torch install was lost in a restart. - 21 Node tests pass.

dejima-agent added 2 commits 2026-10-15 17:05:59 -07:00

webui: keep a far line break from stretching the sheet 95ca68cc59

Since breaks could be moved, the sheet widened its window to show the
breaks either side of a line. Before an instrumental passage the break
sits mid-gap, sometimes 15s away, so the line's notes were crushed into
a corner of the sheet. The window now grows at most 3s past the line to
show a break; one further off is pinned to the edge, labelled with an
arrow toward where it lies, and still drags inward.

README: lead with requirements and Docker, refresh for the editor

tests / test (pull_request_target) Successful in 4m50s

Details

0147386f8e

The README described a CLI with a minimal web UI and told people to fix
charts in Yass. Rewrite it around how songtrace is used now: what it
does, its requirements up front (an NVIDIA GPU, tested on 12 GB, Docker
with the NVIDIA Container Toolkit, a Whisper server of your own, disk for
models and per-song files), a Docker quick start including writing songs
straight into a game's collection, then reviewing, editing and
rebuilding in the web UI. The command line moves near the end.

Regenerate the screenshot to show the note sheet: the screenshot script
now seeds the featured song with syllables, a chart, a pitch track and a
line break, and always scrolls to the review. The example config no
longer sets a real person as #CREATOR, and uses a reserved example host
for Whisper.

branderson approved these changes 2026-10-15 17:21:41 -07:00

branderson merged commit 24de04f6c6 into main

2026-10-15 17:21:45 -07:00

dejima-agent referenced this issue from a commit

2026-10-15 17:44:42 -07:00

Merge pull request 'README: lead with requirements and Docker, refresh for the editor' (#36) from readme-refresh into main

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: branderson/songtrace#36