implementing cava for real time visualization

tasks/real-time-audio-visualization/04-create-realtime-waveform-component.md

@@ -0,0 +1,75 @@
+# 04. Create realtime waveform component
+
+meta:
+  id: real-time-audio-visualization-04
+  feature: real-time-audio-visualization
+  priority: P1
+  depends_on: [real-time-audio-visualization-03]
+  tags: [component, ui]
+
+objective:
+- Create a SolidJS component that displays real-time audio visualization
+- Integrate audio-visualizer and audio-stream-reader
+- Display frequency data as visual waveform bars
+
+deliverables:
+- src/components/RealtimeWaveform.tsx - Real-time waveform component
+- src/components/RealtimeWaveform.test.tsx - Component tests
+
+steps:
+- Create RealtimeWaveform component:
+  - Accept props: audioUrl, position, duration, isPlaying, onSeek, resolution
+  - Initialize audio-visualizer with cavacore
+  - Initialize audio-stream-reader for mpv backend
+  - Create render loop that:
+    - Reads audio samples from stream reader
+    - Passes samples to cavacore execute()
+    - Gets frequency data back
+    - Maps frequency data to visual bars
+    - Renders bars with appropriate colors
+- Implement rendering logic:
+  - Map frequency values to bar heights
+  - Color-code bars based on intensity
+  - Handle played vs unplayed portions
+  - Support click-to-seek
+- Create visual style:
+  - Use terminal block characters for bars
+  - Apply colors based on frequency bands (bass, mid, treble)
+  - Add visual flair (gradients, glow effects if possible)
+- Implement state management:
+  - Track current frequency data
+  - Track playback position
+  - Handle component lifecycle (cleanup)
+- Create unit tests:
+  - Test component initialization
+  - Test render loop
+  - Test click-to-seek
+  - Test cleanup
+
+tests:
+- Unit: Test component props
+- Unit: Test frequency data mapping
+- Unit: Test visual bar rendering
+- Integration: Test with mock audio data
+- Integration: Test with actual audio playback
+
+acceptance_criteria:
+- Component renders without errors
+- Visual bars update in real-time during playback
+- Frequency data is correctly calculated from audio samples
+- Click-to-seek works
+- Component cleans up resources properly
+- Visual style matches design requirements
+
+validation:
+- Run: `bun test` for unit tests
+- Manual: Play audio and verify visualization updates
+- Manual: Test seeking and verify visualization follows
+- Performance: Monitor frame rate and CPU usage
+
+notes:
+- Use SolidJS createEffect for reactive updates
+- Keep render loop efficient to maintain 60fps
+- Consider debouncing if processing is too heavy
+- May need to adjust sample rate for performance
+- Visual style should complement existing MergedWaveform design