FileMaker Pro TimeCode Plugin - Manual

What the Plugin does

Quick Facts

  • Arithmetic and Conversion functions for film and video.
  • Takes and makes timecode, decimal seconds, frame counts, feet & frames.
  • Adds, subtracts, multiplies and divides.
  • Most Conversions are based on frame counts.

The current version of the Plugin is 1.0.0. It is available for download here.

A More Detailed Overview

The TCFXM Timecode Plugin provides Arithmetic and Conversion functions dealing with timing and length values in film and video post production to FileMaker Pro users. It is usable in both 32 and 64 bit.

The plugin takes parameters as timecode, decimal seconds, frame counts, as well as feet & frames.

The plugin can add, subtract, multiply and divide values in each of these formats. Formats can be mixed, e.g. you can add feet & frames to a timecode. Results will be formatted to match the first input parameter.

There are conversion functions to from any to all of the four formats. These conversions keep the number of frames constant, and thus can change running time.

For convenience, there is a function that converts from one timecode format to another timecode format, where the running time is kept constant. This function is likely to incur rounding errors.

There is a function to conveniently add the appropriate colons or semi-colons to a value that has only numbers.

For timecodes at 24, 25, 48 and 50 fps only, there is a pair of functions that lets you simulate the effect of converting to and from drop-frame timecode - which does not exist for these formats. This might be most useful for 24 fps timecode used for 23.98 fps.

The plugin expects frame rates, as well as frames per foot, entered according to industry standards.

(To find out how to get the plugin, go here.)

Using the Plugin

Accessing the Plugin

The plugin provides functions that are available in FileMaker's "Specify Calculation" window. Two places to get this window are when you define a field as a Calculation, or when you use the "Set Variable" Script Step.

The functions provided by the plugin are listed under "TCFXM Timecode Plug-in" in the lower right. The function seen above uses three input parameters, here those are given as field names. Note that there are no quotes around the field names. They can also be entered as literal values, for example as 25 for the number 25, or as "30d" as text.

Number Formats / Counts

The four format types listed below are referred to as 'counts'. They are recognized automatically and can be used interchangeably. When counts are not entered to the specifications below, the calculation is aborted, resulting in a '?' in FileMaker.

Format Description Examples
Timecode 11 digit text where 4 pairs of digits are separated by colons, semicolons or periods. See below for exceptions* 01:23:12:13
10;18;45;12
00.11.22.11
1:18
9;34;09
12.01.22
Seconds decimal number, using period or comma as decimal point 113.4
2288,0
Frames number, using only digits 22517
2288
Footage feet and frames, separated by either + or &
The separating character has no effect of how the value is parsed.
18+12
327&37

*Timecode can be entered with fewer than 8 numerical digits. So 1:18, 12;15 and 8.34.06 are all valid timecode entries. The plugin will add in the missing leading zeros. However, entries with a single decimal point, like 12.15, will be treated as seconds.

Functions

Arithmetic Functions Conversion Functions - from and to any number format
TCFXM_Add TCFXM_To_Frames
TCFXM_Subtract TCFXM_To_TC
TCFXM_Multiply TCFXM_To_Seconds
TCFXM_Divide TCFXM_To_Footage

All of these functions internally convert to and from frame counts. This means: 1:20 @ 30 fps added to 1:01 @ 24 fps is turned into 50 + 25 = 75 frames. That then gets converted to the format of the first count. Here, that would be 75 divided by 24 = 00:00:03:02 @ 24 fps.

Timecode Format Conversion
TCFXM_TC_ConstantTime_Convert

This function is strictly time-based, it does not convert to frames internally. So, 11:09:29 at 30n converted to 24 becomes 11:09:23. This function is likely to incur rounding errors.

'Literal' Conversion to Timecode
TCFXM_NumericalText_To_TC

This function takes a string of digits, treats them as a timecode and adds the missing colons or semicolons. For example, 23141520 becomes 23:14:15:20. The result is always a full 11 digit timecode, as the input is 0-padded.

Timecode Pull Down or Up
TCFXM_TC_Pull_Down
TCFXM_TC_Pull_Up

These two functions only work with timecodes in 24, 25, 48 or 50 fps. They simulate the effect of conversion to and from drop-frame timecodes - which don't exist for these rates. Primarily, these functions can help answer questions like how much real time has actually passed after playing 01:23:48:11 worth of footage at 23.98 fps?

