timeBase - a Multi-Layer Timeline Component

timeBase is a customizable multi-layer timeline component that is designed to play and mix media elements. The current Version 15 is posted here (Dec 17, 2019 - see comments) updated from Version 14 (Nov 2019). 

It is intended to be as customizable as possible, with minimal UI and most of its setup and controls via custom parameters on components, making the timeline easier to extend and use. Its internal architecture is a reflection of recently-developed best-practices, so I hope you learn from its internals.  It is currently developed in 099 2019 Official - the 10000 series.

I suggest you start timeBase.xx.tox and click around in the 3 scenes to get familiar with it, reading the doc below. Then delete Scene Test and Scene TestB (rclick the red scene button on left and select Delete Scene), and then make your own scenes and layers as described below.


The timeBase component contains Scenes (scene1, etc) that each act as a separate mixer of Layers. A Scene contains 1 or more layers, and each layer contains a number of Elements placed along the timeline. There are eight+ element types (“effects”) including Movie File, Audio File, Text, Generative, Channels and Events. The scene contains the network that pulls and mixes video, audio and channels from the layers. A scene outputs image on out1 and audio on out2.

Scene: Click the “Scene 1” button on the left to see all the setup parameters for the whole scene… total length, initialization and start (same as the buttons “I” and “S” in the UI), cue time and cue go, On Each Scene component, there are adaptive panel layout parameters of the UI on the Panel2 page of each Scene component.

Layer: Click the “Layer 1” button to get the layer setup parameters. Each layer can be enlarged with the Expand parameter, useful for audio.

Element: Click any element on a timeline. Here you set the start and length of the element, and set the parameters of the specific element type:

Add an element by right-clicking on the background of the layer and selecting an element type that gets placed where you clicked. For example, right-click on the layer and select example Movie File.

There are seven+ element types that can be intermixed on a layer. The current element types (Effects) include: Movie File (with optional audio), Audio File, Text, Generative, Events, Channels and Scene (will play another scene component).

In a layer, click any element bar to show the element’s parameters to the right. The first custom page “Element” is common to all elements. The Animate page contains fade-in/out, Mute and the Keyframe Channels button to create/edit keyframes for the element. The third page is specific to the type of effect – for Movie File it is the movie file name, etc.


Play Range: To play a sub-range of the Timeline, under the viewers at the top is the “Play Sub” sub-range control (grab its bar’s <, > and <> handles to change the sub-range start and end times). Then press “Play Sub” to play only the sub-range.

View Range: “View Range” at the bottom lets you view a sub-time-range of the layers. You can also roller-wheel over the layers area to zoom the time-range.

Viewers - Click the viewers at the top to bring up the parameters of their source layer. Turn on/off viewers via Layer parameter 'Show Viewer'.

Scrubbing Timeline: You can scrub on the bar to the right of the I (Initialize) and S (Start) buttons, and you can scrub in the empty area below the last layer. Or you can scrub on layers where there is no element.

On these scrub areas, if you click and drag your cursor up above the bar, it will always play forward. If you click on the scrub area and drag down off the bar, it will pause after scrubbing.

The row with - and + will single-step. The button with <> will shuttle around the current frame if you click and drag to the left/right off the button while holding down.

Delete: You can delete via a right-click on an element, layer or a scene button, or you can just go into scene1 and delete any layer1, layer2… component, and within a layer you can delete any element1, element2, … component.

Movie FIle Element: After selecting a file on the Movie File page, you can trim what section you want to play and set a speed. This determines the computed movie length. Then on the Element page you can set a start/end there, where the movie is truncated or repeated based on the computed length.  As with all elements, you can fade in/out on the animate page, including audio.

Copy/Paste: You can shift-click several elements to select them, then rclick->Copy Selected Elements, then on any open spot on any layer, rclick->Paste Copied Elements. (Currently they have to be all copied from the same layer.)  You can alternately do copy/paste in the Network Editor itself - they will be discovered automatically (via OP Find DATs). Layers can be copy/pasted by hand too.

Save .toe: a Save button in the UI.

Play Elements in a Loop: Select an element and shift-click another element. Right-click on an element and choose Loop Selected Elements. It will play the range that spans all the selected elements. 

Making Scenes

Putting timeBase in an existing Project: SImply copy timeBase into your existing project, anywhere, but preferably in root as /timeBase. Delete all its scenes (rclick on the red Scene buttons on the left) and add a new Scene (+ at top of UI). (Inside /timeBase, a new scene was created from sceneEmpty1.)

Moving and Timing Elements: After you right-click on a layer and add an element, you can click-drag it along the timeline. Shift-click to select several elements to move. On the element's parameter dialog on the right, on the Element page, you can set the length or end time of an element using various rules using the Element Method menu.

