DEV Community: Giang Pham Truong

An MXL Archive's First XML File May Not Be the Score

Giang Pham Truong — Mon, 09 Nov 2026 02:21:30 +0000

I make Pianory, a browser piano learning and practice app. AI helped draft this article; I checked the code and focused test results described below against the repository.

A compressed MusicXML (.mxl) file is a ZIP archive. Choosing the first .xml entry can silently load the wrong document if the archive has metadata or a decoy file before the score. The archive's declared root file is the stronger signal.

Pianory first lists the archive entries. If META-INF/container.xml exists, the extractor reads its rootfile tags, takes a full-path ending in .musicxml or .xml that actually exists in the archive, and uses the first matching declaration. Only when that does not yield a usable path does it fall back to the first MusicXML-named entry outside META-INF. If there is no candidate or the selected entry cannot be read, it throws an invalid-archive error. The extracted text then passes through the supported-score check.

The regression fixture makes the mistake concrete: it puts aaa-decoy.xml in the archive before scores/elise.musicxml, while container.xml declares scores/elise.musicxml. The test asserts that both the extractor and the file reader return the declared piano score, not the decoy. A separate fixture checks the fallback when no usable manifest path is present, and another checks rejection of an archive without a score.

I ran pnpm exec vitest run src/lib/music/musicxml-file.spec.ts: 16 focused tests passed. Those tests cover the archive shapes in the fixtures. They do not establish compatibility with every MXL producer. The broader design lesson is to let a format's manifest choose the entry, then test with an earlier file that looks plausible but is wrong.

Source: src/lib/music/musicxml-file.ts and src/lib/music/musicxml-file.spec.ts in the Pianory repository.

Bound a Finite Music Loop at the Scheduler

Giang Pham Truong — Sun, 08 Nov 2026 02:11:59 +0000

I make Pianory. AI helped draft this article; I checked the code paths and focused tests described here against the repository.

A player can stop its UI at the end of a finite loop while a long note or a scheduled metronome click still extends past the passage boundary. That makes the loop boundary a scheduling rule, not just a transport-state rule.

Pianory's score player computes the end quarter for a passage. For a finite loop, it caps each scheduled note's end quarter at that passage end and caps its audio duration to the remaining time. The metronome path likewise caps clicks at the boundary. When the configured repetition budget is spent, the scheduler does not append another passage anchor and finishes playback.

A focused deterministic test uses a short one-pass loop with metronome enabled. It checks that one note is scheduled, that the note ends within the passage boundary, that every click stops within it, and that the player reaches stopped status. Other tests cover one and two passes, preserving a tempo map across a full-score repeat, and changing a live loop without replaying the next onset.

The useful contract is that a finite passage limits every scheduled sound-producing event, even if an event would naturally last longer. The tests use a fake audio rig and check scheduler outputs. They do not establish how a physical audio device sounds or prove browser playback under every timing condition.

Source: src/lib/sheet/player.ts and src/lib/sheet/player.spec.ts in the Pianory repository.

Treat MIDI Device Removal as Input-State Cleanup

Giang Pham Truong — Sat, 07 Nov 2026 02:17:08 +0000

I make Pianory. AI helped draft this article; I checked the code paths and focused tests described here against the repository.

A MIDI keyboard can disappear while a note or sustain pedal is held. Treating that as only a device-list update leaves the input controller’s note state behind. The controller needs to release tracked state before it forgets the old port.

In Pianory’s Web MIDI input controller, active notes are tracked by channel and pitch, and sustain state by channel. When the selected input disappears during a state change, the controller detaches it with cleanup. The cleanup emits sustain-off events before note-offs, removes the message listener, and closes the port. This ordering gives downstream consumers explicit release events instead of relying on a future message from hardware that is no longer connected.

A focused hot-plug test checks that removing the selected input reports an empty device list, emits sustain-off then note-off, and ignores messages from that removed input afterward. Separate coverage checks MIDI All Sound Off, Reset Controllers, and All Notes Off.

