ofxZeitleiste

A modern, lightweight timeline addon for openFrameworks.

English | 日本語

Introduction

ofxTimeline, created by James George, has been the standard timeline tool for openFrameworks for many years. ofxZeitleiste is a reimplementation of this beloved addon, rebuilt from the ground up with modern practices and a focus on simplicity, performance, and extensibility.

Zeitleiste is the German word for Timeline, reflecting this addon's fresh approach while paying homage to its predecessor.

Key Features

• Minimal dependencies - Only requires ofxXmlSettings (included with openFrameworks)
• Visual timeline interface - Intuitive UI with keyframes, tracks, and playhead
• Multiple interpolation modes - Linear, ease-in, ease-out, and ease-in-out
• Interactive editing - Click and drag keyframes, scrub through time with the playhead
• Extensible architecture - Easy to add custom track types
• Performance optimized - Efficient rendering and keyframe lookup

Status

ofxZeitleiste is currently in Phase 1 (MVP) - The following features are working:

• ✅ Timeline playback control (play, pause, stop)
• ✅ Float value keyframe tracks with interpolation
• ✅ Visual timeline UI with tracks, keyframes, and playhead
• ✅ Mouse interaction (drag playhead, select and move keyframes)
• ✅ Multiple easing functions (linear, ease-in, ease-out, ease-in-out)
• ✅ Dark theme UI

Roadmap

Phase 2 - Additional features:

• Multiple simultaneous tracks
• Undo/Redo system
• Copy/paste keyframes
• Double-click to add keyframes
• Context menu for keyframe operations

Phase 3 - New track types:

• Bang tracks (event triggers)
• Color tracks (color animation)
• Curve tracks (multi-dimensional values)
• Switch tracks (on/off states)

Phase 4 - Advanced features:

• Bézier curve editor for custom easing
• Zoom/pan for long timelines
• Page system for multi-scene projects
• XML/JSON serialization

Installation

Clone or copy this addon into your openFrameworks/addons/ folder:

cd openFrameworks/addons/
git clone https://github.com/yourusername/ofxZeitleiste.git

Dependencies

• ofxXmlSettings (included with openFrameworks core)

Quick Start

Basic Usage

// ofApp.h
include "ofxZeitleiste.h"

class ofApp : public ofBaseApp {
public:
    void setup();
    void update();
    void draw();
    void keyPressed(int key);
    
    ofxTimeline timeline;
    float circleX;
};

// ofApp.cpp
void ofApp::setup() {
    ofSetFrameRate(60);
    
    // Setup timeline
    timeline.setup();
    timeline.setDuration(5.0f);  // 5 seconds
    timeline.setFrameRate(60);
    
    // Add a keyframe track
    auto track = timeline.addKeyframes("position_x");
    track->setValueRange(0, ofGetWidth());
    
    // Add keyframes (time is normalized 0.0-1.0)
    track->addKeyframe(0.0f, 100.0f);          // Start at x=100
    track->addKeyframe(0.5f, ofGetWidth()-100); // Middle at right side
    track->addKeyframe(1.0f, 100.0f);          // End back at x=100
    
    // Auto-play
    timeline.play();
}

void ofApp::update() {
    timeline.update();
    
    // Get animated value
    circleX = timeline.getValue("position_x");
}

void ofApp::draw() {
    // Draw your animated content
    ofSetColor(100, 200, 255);
    ofDrawCircle(circleX, ofGetHeight()/2, 50);
    
    // Draw timeline UI (bottom 300px)
    timeline.draw(0, ofGetHeight() - 300, ofGetWidth(), 300);
}

void ofApp::keyPressed(int key) {
    if (key == ' ') {
        if (timeline.isPlaying()) {
            timeline.pause();
        } else {
            timeline.play();
        }
    }
}

Examples

The example-basic demonstrates:

• Creating a timeline
• Adding keyframe tracks
• Animating a circle's position
• Playing/pausing with spacebar
• Interactive timeline UI

To run the example: 1. Use the openFrameworks Project Generator 2. Import the example-basic folder 3. Add ofxZeitleiste and ofxXmlSettings addons 4. Generate and build

API Overview

ofxTimeline

Main timeline controller class.

// Setup
void setup();
void setDuration(float seconds);
void setFrameRate(float fps);

// Playback control
void play();
void pause();
void stop();
bool isPlaying();

// Update and render
void update();
void draw(float x, float y, float w, float h);

// Track management
ofxTLKeyframes addKeyframes(const std::string& name);
ofxTLTrack* getTrack(const std::string& name);
float getValue(const std::string& trackName);

// Time access
ofxTLPlayhead& getPlayhead();
ofxTLTimebase& getTimebase();

ofxTLKeyframes

Float value keyframe track.

// Keyframe management
void addKeyframe(float time, float value);
void removeKeyframe(int index);
void setValueRange(float min, float max);

// Value retrieval
float getValueAtPercent(float percent);
float getValueAtTime(float seconds);

Easing Types

enum class EasingType {
    LINEAR,
    EASE_IN,
    EASE_OUT,
    EASE_IN_OUT
};

Architecture

ofxZeitleiste follows a modular design:

ofxTimeline (main controller)
├── ofxTLTimebase (time management)
├── ofxTLPlayhead (playback control)
├── ofxTLZoomer (view management)
├── ofxTLTheme (visual styling)
└── tracks/
    └── ofxTLKeyframes (float keyframe track)
        └── ofxTLTrack (base class)

Key design principles:

• Separation of concerns - Each component has a clear responsibility
• Extensibility - Easy to add new track types by extending ofxTLTrack
• Performance - Binary search for keyframes, dirty flag rendering
• Modern C++ - Smart pointers, move semantics, C++17 features

Customization

Creating Custom Track Types

Extend ofxTLTrack to create your own track types:

class ofxTLCustomTrack : public ofxTLTrack {
public:
    void update() override;
    void draw() override;
    void mousePressed(ofMouseEventArgs& args) override;
    // ... implement your custom behavior
};

Custom Themes

Modify the visual appearance:

ofxTLTheme customTheme;
customTheme.background = ofColor(20, 20, 30);
customTheme.playhead = ofColor(100, 255, 100);
timeline.setTheme(customTheme);

License

This addon is licensed under the MIT License. See license.md for details.

Credits

ofxZeitleiste was inspired by and pays homage to:

• ofxTimeline by James George - The original and beloved timeline addon
• ofxLineaDeTiempo by Roy Macdonald - A modern reimplementation

Compatibility

• openFrameworks: 0.12.0+
• Platforms: macOS

Support

For questions, issues, or discussions:

• Open an issue on GitHub
• Check the example code in example-basic/
• Read the inline code documentation

---