Internally, the frame counts are multiplied by 1000 and divided by 1001, or vice versa. The subsequent rounding to whole frames incurs rounding errors.

Frame Rates

To control the formatting of time codes that go beyond midnight, in other words: before 00:00:00:00 or after 23.59:59:23, there are two different kinds of Frames-Per-Second specifications. See Timecodes Beyond Midnight for details.

Here is the regular flavor:

Count Type Frames per Second
Timecode
Seconds
Frames
24, 25, 30, 30n, 30d
48, 50, 60, 60n, 60d

n is for non-drop frame timecode, d is for drop frame timecode. If neither n or d is specified, n is assumed. Drop / non-drop timecode is determined solely by the rate parameter, the character used in the count (';', ':' or '.') is ignored.

The second Frames-Per-Second kind specifies a long output format for timecodes only:

Count Type Frames per Second - Long
Timecode l24, l25, l30, l30n, l30d
l48, l50, l60, l60n, l60d

The only difference to the first kind is the prefix "l", a lower-case "L". The absence or presence of the "l" controls the formatting of time codes that go beyond midnight. See Timecodes Beyond Midnight for the difference in formatting.

Count Type Frames per Foot
Footage 16, 20, 40

The plugin will ignore the separating character between feet and frames (+ or &). The number of frames in each foot is solely determined by the frame rate.

Count and Rate Combinations

The count and the rate have to fit together, otherwise the calculation is aborted, resulting in a '?' in FileMaker. The possible combinations are listed in the three tables above.

For example, a count of 17+12 can't have a format of 24. (17+12 is a footage, a compatible rate would be 16. A rate of 24 would be acceptable for any of: 00:23:11:09, 12.8, 442816.)

Function Syntax in FileMaker Pro

Most of the listed parameters are mandatory, only the ones in curly braces '{...}' can be omitted.

Arithmetic

TCFXM_Add( count; rate; count{; rate} )
TCFXM_Subtract( count; rate; count{; rate} )
TCFXM_Multiply( count; rate; factor )
TCFXM_Divide( count; rate; divisor )

Notes:

  • The result is formatted to match the first input count.
  • Any combination of the 4 count types is permitted.
  • For addition and subtraction the fourth parameter is optional. If it is not entered the rate of the first count is applied to the second count.
  • The factor / divisor is a positive or negative either decimal or whole number.
  • Multiplication and Division both incur rounding errors.

Format Conversions

TCFXM_To_Frames( count; rate )
TCFXM_To_TC( count; in_rate; out_rate )
TCFXM_To_Seconds( count; rate )
TCFXM_To_Footage( count; in_rate; out_rate )

Notes:

  • The result's count type (obviously) depends on the function used.
  • Any of the 4 count types can be used with any of the these four functions.

Timecode Conversions

TCFXM_TC_ConstantTime_Convert( count; in_rate; out_rate )

Notes:

  • This function only takes timecode as a count.
  • Internally the timecode is converted into seconds. The subsequent rounding to whole frames incurs rounding errors.
TCFXM_TC_Pull_Up( count{; rate} )

Notes:

  • This function only takes timecode as a count.
  • Internally, the frame counts are multiplied by 1001 and divided by 1000. The subsequent rounding to whole frames incurs rounding errors.
  • The rate has to be one of 24, 25, 48 or 50. Otherwise the function fails and yields '?'.
  • If the second, optional rate parameter is omitted the default of 24 is assumed.
TCFXM_TC_Pull_Down( count{; rate} )

Notes:

  • This function only takes timecode as a count.
  • Internally, the frame counts are multiplied by 1000 and divided by 1001. The subsequent rounding to whole frames incurs rounding errors.
  • The rate has to be one of 24, 25, 48 or 50. Otherwise the function fails and yields '?'.
  • If the second, optional rate parameter is omitted the default of 24 is assumed.

Text to Timecode

TCFXM_NumericalText_To_TC( count; rate )

Notes:

  • This function only takes positive numbers with 1 to 8 digits as a count, e.g. 01120023, resulting in 01:12:00:23.
  • The frame rate has to be suitable for timecodes.
  • If the count has fewer than 8 digits, zeros are added to the head of the number. Thus, 2312 becomes 00:00:23:12.