The practical contract is: any path that stops listening to an input must settle the state that input created. Test removal with a held note and pedal, not only an idle port. The hot-plug test checks release events and ignores later messages from the removed input. Listener removal and port closure are visible in the source, but that test does not directly assert those calls. None of this proves that every physical audio device stops sounding.

Source: src/lib/input/midi.ts and src/lib/input/midi.spec.ts in the Pianory repository.

Keep Quarter-Beat Time When a Score Has Eighth Notes

Giang Pham Truong — Wed, 04 Nov 2026 02:16:55 +0000

I build Pianory, a browser-based piano practice app. AI helped draft this article; I checked its code claims against the current source.

A score can contain a quarter note on beat 1, two eighth-note attacks within beat 2, and quarters on beats 3 and 4. Playback needs to keep one unit for the musical positions and convert to seconds only when scheduling audio. Otherwise a faster note value can accidentally change the click pulse.

Consider this illustrative 4/4 bar: C4 quarter, D4 eighth, D4 eighth, E4 quarter, F4 quarter. In quarter-note units the inferred event starts and lengths are (0, 1), (1, 0.5), (1.5, 0.5), (2, 1), and (3, 1). The two D4 notes are distinct attacks at different positions. This tuple sequence is an example derived from the conversion, not a committed test fixture.

Pianory's score source converts OSMD iterator timestamps and note lengths by multiplying whole-note units by four. Its timeline stores positions and durations in quarter-note units. At quarter-note tempo B, a quarter lasts 60/B seconds and an eighth lasts 30/B seconds. The metronome grid for a complete 4/4 measure still walks quarter positions 0, 1, 2 and 3, with the first beat accented. The player schedules each note at its converted audio time and uses a 96% written-duration sounding length, subject to a 0.06-second floor and passage-end clipping. That small articulation gap does not move the next note's written onset.

I ran pnpm exec vitest run src/lib/sheet/player.spec.ts src/lib/sheet/timeline.spec.ts: 2 files, 39 tests passed. The tests cover quarter onsets, count-in and neighboring duration behavior, but do not assert this exact eighth-note bar or .5 duration. A useful follow-up test would assert both D4 attacks at quarter positions 1 and 1.5 while the click positions remain 0, 1, 2 and 3. That is a source-based expectation, not a measured audio-device result.

Relevant source: src/lib/sheet/types.ts, src/lib/sheet/osmd-source.ts, src/lib/sheet/timeline.ts and src/lib/sheet/player.ts.

Let the Score Meter Set the Count-In, Not Just the Label

Giang Pham Truong — Tue, 03 Nov 2026 02:17:13 +0000

I build Pianory, a browser-based piano practice app. AI helped draft this article; I checked the implementation claims against the current source.

A 2/4 score has two quarter-note beats per complete bar. If the player displays 2/4 but schedules four count-in clicks, the entrance cue contradicts the score. The meter needs to reach the click scheduler, not just a label.

In Pianory's score adapter, each measure contributes its active time signature. If the source has none, the adapter falls back to [4, 4]. The timeline converts a signature into a beat count and the length of each beat in quarter-note units. For [2, 4], the conversion is { beats: 2, beatQuarters: 1 }. Each measure span stores that result.

The click grid steps through a measure by beatQuarters and marks the first beat of a complete bar as accented. Pickups are handled separately: a short opening measure aligns its clicks from the end of that measure rather than pretending it is full length. The player looks up the span at its playback start, schedules beatsInBar count-in clicks, and delays the first note by beatsInBar × countInBeatSeconds. For a complete 2/4 span, that means two count-in clicks before music begins.

I ran pnpm exec vitest run src/lib/sheet/timeline.spec.ts src/lib/sheet/player.spec.ts: 2 files and 39 tests passed. The existing specs cover neighboring meter and count-in cases, but they do not explicitly assert [2, 4]. A focused regression test should construct a complete 2/4 measure, assert two count-in clicks, and check that music begins after two beat intervals. The passing suite is evidence for the tested behavior, not proof of that missing 2/4 case or of real-device audio timing.

