| Age | Commit message (Collapse) | Author |
|---|
|
Updated documentation:
README.md:
- Added waveform visualization to implemented features list
- Added section on loading audio waveform with usage instructions
- Documented wav_dump_backend integration: ./demo64k --dump_wav output.wav
- Added snap-to-beat and resize handles to feature list
- Updated Future Enhancements with music.track visualization
ROADMAP.md:
- Added Phase 2.5: Music.track Visualization & Overlay
- Detailed implementation plan for tracker score overlay
- Visual design specifications (colored bars, sample markers)
- Use case: Align visual sequences with tracker events
- Effort: 12-15 hours, Priority: MEDIUM
The timeline editor now has clear guidance on:
1. How to generate WAV files from demo64k for visual reference
2. Future feature: Display tracker patterns/samples for alignment
|
|
Added audio waveform feature for visual reference when placing sequences:
Features:
- Load Audio (WAV) button to upload audio files
- Waveform canvas displayed above timeline with 80px height
- Waveform scales with zoom (pixels per second)
- Auto-extends timeline to fit audio duration
- Clear Audio button to remove waveform
- Waveform uses Web Audio API for decoding
- Min/max amplitude visualization for better clarity
- Semi-transparent background with center line
UI:
- Waveform positioned above time markers
- Crosshair cursor for precision
- Cyan (#4ec9b0) waveform color matching editor theme
- Scrolls horizontally with timeline
No audio playback - visualization only for sequence placement assistance.
|
|
Added CSS to hide scrollbars on timeline container:
- scrollbar-width: none (Firefox)
- -ms-overflow-style: none (IE/Edge)
- ::-webkit-scrollbar { display: none } (Chrome/Safari/Opera)
Mouse wheel navigation still works, cleaner UI without visible scrollbars.
|
|
Implemented final UI improvements:
- Removed sequence info text (Start:, Priority)
- Removed 'Properties updated' message
- Auto-apply properties with oninput handlers
- Stack-order-based priority with Up/Down buttons
- Added 'Same as Above' toggle for = priority modifier
New functions: autoApplyProperties(), moveEffectUp(), moveEffectDown(), toggleSamePriority()
Task #57 Phase 1 complete: Interactive editor with drag-drop, resize handles, snap-to-beat, and stack-based priority.
handoff(Claude): Timeline editor Phase 1 feature-complete. All dragging bugs fixed, dynamic bounds working, stack-order priority operational. Ready for Phase 2 planning.
|
|
CRITICAL BUG FIX: Effect Start Time Jumping
Root Cause:
Line 788: const currentLeft = parseFloat(e.target.style.left) || 0;
Problem: e.target is what was CLICKED, not what has the listener
- Clicking effect div itself: e.target = effectDiv ✓
- Clicking <small> text inside: e.target = <small> ✗
- If e.target is <small>, it has no style.left property
- parseFloat(undefined) returns NaN, || 0 gives 0
- Wrong offset calculation → effect jumps on click!
The Fix:
Use e.currentTarget instead of e.target
- currentTarget = element with the event listener (always effectDiv)
- target = element that was actually clicked (could be child)
OLD: const currentLeft = parseFloat(e.target.style.left) || 0;
NEW: const currentLeft = parseFloat(e.currentTarget.style.left) || 0;
Why This Caused Intermittent Jumping:
- Click on effect body (not text) → e.target = effectDiv → works fine
- Click on effect text <small> → e.target = <small> → jumps!
- Appears random because depends on WHERE user clicks
Bug Fix #2: Left Handle Can Extend Past Sequence Start
Problem:
Math.max(0, ...) prevented negative effect start times
- Right handle could extend sequence rightward ✓
- Left handle COULDN'T extend sequence leftward ✗
- Inconsistent behavior
The Fix:
Remove Math.max(0, ...) constraint
Allow negative effect start times
OLD: effect.startTime = Math.max(0, Math.min(..., effect.endTime - 0.1));
NEW: effect.startTime = Math.min(newStartTime, effect.endTime - 0.1);
How It Works Now:
1. Drag left handle past sequence start
2. effect.startTime becomes negative (e.g., -2.0)
3. renderTimeline() calculates sequence bounds:
seqVisualStart = seq.startTime + min(effect.startTime)
= 10.0 + (-2.0) = 8.0
4. Sequence box extends leftward automatically!
Example:
Sequence at t=10s with effect [0.0, 5.0]
Drag left handle to t=8s:
- effect.startTime = 8.0 - 10.0 = -2.0 (relative)
- Sequence visual start = 10.0 + (-2.0) = 8.0 (absolute)
- Sequence box now starts at 8.0s ✓
Technical Details:
- e.currentTarget: Element that addEventListener was called on
- e.target: Deepest element that triggered the event
- Effect innerHTML has children: <handle><small><handle>
- Clicking text triggers event but e.target is <small>, not effectDiv
- This is a classic event delegation bug
Result: Both dragging and handles now work correctly!
|
|
Feature #1: Editable Sequence Names
- Added "Name" field to sequence property panel
- User can set custom sequence names (replaces generic "Sequence N")
- Name stored in seq.name property
- Persists in demo.seq file when saved
- Displays in large centered overlay on timeline
- Empty name falls back to "Sequence N" display
Property Panel:
[Name ] ← NEW: editable text field
[Start Time ]
[Priority ]
[Apply]
Usage: Select sequence → Edit name in property panel → Apply
Feature #2: Effect Resize Handles
- Added draggable handles at left/right edges of selected effects
- Left handle: Adjusts start time (end time fixed)
- Right handle: Adjusts end time (start time fixed)
- Handles only visible on selected effects
- Smooth dragging with snap-to-beat support
Visual Design:
- 6px wide teal handles (rgba(78, 201, 176, 0.8))
- Cursor: ew-resize (horizontal resize)
- Hover: Expands to 8px, full opacity
- z-index: 10 (above effect content)
- Border radius matches effect corners
Handle Dragging Algorithm:
1. Click handle → startHandleDrag(type: 'left'|'right')
2. mousemove → onHandleDrag:
- Calculate newTime from mouse position
- Apply snap-to-beat if enabled
- Convert to sequence-relative time
- If left handle: effect.startTime = min(newTime, endTime - 0.1)
- If right handle: effect.endTime = max(startTime + 0.1, newTime)
3. mouseup → stopHandleDrag
4. renderTimeline() → recalculates sequence bounds
Technical Details:
- Global state: isDraggingHandle, handleType
- Separate drag handlers from effect move
- Minimum effect duration: 0.1 seconds
- Prevents handle overlap (start < end enforced)
- Works with beat snapping when enabled
- Property panel updates in real-time
CSS:
.effect-handle {
position: absolute;
width: 6px;
height: 100%;
cursor: ew-resize;
display: none (only on .effect.selected)
}
Event Flow:
Click handle → stopPropagation (don't trigger effect drag)
↓
startHandleDrag → set isDraggingHandle, handleType
↓
mousemove → onHandleDrag → adjust start/end time
↓
mouseup → stopHandleDrag → cleanup
↓
renderTimeline → sequence bounds recalculate
↓
updateProperties → panel shows new times
User Experience:
- Select effect → handles appear at edges
- Drag left handle → shorten/lengthen from start
- Drag right handle → shorten/lengthen from end
- Visual feedback: effect resizes in real-time
- Sequence box adjusts to fit resized effect
- Property panel shows updated times immediately
|
|
Bug Fix #1: Effect Drag Offset Calculation
- Fixed erratic jumping when clicking/dragging effects
- Problem: dragOffset calculated from element edge, not timeline origin
- Old calculation:
dragOffset.x = e.clientX - rect.left (element-relative)
- New calculation:
dragOffset.x = e.clientX - timelineRect.left - currentLeft (timeline-relative)
- Now correctly accounts for element's current position on timeline
- Dragging feels natural, no unexpected jumps
Bug Fix #2: Effect Positioning Relative to Sequence
- Effects now correctly positioned relative to parent sequence
- Problem: Effects were using absolute timeline positions
- Old behavior: effect.startTime = newTime (absolute)
- New behavior: effect.startTime = newTime - seq.startTime (relative)
- Algorithm:
1. Calculate newTime from mouse position (absolute timeline)
2. Convert to relative: relativeTime = newTime - seq.startTime
3. Store relative time in effect
4. Rendering uses: seq.startTime + effect.startTime (absolute)
- Sequence bounds now update correctly after effect moves
Bug Fix #3: Property Panel Updates Trigger Re-render
- Property changes now properly update timeline visual
- Added updateProperties() call after renderTimeline()
- Ensures property panel shows calculated values
- Cascade of events after property change:
a) Update data model (sequence/effect properties)
b) renderTimeline() → recalculates sequence bounds
c) updateProperties() → refreshes property panel display
d) showMessage() → user feedback
- Sequence start/end bounds recalculate correctly
- Visual updates immediately reflect property changes
Technical Details:
- startDrag: dragOffset from timeline origin, not element
- onDrag: Convert absolute position to sequence-relative time
- applyProperties: Call both renderTimeline() and updateProperties()
- Sequence visual bounds: calculated dynamically during render
* seqVisualStart = seq.startTime + min(effect.startTime)
* seqVisualEnd = seq.startTime + max(effect.endTime)
Result: All three operations (drag, property edit, bounds calc) work correctly
|
|
Feature #1: Re-order Sequences by Time
- Added "🔄 Re-order by Time" button to controls
- Sorts sequences by startTime (ascending order)
- Preserves focus on currently active sequence
- Algorithm:
1. Store reference to current active sequence (lastActiveSeqIndex)
2. Sort sequences array: sequences.sort((a, b) => a.startTime - b.startTime)
3. Re-render timeline (recalculates _yPosition for all)
4. Find new index of previously active sequence
5. Scroll to its new Y position
6. Update lastActiveSeqIndex to new index
- Button enabled when file is loaded
- Shows success message after re-ordering
- Useful when sequences are added/moved out of order
Use Case:
Before: Seq2(10s), Seq0(0s), Seq1(5s) ← Out of order
After: Seq0(0s), Seq1(5s), Seq2(10s) ← Chronological order
Feature #2: 10% Viewport Slack for Visual Comfort
- Added headroom when calculating current time during scroll
- Previously: currentTime = scrollLeft / pixelsPerSecond
- Now: currentTime = (scrollLeft / pixelsPerSecond) + slack
- Slack = 10% of viewport width in time units
Benefits:
- Sequences don't get targeted when right at left edge
- More comfortable visual positioning
- Sequences become active when ~10% into viewport
- Prevents "edge hugging" during diagonal scroll
Example:
Viewport width: 1000px, pixelsPerSecond: 100
Slack = (1000 / 100) * 0.1 = 1.0 second
scrollLeft = 500px → currentTime = 5.0s + 1.0s = 6.0s
Sequence at 6.0s becomes active (not 5.0s)
Technical Details:
- viewportWidth = timelineContainer.clientWidth
- slack = (viewportWidth / pixelsPerSecond) * 0.1
- Applied before finding target sequence
- Works with any zoom level (pixelsPerSecond changes)
- Dynamic calculation on every wheel event
|
|
Bug Fix #1: Remove Current Time Indicator
- Removed vertical time indicator line (user feedback: didn't look good)
- Deleted .current-time-indicator CSS class
- Removed HTML element from timeline-container
- Cleaner visual appearance without the distracting line
Bug Fix #2: Dynamic Y Positioning to Prevent Overlap
- Sequences now use cumulative Y positioning instead of fixed spacing
- Previously: seqIndex * 80px (fixed spacing caused overlaps)
- Now: Accumulate Y position based on actual sequence heights
Algorithm:
1. Track cumulativeY starting at 0
2. Calculate each sequence height dynamically:
height = max(70, 20 + numEffects * 30 + 5)
3. Position sequence at cumulativeY
4. Store Y position in seq._yPosition
5. Increment: cumulativeY += height + 10px gap
6. Effects use seq._yPosition + offset
7. Scroll handler uses seq._yPosition for target
Example (3 sequences with different effect counts):
Before (overlap): After (no overlap):
Seq0: y=0, h=70 Seq0: y=0, h=70
Seq1: y=80, h=120 ✗ Seq1: y=80, h=120
Seq2: y=160 (hidden) Seq2: y=210, h=70 ✓
Technical Changes:
- Added cumulativeY tracking variable
- Added sequenceGap = 10px constant
- Sequences store _yPosition property
- Effects use seq._yPosition instead of seqIndex * 80
- Wheel scroll uses sequences[i]._yPosition
- Properly handles varying sequence heights
Result: Sequences never overlap, regardless of effect count
|
|
Visual Enhancements:
1. Current Time Indicator (Vertical Line)
- Faint vertical line shows current scroll position
- Fixed position at left: 80px with gradient fade
- Color: rgba(78, 201, 176, 0.6) (teal/cyan)
- Gradient: fades at top/bottom for smooth appearance
- pointer-events: none (doesn't block interaction)
- z-index: 100 (appears above timeline elements)
- Guides the eye during mouse wheel navigation
2. Sequence Flash Effect
- Brief highlight when active sequence changes
- 0.6s animation: bright glow → normal state
- Keyframe animation sequenceFlash:
* Start: box-shadow 20px glow, teal border
* End: normal 10px glow, blue border
- Triggers on lastActiveSeqIndex change
- Auto-removes class after 600ms
- Helps user track which sequence is now active
3. Taller Timeline View
- timeline-container: height = calc(100vh - 280px)
- min-height: 500px (prevents over-shrinking)
- Uses full vertical real estate
- Much less squished appearance
- Better utilization of screen space
- Accommodates more sequences in viewport
Technical Implementation:
- Added lastActiveSeqIndex global state variable
- Wheel handler detects sequence index changes
- querySelector to find sequence div and add flash class
- setTimeout removes flash class after animation
- Fixed positioning for time indicator
- Responsive height calculation for container
User Experience:
- Visual feedback during diagonal scrolling
- Clear indication of current time position
- Smooth flash draws attention to sequence changes
- More comfortable editing with taller view
- Better spatial awareness of timeline position
|
|
Enhancement: Smart Vertical Scrolling
- Mouse wheel now scrolls diagonally (horizontal + vertical)
- Automatically brings relevant sequence to top-left of viewport
- Follows the time-ordered cascade of sequences
Algorithm:
1. Scroll horizontally as before (timeline.scrollLeft += deltaY)
2. Calculate current time position (left edge of viewport)
currentTime = scrollLeft / pixelsPerSecond
3. Find closest sequence at that time:
- Last sequence that starts before or at currentTime
- Sequences sorted by startTime
4. Smooth scroll vertically to target sequence:
- targetScrollTop = seqIndex * 80px
- Smooth transition: scrollTop += diff * 0.3 (not instant jump)
User Experience:
- Scroll forward in time → later sequences move to top
- Scroll backward in time → earlier sequences move to top
- Creates natural "diagonal" navigation along timeline
- Top-left corner always shows the most relevant sequence
Example timeline:
Seq 0 (0s) ──────────────
Seq 1 (5s) ──────────────
Seq 2 (10s) ──────────────
Scroll to 7s → Seq 1 moves to top (it's active at that time)
Scroll to 12s → Seq 2 moves to top (it's active at that time)
This provides intuitive navigation through time-ordered sequences.
|
|
responsive layout
Bug Fix #1: Dynamic Sequence Start Time
- Sequences now dynamically adjust start position based on earliest effect
- Sequence box shrinks from left when effects move later in time
- Calculate visual bounds: min(effect.startTime) to max(effect.endTime)
- Sequence position: seq.startTime + minEffectStart
- Sequence width: maxEffectEnd - minEffectStart
- Time display shows actual visual start time, not fixed seq.startTime
- Eliminates empty space at sequence start when effects are delayed
Bug Fix #2: Mouse Wheel Horizontal Scroll
- Mouse wheel now scrolls timeline horizontally (natural navigation)
- Prevents default vertical scroll behavior on timeline container
- More intuitive than using horizontal scrollbar
- Smooth scrolling with deltaY mapped to scrollLeft
Bug Fix #3: Responsive Layout
- Container now uses 100% width (was: fixed 1400px max)
- Added window resize event listener to re-render timeline
- Body uses box-sizing: border-box for proper padding
- Timeline recalculates on browser window resize
- Works correctly when going fullscreen
Technical details:
- seqVisualStart = seq.startTime + Math.min(effect.startTime)
- seqVisualEnd = seq.startTime + Math.max(effect.endTime)
- Wheel event uses { passive: false } to allow preventDefault()
- Window resize debouncing not needed (renderTimeline is fast)
|
|
UX improvement:
- Sequence name now displays as large centered overlay (24px bold)
- Strong text shadow for readability over effect stack
- Fades out smoothly when mouse enters sequence box (0.3s transition)
- Fades back in when mouse leaves sequence box
- Small info text (time, priority) stays in top-left corner
Visual hierarchy:
- Default: Large sequence name visible, dominates the view
- On hover: Name fades away, effects become clearly visible
- Smooth 300ms opacity transition for polished feel
CSS implementation:
- .sequence-name: Centered absolutely, z-index 10, pointer-events none
- .sequence.hovered .sequence-name: opacity 0
- .sequence-info: Small text in corner, always visible
- Multi-layer text shadow for high contrast
JavaScript:
- mouseenter: Add 'hovered' class to trigger fade out
- mouseleave: Remove 'hovered' class to restore name
- Supports custom sequence names from demo.seq file
|
|
UI improvements:
- Properties panel now floats in top-right corner (fixed position)
- Added collapse/expand button for properties panel
- Panel slides out of view when collapsed, button appears to restore
- Effects now show only class name, full details on hover (tooltip)
- Tooltip shows: ClassName, Time, Priority, Args
- Effect bars reduced from 35px to 26px height (cleaner appearance)
- Effect spacing reduced from 40px to 30px (more compact stacking)
- Effects use flexbox centering for better text alignment
- Added hover highlight for better visual feedback
CSS changes:
- Properties panel: position fixed, z-index 1000, slide animation
- Collapse button appears at top-right when panel hidden
- Effects: single-line display with ellipsis overflow
- Improved padding and font sizing for compact effect bars
The properties panel is now always accessible without scrolling to the
bottom of the page, and effect bars are much cleaner while still showing
all information on hover.
|
|
Bugs fixed:
- Effects within sequences now stack vertically instead of overlapping
- Sequence height now dynamically adjusts based on effect count
- Effects positioned with proper 40px vertical spacing
Features added:
- Seconds/Beats toggle checkbox with BPM display
- Time markers show beats (0b, 1b, etc.) when in beat mode
- Snap-to-beat when dragging in beat mode
- Effect/sequence time labels show beats when enabled
- BPM tracking from loaded demo.seq file
The effect stacking bug was caused by all effects using the same vertical
position formula (seqIndex * 80 + 25). Fixed by adding effectIndex * 40
to stack effects properly. Sequences now grow in height to accommodate
multiple stacked effects.
|
|
Documentation improvements:
1. Added reference to doc/SEQUENCE.md in README
2. Added comment in parser pointing to format spec
3. Updated README with complete format examples including:
- Priority modifiers (+, =, -)
- Time notation (beats vs seconds)
- Optional sequence names
- BPM declaration
New feature task (Phase 1):
Task 1.2b: Priority Editing UI (HIGH PRIORITY, 6-8h)
- Edit sequence priority (0-9 for scene, 10+ for post-processing)
- Toggle effect priority modifiers (+/=/-)
- Visual priority indicators and z-order visualization
- Computed priority display
- Priority conflict warnings
Implementation details:
- Radio buttons for priority modifiers
- Up/down buttons for sequence priority
- Color-coded priority levels
- Priority badges on timeline items
- Automatic priority recalculation
Rationale:
Priority control is essential for proper render order and z-stacking.
Currently, priorities are shown but not easily editable. This task
makes priority a first-class editable property.
Updated effort estimates:
- Phase 1: 28-36 hours (was 22-28)
- Total: ~117-161 hours for full feature set
|
|
Fixed critical parsing bugs that prevented loading real demo.seq files.
Issues fixed:
1. Beat notation support: Parse '0b', '4b' as beats and convert to seconds
- Added BPM parsing from '# BPM 120' comments
- Helper function: parseTime() converts beats to seconds using BPM
2. Priority modifiers: Handle '+', '=', '-' modifiers correctly
- '+' increments priority
- '=' keeps same priority
- '-' decrements priority (for background effects)
- Store both absolute priority and modifier for round-trip
3. Inline comments: Strip comments from end of lines with '#'
- Effect lines like 'EFFECT + FlashEffect 0.0 1.0 # comment' now parse
4. Sequence names: Parse optional sequence names in quotes
- Format: SEQUENCE <time> <priority> "name" [end]
5. Updated serializer: Output correct format with modifiers
- Generate 'EFFECT + ClassName ...' instead of 'EFFECT ClassName ... priority'
- Preserve BPM comment in output
- Preserve sequence names
Parser now correctly handles:
- SEQUENCE 0b 0 → Start at beat 0, priority 0
- SEQUENCE 4b 0 → Start at beat 4 (2 seconds @ 120 BPM)
- EFFECT - FlashCubeEffect .2 3 → Background effect (priority -1)
- EFFECT + FlashEffect 0.0 1. → Normal effect (priority 0)
- EFFECT = GaussianBlur 0 8 → Same priority as previous
Testing: Load assets/demo.seq should now work correctly.
|
|
Created detailed roadmap for timeline editor future development.
Phase 1: Core Editing Features (HIGH PRIORITY)
- Snap-to-beat: Musical timing with BPM-based grid (4-6h)
- Create new effects: Modal dialog for adding effects (6-8h)
- Overlap detection: Visual warnings for conflicts (8-10h)
Total: 22-28 hours
Phase 2: Productivity Enhancements (MEDIUM PRIORITY)
- Undo/redo system with command pattern (10-12h)
- Multi-select & batch operations (12-15h)
- Copy/paste & duplication (6-8h)
- Keyboard shortcuts & navigation (4-6h)
Total: 38-51 hours
Phase 3: Advanced Features (LOW PRIORITY)
- Timeline playback indicator (4-6h)
- Templates & presets (8-10h)
- Search & filter (6-8h)
- Timeline comparison view (15-20h)
- Export formats (JSON, CSV, MD) (6-8h)
- Auto-save & local storage (4-6h)
Total: 51-74 hours
Implementation Details:
- Technical approach for each feature
- UI mockups and code snippets
- Effort estimates and dependencies
- Success metrics and design principles
Priority recommendation:
1. Snap-to-beat (makes musical timing easy)
2. Create effects (essential for productivity)
3. Overlap detection (prevents rendering bugs)
Total effort for full feature set: ~110-150 hours
The roadmap provides clear guidance for incremental development
while keeping the tool simple and self-contained.
|
|
Created a functional web-based timeline editor for demo.seq files.
Features implemented:
✅ Load/save demo.seq files via browser file API
✅ Visual Gantt-style timeline with time markers
✅ Drag & drop sequences and effects along timeline
✅ Properties panel for editing timing, priorities, arguments
✅ Zoom controls (10% - 200%)
✅ Add/delete sequences and effects
✅ Real-time statistics (sequence count, effect count, duration)
✅ Dark theme matching VSCode aesthetic
✅ Color-coded items (sequences blue, effects gray)
✅ Selection highlighting
Technical details:
- Pure HTML/CSS/JavaScript (no dependencies, no build step)
- ~600 lines in single self-contained HTML file
- Works offline, no backend needed
- Parser converts demo.seq text → JavaScript objects
- Serializer converts JavaScript objects → demo.seq text
Usage:
1. Open tools/timeline_editor/index.html in browser
2. Load assets/demo.seq
3. Drag items, edit properties
4. Save modified file
5. Copy to assets/demo.seq and rebuild
Limitations (acceptable for v1):
- No undo/redo yet
- No effect creation UI (must use properties panel)
- No overlap detection warnings
- No snap-to-grid
- No preview rendering (intentional - editor only)
This provides a quick way to experiment with demo timing without
recompiling, and better visualization of sequence/effect relationships.
Size: ~25KB (HTML + embedded JS/CSS)
Status: Task #57 basic implementation complete
|
|
SUMMARY
=======
Successfully completed comprehensive 4-phase refactor of audio subsystem to
eliminate fragile initialization order dependency between synth and tracker.
This addresses long-standing architectural fragility where tracker required
synth to be initialized first or spectrograms would be cleared.
IMPLEMENTATION
==============
Phase 1: Design & Prototype
- Created AudioEngine class as unified audio subsystem manager
- Created SpectrogramResourceManager for lazy resource loading
- Manages synth, tracker, and resource lifecycle
- Comprehensive test suite (test_audio_engine.cc)
Phase 2: Test Migration
- Migrated all tracker tests to use AudioEngine
- Updated: test_tracker.cc, test_tracker_timing.cc,
test_variable_tempo.cc, test_wav_dump.cc
- Pattern: Replace synth_init() + tracker_init() with engine.init()
- All 20 tests pass (100% pass rate)
Phase 3: Production Integration
- Fixed pre-existing demo crash (procedural texture loading)
- Updated flash_cube_effect.cc and hybrid_3d_effect.cc
- Migrated main.cc to use AudioEngine
- Replaced tracker_update() calls with engine.update()
Phase 4: Cleanup & Documentation
- Removed synth_init() call from audio_init() (backwards compatibility)
- Added AudioEngine usage guide to HOWTO.md
- Added audio initialization protocols to CONTRIBUTING.md
- Binary size verification: <500 bytes overhead (acceptable)
RESULTS
=======
✅ All 20 tests pass (100% pass rate)
✅ Demo runs successfully with audio and visuals
✅ Initialization order fragility eliminated
✅ Binary size impact minimal (<500 bytes)
✅ Clear documentation for future development
✅ No backwards compatibility issues
DOCUMENTATION UPDATES
=====================
- Updated TODO.md: Moved Task #56 to "Recently Completed"
- Updated PROJECT_CONTEXT.md: Added AudioEngine milestone
- Updated HOWTO.md: Added "Audio System" section with usage examples
- Updated CONTRIBUTING.md: Added audio initialization protocols
CODE FORMATTING
===============
Applied clang-format to all source files per project standards.
FILES CREATED
=============
- src/audio/audio_engine.h (new)
- src/audio/audio_engine.cc (new)
- src/audio/spectrogram_resource_manager.h (new)
- src/audio/spectrogram_resource_manager.cc (new)
- src/tests/test_audio_engine.cc (new)
KEY FILES MODIFIED
==================
- src/main.cc (migrated to AudioEngine)
- src/audio/audio.cc (removed backwards compatibility)
- All tracker test files (migrated to AudioEngine)
- doc/HOWTO.md (added usage guide)
- doc/CONTRIBUTING.md (added protocols)
- TODO.md (marked complete)
- PROJECT_CONTEXT.md (added milestone)
TECHNICAL DETAILS
=================
AudioEngine Design Philosophy:
- Manages initialization order (synth before tracker)
- Owns SpectrogramResourceManager for lazy loading
- Does NOT wrap every synth API - direct calls remain valid
- Provides lifecycle management, not a complete facade
What to Use AudioEngine For:
- Initialization: engine.init() instead of separate init calls
- Updates: engine.update(music_time) instead of tracker_update()
- Cleanup: engine.shutdown() for proper teardown
- Seeking: engine.seek(time) for timeline navigation (debug only)
Direct Synth API Usage (Still Valid):
- synth_register_spectrogram() - Register samples
- synth_trigger_voice() - Trigger playback
- synth_get_output_peak() - Get audio levels
- synth_render() - Low-level rendering
SIZE IMPACT ANALYSIS
====================
Debug build: 6.2MB
Size-optimized build: 5.0MB
Stripped build: 5.0MB
AudioEngine overhead: <500 bytes (0.01% of total)
BACKWARD COMPATIBILITY
======================
No breaking changes. Tests that need low-level control can still call
synth_init() directly. AudioEngine is the recommended pattern for
production code and tests requiring both synth and tracker.
handoff(Claude): Task #56 COMPLETE - All 4 phases finished. Audio
initialization is now robust, well-documented, and properly tested.
The fragile initialization order dependency has been eliminated.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
|
- Added test_image.tga (generated via tools/gen_test_tga.cc).
- Updated test_assets_list.txt to include the TGA.
- Updated test_assets.cc to verify image decompression and pixel values.
|
|
- Integrated stb_image for image decompression in asset_packer.
- Added GetTextureAsset helper in asset_manager.
- Updated procedural asset generation to include dimensions header for consistency.
- Updated test_assets to verify new asset format.
|
|
Improvements to seq_compiler Gantt chart visualization:
- Add optional sequence name support: SEQUENCE <start> <pri> ["name"] [end]
Names displayed in both ASCII and HTML Gantt charts for better readability
- Implement adaptive tick intervals based on demo duration:
* ≤5s: 1s intervals
* ≤40s: 2s intervals (fixes 32.5s demo from 5s to 2s)
* ≤100s: 5s intervals
* >100s: 10s+ intervals
- Sort sequences by start time in Gantt output for chronological visualization
- Add horizontal visual separators between sequences in both ASCII and HTML
- Update documentation (SEQUENCE.md) and quick reference (demo.seq)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
|
Fixes bug where all sequences appeared to run until demo end time instead
of their actual end times in Gantt chart visualizations.
Issue:
- Both ASCII and HTML Gantt generators initialized seq_end to max_time
- This caused all sequences to display full demo duration
- Example: SEQ@0s showed (0-36s) instead of actual (0-2s)
Fix:
- Initialize seq_end to seq_start instead of max_time
- Calculate actual end from effects or explicit [end_time]
- Sequences now show correct duration in visualizations
Before:
SEQ@0s [pri=0] (0-36s) # Wrong - shows full demo duration
SEQ@2s [pri=0] (2-36s) # Wrong
After:
SEQ@0s [pri=0] (0-2s) # Correct - shows actual sequence duration
SEQ@2s [pri=0] (2-5s) # Correct
This makes Gantt charts much more accurate for understanding actual
sequence overlap and timing relationships.
|
|
Simplifies effect priority management by using relative modifiers instead
of explicit numbers, making timeline reordering much more practical.
## New Priority System
Effects now use priority modifiers after EFFECT keyword:
- `+` increment priority by 1 (or start at 0 if first)
- `=` keep same priority as previous effect
- `-` decrement priority (or start at -1 if first, for background)
Old syntax:
```
EFFECT FlashEffect 0.0 0.5 0
EFFECT FadeEffect 0.1 0.3 1
EFFECT BgCube 0.2 3 -1
```
New syntax:
```
EFFECT - BgCube 0.2 3 # Priority -1 (background)
EFFECT + FlashEffect 0.0 0.5 # Priority 0
EFFECT + FadeEffect 0.1 0.3 # Priority 1
```
## Benefits
✓ Reordering effects no longer requires renumbering all priorities
✓ Priority relationships are explicit and relative
✓ File order matches render order (easier to understand)
✓ Same-priority effects clearly marked with `=`
✓ Background layers (-1) clearly marked with `-`
✓ Reduces errors when reorganizing timelines
## Implementation
- Updated seq_compiler to parse +/=/- modifiers
- Tracks current priority per sequence
- First effect sets base priority (0 or -1)
- Subsequent effects modify relative to previous
- Generated C++ code unchanged (still uses integer priorities)
## Changes to demo.seq
- All effects updated to use new syntax
- Effects reordered by priority within sequences
- Priority gaps removed (were likely unintentional)
- Comments updated to reflect new system
## Documentation
- Updated SEQUENCE.md with new syntax
- Added examples showing +, =, - usage
- Explained priority calculation rules
This makes timeline authoring significantly more maintainable, especially
when experimenting with different effect orderings during development.
|
|
Enhances seq_compiler with flexible output modes and beautiful HTML visualization.
## New Features
### 1. Optional C++ Output (Validation Mode)
- Output .cc file is now optional
- Running without output performs validation only
- Useful for checking .seq syntax before committing
- Example: `./seq_compiler assets/demo.seq`
### 2. HTML/SVG Gantt Chart
- New --gantt-html=<file.html> option
- Generates interactive HTML page with SVG timeline
- Much more readable than ASCII version
- Features:
* Color-coded sequences (blue) and effects (teal)
* Invalid time ranges highlighted in red
* Hover tooltips with full effect details
* Time axis with 5-second markers
* Dark theme matching IDE aesthetics
* Vertical time markers for easy reading
* Legend explaining visual elements
### 3. Flexible Command Line
All output modes can be combined:
```bash
# Validation only
./seq_compiler demo.seq
# Code + ASCII Gantt
./seq_compiler demo.seq timeline.cc --gantt=chart.txt
# Code + HTML Gantt
./seq_compiler demo.seq timeline.cc --gantt-html=chart.html
# All outputs
./seq_compiler demo.seq timeline.cc --gantt=t.txt --gantt-html=t.html
```
## HTML Gantt Advantages Over ASCII
✓ Precise pixel-perfect positioning
✓ Scalable vector graphics (zoom without quality loss)
✓ Color coding for priorities and validity
✓ Interactive hover tooltips
✓ Professional dark theme
✓ Much easier to read complex timelines
✓ Can be shared via browser or screenshots
## Implementation Details
- Added ~190 lines for HTML/SVG generation
- Dark theme (#1e1e1e background) matches IDE
- SVG dynamically sized based on sequence count
- Invalid time ranges rendered in red with warning symbol
- Time scale automatically calculated from demo duration
- Hover effects provide detailed information
## Use Cases
- **Validation**: Quick syntax check without code generation
- **ASCII Gantt**: Terminal-friendly, git-friendly text visualization
- **HTML Gantt**: Beautiful presentation for design discussions
- **Combined**: Full toolchain for timeline development
The HTML output answers your question about SVG generation - it turned out
to be straightforward (~190 lines) and provides significantly better
visualization than ASCII art!
## Files Changed
- tools/seq_compiler.cc: Added validation mode and HTML generation
- assets/demo.seq: Updated documentation with new usage examples
- .gitignore: Exclude generated timeline files
Example HTML output: 17KB file with full interactive timeline visualization.
|
|
Implements ASCII Gantt chart generation for timeline debugging and visualization.
## New Feature
- Added --gantt=<output.txt> flag to seq_compiler
- Generates visual timeline showing sequences and effects on time axis
- Displays sequence priority, effect priority, and time ranges
- Shows explicit sequence end times with [END=...] markers
- Detects and warns about invalid time ranges (end < start)
## Usage
```bash
./build/seq_compiler assets/demo.seq src/generated/timeline.cc --gantt=timeline.txt
```
## Chart Format
- Time axis in seconds with 5-second markers
- Sequences shown as solid bars (█)
- Effects shown as shaded bars (▓) with sequence background (·)
- Labels include start/end times and priorities
- Legend and documentation at chart end
## Example Output
```
Time (s): 0 5 10 15 20 25 30
|----|----|----|----|----|----|----|
SEQ@0s [pri=0]
████████████████████████████████ (0-30s)
FlashEffect [pri=4]
▓▓·························· (0-1s)
HeptagonEffect [pri=0]
▓▓▓▓▓▓▓▓▓▓▓▓················ (0-10s)
```
## Benefits
- Visualize sequence overlap and layering
- Identify timing conflicts and gaps
- Verify effect priorities render in correct order
- Debug invalid time ranges
- Plan demo choreography visually
## Files Changed
- tools/seq_compiler.cc: Added generate_gantt_chart() function
- assets/demo.seq: Added usage documentation
- .gitignore: Exclude generated demo_timeline.txt
This debugging tool significantly improves timeline development workflow
by providing visual feedback on sequence and effect timing.
|
|
This milestone implements several key enhancements to the sequencing system
and developer documentation:
## Optional Sequence End Times (New Feature)
- Added support for explicit sequence termination via [time] syntax
- Example: SEQUENCE 0 0 [30.0] forcefully ends all effects at 30 seconds
- Updated seq_compiler.cc to parse optional [time] parameter with brackets
- Added end_time_ field to Sequence class (default -1.0 = no explicit end)
- Modified update_active_list() to check sequence end time and deactivate
all effects when reached
- Fully backward compatible - existing sequences work unchanged
## Comprehensive Effect Documentation (demo.seq)
- Documented all effect constructor parameters (standard: device, queue, format)
- Added runtime parameter documentation (time, beat, intensity, aspect_ratio)
- Created detailed effect catalog with specific behaviors:
* Scene effects: HeptagonEffect, ParticlesEffect, Hybrid3DEffect, FlashCubeEffect
* Post-process effects: GaussianBlurEffect, SolarizeEffect, ChromaAberrationEffect,
ThemeModulationEffect, FadeEffect, FlashEffect
- Added examples section showing common usage patterns
- Documented exact parameter behaviors (e.g., blur pulsates 0.5x-2.5x,
flash triggers at intensity > 0.7, theme cycles every 8 seconds)
## Code Quality & Verification
- Audited all hardcoded 1280x720 dimensions throughout codebase
- Verified all shaders use uniforms.resolution and uniforms.aspect_ratio
- Confirmed Effect::resize() properly updates width_/height_ members
- No issues found - dimension handling is fully dynamic and robust
## Files Changed
- tools/seq_compiler.cc: Parse [end_time], generate set_end_time() calls
- src/gpu/effect.h: Added end_time_, set_end_time(), get_end_time()
- src/gpu/effect.cc: Check sequence end time in update_active_list()
- assets/demo.seq: Comprehensive syntax and effect documentation
- Generated files updated (timeline.cc, assets_data.cc, music_data.cc)
This work establishes a more flexible sequencing system and provides
developers with clear documentation for authoring demo timelines.
handoff(Claude): Optional sequence end times implemented, effect documentation
complete, dimension handling verified. Ready for next phase of development.
|
|
logging infrastructure
MILESTONE: Audio System Robustness & Debugging
Core Audio Backend Optimization:
- Fixed stop-and-go audio glitches caused by timing mismatch
- Core Audio optimized for 44.1kHz (10ms periods), but 32kHz expected ~13.78ms
- Added allowNominalSampleRateChange=TRUE to force OS-level 32kHz native
- Added performanceProfile=conservative for 4096-frame buffers (128ms)
- Result: Stable ~128ms callbacks, <1ms jitter, zero underruns
Ring Buffer Improvements:
- Increased capacity from 200ms to 400ms for tempo scaling headroom
- Added comprehensive bounds checking with abort() on violations
- Fixed tempo-scaled buffer fill: dt * g_tempo_scale
- Buffer maintains 400ms fullness during 2.0x acceleration
NOTE_ Parsing Fix & Sample Caching:
- Fixed is_note_name() checking only first letter (A-G)
- ASSET_KICK_1 was misidentified as A0 (27.5 Hz)
- Required "NOTE_" prefix to distinguish notes from assets
- Updated music.track to use NOTE_E2, NOTE_G4 format
- Discovered resource exhaustion: 14 unique samples → 228 registrations
- Implemented comprehensive caching in tracker_init()
- Assets: loaded once from AssetManager, cached synth_id
- Generated notes: created once, stored in persistent pool
- Result: MAX_SPECTROGRAMS 256 → 32 (88% memory reduction)
Debug Logging Infrastructure:
- Created src/util/debug.h with 7 category macros
(AUDIO, RING_BUFFER, TRACKER, SYNTH, 3D, ASSETS, GPU)
- Added DEMO_ENABLE_DEBUG_LOGS CMake option (defines DEBUG_LOG_ALL)
- Converted all diagnostic code to use category macros
- Default build: macros compile to ((void)0) for zero runtime cost
- Debug build: comprehensive logging for troubleshooting
- Updated CONTRIBUTING.md with pre-commit policy
Resource Analysis Tool:
- Enhanced tracker_compiler to report pool sizes and cache potential
- Analysis: 152/228 spectrograms without caching, 14 with caching
- Tool generates optimization recommendations during compilation
Files Changed:
- CMakeLists.txt: Add DEBUG_LOG option
- src/util/debug.h: New debug logging header (7 categories)
- src/audio/miniaudio_backend.cc: Use DEBUG_AUDIO/DEBUG_RING_BUFFER
- src/audio/ring_buffer.cc: Use DEBUG_RING_BUFFER for underruns
- src/audio/tracker.cc: Implement sample caching, use DEBUG_TRACKER
- src/audio/synth.cc: Use DEBUG_SYNTH for validation
- src/audio/synth.h: Update MAX_SPECTROGRAMS (256→32), document caching
- tools/tracker_compiler.cc: Fix is_note_name(), add resource analysis
- assets/music.track: Update to use NOTE_ prefix format
- doc/CONTRIBUTING.md: Add debug logging pre-commit policy
- PROJECT_CONTEXT.md: Document milestone
- TODO.md: Mark tasks completed
Verification:
- Default build: No debug output, audio plays correctly
- Debug build: Comprehensive logging, audio plays correctly
- Caching working: 14 unique samples cached at init
- All tests passing (17/17)
handoff(Claude): Audio system now stable with robust diagnostic infrastructure.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
|
Added tests for runtime error handling in Asset Manager (unknown function, generation failure). Updated asset_packer to warn instead of fail on unknown functions to facilitate testing. Increased coverage from 71% to 88%.
|
|
- Consolidated all WebGPU shims and platform-specific logic into src/platform.h.
- Refactored platform_init to return PlatformState by value and platform_poll to automatically refresh time and aspect_ratio.
- Removed STL dependencies (std::map, std::vector, std::string) from AssetManager and Procedural subsystems.
- Fixed Windows cross-compilation by adjusting include paths and linker flags in CMakeLists.txt and updating build_win.sh.
- Removed redundant direct inclusions of GLFW/glfw3.h and WebGPU headers across the project.
- Applied clang-format and updated documentation.
handoff(Gemini): Completed Task #20 and 20.1. Platform abstraction is now unified, and core paths are STL-free. Windows build is stable.
|
|
Critical Bug Fixes:
- Fixed pool exhaustion: Tracker slots never freed after use, music stopped
after 8 patterns. Implemented round-robin allocation with cleanup.
- Fixed note name parsing: Added automatic note-to-frequency conversion
in tracker_compiler. Bass and melody now play correctly.
- Fixed timing mismatch: Patterns are 2 seconds but triggered every 4 seconds,
causing silence gaps. Updated SCORE to trigger every 2 seconds.
Improvements:
- Implemented dynamic resource sizing in tracker_compiler: Analyzes score to
determine optimal MAX_VOICES/MAX_SPECTROGRAMS values.
- Created comprehensive rock track: 11 patterns with drums, bass, power chords,
and lead melody over 25 seconds.
- Added 213 lines of asset system documentation with 8 prioritized tasks.
Known Issues for next session:
- Audio quality could be improved (some artifacts remain)
- Note synthesis uses default parameters, needs tuning
- Pattern overlaps might cause voice exhaustion under heavy load
Files Changed:
- src/audio/tracker.cc: Round-robin pool allocation, cleanup logic
- tools/tracker_compiler.cc: Note name parser, resource usage analysis
- src/audio/synth.h: Increased limits to 16 based on analysis
- assets/music.track: 230-line rock arrangement
- doc/ASSET_SYSTEM.md: Comprehensive documentation + 8 tasks
- TODO.md: Updated with recent completions and known issues
handoff(Gemini): Music system now functional but needs quality improvements.
Audio artifacts and synthesis tuning remain. See TODO.md for details.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
|
Replaces the global array with which wraps a local static array. This ensures the asset table is initialized on first use, preventing crashes when other globals (like shader strings) try to access assets during dynamic initialization.
|
|
Updates asset_packer to align static asset arrays to 16 bytes and append a null-terminator. This allows assets to be safely reinterpreted as typed pointers (e.g., float*, const char*) without copying. Updates AssetManager documentation to reflect these guarantees.
|
|
|
|
|
|
- Implemented the basic tracker system with runtime support (tracker.h, tracker.cc).
- Added a sample music track file (assets/music.track).
- Created a tracker compiler tool (tools/tracker_compiler.cc) to generate music data.
- Updated CMakeLists.txt to build the tracker compiler and integrate generated data.
- Updated GEMINI.md to reflect new file locations and project context.
|
|
- Implemented dynamic resolution support in all shaders and effects.
- Added explicit viewport setting for all render passes to ensure correct scaling.
- Fixed 3D shadow mapping by adding PLANE support and standardizing soft shadow logic.
- Propagated resize events through the Effect hierarchy.
- Applied project-wide code formatting.
|
|
- Task #4b: Added scripts/check_all.sh to build and test all platform targets (native and Windows cross-compile) to ensure pre-commit stability.
- Task #10: Modified spectool to trim both leading and trailing silent frames from generated .spec files, reducing asset size.
|
|
- Added preprocessor definitions for 'WGPUOptionalBool_True' and 'WGPUOptionalBool_False' to ensure successful cross-compilation against the older wgpu-native headers used for the Windows build.
- This resolves the build failures in the Windows CI/check script.
|
|
- Task A: Centralized all generated code (assets, timeline) into a single directory to create a single source of truth.
- Task A: Isolated test asset generation into a temporary build directory, preventing pollution of the main source tree.
- Task B: Vertically compacted all C/C++ source files by removing superfluous newlines.
- Task C: Created a top-level README.md with project overview and file descriptions.
- Task D: Moved non-essential documentation into a directory to reduce root-level clutter.
|
|
- Replaced all global static variables in the platform layer with a single PlatformState struct.
- Updated all platform function signatures to accept a pointer to this struct, making the implementation stateless and more modular.
- Refactored main.cc, tests, and tools to instantiate and pass the PlatformState struct.
- This improves code organization and removes scattered global state.
|
|
- Fixed a 'squished' viewport bug on high-DPI (Retina) displays by querying the framebuffer size in pixels instead of using the window size in points.
- Centralized window dimension management within the platform layer.
- Added a '--resolution WxH' command-line option to allow specifying a custom window size at startup. This option is stripped in STRIP_ALL builds.
- Updated all test and tool executables to use the new platform API.
|
|
- Fixed test_sequence by restoring MainSequence::init_test for mocking.
- Corrected CMakeLists.txt dependencies and source groupings to prevent duplicate symbols.
- standardizing Effect constructor signature for seq_compiler compatibility.
- Implemented Hybrid3DEffect using bumpy Renderer3D and procedural NOISE_TEX.
- Updated MainSequence to support depth buffer for 3D elements.
- Formatted all source files with clang-format.
|
|
- Added depth buffer support to MainSequence.
- Implemented Hybrid3DEffect for the main timeline.
- Fixed effect initialization order in MainSequence.
- Ensured depth-stencil compatibility for all scene effects.
- Updated demo sequence with 3D elements and post-processing.
|
|
- Updated asset_packer to parse PROC(...) syntax.
- Implemented runtime dispatch in AssetManager for procedural generation.
- Added procedural generator functions (noise, grid, periodic).
- Added comprehensive tests for procedural asset lifecycle.
|
|
- Refactored asset manager to use a static array for caching, improving performance and memory efficiency.
- Updated asset_packer to correctly generate ASSET_LAST_ID for array sizing.
- Modified asset_manager.h to use a forward declaration for AssetId.
- Updated asset_manager.cc to use the conditional include for generated asset headers.
- Added a test case in test_assets to verify the array-based cache and ASSET_LAST_ID logic.
|
|
|
|
|
|
- Enabled AllowShortFunctionsOnASingleLine: All
- Enabled AllowShortBlocksOnASingleLine: Always
- Enabled AllowShortIfStatementsOnASingleLine: Always
- Enabled AllowShortLoopsOnASingleLine: true
- Set MaxEmptyLinesToKeep: 1
- Applied formatting to all source files.
|
