Timecode
What is timecode for?
Timecode is a running clock in the form hours:minutes:seconds:frames (00:12:34:07) that is shared between machines. A band's playback computer, a lighting desk, a video server and a DAW can all be told "it is now 00:12:34:07", so they stay in step with each other without anybody pressing buttons at the right moment.
EWOCvj2 can follow such a clock and do things at fixed moments of it. You write a cue list (a table: "at 00:01:30:00 launch this shelf element, at 00:02:10:12 go to the next clip of layer 1, at 00:03:00:00 switch to scene 2") and the program fires the cues when the timecode passes them. Optionally the layers that a cue launched can also chase the timecode: they play the part of the video that belongs to the timecode position, so that a locate in the DAW puts the video at the right place too.
Timecode only exists in live modus. In preview modus there is no TIMECODE button, no table and no cue firing.
Opening the table
The TIMECODE button sits above the live/preview modus button. It opens the timecode table. While it is open, small copies of the deck and mix monitors are shown under the loopstation block, so you keep an overview of the output.
Close the table with CLOSE (top right). The cues keep firing when the table is closed. Switching to preview modus closes it.
Sources
Choose the clock that the program follows with the SOURCE button, which opens a menu with the choices.
| Source | Where the clock comes from | Notes |
|---|---|---|
| OFF | nothing | No cues fire. |
| MIDI (MTC) | MIDI timecode on a MIDI input | Needs the input to be opened in the preferences (Input devices tab). The IN menu in the second header row takes the timecode from any opened port, or from one port only. 24, 25, 29.97 and 30 fps. A locate (full frame message) is recognised. |
| ART-NET | ArtTimeCode packets on UDP port 6454 | The IN menu takes the timecode from any sender, or from one sender only (an IP address; the menu lists the senders that were heard in the last seconds). The port is shared with other Art-Net software only if that software allows it. |
| LTC | linear timecode as audio | See below. |
| INTERNAL | a clock inside the program | Start, stop and set it yourself. Can also be the master for other machines (see Timecode out). |
An external source tells its own frame rate, and the table follows it. The frame rate that you choose with FPS is used by the internal clock, and for writing the labels while there is no signal.
LTC
LTC is timecode recorded as an audio signal. It is the choice for a timecode that has to travel on a cable or an audio line, or that is played from a sound file. The input is read as follows:
- LTC IN (second header row, visible while LTC is the source) chooses the audio input. The first choice, beat device, uses the Beatmatch input device, which is also what the beat detection listens to. That stream is shared, so nothing extra is opened. Any other recording device gets a stream of its own, so LTC and the beat detection can listen to different devices.
- LTC CH chooses the channel: mix (both channels averaged), left or right. Take left or right when the other channel carries music. A channel of its own always uses a separate stream, also on the beat detection's device.
- A separate stream is opened at the device's own sample rate. The shared stream of the beat detection is fixed at 44.1 kHz, which costs very little timecode precision (an edge of the signal is located to a fraction of a sample), but a separate stream is drained at once and therefore recommended for shows.
The decoder follows the level of the signal by itself (any input level, any DC offset), locates every edge between two samples, checks every decoded frame (decimal digits, ranges, an even number of zero bits as the standard demands) and believes the first frame after a start only when the next one follows it. The frame rate is read from the frame numbers it sees (24, 25 or 30) so a few percent of varispeed does not confuse it, and 29.97 drop frame is recognised by its flag. Reverse play is not decoded.
LTC in a show
For rehearsals, LTC on the beat detection's device works fine. For a show, give LTC an input stream of its own: choose left or right in LTC CH (this opens a separate stream also on the beat detection's device), or choose another device in LTC IN. Choosing the beat detection's own device with mix shares its stream. A separate stream runs at the device's own sample rate and is emptied the moment audio arrives, while the shared stream is read by the beat detection loop and is resampled to 44.1 kHz. It also keeps music on the other channel out of the timecode. Keep the LTC signal fairly hot and free of effects, and watch the jitter figure in the diagnostics: a steady source shows a small, steady number.
The header of the table
First row:
- SOURCE: the clock, see above.
- FPS: the frame rate: 23.976, 24, 25, 29.97, 29.97 drop frame, 30, 48, 50, 59.94 and 60. A source that sends its own rate shows that rate. Frame rates above 30 only exist for the internal clock and for the labels: MTC, Art-Net and LTC themselves carry 24 to 30 fps (50 and 60 fps material runs its timecode at 25 and 30).
- Offset (ms): moves the position to make up for latency. Positive values make cues come earlier. The delay between reading the position and the frame being on the screen (one frame period) is already added automatically; the offset is for what comes after the screen (projector, LED processor) and for the delay of the timecode source itself. The CALIBRATE button helps to find it.
- Position: the clock, as the cues read it. Green while it runs. For the internal clock the position can be typed, see Typing a time.
- PLAY / STOP, RESET (internal clock): start and stop the clock; reset stops it and sets it back to 00:00:00:00.
- Freewheel (ms) (external sources): see Signal handling.
- OUT: timecode output, see below.
- CLOSE.
Second row:
- + CUE: adds a cue at the current position (or one second behind the last cue when there is no position).
- CHASE: the layer chase, see below.
- Pre-roll (ms): how long before their time cues start loading their files, see below.
- CALIBRATE: latency calibration.
- Status and the NEXT cue: NO SIGNAL, LOCKING, LOCKED, FREEWHEEL, RUNNING or STOPPED, followed by the name and time of the cue that fires next.
- Diagnostics: jitter (how far the arriving positions lie from the smoothed clock, a measure for the quality of the source), cue (how late the last cue fired against its time) and lag (how many frames the decoders of chased layers are behind the frame the timecode asks for). With LTC, MTC or Art-Net as source, the input choices take the room and the diagnostics are shown in the strip at the bottom of the table. Hover over any box for a tooltip.
The cue list
Each row of the table is a cue:
| Column | Meaning |
|---|---|
| ON | Green: the cue fires. Click to switch it off or on. |
| TIME | When the cue fires. Yellow once the timecode has passed it. |
| ACTION | What it does (click to list the actions). |
| TARGET | What it does it to; the format depends on the action. Red text means the target does not fit the action. |
| NAME | A free name, for looking at the list. |
| colour swatch | A colour for the row, for looking at the list. Click and choose from the palette. |
| DUP | Adds a copy of the cue right behind it. Change its time to move it. |
| DEL | Deletes the cue. |
The row of the cue that fires next has a light blue border. The table shows 9 rows; with more cues the mouse wheel scrolls.
Typing a time
A time is not edited as one piece of text but as four parts. Click one of hh, mm, ss or ff: it is inverted and takes digits (nothing else). When you have typed two digits, the next part gets the focus (after the frames it wraps around to the hours). The colons are never edited. Tab and Shift+Tab (or the arrow keys) move between the parts, Backspace removes a typed digit, Return sets the time, Esc cancels, and a click outside the cell sets the time too. Minutes and seconds are limited to 59 and the frames to the frame rate minus one.
Actions and targets
Cues run as OSC messages, so everything that a cue does can also be done from an OSC controller (see the OSC chapter).
| Action | Target | Does |
|---|---|---|
| CLIP NEXT | A1 | The next clip of the queue of layer 1 of deck A. |
| PLAY / PAUSE / STOP | A1 | The transport of layer 1 of deck A. |
| JUMP | A1 0.25 | Moves layer 1 of deck A to a quarter of the video (position 0 to 1). |
| SHELF | A2 5 B3 | Triggers element 5 of bank 2 of shelf A into layer 3 of deck B. Bank and layer are always given. |
| SCENE | A2 or 2 | Switches deck A to scene 2, or both decks. |
| LPST START / LPST STOP | 3 | Switches the loop play button of loopstation line 3 on or off. |
| LOAD BIN | my bin A1 3 | Loads block 3 (1 to 9) of the bin called my bin into bank A1 (A1 to A4, B1 to B4). Choose the bin with the BIN menu in the target cell, then type the bank and block. Loading takes some time, so put this cue a bit before the first cue that uses the newly loaded bank. |
| OSC | /mix/output/deckA/layer/1/opacity 0.5 | Any OSC message. |
Layer chase
With CHASE on, the layers that SHELF and CLIP NEXT cues launch follow the timecode. A layer chases as follows:
- It plays the frame that belongs to the timecode position: the position since the cue, folded by the loop or bounce setting of the layer. A play-once video stops at its end.
- After a locate (the position jumps, or the first position arrives) the program relaunches, for every layer that a SHELF cue has filled, the last cue before the new position, so the layers show what belongs at that moment.
- A layer with a clip queue is brought to the right clip after a locate. The program replays the history from the SHELF cue to the new position: every CLIP NEXT cue of that layer advances the queue, and a clip that plays once and ends starts the next one (a looping or bouncing clip only advances by cue). It then loads the clip that belongs to the position, with the queue in the order it would have had, and chases it from the moment that clip began. This needs the length of every clip in the queue, which is read from the video files (the first locate that needs a file can take a moment). It assumes that the layer's speed has not been changed by hand or by cue since the SHELF cue, and that the queue was not changed by hand.
- When a chased layer reaches the end of a play-once clip that has a queue, the next clip is started from the end moment, so a queue stays in step.
Pre-roll
A video takes time to open and decode, so it would appear a little after its cue time. With a Pre-roll above zero, a SHELF cue for a video, layer, deck or mix (and a CLIP NEXT cue) fires that many milliseconds early. The file is loaded and waits while the old layers stay visible, and it appears exactly at the cue time. Choose the pre-roll longer than your slowest file takes to load. For a CLIP NEXT cue the old clip keeps playing until the new one takes over. For decks and mixes, the global values that a deck or mix changes (crossfade, deck speed, scroll position, wipe) and the clearing of the loopstation are applied at the cue time too. While a file waits, other launches and layer swaps wait as well, because the swap barrier is global.
Cues with a pre-roll of zero fire one half display frame early, so the nearest display frame gets the cue.
Accuracy and signal handling
- Look-ahead. The cues read the position as it will be on the screen: one frame period ahead of the moment of reading. Use the Offset for everything that comes after the screen output and for the delay of the source.
- Calibration. Press CALIBRATE: the output windows flash white at the start of every timecode second. Compare the flash with whatever the timecode has to be in step with (a click track, a light, a camera film of both) and move the Offset until they coincide. CLOSE ends the calibration. It is measured by eye (or by a camera): the program has no sensor for the output.
- Smoothing. Positions arrive with jitter (MIDI and network timing, audio blocks). A small phase-locked clock runs between them, so cues do not jump with every packet. A position that lies more than 100 ms off is believed only when the next packet agrees; a stop, a locate or a change of frame rate takes over at once.
- Lock. After five steady packets within a frame the source is LOCKED; until then LOCKING.
- Freewheel. When an external source stops sending, the clock keeps running for the freewheel time (the Freewheel (ms) slider) so a short dropout (cable, audio glitch) does not stop the show. A sender that is really stopped looks the same, so the clock runs on past the stop for this long. With 0 the position holds as soon as the packets stop. The status shows FREEWHEEL while this happens.
- Jumps. A jump backwards, or forwards by more than a few seconds, fires no cues; it only marks which cues lie behind the new position. With CHASE on, the layers are rebuilt for the new position.
Timecode out
The OUT menu lets the program send the position on, so that other machines can follow. With the internal clock as source, the program is the master; with any other source the position is re-sent as it arrives (without the offset), also in another format.
- MTC: sent to a MIDI output port. Choosing MTC in the OUT menu opens a list of the MIDI output ports; the first entry is the MIDI clock output port of the preferences (Input devices tab).
- Art-Net: broadcast on UDP port 6454.
- LTC: played on an audio output device. Choosing LTC opens a list of the audio output devices; the first entry is the default output device. The signal is generated at the sample rate of the device.
A standard foldout menu opens when you choose the output, so the choice does not take room in the header. The current choice is marked with a "v". To change the port or the device later, rightclick the OUT box. Click outside the menu to close it without a change. The choices are saved in the preferences.
Only 24, 25, 29.97 drop frame and 30 fps can be sent (23.976 goes out as 24). The LTC output has no polarity correction and no level setting.
Importing and exporting the cue list
The strip at the bottom of the table has:
- IMPORT: adds cues from a file. A CSV file is read with the columns of the export (enabled, time, action, name, target, color) or as a marker list of a DAW (the time from a Start, Position or Time column; the name from Name, Marker or Description; times as timecode, as seconds or as h:mm:ss.mmm). Cues without an action column come in switched off, so nothing fires before you have chosen the actions. A CMX3600 EDL file (recognised by its .edl extension or its TITLE line) makes a cue at the record-in of every video event, named after the reel or the clip name, and one at each
* LOC:marker with its colour. EDL cues come in switched off too. They use the table's frame rate, and the FCM line decides drop frame at 29.97. - EXPORT: saves the list as a CSV file.
- SHIFT ALL: moves every cue by an amount. Choose the sign (click the box, or type + or -) and the amount (typed per part, like a time), then Return.
Undo and saving
Changes to the cue list are part of the normal undo history, undo and redo step through them in the order they were made. Changes to the clock settings (source, frame rate, offset, freewheel, output) are not part of the undo history.
The cue list is saved in the project. The source, frame rate, offset, chase, pre-roll, freewheel, output and the LTC input settings are saved in the preferences.