feat(spectral-editor): add waveform intensity viewer for sample offset

Add interactive waveform timeline for determining SAMPLE OFFSET values:

Features:
- RMS envelope visualization (10ms windows, normalized)
- Uses synthesized PCM from spectrogram (not original WAV)
- Draggable offset marker with numeric input (0.001s precision)
- Snap-to-onset: auto-detects first transient (threshold 0.01)
- Copy button: generates `SAMPLE <name> OFFSET <seconds>` command
- Top panel (120px) with controls, z-indexed above spectrogram

Design rationale:
- Offset measured on procedural output (matches runtime behavior)
- Interactive workflow: load .spec → inspect → set offset → copy
- Supports tracker compile-time SAMPLE OFFSET feature

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

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: