1 files changed, 82 insertions, 0 deletions
diff --git a/tools/track_visualizer/README.md b/tools/track_visualizer/README.md
new file mode 100644
index 0000000..a036dbd
--- /dev/null
+++ b/tools/track_visualizer/README.md
@@ -0,0 +1,82 @@
+# Music Track Visualizer
+
+A simple HTML-based visualizer for `.track` music files.
+
+## Features
+
+- **Load .track files** via file input button
+- **Zoomable timeline** with horizontal and vertical zoom controls
+- **Pan/scroll** by clicking and dragging on the canvas
+- **Color-coded patterns** with deterministic colors based on pattern names
+- **Sample ticks** displayed within each pattern box (vertical marks showing when samples trigger)
+- **Stack-based layout** prevents overlapping patterns automatically
+- **Time ruler** at the top with second markers
+- **Pattern duration** calculated from max beat time in each pattern
+
+## Usage
+
+1. Open `index.html` in a web browser
+2. Click "Choose File" and select a `.track` file (e.g., `assets/music.track`)
+3. Use the zoom controls to adjust horizontal and vertical scale
+4. Click and drag on the canvas to pan around
+5. Use mouse wheel to zoom (Shift+wheel for vertical zoom)
+
+## Controls
+
+| Action | Method |
+|--------|--------|
+| **Load file** | Click "Choose File" button |
+| **Zoom in/out** | Use + / − buttons or mouse wheel |
+| **Vertical zoom** | Use vertical zoom buttons or Shift+wheel |
+| **Pan** | Click and drag on canvas |
+| **Reset zoom** | Click "Reset" buttons |
+
+## Track File Format
+
+The visualizer parses `.track` files with the following structure:
+
+```
+# Comments start with #
+
+SAMPLE ASSET_KICK_1
+SAMPLE ASSET_SNARE_1
+
+PATTERN pattern_name
+  beat, sample_id, volume, pan
+  0.0, ASSET_KICK_1, 1.0, 0.0
+  2.0, ASSET_SNARE_1, 0.9, 0.1
+
+SCORE
+  time, pattern_name
+  0.0, pattern_name
+  4.0, pattern_name
+```
+
+### Elements Visualized
+
+- **Pattern boxes**: Color-coded rectangles representing each pattern trigger
+- **Sample ticks**: Vertical marks inside boxes showing when samples play
+- **Volume indicators**: Tick height varies with sample volume
+- **Time labels**: Start time displayed in each pattern box
+- **Stack levels**: Patterns automatically stack to avoid visual overlap
+
+## Implementation Details
+
+- **Stack-based layout**: Patterns are automatically arranged in vertical stacks to prevent overlaps
+- **Deterministic colors**: Pattern colors are generated from pattern name hashes for consistency
+- **Responsive canvas**: Canvas size adapts to track duration and pattern count
+- **Efficient rendering**: Full redraw on zoom/pan changes
+
+## Keyboard Shortcuts
+
+None currently - all controls via mouse/buttons.
+
+## Future Enhancements
+
+Potential additions:
+- Beat grid overlay
+- Pattern highlighting on hover
+- Sample name tooltips
+- Export to image
+- Playback cursor
+- Edit mode (move/resize patterns)