Files

Tretzi a2669d6f59 MindMachine: add timeline editor screen with pinch zoom and duration slider

2026-03-19 15:56:50 -05:00

7.8 KiB

Raw Blame History

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.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

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

User enters timeline editor from main screen
User selects which curves to edit (visual/audio)
User creates initial points by tapping
User adjusts points by dragging
User sets duration using selection handles
User previews session with playback controls
User saves session or starts immediate playback

8.2 Editing Existing Sessions

User opens saved session in editor
All curves and points load from saved state
User can modify any aspect (curves, duration, selection)
User can preview changes before saving
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

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

Touch gesture accuracy and responsiveness
Curve editing precision and smoothness
Zoom and pan performance
Audio-visual synchronization
Edge case handling (extreme values, rapid gestures)

13. Open Questions for Joe

Curve Smoothing: Should there be automatic curve smoothing between points, or should users create every point manually?
Preview Behavior: When previewing, should the session loop continuously or play once through?
Default Presets: Should the timeline editor include some pre-built curve templates (e.g., "Gradual fade", "Pulsing rhythm")?
Sharing: Do users need to share custom sessions with others, or is this purely personal use?
Undo/Redo: Should there be an undo/redo system for curve editing, or is the current state sufficient?
Curve Export: Should users be able to export their custom curves as data files for backup or sharing?
Tutorial: Is a guided tutorial needed for first-time users, or should the interface be intuitive enough to learn through exploration?

7.8 KiB Raw Blame History