Merge pull request #29 from boostcampwm-snu-2026-1/feat/23-sampler-advanced-sustain

feat: add sampler sustain playback

Author: britle20

PLANS.md

@@ -29,8 +29,7 @@ M1 should include:
 
 Use this section as the current execution order for agent work. Feature document numbering describes the planned product sequence, but actual issue order may change as dependencies, review feedback, or implementation risks become clearer.
 
-1. #26 Arrangement view UI shell -> `docs/features/11-arrangement-view-ui-shell.md` (PR in review)
-2. #23 Sampler for advanced sustain -> `docs/features/09-sampler-advanced-sustain.md`
+1. #23 Sampler for advanced sustain -> `docs/features/09-sampler-advanced-sustain.md` (PR in review)
 
 ## Planned Milestones
 

docs/audio-engine.md

@@ -74,15 +74,13 @@ Sample-based pitched playback should:
 - Use a gain envelope for attack and release.
 - Stop or release active voices when transport stops.
 
-The first Iowa Piano implementation should avoid sustain looping. The bundled one-second piano samples are not reliable loop-ready sustain samples yet, and early loop points can make long notes sound like repeated strikes. Iowa Piano notes should currently play the sample once from the configured start offset, then stop or naturally decay.
+The current Iowa Piano implementation uses the shared sampler sustain path. Iowa Piano zones include explicit `sustain` metadata with forward-loop points and an envelope. If that metadata is valid for the decoded buffer and note duration, the source node uses `loop = true`, `loopStart`, and `loopEnd`. If the metadata is missing, unsupported, or invalid, playback falls back to one-shot sample behavior.
 
-A future sampler sustain task may add explicit sustain metadata with `loopStartSeconds` and `loopEndSeconds`; if those values are present and valid, the source node may use `loop = true` with those loop points. Loop metadata is serializable instrument/sample metadata, but decoded buffers and active source nodes are runtime-only.
-
-Do not attempt automatic loop point detection in the first pass. If loop points are added later, update the explicit metadata and document the decision.
+Do not attempt automatic loop point detection in this pass. Loop points are explicit serializable metadata and should be tuned by editing the zone metadata or replacing sample material.
 
 Current Iowa Piano sample zones use explicit `sampleStartSeconds` offsets because the bundled one-second C4-C5 WAV files contain leading silence before the audible note attack. The engine should pass that value as the second argument to `AudioBufferSourceNode.start(when, offset)`.
 
-Current Iowa Piano sample zones intentionally omit sustain metadata, so the audio engine does not enable `AudioBufferSourceNode.loop` for Iowa Piano.
+Current Iowa Piano loop metadata is a pragmatic first pass for the bundled 5-second samples. It uses a late tail loop region so short notes and most 1-bar notes play the natural sample decay without looping, while longer notes can loop the quieter tail instead of repeating the audible attack portion. Some samples may still have weak sustain quality depending on their source material. The engine must reject unsafe loop metadata rather than clamp invalid values into a loop.
 
 The audio engine should load sample zones needed by selected note events before handing them to the lookahead scheduler. If a sample-based instrument has no zone for a note, the engine may fall back to `Default Synth` behavior for that note rather than storing any runtime fallback state in project data.
 
@@ -101,6 +99,7 @@ Sampler sustain should:
 - Keep musical event positions and durations in ticks and convert them to seconds only at scheduling time.
 - Validate loop metadata before enabling looping.
 - Fall back to one-shot sample playback when loop metadata is missing or invalid.
+- For one-shot sample playback, complete the release fade before the earlier of note end and the usable sample region end so the buffer does not end abruptly at non-zero gain.
 - Apply release behavior at note end, transport pause, and transport stop so sustained voices do not remain stuck.
 
 The first implementation should prefer explicit metadata over automatic analysis. Automatic loop point detection, visual loop point editing, velocity layers, round-robin selection, and full sampler preset management belong in later tasks.

docs/data-model.md

@@ -160,7 +160,7 @@ The `sustain` fields are serializable metadata. They describe how the runtime au
 
 The `sampleStartSeconds` field skips leading silence before note attack. `sampleEndSeconds`, sustain loop points, crossfade length, and envelope values are sample-local seconds because they describe positions or durations inside a sample, not musical event time.
 
-Current Iowa Piano sample zones intentionally omit `sustain` metadata. The samples play once from their configured start offsets and do not loop in the initial implementation. Advanced sampler sustain may add explicit loop metadata later if the loop points are tuned well enough to avoid repeated-strike artifacts.
+Current Iowa Piano sample zones include explicit `forward-loop` sustain metadata and basic envelope metadata for the bundled 5-second samples. The loop points use a late tail region so short notes can use the natural sample decay and longer notes avoid repeating the audible note attack. These fields are still serializable sample-zone data only. The runtime audio engine validates them against decoded buffer duration and note duration before enabling `AudioBufferSourceNode.loop`; invalid or unsupported metadata falls back to one-shot sample playback.
 
 ## Initial Piano Roll Implementation
 

docs/features/09-sampler-advanced-sustain.md

@@ -1,7 +1,7 @@
 # Feature: 09 Sampler Advanced Sustain
 
 ## Status
-Planned
+In Review
 
 ## Goal
 

docs/features/11-arrangement-view-ui-shell.md

@@ -1,7 +1,7 @@
 # Feature: 11 Arrangement View UI Shell
 
 ## Status
-In Review
+Done
 
 ## Goal
 
@@ -20,7 +20,7 @@ A Google Stitch prototype provides a visual reference for the arrangement view.
 - Fixed left track headers.
 - Scrollable grid with track lanes.
 - Demo clip blocks placed on the timeline.
-- Bottom scrollbar and zoom area.
+- Native horizontal scrolling for the timeline.
 
 The prototype uses Tailwind and includes layout issues, including track and clip alignment problems. Treat it as visual reference only.
 
@@ -36,7 +36,7 @@ Included:
 - Add fixed-width track headers.
 - Add a scrollable timeline grid with horizontal track lanes and vertical bar/beat lines.
 - Add a few static/demo clip blocks to communicate intended layout.
-- Add a bottom horizontal scrollbar or scrollbar-like visual area and zoom placeholder.
+- Keep native horizontal scrolling available when the timeline is wider than the viewport.
 - Keep track headers, grid rows, and clip blocks vertically aligned through shared row-height constants.
 - Keep ruler, grid columns, and clip left/width values horizontally aligned through shared timeline geometry constants.
 - Use CSS Modules and semantic design tokens.
@@ -52,7 +52,7 @@ Excluded:
 - Clip duplication, clip splitting, or clip creation in the arrangement.
 - Real audio clips or generated waveforms.
 - Track mute, solo, arm, or routing behavior beyond nonfunctional visual controls.
-- Arrangement zoom implementation beyond a visual placeholder.
+- Arrangement zoom implementation.
 - Tailwind installation, Tailwind config, Tailwind CDN, or Tailwind utility-class-heavy React markup.
 
 ## Constraints

docs/testing.md

@@ -38,6 +38,7 @@ Test files should use `*.test.ts` or `*.test.tsx`. Keep paths grouped by the pro
 
 ```text
 tests/unit/audio/lookahead-scheduler.test.ts
+tests/unit/audio/sampler-sustain.test.ts
 tests/unit/utils/tick-time.test.ts
 ```