Source files: src/lib/sheet/osmd-source.ts, src/lib/sheet/timeline.ts, and src/lib/sheet/player.ts. The useful contract is simple: carry the score's meter all the way to the audible cue.

Let Course Progress Follow Evidence, Not Session Endings

Giang Pham Truong — Mon, 02 Nov 2026 02:55:47 +0000

I build Pianory, a browser-based piano practice app. AI helped draft this article; I checked every implementation claim against the current course source and focused spec file.

A finished player session tells you that playback ended. It does not, by itself, tell you that a course step met its completion rule. In Pianory’s course domain model, progress is tied to the evidence each step asks for.

courseAttemptMeetsPolicy first requires a completed attempt with evidence. It then applies the step’s rule: a self-report needs the configured rating, pass count, and criteria, plus any configured delayed-review requirement; a quiz needs the minimum total and correct answers; measured evidence needs a passing observation with supported input, enough confidence, and the matching capability and benchmark version.

advanceCourseEnrollment also checks that the attempt matches the active enrollment, pinned course version, current step, and phase. An ordinary partial result increments the revision while keeping the learner on the same cursor. A stuck self-report can enter an explanation phase only when that step has a configured recovery branch. A skip is different: it can advance the cursor, while its immutable attempt remains labeled skipped.

There is a persistence boundary too. commitCourseEnrollment writes the progress snapshot and immutable attempt in one IndexedDB readwrite transaction; for signed-in accounts it also queues the sync operation in that transaction. Replaying the same attempt id with identical evidence is a no-op. Reusing it with different evidence conflicts.

The focused course-journey spec includes cases for quiz evidence, partial attempts, and explicit skips. This article describes source and spec behavior; I did not run the test suite today, and these rules do not establish a learner outcome or prove every remote sync scenario. Sources: src/lib/domain/course.ts, src/lib/domain/course-journey.ts, src/lib/client/storage/index.ts, and src/lib/domain/course-journey.spec.ts.

Paginate an Append-Only Sync Feed with a Fixed Snapshot Boundary

Giang Pham Truong — Sun, 01 Nov 2026 02:23:56 +0000

I build Pianory, a browser-based piano practice app. AI helped draft this article; I checked the claims against the course-ledger client, server handler and focused tests.

A course-attempt ledger can grow while a client is fetching more than one page. If every page treats the latest row as its endpoint, a new attempt can enter halfway through the pull. For this append-only feed, we keep two sequence values with different jobs: after marks progress, while through fixes the upper bound for one traversal.

The server selects rows with sequence > after and sequence <= through. It fetches one row beyond the requested page size to decide hasMore, then returns an advancing cursor. The client carries the same through value on later pages and rejects a changed upper bound or a page that does not advance.

The tests make the boundary concrete. In the client test, a sequence 104 is appended while the current traversal covers 1–103; the current pull ends at 103. In the server API test, five attempts added after the initial bound are excluded from that traversal, while a fresh traversal can see the later bound. pnpm exec vitest run src/lib/client/course-ledger.spec.ts src/lib/server/api/course-ledger.spec.ts passed 15 tests in two files on 1 November 2026.

This is a bounded design choice for Pianory's append-only course-attempt ledger, not a universal database snapshot guarantee. The focused client transport and server test harness verify these cases; they do not measure production sync latency or every deployment's concurrency behavior. Source: src/lib/client/course-ledger.ts, src/lib/server/api/course-ledger.ts, and their focused specs.

Keeping Browser Recordings Compatible in IndexedDB

Giang Pham Truong — Sat, 31 Oct 2026 02:12:21 +0000

I build Pianory, a browser-based piano practice app. AI helped draft this article; I checked the claims against the recording-store source and its focused tests.

