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.6
  • fix for #42 - 59.94 and 29.97 non-drop-frame timecodes would not initialize properly
• 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

Legal

License: MIT

Copyright © 2023 LTN Global Communications, Inc. http://www.ltnglobal.com
Copyright © 2017 Crystal Computer Corp. http://www.crystalcc.com