diff options
Diffstat (limited to 'tools/spectral_editor/README.md')
| -rw-r--r-- | tools/spectral_editor/README.md | 51 |
1 files changed, 51 insertions, 0 deletions
diff --git a/tools/spectral_editor/README.md b/tools/spectral_editor/README.md index 6bb3681..95b4769 100644 --- a/tools/spectral_editor/README.md +++ b/tools/spectral_editor/README.md @@ -39,6 +39,17 @@ Replace large `.spec` binary assets with tiny procedural C++ code: - Dual display: Reference (green) and Procedural (red) overlaid - Always visible for instant feedback +### Sample Offset Tool +- **Waveform intensity timeline** (top panel): + - RMS envelope calculated from synthesized PCM (10ms windows) + - Visualizes procedural audio output, not original WAV + - Click or drag to set offset marker +- **Offset controls**: + - Numeric input (0.001s precision) + - Copy button: Generates `SAMPLE <name> OFFSET <seconds>` for .track files + - Snap-to-onset: Auto-detects first transient above threshold (0.01) +- **Use case:** Determine intrinsic sample offset for tracker SAMPLE declarations + ## Quick Start 1. **Open the editor:** @@ -153,6 +164,46 @@ Generated code using the spectral_brush runtime API. Copy-paste into `src/audio/ ## Technical Details +### Sample Offset Design + +**Problem:** Tracker system needs compile-time offsets to align procedural samples with beat grid. Requires manual inspection to identify where audio "truly" begins. + +**Solution:** Waveform intensity viewer that visualizes RMS envelope of synthesized audio. + +**Key Design Decisions:** + +1. **Use Synthesized PCM, Not Original WAV:** + - Offset applies to procedural output (what's heard in demo) + - Calls `spectrogramToAudio()` to generate PCM via IDCT + - Ensures offset measurement matches runtime behavior + +2. **RMS Envelope (10ms windows):** + - Smooths out sample-level noise + - Provides clear visual representation of attack envelope + - Normalized to max intensity for consistent display + +3. **Interactive Offset Marker:** + - Red dashed line draggable across timeline + - Click anywhere to jump to time position + - Direct feedback on offset value (4 decimal places) + +4. **Auto-Detection (Snap-to-Onset):** + - Simple threshold-based onset detection (|sample| > 0.01) + - Finds first significant transient + - Good starting point, can be manually refined + +5. **Copy Command Format:** + - Generates `SAMPLE <name> OFFSET <seconds>` for .track files + - Clipboard integration for fast workflow + - Infers sample name from loaded filename + +**Workflow:** +1. Load .spec file +2. Inspect waveform envelope (top panel) +3. Click/drag or snap-to-onset to set offset +4. Copy command → paste into .track file +5. Rebuild demo with sample offset baked in + ### Spectral Brush Primitive A spectral brush consists of: |