# 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?