A browser recording can have metadata and audio bytes that need to move together. Our IndexedDB store saves the audio as an ArrayBuffer and reconstructs a Blob when reading it. The code also accepts legacy rows whose audio was stored as a Blob, so an older local recording remains readable through that path.

The save path obtains the bytes before opening the transaction. Then it puts metadata and audio in one readwrite transaction. On quota failure, the transaction aborts instead of leaving a metadata row that points to missing audio. This is a practical boundary: asynchronous byte conversion should not stretch the lifetime of an IndexedDB transaction.

The tests cover save, read and export behavior, plus a quota failure that leaves no metadata row. pnpm exec vitest run src/lib/recordings/store.spec.ts src/lib/input/detector.spec.ts passed 11 tests in two files on 31 October 2026. These mocked-storage tests support the round-trip and rollback claims; they do not independently reproduce a Safari failure or prove behavior in every browser.

The product lesson is to define both the current storage format and the old rows you still need to read. Source: src/lib/recordings/store.ts and src/lib/recordings/store.spec.ts.

Counting Only Active Practice Time in a Browser

Giang Pham Truong — Fri, 30 Oct 2026 02:18:49 +0000

I build Pianory, a browser-based piano practice app. AI helped draft this article; I checked the behavior against the timer and timed-run source and its focused tests.

A practice timer should count time spent in the active session, not the whole interval since a tab was opened. Pianory's foreground timer reads performance.now() to compute elapsed milliseconds. A 250 ms interval asks for updates, but those ticks are not added as 250 ms chunks; the elapsed duration comes from the clock. The callback reports only when the whole-second count changes.

The page lifecycle matters. When the document becomes hidden or the page is leaving, the timed-practice component pauses the controller. A saved run with status running is restored as paused after reload. That avoids counting the time the browser was closed or in the background as active practice. One focused test runs for three seconds, hides the page for 60 seconds and still records only three seconds before resuming.

Each measured delta is applied to the current unfinished activity. The domain function rejects invalid deltas, caps elapsed time at the session budget and marks a run expired at that limit. A five-minute test reaches 300 seconds while the current activity remains unfinished; duration does not pretend to grade the playing or complete a learning goal.

Local storage can also change in another tab. Before writing, the controller compares the current stored string with the snapshot it loaded. If the value changed, it stops rather than silently overwriting that other state. This is conflict detection, not an atomic cross-tab lock. Tests cover storage failures and recovery as well.

The design lesson is to define what a timer measures and what it does not. The focused suite pnpm exec vitest run src/lib/components/practice/timed-run.spec.ts src/lib/components/stats/session-groups.spec.ts passed 10 tests on 30 October 2026. It verifies these units, not timing precision in every browser or a measured improvement in practice outcomes. Relevant source: src/lib/components/practice/timing.ts, timed-run.ts, TimedPracticeSession.svelte, and src/lib/domain/timed-session-run.ts.

Exact Beat Fractions for Pickup and Closing Bars

Giang Pham Truong — Thu, 29 Oct 2026 02:23:09 +0000

I build Pianory, a browser-based piano learning app. AI helped draft this article; I checked the claims against src/lib/domain/course-timeline.ts and its focused test suite.

A score import needs a stable representation of musical time. In Pianory's course timeline domain contract, beat positions and durations are rational quarter-note values, rather than floating-point estimates. The fraction helper requires a reduced numerator and denominator, so equivalent values have one canonical form.

Comparison uses BigInt cross-products. That matters when numerator times denominator exceeds JavaScript's safe-integer range: rounding could make two distinct beat positions appear equal or reverse their order. The focused tests include such a large-integer comparison and reject noncanonical fractions.

Pickup measures create a second edge case. An opening partial measure does not mean every later bar may be partial. The validator accepts a final partial bar when it exactly complements the opening pickup in the same meter. It rejects duration combinations that do not satisfy that relationship. That is a domain rule for a score timeline, not a claim that every imported MIDI file has perfect notation.

