MindMachine: add timeline editor screen with pinch zoom and duration slider
This commit is contained in:
Tretzi
231
MindMachine-Timeline-Spec.md
Normal file
231
MindMachine-Timeline-Spec.md
Normal file
@@ -0,0 +1,231 @@
|
||||
# MindMachine - Timeline-Based Parameter Editing UX Spec
|
||||
|
||||
## 1. Feature Overview
|
||||
|
||||
This feature introduces timeline-based parameter editing for creating custom MindMachine sessions. Users can define visual and audio parameter curves over time using two synchronized graphs with pinch-to-zoom navigation and touch-based curve editing.
|
||||
|
||||
## 2. Core Interaction Model
|
||||
|
||||
### 2.1 Immersive Mode
|
||||
- Full-screen editing canvas with no visible system UI
|
||||
- All controls accessible via touch gestures only
|
||||
- Visual feedback through the parameter curves themselves
|
||||
- Haptic feedback for key interactions (optional)
|
||||
|
||||
### 2.2 Timeline Graphs
|
||||
Two synchronized graphs displayed vertically:
|
||||
- **Top Graph**: Visual parameters (brightness, blink rate)
|
||||
- **Bottom Graph**: Audio parameters (carrier frequency, binaural beat)
|
||||
|
||||
Both graphs share:
|
||||
- Same time scale (horizontal axis)
|
||||
- Pinch-to-zoom for time axis
|
||||
- Shared selection of editable curve
|
||||
- Synchronized playback cursor
|
||||
|
||||
## 3. Curve Selection and Editing
|
||||
|
||||
### 3.1 Selecting Curves
|
||||
- **Visual Curve**: Brightness (left) / Blink Rate (right)
|
||||
- **Audio Curve**: Carrier Frequency (left) / Binaural Beat (right)
|
||||
|
||||
**Selection Method**:
|
||||
- Tap left side of graph to select left curve
|
||||
- Tap right side of graph to select right curve
|
||||
- Visual indicator shows active selection (highlighted curve)
|
||||
|
||||
### 3.2 Editing Gestures
|
||||
- **Create Point**: Tap on empty graph area
|
||||
- **Move Point**: Drag existing point
|
||||
- **Delete Point**: Long-press point (haptic feedback, then fade out)
|
||||
- **Smooth Curve**: Double-tap between points (auto-smooth)
|
||||
|
||||
## 4. Timeline Navigation
|
||||
|
||||
### 4.1 Pinch-to-Zoom
|
||||
- **Pinch In**: Zoom in (show more detail, shorter time range)
|
||||
- **Pinch Out**: Zoom out (show longer duration, less detail)
|
||||
- **Zoom Range**: 1 minute ← 8 hours
|
||||
- **Minimum Zoom**: 30 seconds per screen width
|
||||
- **Maximum Zoom**: 24 hours total visible
|
||||
|
||||
### 4.2 Pan Navigation
|
||||
- **Drag Graph**: Pan horizontally through time
|
||||
- **Edge Bounce**: Visual feedback when reaching timeline ends
|
||||
- **Momentum Scrolling**: Natural deceleration after quick swipe
|
||||
|
||||
### 4.3 Time Indicators
|
||||
- **Current Time Cursor**: Vertical line showing current playback position
|
||||
- **Selection Handles**: Left/right handles for selecting time range
|
||||
- **Duration Display**: Shows total selected duration
|
||||
|
||||
## 5. Parameter Ranges and Constraints
|
||||
|
||||
### 5.1 Visual Parameters
|
||||
- **Brightness**: 0% - 100% (logarithmic scale for perceptual uniformity)
|
||||
- **Blink Rate**: 0.1 - 30 Hz (logarithmic scale)
|
||||
|
||||
### 5.2 Audio Parameters
|
||||
- **Carrier Frequency**: 200 - 1200 Hz (logarithmic scale)
|
||||
- **Binaural Beat**: 0.5 - 30 Hz (logarithmic scale)
|
||||
|
||||
### 5.3 Duration Constraints
|
||||
- **Minimum Duration**: 1 minute
|
||||
- **Maximum Duration**: 8 hours
|
||||
- **Default Duration**: 20 minutes
|
||||
|
||||
## 6. Visual Design System
|
||||
|
||||
### 6.1 Graph Appearance
|
||||
- **Background**: Dark theme (reduces eye strain)
|
||||
- **Grid Lines**: Light gray, 10% opacity
|
||||
- **Curve Color**: Color-coded per parameter (blue for visual, green for audio)
|
||||
- **Selected Curve**: Brightened with glow effect
|
||||
- **Points**: White circles with 8px diameter
|
||||
|
||||
### 6.2 Touch Feedback
|
||||
- **Point Creation**: White flash + haptic tap
|
||||
- **Point Movement**: Subtle glow + haptic feedback
|
||||
- **Curve Selection**: Smooth color transition + haptic
|
||||
- **Zoom Gestures**: Dynamic scaling + haptic pulse at zoom stops
|
||||
|
||||
## 7. Edge Cases and Special Behaviors
|
||||
|
||||
### 7.1 Curve Intersections
|
||||
- Allow curves to cross freely
|
||||
- No special handling for intersections
|
||||
- Visual clarity maintained through color coding
|
||||
|
||||
### 7.2 Extreme Values
|
||||
- Clamp values to defined ranges
|
||||
- Show visual indicator when reaching limits
|
||||
- Provide haptic feedback at range boundaries
|
||||
|
||||
### 7.3 Zero-Length Curves
|
||||
- Minimum 2 points required for valid curve
|
||||
- Single point creates constant value
|
||||
- Zero points = invalid state (show error)
|
||||
|
||||
### 7.4 Time Range Management
|
||||
- Auto-extend timeline when creating points beyond current range
|
||||
- Maintain zoom level when extending timeline
|
||||
- Preserve curve shape during zoom/pan operations
|
||||
|
||||
## 8. User Workflow
|
||||
|
||||
### 8.1 Creating a Custom Session
|
||||
1. User enters timeline editor from main screen
|
||||
2. User selects which curves to edit (visual/audio)
|
||||
3. User creates initial points by tapping
|
||||
4. User adjusts points by dragging
|
||||
5. User sets duration using selection handles
|
||||
6. User previews session with playback controls
|
||||
7. User saves session or starts immediate playback
|
||||
|
||||
### 8.2 Editing Existing Sessions
|
||||
1. User opens saved session in editor
|
||||
2. All curves and points load from saved state
|
||||
3. User can modify any aspect (curves, duration, selection)
|
||||
4. User can preview changes before saving
|
||||
5. User can revert to original or save modifications
|
||||
|
||||
## 9. Accessibility Considerations
|
||||
|
||||
### 9.1 Visual Accessibility
|
||||
- High contrast mode available
|
||||
- Larger touch targets for motor-impaired users
|
||||
- VoiceOver support for all interactive elements
|
||||
- Color-blind friendly color palette
|
||||
|
||||
### 9.2 Motor Accessibility
|
||||
- Adjustable touch target size
|
||||
- Alternative input methods (keyboard navigation)
|
||||
- Reduced motion option for animations
|
||||
- Voice control for basic operations
|
||||
|
||||
## 10. Performance Requirements
|
||||
|
||||
### 10.1 Rendering Performance
|
||||
- Maintain 60fps during all interactions
|
||||
- Smooth curve rendering with anti-aliasing
|
||||
- Efficient hit detection for touch points
|
||||
- Low memory footprint for curve data
|
||||
|
||||
### 10.2 Battery Impact
|
||||
- Optimize for minimal battery drain
|
||||
- Reduce refresh rate when idle
|
||||
- Efficient audio synthesis during preview
|
||||
- Screen brightness management for visual elements
|
||||
|
||||
## 11. Error States and Recovery
|
||||
|
||||
### 11.1 Invalid Configurations
|
||||
- **Too Few Points**: Show "At least 2 points required" message
|
||||
- **Invalid Duration**: Show "Duration must be 1-8 hours" message
|
||||
- **Out of Range Values**: Show "Value out of range, adjusted to limit"
|
||||
|
||||
### 11.2 System Errors
|
||||
- **Audio Synthesis Failure**: Show "Audio generation failed" message
|
||||
- **Rendering Issues**: Show "Graphics error, restarting" message
|
||||
- **Memory Pressure**: Show "Low memory, closing editor" message
|
||||
|
||||
## 12. Implementation Notes for Andy
|
||||
|
||||
### 12.1 Data Structures
|
||||
```java
|
||||
class TimelineSession {
|
||||
Duration duration;
|
||||
Curve visualCurve; // Brightness/Blink Rate
|
||||
Curve audioCurve; // Carrier/Binaural
|
||||
boolean isPlaying;
|
||||
}
|
||||
|
||||
class Curve {
|
||||
List<Point> points;
|
||||
CurveType type; // LEFT or RIGHT
|
||||
boolean isActive;
|
||||
}
|
||||
|
||||
class Point {
|
||||
Time time;
|
||||
double value;
|
||||
boolean isSelected;
|
||||
}
|
||||
```
|
||||
|
||||
### 12.2 Key Algorithms
|
||||
- **Curve Interpolation**: Cubic spline between points
|
||||
- **Zoom Management**: Maintain aspect ratio, clamp zoom levels
|
||||
- **Hit Detection**: Spatial indexing for touch points
|
||||
- **Audio Synthesis**: Real-time parameter modulation based on curve
|
||||
|
||||
### 12.3 Performance Optimizations
|
||||
- Use GPU acceleration for curve rendering
|
||||
- Implement spatial indexing for hit detection
|
||||
- Cache interpolated values for playback
|
||||
- Use object pooling for point objects
|
||||
|
||||
### 12.4 Testing Priorities
|
||||
1. Touch gesture accuracy and responsiveness
|
||||
2. Curve editing precision and smoothness
|
||||
3. Zoom and pan performance
|
||||
4. Audio-visual synchronization
|
||||
5. Edge case handling (extreme values, rapid gestures)
|
||||
|
||||
---
|
||||
|
||||
## 13. Open Questions for Joe
|
||||
|
||||
1. **Curve Smoothing**: Should there be automatic curve smoothing between points, or should users create every point manually?
|
||||
|
||||
2. **Preview Behavior**: When previewing, should the session loop continuously or play once through?
|
||||
|
||||
3. **Default Presets**: Should the timeline editor include some pre-built curve templates (e.g., "Gradual fade", "Pulsing rhythm")?
|
||||
|
||||
4. **Sharing**: Do users need to share custom sessions with others, or is this purely personal use?
|
||||
|
||||
5. **Undo/Redo**: Should there be an undo/redo system for curve editing, or is the current state sufficient?
|
||||
|
||||
6. **Curve Export**: Should users be able to export their custom curves as data files for backup or sharing?
|
||||
|
||||
7. **Tutorial**: Is a guided tutorial needed for first-time users, or should the interface be intuitive enough to learn through exploration?
|
||||
Reference in New Issue
Block a user