Feature Spec
Related feature document: docs/features/16-arrangement-clip-placement-and-playback.md
Goal
Allow users to place reusable clips on the SONG arrangement timeline and play the arranged song from transport controls.
Context
The app already has a PAT clip editor, a SONG arrangement UI shell, and a sidebar clip list. Users now need to drag clips from the sidebar into arrangement tracks, move placed clip instances, and hear the arrangement playback rather than only the selected clip loop.
This feature should build on the planned WAV audio clip import work so both hybrid clips and imported audio clips can eventually be placed in the arrangement.
Scope
Included:
- Make sidebar clips draggable into the arrangement timeline where practical.
- Create serializable
ClipInstance entries with clipId, trackId, startTick, and lengthTicks.
- Render arrangement clip blocks from project/app state instead of static demo blocks.
- Move existing clip instances horizontally and vertically by drag where practical.
- Select and delete placed clip instances.
- Snap dropped and moved clip instances to the arrangement grid.
- Add arrangement playhead display in
SONG mode.
- Make transport play/pause/resume/stop operate on arrangement playback in
SONG mode.
- Schedule placed hybrid clip drum/note events at arrangement tick positions.
- Schedule placed audio clips when audio clip runtime buffers are available.
- Add focused tests for model transformations, snapping, and scheduler event expansion where practical.
- Update relevant product, data model, audio, UI, and testing docs.
Excluded:
- Time stretching.
- Clip instance resize handles.
- Clip splitting.
- Arrangement recording.
- Track creation, deletion, or reordering.
- Multi-select, copy/paste, and duplicate shortcuts.
- Persistent project export/import beyond serializable in-memory state changes.
- IndexedDB persistence for imported audio bytes.
- Full mixer audio routing or effects.
Constraints
- React UI must not own exact audio timing.
- Store arrangement positions and lengths in ticks.
- Keep project data serializable.
- Do not store
AudioBuffer, File, Blob, object URLs, audio nodes, or scheduler timers in project JSON.
- Playback must schedule audio against
AudioContext.currentTime.
- Imported audio clips play at original speed unless a later time-stretching feature is added.
- Use CSS Modules and semantic design tokens for UI changes.
Done when
- Users can drag a sidebar clip into a
SONG arrangement track and see a placed clip block.
- Placed clip instances are backed by serializable model state.
- Users can move placed clip instances to another snapped time or track.
- Users can select and delete placed clip instances.
SONG transport playback schedules placed clip instances, not the selected PAT clip loop.- Pause/resume/stop behavior works in
SONG mode.
- A visual arrangement playhead follows playback and is hidden or reset appropriately when stopped.
- Hybrid clip events play at their arrangement positions.
- Audio clip instances play when their runtime sample data is available and fail clearly when imported file data is missing.
- Static demo arrangement clips are removed or replaced by seeded serializable state.
- Relevant docs and tests are updated.
Verification
Run:
npm run typechecknpm run lintnpm run testnpm run build
Manual check:
- Switch to
SONG mode.
- Drag a clip from the sidebar into an arrangement track.
- Confirm the clip appears at the snapped time and correct track.
- Drag the placed clip to another time and track.
- Delete the placed clip.
- Place multiple clips and press play.
- Confirm arrangement playhead movement roughly matches audible playback.
- Confirm pause/resume/stop behavior in
SONG mode.
- Confirm
PAT mode playback still works.
Notes
This feature depends on the clip list and arrangement shell already existing. Imported audio clip placement should be implemented after or alongside the WAV import feature; if WAV import is not ready, the implementation should keep the audio-clip path clearly guarded.
Feature Spec
Related feature document:
docs/features/16-arrangement-clip-placement-and-playback.mdGoal
Allow users to place reusable clips on the
SONGarrangement timeline and play the arranged song from transport controls.Context
The app already has a
PATclip editor, aSONGarrangement UI shell, and a sidebar clip list. Users now need to drag clips from the sidebar into arrangement tracks, move placed clip instances, and hear the arrangement playback rather than only the selected clip loop.This feature should build on the planned WAV audio clip import work so both hybrid clips and imported audio clips can eventually be placed in the arrangement.
Scope
Included:
ClipInstanceentries withclipId,trackId,startTick, andlengthTicks.SONGmode.SONGmode.Excluded:
Constraints
AudioBuffer,File,Blob, object URLs, audio nodes, or scheduler timers in project JSON.AudioContext.currentTime.Done when
SONGarrangement track and see a placed clip block.SONGtransport playback schedules placed clip instances, not the selectedPATclip loop.SONGmode.Verification
Run:
npm run typechecknpm run lintnpm run testnpm run buildManual check:
SONGmode.SONGmode.PATmode playback still works.Notes
This feature depends on the clip list and arrangement shell already existing. Imported audio clip placement should be implemented after or alongside the WAV import feature; if WAV import is not ready, the implementation should keep the audio-clip path clearly guarded.