The design lesson is to make the time unit and equality rule explicit before wiring import or playback adapters. A versioned JSON score contract with canonical fractions gives tests a precise target. pnpm exec vitest run src/lib/domain/course-timeline.spec.ts passed 8 tests on 29 October 2026. This focused check verifies the domain model and tests only; I did not trace every production import or playback path for this article.

Relevant source: src/lib/domain/course-timeline.ts and src/lib/domain/course-timeline.spec.ts.

A Recovery Branch That Keeps the Learner on the Same Step

Giang Pham Truong — Wed, 28 Oct 2026 02:15:52 +0000

I build Pianory, a browser-based piano learning app. AI helped draft this article; I checked the behavior against the current implementation and its focused tests.

A course step can be hard without being finished or abandoned. Our course journey models that case with a recovery branch attached to the original step. The important invariant is that help changes the active activity, while the learner's step identity remains stable.

The branch is deliberately narrow. A partial attempt with a self-report rating of stuck can enter recovery only when the authored step has a recovery path and the cursor is in the original or retest phase. A failed quiz alone does not trigger it. When the condition matches, the enrollment cursor keeps its stepId and preset, adds the recovery branchId, and changes phase to explanation.

courseActiveStep resolves the explanation phase to an authored lesson and the drill phase to an authored drill. Both are temporary activities under the original step. Passing the explanation moves to the drill; passing the drill moves to a retest of the original task. A failed recovery quiz keeps the learner in its current phase. The original completion policy, rather than the helper quiz, decides whether the course step is complete.

This is a useful state-machine boundary: the learner can ask for help and return to the same passage rather than losing their place or silently advancing. In course-journey.spec.ts, the recovery case checks preservation of step and preset, a failed explanation quiz, and the return to the original passage. The focused suite passed 11 tests on 28 October 2026. A separate browser test describes recovery surviving a reload; I did not rerun that end-to-end test for this article.

The limitation is as important as the path. This behavior applies to steps with an authored recovery path and an explicit stuck self-report. It is not a general promise that every failed attempt automatically selects a lesson.

Implementation: src/lib/domain/course-journey.ts (courseActiveStep and attempt transition), with the focused test in src/lib/domain/course-journey.spec.ts. The design lesson for me is to make help a reversible route through the original task, with the transition conditions visible in tests.

When a Sustained MIDI Note Meets the Next Onset

Giang Pham Truong — Tue, 27 Oct 2026 02:07:51 +0000

A MIDI file can contain note events that overlap in time. A readable score needs a voice model, and that model makes choices about which overlaps it can represent. Pianory's MIDI-to-MusicXML converter currently builds one notation voice per hand. This article describes that constraint and a test that makes it visible.

Within a hand, notes sharing the same start are grouped into one chord. The converter sorts those starts, inserts a rest when the next start is later than the current cursor, and limits each group's written length to the next onset in that hand. Even when an input note sustains longer, the generated one-voice score can end it at that next onset. This keeps the measures filled consistently, but it does not preserve independently overlapping voices within the same hand.

The focused fixture is concrete. Three right-hand pitches, MIDI 60, 64 and 67, begin together at quarter 0 and last two quarters; the test expects C4, E4 and G4 in a chord. In the left hand, MIDI 48 begins at quarter 0 for four quarters and MIDI 55 begins at quarter 2 for two. The test states that the first left-hand whole note is cut where the next left-hand note starts, expects C3 then G3, and checks the measure sums.

This is an explicit notation tradeoff, not a statement that MIDI always means legato or that the output captures every overlapping line. If the product needs independent same-hand voices, the representation must change rather than hiding the overlap. I make Pianory. AI helped draft this article; I checked the claims against src/lib/music/midi.ts and src/lib/music/midi.spec.ts. On 27 October, pnpm test:unit -- --run src/lib/music/midi.spec.ts passed all 16 focused tests.