Timeline

Overview#

The Timeline panel provides tools for creating and managing keyframe animations. Located at the bottom of the viewport area (default height: 150px), it offers playback control, keyframe editing, and multi-track support.

Quick Start#

from witwin import Timeline
 
# Start recording
Timeline.record()
 
# Set time and animate
Timeline.set_time(0.0)
# ... modify object properties ...
Timeline.set_time(1.0)
# ... modify object properties ...
 
# Stop recording
Timeline.stop_recording()
 
# Play animation
Timeline.play()

API Reference#

from witwin import Timeline
 
# Recording
Timeline.record()                    # Start recording keyframes
Timeline.stop_recording()            # Stop recording
 
# Time control
Timeline.set_time(time_seconds)      # Set current time position
Timeline.get_state_at(time_seconds)  # Get scene state at time
 
# Playback
Timeline.play()                      # Start playback
Timeline.pause()                     # Pause playback
Timeline.stop()                      # Stop and reset to start

Playback Controls#

Transport Bar#

Time Display#

• Current Time: Active time position
• Duration: Total timeline length
• Format: Frames or timecode (HH:MM:SS:FF)

Default Settings#

DEFAULT_FPS: 30
DEFAULT_DURATION: 10 seconds
TRACK_HEIGHT: 24px
HEADER_WIDTH: 120px

Timeline Track#

Time Ruler#

• Scale: Zoom in/out on timeline
• Markers: Frame numbers or time values
• Scrubber: Red line indicating current position
• Click to Seek: Click anywhere to jump to time

Keyframe Display#

• Diamond Markers: Visual keyframe indicators
• Color Coding: Different colors per property
• Selection: Click to select keyframes
• Multi-select: Ctrl+Click or drag box selection

Track Layers#

Object Tracks#

• Per-Object: Each object has its own track
• Expandable: Show property sub-tracks
• Visibility: Toggle track visibility (eye icon)
• Lock: Prevent editing (padlock icon)

Property Tracks#

Keyframe Editing#

Adding Keyframes#

1. Auto-key Mode: Enable recording with Timeline.record()
2. Manual: Press K to add keyframe at current time
3. Properties Panel: Click keyframe icon next to property

Editing Keyframes#

Interpolation Types#

Animation Tools#

Curve Editor#

The Curve Editor provides graph-based editing of animation curves:

• Graph View: Visual representation of value over time
• Handles: Adjust curve tangents for smooth motion
• Presets: Quick ease in/out templates

Dope Sheet#

The Dope Sheet provides a summary view of all keyframes:

• Overview: See all keyframes at once
• Box Selection: Select multiple keyframes
• Scale Selection: Stretch/compress timing

Recording Workflow#

Basic Recording#

from witwin import Timeline
 
# 1. Start recording
Timeline.record()
 
# 2. Set initial state at t=0
Timeline.set_time(0.0)
cube.transform.position = [0, 0, 0]
 
# 3. Set final state at t=2
Timeline.set_time(2.0)
cube.transform.position = [5, 0, 0]
 
# 4. Stop recording
Timeline.stop_recording()
 
# 5. Preview
Timeline.play()

Querying State#

# Get the scene state at a specific time
state = Timeline.get_state_at(1.0)
print(state)  # Returns object transforms at t=1.0

Integration#

With Viewport#

• Real-time preview during playback
• Objects update on scrub
• Selection state synchronized

With Properties Panel#

• Set keyframes from property changes
• Display animated properties with indicator
• Show interpolated values at current time

With Node Editor#

• Time input nodes for procedural animation
• Parameter nodes can drive animation

Performance#

Optimization#

• Frame Skipping: Maintain target FPS during playback
• Cached Interpolation: Pre-computed curve values
• Batch Updates: Grouped viewport render calls

Data Format#

Animation data is stored in JSON format:

{
  "duration": 10.0,
  "fps": 30,
  "tracks": [
    {
      "objectId": "cube_1",
      "property": "transform.position",
      "keyframes": [
        { "time": 0.0, "value": [0, 0, 0], "interpolation": "bezier" },
        { "time": 2.0, "value": [5, 0, 0], "interpolation": "bezier" }
      ]
    }
  ]
}