Elements Following Elements: Set the Start Method menu to Follow Element. To make this element follow another element on the same layer, put the element name (e.g. element2) in the Follow Element parameter. If you want your element to follow an element in another layer, you put something like ../layer2/element3.

Mixing Layers: The layers can be mixed in any combination you want. In timeBase/scene1, you select and composite layers as you see fit, and select and mix audio to suit your needs. The default scene typically has layer 1 and 2 screened together, with layer 3 composited over 1 and 2. Layer 4 is used for an audio track, and any audio on movies in layer 1 gets mixed in. But you need to decide how the layers are mixed.

Keyframing: Keyframing is basically implemented. Click Keyframe Channels on the Animate page of elements. You need to manually wire where channels go, prefeably directly from the element*/animate COMP's viewer.

Element Types

Movie File Element: See Movie File Element above.

Audio File Element: On the layer where you create an Audio File element, turn on the Expand parameter to see a rough sonograph. Each element has its own audio level, and there is a master level on each Scene's UI. The scene's output 2 has the mixed audio for that scene. The first 5 scenes' audio is mixed and sent out the second output of timeBase.

Text Element: Simple component for placing text in a layer. Yuo may want to add features to this, so see Adding Features to an Existing Element Type below.

Generative Element: This is the open playground of timeBase where you can put anything in an element and it will run only while the timeline is at the Generative element.

Event Element: Event elements run one python command on start and one command at end. The easiest thing to do is to put a 1-line python command in the Run Command On parameter. The default command does nothing, but if you un-comment it to read  parent.Scene.par.Play = 0, the scene will pause when it reaches the element's start frame. (When the scene pauses, click timeBase’s play/pause button to continue.) Beyond running a command at the end of the element, the Event element can be customized internally similar to Generative elements.  See the Generative element to learn how you can customize the Event element.

Channels Element: This doesn't do much since all elements have Keyframe Channel on their Animate page. But it's set up to output a third OP from the element (image and audio being the first two) and you can route it to suit your needs.

Movie Spec Element: The most common case will be to use the self-contained Movie File elements as described above.  Movie Spec elements let you refer to a Movie Spec component, which defines a movie, color/cropping treatments, and multipe cues you can set to split a file into parts without changing the file or writing anything out. A single Movie Spec can be used in multiple elements in timeBase. Movie Spec Elements are created and edited using the moviePlayer component in the palette. See its built-in Help.

Scene Element: Scenes playing Scenes - A scene can embed another scene. One element type is 'Scene' which lets you point to another scene. Just make sure a scene isn't being played by two Scene elements at the same time.  WARNING: In version 15 there is a mis-labelled parameter: The Parameter “External Master Scene” is labelled wrong. It should be “External Master Scene-type Element”, and should contain a path to an element such as:  parent.TimeBase.op(‘scene1/layer1/element2’).

Things of Note

  • timeBase is a community contribution, not an official 'product'. Use it if it's useful for your work, mod it and share, learn from it, no guarantee of support, roadmap, or assurance it will do what you want.
  • timeBase is highly procedural with minimal scripts, many parameter expressions. It uses Parent Shortcuts extensively (parent.Scene, parent.Layer, parent.Element, parent.TimeBase), Binding, Internal Parameters, Read-only parameters.
  • When altering things in the Network Editor, the scenes, layers and elements should be named scene#, layer# and element# where # is an integer 1 or above.
  • When it's time to run it without a UI, you can un-cook or remove timeBase/scene*/ui to get a bit of speed improvement.
  • Change the overall size with Width and Height of /timeBase. You can adjust a scene's Layer/Viewer Split parameters on its Panel2 page.


Customizing Elements

Customizing a Generative Element: Every element (layer1/element1, element2…) has common parts. Every element type has a built-in default effect (element1/effect) . For example, the effect in a Text element is a simple Text TOP connected to a few parameters on the Text Element.

Generative elements (and Event elements and Channel elements) are meant to be customized in a way that every generative element has nodes that are different than others (you can actually customize any element). If scene1/layer1/element2 is a Generative element, you can go into element2 and make the 'effect' component Clone Immune (see wiki for "Immune") and edit effect's Custom parameters and its interior network.  In element2/effect you need to keep selectTimer as-is, and make sure out1 remains a TOP output, and out2 as an audio CHOP output, even if you are not using them. 

You can copy/paste the element by hand in the Network Editor into any scene's layer.

