ofxTimeline

ofxTimeline is a simple to use openFrameworks add on for creating a user interface to an editable timeline. The framework allows you to compose sequences of change over time, controlling the variables in your openFrameworks application to create time based interactions.

If you're familiar with timelines from programs like After Effects, Final Cut, or Blender then ofxTimeline should feel comfortable. With just a few lines of code you can add a visual editor to smoothly interpolate curves, colors, video, oscillators, audio, and 3d cameras.

You can also extend ofxTimeline with custom tracks to work with other types of time based data. Check out Designing Custom Tracks

Licensed under the Apache License

Philosophy of Reusable Tools##

ofxTimeline is part of my reserach into how creating GUI based tools within creative coding environments can open up new ways of creating and interacting with media.

Interface based timeline systems are most commonly found in expensive big box applications like After Effects or Cinema4d, which can be prohibitively complex and aren't open source. There are open timeline implementations are tied up in huge projects like Blender, VLMC and Audacity. Even very talented programmers have trouble extracting reusable pieces from these applications for creative reuse. Moreover their GPL licensing have commercially restrictive licenses, a deal breaker for inclusion in creative coding platforms like openFrameworks, Processing, and Cinder.

If the community were to build many small components for creating small and intuitive applications, what new possibilities would we uncover? What collaborations between creative coders and other designers and artists would emerge?

Major features

Very few lines of code to include in openFrameworks project
Precise millisecond level timing and drift-free playback
Several track types built in, such as curved, colors, and video tracks with thumbnail previews
Convenient controls for efficient editing, such as multi-select, copy+paste, arrow keys nudging, and snapping to points
Zooming in for detailed control and editing timelines with long durations
Saving and loading of values to XML
Adding multiple pages
Ability to set beats per minute measure marks conjunction with snapping
Easily extended for implementing your own tracks

Getting started

Here are a series of video tutorials for getting started: https://vimeo.com/59653952

1 Pages

You can divide the timeline into pages, each page containing its own set of tracks.

2 Ticker and Playhead

The header displays tick marks at minutes, seconds, and milliseconds. Clicking inside the header allows you to scrube the playhead time. The green line extending down the height of the timeline indicates the current time, while the red line displays the hovering time.

3 In/Out Handles

The bar below the ticker allows you to drag the in and out points on the timeline. The region defined by the in and out point is all that is included during playback.

4 Tracks

The main body of the timeline is a list of tracks that are editable and resizable.

5 Zoomer

The control at the bottom of the track allows for zooming in and precisely editing time.

Examples

Simple Curves

Simple Curves shows how to use two keyframes and a switcher to animate and color a cube

Audio Waveform

Audio Waveform shows how to add an audio track to a project.

Video Renderer

Video Renderer shows how to build a simple video effects app using the timeline and a shader. Drag & Drop a video into the application, edit and export the modified frames as an image sequence

Multi-timeline

Muli-timeline shows how to use Flags to trigger start and stop the playback of other timelines in the same application.

Hotkeys

ofxTimeline has a few hot keys built in

Enabling Hotkeys on OS X

On OS X, GLUT overrides COMMAND+C, COMMAND+V, and COMMAND+S behavior. ofxTimeline has a function to remove these default bindings in order that the key commands in the timeline work. Add the following line of code to your setup function:

  ofxTimeline::removeCocoaMenusFromGlut("myAppName");

All Hotkeys

Note on OS X the COMMAND key is used, on Linux and Windows the CTRL key is used

