final feature set

tasks/merged-waveform/06-waveform-audio-analysis.md

@@ -0,0 +1,46 @@
+# 06. Implement Audio Waveform Analysis
+
+meta:
+  id: merged-waveform-06
+  feature: merged-waveform
+  priority: P2
+  depends_on: []
+  tags: [audio, waveform, analysis]
+
+objective:
+- Analyze audio data to extract waveform information
+- Create real-time waveform data from audio streams
+- Generate waveform data points for visualization
+
+deliverables:
+- Audio analysis utility
+- Waveform data extraction function
+- Integration with audio backend
+
+steps:
+1. Research and select audio waveform analysis library (e.g., `audiowaveform`)
+2. Create `src/utils/audio-waveform.ts`
+3. Implement audio data extraction from backend
+4. Generate waveform data points (amplitude values)
+5. Add sample rate and duration normalization
+
+tests:
+- Unit: Test waveform generation from sample audio
+- Integration: Test with real audio playback
+- Performance: Measure waveform generation overhead
+
+acceptance_criteria:
+- Waveform data is generated from audio content
+- Data points represent audio amplitude accurately
+- Generation works with real-time audio streams
+
+validation:
+- Generate waveform from sample MP3 file
+- Verify amplitude data matches audio peaks
+- Test with different audio formats
+
+notes:
+- Consider using `ffmpeg` or `sox` for offline analysis
+- For real-time: analyze audio chunks during playback
+- Waveform resolution: 64-256 data points for TUI display
+- Normalize amplitude to 0-1 range

tasks/merged-waveform/07-merged-waveform-component.md

@@ -0,0 +1,46 @@
+# 07. Create Merged Progress-Waveform Component
+
+meta:
+  id: merged-waveform-07
+  feature: merged-waveform
+  priority: P2
+  depends_on: [merged-waveform-06]
+  tags: [ui, waveform, component]
+
+objective:
+- Design and implement a single component that shows progress bar and waveform
+- Component starts as progress bar, expands to waveform when playing
+- Provide smooth transitions between states
+
+deliverables:
+- MergedWaveform component
+- State management for progress vs waveform display
+- Visual styling for progress bar and waveform
+
+steps:
+1. Create `src/components/MergedWaveform.tsx`
+2. Design component state machine (progress bar → waveform)
+3. Implement progress bar visualization
+4. Add waveform expansion animation
+5. Style progress bar and waveform with theme colors
+
+tests:
+- Unit: Test component state transitions
+- Integration: Test component in Player
+- Visual: Verify smooth expansion animation
+
+acceptance_criteria:
+- Component displays progress bar when paused
+- Component smoothly expands to waveform when playing
+- Visual styles match theme and existing UI
+
+validation:
+- Test with paused and playing states
+- Verify expansion is smooth and visually appealing
+- Check theme color integration
+
+notes:
+- Use existing Waveform component as base
+- Add CSS transitions for smooth expansion
+- Keep component size manageable (fit in progress bar area)
+- Consider responsive to terminal width changes

tasks/merged-waveform/08-realtime-waveform-rendering.md

@@ -0,0 +1,46 @@
+# 08. Implement Real-Time Waveform Rendering During Playback
+
+meta:
+  id: merged-waveform-08
+  feature: merged-waveform
+  priority: P2
+  depends_on: [merged-waveform-07]
+  tags: [audio, realtime, rendering]
+
+objective:
+- Update waveform in real-time during audio playback
+- Highlight waveform based on current playback position
+- Sync waveform with audio backend position updates
+
+deliverables:
+- Real-time waveform update logic
+- Playback position highlighting
+- Integration with audio backend position tracking
+
+steps:
+1. Subscribe to audio backend position updates
+2. Update waveform data points based on playback position
+3. Implement playback position highlighting
+4. Add animation for progress indicator
+5. Test synchronization with audio playback
+
+tests:
+- Integration: Test waveform sync with audio playback
+- Performance: Measure real-time update overhead
+- Visual: Verify progress highlighting matches audio position
+
+acceptance_criteria:
+- Waveform updates in real-time during playback
+- Playback position is accurately highlighted
+- No lag or desynchronization with audio
+
+validation:
+- Play audio and watch waveform update
+- Verify progress bar matches audio position
+- Test with different playback speeds
+
+notes:
+- Use existing audio position polling in `useAudio.ts`
+- Update waveform every ~100ms for smooth visuals
+- Consider reducing waveform resolution during playback for performance
+- Ensure highlighting doesn't flicker

tasks/merged-waveform/09-waveform-performance-optimization.md

@@ -0,0 +1,46 @@
+# 09. Optimize Waveform Rendering Performance
+
+meta:
+  id: merged-waveform-09
+  feature: merged-waveform
+  priority: P3
+  depends_on: [merged-waveform-08]
+  tags: [performance, optimization]
+
+objective:
+- Ensure waveform rendering doesn't cause performance issues
+- Optimize for terminal TUI environment
+- Minimize CPU and memory usage
+
+deliverables:
+- Performance optimizations
+- Memory management for waveform data
+- Performance monitoring and testing
+
+steps:
+1. Profile waveform rendering performance
+2. Optimize data point generation and updates
+3. Implement waveform data caching
+4. Add performance monitoring
+5. Test with long audio files
+
+tests:
+- Performance: Measure CPU usage during playback
+- Performance: Measure memory usage over time
+- Load test: Test with 30+ minute audio files
+
+acceptance_criteria:
+- Waveform rendering < 16ms per frame
+- No memory leaks during extended playback
+- Smooth playback even with waveform rendering
+
+validation:
+- Profile CPU usage during playback
+- Monitor memory over 30-minute playback session
+- Test with multiple simultaneous audio files
+
+notes:
+- Consider reducing waveform resolution during playback
+- Cache waveform data to avoid regeneration
+- Use efficient data structures for waveform points
+- Test on slower terminals (e.g., tmux)

tasks/merged-waveform/README.md

@@ -0,0 +1,21 @@
+# Merged Waveform Progress Bar
+
+Objective: Create a real-time waveform visualization that expands from a progress bar during playback
+
+Status legend: [ ] todo, [~] in-progress, [x] done
+
+Tasks
+- [ ] 06 — Implement audio waveform analysis → `06-waveform-audio-analysis.md`
+- [ ] 07 — Create merged progress-waveform component → `07-merged-waveform-component.md`
+- [ ] 08 — Implement real-time waveform rendering during playback → `08-realtime-waveform-rendering.md`
+- [ ] 09 — Optimize waveform rendering performance → `09-waveform-performance-optimization.md`
+
+Dependencies
+- 06 -> 07
+- 07 -> 08
+- 08 -> 09
+
+Exit criteria
+- Waveform smoothly expands from progress bar during playback
+- Waveform is highlighted based on current playback position
+- No performance degradation during playback