Generative Elements outside timeBase: Often you will have a bunch of generative components that you want to run in timeBase, but they are located outside timeBase. To set it up properly, you need to enhance your generative components with parameters and nodes that will be described here. First create a Generative element in a layer. Let's see how it's constructed. Go to the element in the Network Editor, say it's /timeBase/scene1/layer1/element2. Inside it is a component called 'effect', which is used to help customize element2. Copy 'effect' to the network where your generative components are (or will be) located. Rename it, say you all it myeffect. You will see errors. The element and its effect are related to each other via their Internal Shortcut 1 parameters on their Common pages.  So make the Internal OP 1 parameter of myeffect point to where the element is located, something like /timeBase/scene1/layer1/element2, You need to also point the other way: Make the Internal OP 1 parameter of /timeBase/scene1/layer1/element2 point to where the effect is now located, something like /generative/myeffect.

Then everything inside /generative/myeffect will get played on the timeline for element2. (To make it more modular, you can put a name in the Global OP Shortcut parameter of /timeBase and /generative like 'TimeBase'  and 'Generative', so you can refer to each with op.TimeBase and op.Generative from anywhere in your project.)

Inside /generative/effect you can add what you want, but you need to keep selectTimer plus out1 (a TOP for images) and out2 (a CHOP for audio). 

If you have a pre-existing generative component, you can merge the two. If you want to retrofit one of your existing components with the right parts: Set the parameter Parent Shortcut set to 'Effect'. Set the parameter Internal Shortcut 1 to 'Element' Set Internal OP 1 to the path of the element. Inside you need the nodes selectTimer, out1 and out2. selectTimer can be copied as-is from an existing effect component. Wire your image output to out1, and at least keep a stand-in for the audio, which you can get from effect/select2. Finally hook in selectTimer channels to you existing component, using any of its channels, like timer_seconds, timer_pulse, running or  donetimer_seconds starts counting when timeBase plays element2. Wherever your effects are, they must have the same barebones internal structure that you find in a default Generative element's effect component.

Note also that you can get the scene's resolution using the expression in the stand-in Ramp TOP of effect2.  Access to things relative to the element use this in the experssion: parent.Effect.par.Element.eval().

Adding Features to an Existing Element Type

Let's say you want all Text element types to have a feature that is not there or is not exposed. The best is to change the clone master component for the Text elements so all Text elements, for example, have an Italics option. The master Text element is located at /timeBase/scene0/layerMaster1/elementText1.

Create a new custom parameter on elementText1. The easiest would be this: Go to /timeBase/scene0/layerMaster1/elementText1/effect/text in the network editor and go to the Font page. Then bring up the Component Editor for elementText1 by right-clicking on the word elementText1 in the path at the top of the network editor and select Customize Component. Now you should have the Component Editor in a floating windiow for /timeBase/scene0/layerMaster1/elementText1. Go to its Text page.

Drag-drop from the Italics parameter of the Text TOP to the Parameter area of the Component Editor. If you get a menu asking about binding, select Bind New Par as Master. (Otherwise you bind the new parameter via the parameter dialog of text and elementText1 or any other way where elementText1 is the master.)

This will of course propagate to all the Text elements in your timeline. Select any Text element in the timeline and go to its Text page. Turn on the Italics parameter there. Put your play bar in timeBase anywhere during the Text element. You should see it in a viewer at the top.

You can also add operators in elementText1/effect etc. and hook them up to custom parameters on elementText1.

Making a New Element Type: If you are going to use this customized element in a lot of places, you can make this a new element type. See scene0/layerMaster1 and create a new element type, then add it to the menu at scene0/menuItemsBackdrop. Turn off the Immuning of your new element type's 'effect' component so all changes in you master get propagated to your elements on the timeline.

You can give your new element type more outputs at your discretion, as long as you select it in the element, (see element2/select1 and select2), output it in the element like as out3, and use it in your scene.

Saving all your Scenes and States to JSON file

Version 15 lets you save the full state of your work in a .json file so when Version 16 and later come out, you can migrate to the newer version. If you are running Version 15, go to timeBase and on the saveRestore component, press Save to TimeBase.1.json. It will create the file... note it's rigid - it doesn't auto-increment. If you are currently running Version 14, then copy the component saveRestore from Version 15 into Version 14, and press Save to TimeBase.1.json.   Then go into your newer version of TimeBase, go to saveRestore and press Restore from TimeBase.1.json. It will recreate your scenes, layers and elements from your previous version.


Mod: Please take this component apart or mod and use it with TouchDesigner as you please.

Future: Version 16 will use numerous new TouchDesigner 2019.30000 features. Then optimizations, rubber time, better keyframing.

[ Inception: I started working on this intermittently after the Day For Night festival (Dec 2017) after looking at the terrific digital installation art and talking to the 27 other TouchDesigner users there. At that point I decided to stop talking about timelines and just make one. ]

Asset Downloads