Smpte-timecode NPM

smpte-timecode

smpte-timecode is a JavaScript library for operations with SMPTE timecodes.

Features

usable in browser and Node environments;
supports drop-frame and non-drop-frame codes;
instantiate timecodes from frame count, string time code or JavaScript Date() objects;
timecode arithmetics: adding frame counts and other timecodes;
support of implicit conversiont to string (toString()) and number (valueOf());

Usage

const Timecode = require('smpte-timecode')
var t = Timecode('00:15:10;03');
t.add('00:02:30;00');
console.log(t.frameCount);
t.subtract(100); //frames
console.log(t.toString());

Creating Timecode() Objects

Timecode = function (timecode, frameRate, dropFrame) {...};

timecode: number, string or Date
- Numbers are interpreted as frame count.
- Strings are expected as "HH:MM:SS:FF" (non-drop-frame) or "HH:MM:SS;FF" (drop-frame). The constructor will throw if the string contains invalid timecode, for example frame count above framerate or 0 frames in a drop-frame second.
- If Date() is passed, it is converted to the timecode a master clock would have with a given framerate. Month, date and year discarded.
frameRate: number (frames per second) or Array (numerator,denominator), optional
- if a non-integer number is passed that is near 24, 30 or 60, (i.e. 23.97 or 29.97 for example) the fractional 24000/1001, 30000/1001 or 60000/1001 rates will be assumed.
- If an array is passed, the framerate is assumed to be a natural fraction, with first element the numerator and second the denominator (for example, 60000,1001).
- 30000/1001 (29.97) is assumed if the parameter is omitted.
dropFrame: boolean, optional
whether the timecode is using drop-frame or non-drop-frame mode. If omitted, and timecode is a string, the drop-frame mode is determined based on the ":" or ";" characters separating the frames in the timecode parameter. If timecode parameter is not a string, drop-frame assumed for 29.97 and 59.94 framerates, non-drop-frame for all others.

Examples:

var minute = new Timecode('00:01:00:00');
var eightHundredFrames = new Timecode(800,29.97,true);
var nineHundredFrames = new Timecode(900,[60000,1001],true);
var wallClock = new Timecode(new Date());

Note: a direct call to Timecode() returns a Timecode object too, so both direct calls and instantiating with new return the same result:

console.log((new Timecode('00:15:00;00')).toString()); 
// is the same as
console.log(Timecode('00:15:00;00').toString());

Using Timecode() Objects

Once a Timecode object is created, the following member variables are available:

frameCount: number, total number of frames
frameRate: number, framerate in FPS
hours: number
minutes: number
seconds: number
frames: number
dropFrame: boolean, whether timecode is drop-frame or not

The Timecode object also provides the following member functions:

add(x): Timecode, adds x to timecode, x can be a number, Date or Timecode
subtract(x): Timecode, subtracts x from timecode, x can be a number, Date or Timecode
toString(): string, returns the timecode in "HH:MM:SS:FF" or "HH:MM:SS;FF" format
toString('field'): string, returns the timecode in VITC format, where timecodes above 30fps are represented as frame.field, i.e. HH:MM:SS:FF.f
toDate(): date, returns a Date object using today's date and timecode as wall clock
valueOf(): number, returns this.frameCount

For more usage examples, see the unit tests.

Running Tests

To run tests, make sure you run

npm ci

The tests can be run in Node using:

npm test
npm run coverage

To run the tests in a browser environment, open the test/smpte-timecode-test.html file in a browser.

Update History

1.3.5
- packaging fix
1.3.4
- fix for #37 - support for framerates above 100
1.3.3
- fix for #36 - 23.976 is never a drop frame timecode.
1.3.2
- fixed to browser-based tests, documentation.
1.3.1
- Coverage tests changed to nyc
- Support for fractional framerates and framerates above 60fps
1.2.3
- Fix for adding a string-based timecode to already initialized timecode with original framerate (@tommilburn)
- A couple of other date conversion issues (@nkurdybakha & @74ls04)
1.2.1
- Added support for 23.976 fps framerate (@funkelodeon)
1.2.0
- Added support for 59.94 fps drop-frame expressed without fields - i.e. 00:00:00;59 is 1 frame short of a second;
- Added .ToString('field') output in HH:MM:SS;FF.f format;
1.1.0
- Fixed the problem with Timecode.add(0) subtracting the frameCount for drop frame timecodes

Credits

https://www.npmjs.com/package/timecode NPM module, which in the end I decided to rewrite. The things I needed would have been breaking changes for anyone who used it.
http://andrewduncan.net/timecodes/ by Andrew Duncan