| Age | Commit message (Collapse) | Author |
|---|
|
Implement C++ runtime foundation for procedural audio tracing tool.
Changes:
- Created spectral_brush.h/cc with core API
- Linear Bezier interpolation
- Vertical profile evaluation (Gaussian, Decaying Sinusoid, Noise)
- draw_bezier_curve() for spectrogram rendering
- Home-brew deterministic RNG for noise profile
- Added comprehensive unit tests (test_spectral_brush.cc)
- Tests Bezier interpolation, profiles, edge cases
- Tests full spectrogram rendering pipeline
- All 9 tests pass
- Integrated into CMake build system
- Fixed test_assets.cc include (asset_manager_utils.h)
Design:
- Spectral Brush = Central Curve (Bezier) + Vertical Profile
- Enables 50-100x compression (5KB .spec to 100 bytes C++ code)
- Future: Cubic Bezier, composite profiles, multi-dimensional curves
Documentation:
- Added doc/SPECTRAL_BRUSH_EDITOR.md (complete architecture)
- Updated TODO.md with Phase 1-4 implementation plan
- Updated PROJECT_CONTEXT.md to mark Task #5 in progress
Test results: 21/21 tests pass (100%)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
|
Updated documentation to reflect completed build system improvements:
TODO.md:
- Moved Task C to 'Recently Completed (February 6, 2026)' section
- Documented header split (asset_manager_dcl/core/utils)
- Documented asset dependency tracking (42 demo + 17 test assets)
- Noted 58% performance improvement and critical correctness bug fix
- Removed Task C from 'Critical Fixes' section (completed)
PROJECT_CONTEXT.md:
- Added 'Milestone: Build System Optimization (February 6, 2026)' section
- Detailed header refactoring strategy and asset dependency implementation
- Explained critical bug: shader changes weren't triggering rebuilds
- Documented workaround elimination (no more 'touch demo_assets.txt')
HOWTO.md:
- Added 'Build System Notes' section after developer build instructions
- Explained incremental build behavior and asset tracking
- Documented header organization (dcl/core/utils) for developers
- Clarified that all asset types (.wgsl, .spec, .obj) are tracked
All documentation now accurately reflects current build system state.
Ready to begin next task: Spectrogram Editor (HTML).
|
|
Split monolithic asset_manager.h (61 lines) into 3 focused headers:
- asset_manager_dcl.h: Forward declarations (AssetId, ProcGenFunc)
- asset_manager.h: Core API (GetAsset, DropAsset, AssetRecord)
- asset_manager_utils.h: Typed helpers (TextureAsset, MeshAsset)
Updated 17 source files to use appropriate headers:
- object.h: Uses dcl.h (only needs AssetId forward declaration)
- 7 files using TextureAsset/MeshAsset: Use utils.h
- 10 files using only GetAsset(): Keep asset_manager.h
Performance improvement:
- Before: Touch asset_manager.h → 4.82s (35 files rebuild)
- After: Touch asset_manager_utils.h → 2.01s (24 files rebuild)
- Improvement: 58% faster for common workflow (tweaking mesh/texture helpers)
Note: Touching base headers (dcl/core) still triggers ~33 file rebuilds
due to object.h dependency chain. Further optimization would require
reducing object.h's footprint (separate task).
Files changed:
- Created: asset_manager_dcl.h, asset_manager_utils.h
- Modified: asset_manager.h (removed structs), asset_manager.cc
- Updated: object.h, visual_debug.h, renderer_mesh.cc,
flash_cube_effect.cc, hybrid_3d_effect.cc, test files
|
|
Updated PROJECT_CONTEXT.md and TODO.md to include new critical tasks and reflect changes in task prioritization.
Modified doc/3D.md to adjust task descriptions.
Modified doc/CONTRIBUTING.md to incorporate the new in-memory replacement rule.
Regenerated asset files (src/generated/assets.h, src/generated/assets_data.cc, src/generated/test_assets.h, src/generated/test_assets_data.cc) to reflect any changes in asset definitions.
Removed temporary changes to GEMINI.md and HANDOFF.md.
|
|
Completed final cleanup phase of Audio Lifecycle Refactor. Removed backwards
compatibility shims and updated documentation to reflect new AudioEngine-based
initialization patterns.
Changes:
1. Removed Backwards Compatibility:
- Removed synth_init() call from audio_init() in audio.cc
- Added comment explaining AudioEngine is the preferred initialization method
- All tests already explicitly call synth_init() or use AudioEngine
2. Documentation Updates:
- Updated HOWTO.md with AudioEngine usage examples and best practices
- Updated CONTRIBUTING.md with audio subsystem initialization protocols
- Documented when to use AudioEngine vs direct synth API calls
- Clarified that AudioEngine is a lifecycle manager, not a complete facade
3. Size Verification:
- Size-optimized build: 5.0MB (vs 6.2MB debug)
- AudioEngine overhead: <500 bytes (within acceptable limits)
- No size regression from refactor
Results:
- All 20 tests pass (100% pass rate)
- Demo runs successfully
- No backwards compatibility issues
- Clear documentation for future development
- Binary size impact negligible
Design Philosophy:
- AudioEngine manages initialization order (synth before tracker)
- Direct synth API calls remain valid for performance-critical paths
- Low-level tests can still use synth_init() directly if needed
- Preferred pattern: Use AudioEngine for lifecycle, direct APIs for operations
handoff(Claude): Completed Task #56 Phase 4 - All phases complete! Audio
Lifecycle Refactor is fully implemented, tested, and documented. The
fragile initialization order dependency has been eliminated.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
|
Phase 1)
Implements Phase 1 of the audio lifecycle refactor to eliminate initialization
order dependencies between synth and tracker.
New Components:
1. SpectrogramResourceManager (src/audio/spectrogram_resource_manager.{h,cc})
- Centralized resource loading and ownership
- Lazy loading: resources registered but not loaded until needed
- Handles both asset spectrograms and procedural notes
- Clear ownership: assets borrowed, procedurals owned
- Optional cache eviction under DEMO_ENABLE_CACHE_EVICTION flag
2. AudioEngine (src/audio/audio_engine.{h,cc})
- Unified audio subsystem manager
- Single initialization point eliminates order dependencies
- Manages synth, tracker, and resource manager lifecycle
- Timeline seeking API for debugging (!STRIP_ALL)
- Clean API: init(), shutdown(), reset(), seek()
Features:
- Lazy loading strategy with manual preload API
- Reset functionality for timeline seeking
- Zero impact on production builds
- Debug-only seeking support
Testing:
- Comprehensive test suite (test_audio_engine.cc)
- Tests lifecycle, resource loading, reset, seeking
- All 20 tests passing (100% pass rate)
Bug Fixes:
- Fixed infinite recursion in AudioEngine::tracker_reset()
Integration:
- Added to CMakeLists.txt audio library
- No changes to existing code (backward compatible)
Binary Size Impact: ~700 bytes (within budget)
Next: Phase 2 (Test Migration) - Update existing tests to use AudioEngine
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
|
Updated AUDIO_LIFECYCLE_REFACTOR.md to support lazy loading instead of
eager "load all at init" approach.
Key changes:
- Lazy loading with 1-2s pre-warming lookahead (recommended)
- On-demand decompression for compressed assets (future)
- Cache eviction policy for long demos (optional)
- Async background loading (post-MVP enhancement)
Benefits over eager loading:
- Instant startup (no upfront loading delay)
- Memory efficient (only load active + upcoming samples)
- No trigger stutter (pre-warming prevents load-on-access)
- Spreads load cost over time
Example timeline:
t=0.0s: Load 0 samples (instant)
t=0.0s: Pre-warm 3-5 samples for next 2s
t=1.0s: Pre-warm 2-3 more samples
By t=10s: Only ~10 samples loaded (not all 19)
Addresses concern about "load all samples at init" being too costly.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
|
Updated AUDIO_LIFECYCLE_REFACTOR.md to explicitly address asset/procedural
spectrogram handling and AssetManager relationship.
Key additions:
- SpectrogramResourceManager component separates resource loading from sequencing
- Clear ownership rules: AssetManager owns assets, ResourceManager owns procedurals
- Unified interface for both asset and procedural spectrograms
- Reduces Tracker responsibility to pattern sequencing only
- FAQ section answering common questions about dependencies and caching
Architecture change:
AudioEngine → { Synth, Tracker, ResourceManager }
ResourceManager → { AssetManager, ProceduralGenerator }
This addresses the concern about coupling between tracker, synth, and assets.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
|
Created comprehensive design document for refactoring the tracker-synth
relationship to eliminate initialization order dependencies.
Proposed solution: AudioEngine class that manages both synth and tracker
as private members, providing order-independent initialization and clear
ownership semantics.
Three options analyzed:
- Option A: Unified AudioEngine (recommended)
- Option B: Registration Handle System
- Option C: Reference-Counted Resources
Estimated effort: 2-3 weeks with incremental migration path.
Binary size impact: ~500 bytes (acceptable).
See doc/AUDIO_LIFECYCLE_REFACTOR.md for complete design rationale,
implementation plan, and decision matrix.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
|
Completed Task #49.
- Implemented CPU-side SDF library (sphere, box, torus, plane).
- Implemented Dynamic BVH construction (rebuilt every frame).
- Implemented PhysicsSystem with semi-implicit Euler integration and collision resolution.
- Added visual debugging for BVH nodes.
- Created test_3d_physics interactive test and test_physics unit tests.
- Updated project docs and triaged new tasks.
|
|
|
|
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>
|
|
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.
|
|
Moves comprehensive sequence system documentation out of demo.seq into
a proper documentation file, keeping the timeline file clean and focused.
Changes:
- New file: doc/SEQUENCE.md with complete .seq format reference
- Streamlined: assets/demo.seq reduced from 207 to 104 lines
- Updated: README.md to include SEQUENCE.md reference
Benefits:
- Easier to read and navigate the actual timeline
- Documentation separately viewable in markdown
- Better for version control (timeline vs doc changes separated)
- Follows project convention of dedicated doc files
- Makes demo.seq more approachable for quick edits
The timeline file is now 50% smaller while all documentation remains
easily accessible in the standard doc/ directory.
|
|
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 detailed design for dynamic BVH and GPU traversal in 3D.md.
- Outlined SDF-based collision detection and semi-implicit Euler physics loop.
- Updated TODO.md with atomic tasks for physics implementation and granular WGSL refactoring.
|
|
Updated gen_coverage_report.sh to accept an optional argument for targeting specific directories using lcov --extract.
|
|
Added CMake support for coverage builds and a script to generate HTML reports using lcov on macOS. Also cleaned up .gitignore.
|
|
Assigned reference numbers to all remaining tasks in documentation:
- Task #34: Full STL Removal
- Task #35: CRT Replacement
- Task #36: Blender Exporter
- Task #37: Asset Ingestion
- Task #38: Runtime Loader
- Task #39: Visual Debugging System
- Task #40: Advanced Lighting & Transparency
- Task #41: Spectrogram Editor HTML Tool
- Task #42: Vectorial Spectrogram Reader (C++)
- Task #43: Spectrogram Drawing Bricks
Ensured consistent task numbering across PROJECT_CONTEXT.md and TODO.md.
|
|
Lowered the priority of the 'replace STL' task. It will be addressed in the final optimization phase (Phase 2) to simplify current development. Hot paths in AssetManager and Procedural remain optimized.
handoff(Gemini): STL usage is now permitted for non-critical paths until the final optimization phase. PROJECT_CONTEXT.md and TODO.md updated accordingly.
|
|
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>
|
|
|
|
Adds a section on Alignment, String Safety, and Size Reporting to ASSET_SYSTEM.md.
|
|
Updates ASSET_SYSTEM.md to describe shader asset handling. Adds Task #24 to TODO.md and PROJECT_CONTEXT.md to extract hardcoded shaders and integrate them with the AssetManager and ShaderComposer.
|
|
|
|
|
|
into BUILD.md
|
|
|
|
|
|
- Moved 3D.md into the doc/ directory to centralize documentation.
- Updated README.md to reflect the new location of 3D.md.
- Captured the action items from 3D.md (visual debug mode, Blender exporter) and added them as a new task (#18) in the PROJECT_CONTEXT.md roadmap.
|
|
- Moved PHASE2_COMPRESSION.md into the doc/ directory.
- Updated README.md to list and describe the new documentation file.
|
|
- Reverted modifications made to files within the 'third_party/' directory.
- Updated CONTRIBUTING.md to explicitly forbid any automated or manual changes to third-party code.
|
|
- 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.
|