<table> <tr> <td style="font-weight:bold">Function</td><td style="font-weight:bold">Shortcut</td> </tr> <tr> <td>Cut Selection</td><td>command+x</td> </tr> <tr> <td>Copy Selection</td><td>command+c</td> </tr> <tr> <td>Paste Selection</td><td>command+v</td> </tr> <tr> <td>Undo</td><td>command+z</td> </tr> <tr> <td>Redo</td><td>shift+command+z</td> </tr> <tr> <td>Select all keyframes in Focused track</td><td>command+a</td> </tr> <tr> <td>Add all keyframes in Focused track to selection</td><td>command+shift+a</td> </tr> <tr> <td>Delete all selected keyframes</td><td>delete or backspace</td> </tr> <tr> <td>Nudge keyframes a little</td><td>arrow keys</td> </tr> <tr> <td>Nudge keyframes a little more</td><td>shift+arrow keys</td> </tr> <tr> <td>Expand Focused track</td><td>alt+e</td> </tr> <tr> <td>Collapse all tracks</td><td>alt+c</td> </tr> <tr> <td>Evenly distribute track sizes</td><td>alt+shift+c</td> </tr> </table>

Including ofxTimeline in your openFrameworks project

Clone ofxTimeline and dependencies

to download the timeline open up the terminal and type

$cd of_0073_osx_release/addons
$git clone https://github.com/YCAMInterlab/ofxTimeline.git
$cd ofxTimeline/
$./clone_addons.sh

This will download the necessary addons, but won't overwrite any changes if you already have some of them installed If you're using linux, please make sure you checkout the develop branch of ofxTextInputField

Install OpenAL

For Windows: If you don't have OpenAL, you can install it. Follow this link http://connect.creativelabs.com/openal/Downloads/Forms/AllItems.aspx and download "OpenAL with OpenAL Installer for Windows".

Create a new ofxTimeline project

Open the ProjectGenerator in of_0073_osx_release/projectGenerator/
Give the project a name
Under the addons tab select the following addons
- ofxTimeline
- ofxTimecode
- ofxMSATimer
- ofxTextInputField
- ofxRange
- ofxTween
- ofxAudioDecoder
Generate project

If you are in Windows VC2015, go to Project Properties -> Configuration Properties -> Build Events -> Post-Build events -> Command Line and paste in the following build event (replace the standard OF command)

     robocopy "$(OF_ROOT)/export/vs/$(Platform_Actual)/" "$(ProjectDir)bin/" "*.dll" /njs /njh /np /fp /bytes
     robocopy "$(OF_ROOT)/addons/ofxTimeline/libs/openal/export/vs/$(Platform_Actual)/" "$(ProjectDir)bin/" "*.dll" /njs /njh /np /fp /bytes
     robocopy "$(OF_ROOT)/addons/ofxTimeline/libs/sndfile/export/vs/$(Platform_Actual)/" "$(ProjectDir)bin/" "*.dll" /njs /njh /np /fp /bytes
     if errorlevel 1 exit 0 else exit %errorlevel%

If you are on OS X, you'll need to add the OpenAL.framework to your project in order to use the AudioTrack

Add a timeline to your code

in your testApp.h file add:

#include "ofMain.h"
#include "ofxTimeline.h" //add timeline include

class testApp : public ofBaseApp{
public:
  ofxTimeline timeline; //inside of the class add a timeline

in your setup of testApp.cpp file set up the timeline

//--------------------------------------------------------------
void testApp::setup(){
  
  timeline.setup(); //registers events
  timeline.setDurationInSeconds(60); //sets time
  timeline.setLoopType(OF_LOOP_NORMAL); //turns the timeline to loop
  
  //add a tracks, etc
  timeline.addCurves("MyCircleRadius", ofRange(0, 200));

in your draw or update function, read the value

//--------------------------------------------------------------
void testApp::draw(){
  //the value of changingRadius will be different depending on the timeline
  float changingRadius = timeline.getValue("MyCircleRadius"),
  //use the value for something amazing!
  ofCircle(mouseX, mouseY, changingRadius);
  //don't forget to draw your timeline so you can edit it.
  timeline.draw();
}

Track Types

ofxTimeline has several built in track types for doing standard timeline tasks.

Bangs

A bang is a simple time marker that sends an event when the playhead passes it. To use a bang track you need a class that listens to bang events, like so:

MyClass.h

  ofxTimeline timeline;
  void receivedBang(ofxTLBangEventArgs& bang);

MyClass.cpp

//--

OfxTimeline

Install / Use

README