fix: studio save, memory and storage issues in multitrack recording

[Nowkoo]

Fixes bugs and performance problems found while reviewing the multitrack studio released in v3.3.0, focused on server-thread stalls, memory use and disk growth. One commit per topic.

Correctness

• Stopping a take no longer blocks the server thread. The final take uses the shared ordered writer, following any in-flight checkpoint and replacing obsolete queued snapshots; it stays in memory while it is written.
• Keeping a take uses the track's current volume and mute, not the mix captured when recording started.
• Reviewing a take recorded over a muted or zero-volume track plays the take. Listening to a mix or a track with nothing audible is refused instead of running silently.
• Stop cancels private samples (previews, backing tracks, metronome) already sent to the client. They now use the Players category; live instruments and jukeboxes keep Records and are not cut.
• One unreadable project file no longer breaks the library. It is skipped, logged once and left on disk; the player can still list, create, open and delete their other projects. A damaged active project leaves the player without an active one.
• A hopper taking a recording disc from a jukebox stops its song at once instead of at the next once-a-second check. Notes already sent end on their own: each note is short, and stopping a sound by name would also cut a live instrument playing the same sample.
• Studio files share a 32 MB read/write limit, checked before replacing the previous file.
• Delete confirmations capture the full immutable project and compare it again before deleting. Changes to notes, track mix, tempo, metronome or a pending take invalidate an older confirmation even when its title, track count and duration stay the same. Active projects use the latest cached content, including failed writes; archived projects read only the chosen song.

Server-thread time and memory

• Edits (volume, mute, tempo, metronome, title, keep, discard) apply to the cached project at once and are written in the background, in order, after the final take and older edits. They no longer wait for a take to finish saving. Each owner has at most one queued snapshot and shared completion future, besides the single snapshot currently being written. Further edits replace the queued snapshot; changes arriving during an in-flight save queue at the tail so other musicians can save first. Creating, opening and deleting projects still wait for queued writes, because they read or remove project files.
• Opening another project only rewrites the small selection file. Creating one no longer rewrites the previous project unless its last write failed.
• A failed write keeps the change in memory, tells the player, and is retried by the next change, every minute, on disconnect and on shutdown. Shutdown waits up to 30 seconds for queued writes. A transient failure first discovered during that drain is retried once on the writer if the shutdown deadline has not expired; persistent failures do not retry indefinitely.
• The library, /music projects and the 36-project limit read a per-owner library.index of project summaries instead of decoding every project (36 projects of 7,500 notes: about 1.9 s and 40 MB down to under 5 ms). Delete confirmations load only the requested project to check its full content.
• Decoded notes share one copy of each instrument and sample name (a 7,500-note project: about 1.11 MB to 0.22 MB of heap).
• Disconnect and shutdown write only unsaved projects, and a disconnect evicts the cached project.
• Jukebox playback reads the record once a second instead of copying the block state every tick. The jukebox click handler checks the block type before getState().
• ItemsAdder station lookups are cached, and are skipped entirely while ItemsAdder is not enabled. Before, an ia.* station without ItemsAdder made every right-click on any block fail a reflective class lookup.

Disk

• New compact file format 2: each track lists its instrument and sample names once and stores each note as one line. With a 6,000-note project on a development machine: 459 KB to 132 KB, save 31 ms to 7 ms, load 45 ms to 4 ms, edition load for a jukebox 40 ms to 3 ms, republishing unchanged music 72 ms to 5 ms.
• The selected project is no longer kept as a second full copy; projects/<owner>/selected holds its ID.
• Edition IDs are derived from their content, so republishing unchanged music reuses the earlier edition. Editions leave out muted, silent and empty tracks and silent notes, which playback never emits.
• New publish-cooldown-seconds (default 30) and max-editions-per-day (default 20, per player in any 24 hours, tracked in editions/<owner>.log) in studio.yml; 0 disables either. Republishing existing music does not count, and a refused publication keeps the disc.
• Startup removes studio-*.tmp files left by an interrupted write.

Behaviour changes

• No data migration: the studio only ran on TF Dev. Files written by 3.3.0 (format 1, and projects/<owner>.yml) are not read; format 1 files are logged and skipped. Older plugin versions cannot read format 2.
• Servers with an existing studio.yml use the default max-editions-per-day until the key is added.

Validation

• Java 21 mvn clean verify: 326 tests passed; 100% instruction and branch coverage, with no production exclusions.
• The damaged-file warning test checks for the expected file independently of filesystem enumeration order, so the same assertion works on Windows and Linux.
• Six save regressions cover 1,000 edits sharing one queued write, ordering and fairness across musicians, immutable in-flight snapshots, transient shutdown failures, persistent failures and an exhausted shutdown deadline.
• Thirteen deletion regression cases cover a real replacement recording of the same duration, individual note and mix changes, tempo, metronome, pending takes, archived projects and newer cached content after a failed write. The replacement-recording test reproduced the destructive failure before the fix and passes afterward.
• Earlier TF Dev protocol-bot checks were performed on a58a610. The latest save and deletion fixes (through 4b09d1f) were verified locally and have not been installed or activated on any server; bots have not been rerun on these commits.

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: bf745c2e-3194-436e-92dd-894b9b1c1867

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}