TCFXM_To_TC and TCFXM_TC_ConstantTime_Convert compared

The fundamental difference between TCFXM_To_TC and TCFXM_TC_ConstantTime_Convert is that the former preserves the frame count, and the latter preserves the running time.

With an input of count: 10:10 in_rate: 24 out_rate: 30, here is what happens:

Function Result Methodology
TCFXM_To_TC 00:00:08:10 10*24 frames + 10 => 250 frames
250 divided by 30 => 8 seconds, 10 frame remainder
TCFXM_TC_ConstantTime_Convert 00:00:10:13 10 + 10/24 secs => 10.416667 secs
10.41667 * 30 fr => 10 secs 12.5 fr
12.5 fr rounded up to 13

Value Overflows

Whenever timecodes are entered using impossible values, such as 00:80:00:00, where 80 minutes are not strictly 'legal', the plugin converts to a proper output. In this case, that would be 01:20:00:00.

For frames, seconds and minutes this behaviour produces results that are equivalent to the overflowing values. Above, 80 minutes are exactly the same as 1 hour and 20 minutes.

This also works for feet & frames, e.g. an entry of 150+48 at 16 is not strictly correct, because a foot only has 16 frames. The plugin turns the 48 frames into 3 feet, for a result of 153+00.

Timecodes Beyond Midnight

Regular Formatting

When the rate parameter is specified as non-long, i.e. without a leading "l" (a lower-case "L"), the timecodes roll over much like the time code display on a tape deck would.

When timecode hours flow over, the real value would be in the next day, so to speak: a timecode value of 29:00:00:00 could be thought of as 1 day and 5 hours. However, since there is no day count in timecode, the extra day is simply omitted. Thus, 29:00:00:00 simply becomes 05:00:00:00.

When 'crossing midnight' in the other direction, e.g. by subtracting 12:00:00:00 from 08:00:00:00, the result would be a negative timecode (here: -04:00:00:00). The plugin instead converts to the corresponding value 'on the previous day'. Here that would be 20:00:00:00, i.e. 4 hours before midnight.

Long Formatting

When the rate parameter is specified as long, i.e. with a leading "l" (a lower-case "L"), the timecodes can overflow midnight (or 23:59:59:23). Timecodes with more hours than 23 are simply left alone, i.e. shown as they are. This allows for values like 33:00:00:00, and 1232:00:00:00.

However, long timecodes can not underflow 00:00:00:00. Any negative timecode values produce an error string shown in the field in question.

Long Formatting - Possible Hiccup

Sometimes you will see a long timecode displayed like this: 239103422 where you expect to see it like this: 239:10:34:22.

There are two possible fixes. The first one is to set the 'Data Formatting' in the Inspector while in Layout Mode for the field to 'As entered', like this:

The other fix, probably the better one, is to set the calculation's result in the 'Specify Calculation' dialog to 'Text', like this:

Generally FileMaker seems rather forgiving when it comes to selecting the result type, long timecodes might be the exception. Regardless, the Plugin deals with all types and processes them as Text.

Usage Hints

Function Parameters that contain Text

When you enter a count parameter for a drop-frame timecode, it would be tempting to just write 30d - but this will not work. FileMaker will look for a data field named 30d. (It is smart enough to assume that 30 is meant to be a literal number.) Whenever a literal function parameter contains a letter you will need to include that value in a pair of quotes, like this: "30d".

Nothing is Zero

An empty field - not be confused with a field containing an empty 'Text', like "" - is interpreted by the Plugin as an input of '0', the number zero.

Speed-Select a TCFXM Function for a Calculation

When you enter a calculation in FileMaker and you want to use a function from the TCFXM TimeCode Plugin, you can follow these steps to save some typing work:

  • get to the window titled 'Specify Calculation'
  • press the tab key until you reach the search field
  • type 'TC' on the keyboard
  • the function list now only shows the functions from the plugin, and it's easy to double-click the one you want to use.

Alternatively, you can just enter 'TC' in the calculation field, and use FileMaker's text completion feature. Use arrow-up and arrow-down to select the function you want and press return.

Plugin Version Check

To check the version of TCFXM that is currently installed, open FileMaker's Preferences window. Under the 'Plug-Ins' tab, click the line 'TCFXM Timecode Plug-In' so that it is highlighted. The version number will be listed under the text field.