netflix-skunkworks/framerate-utils

Useful conversion utilities for working with video frame rate and display

JavaScript Framerate Utils

Utilities for formatting and converting times to frame rates

Installation

npm install --save framerate-utils

Example usage

import { fromTag, secondsToSmpte } from 'framerate-utils';

const fr = fromTag('FPS_2397');
const seconds = 100;
const smpte = secondsToSmpte(fr, seconds);

console.log(smpte);
// output 00:01:39:21

API

There are numerous functions and constants available for use. While looking through methods if you come across a frameRate argument, you will need to create one first and pass that in.

This FrameRate object has the following shape:

{
  rate: number // The frame rate
  numerator: number // The numerator of the frame rate multiplier
  denominator: number // The denominator of the frame rate multiplier
  dropFrame: bool // drop mode, true - NTSC drop frame, false - non drop frame
  fps: number // The effective frame rate in frames per second (rate * (numerator/denominator))
}

And can be created using the following code:

import { create } from 'framerate-utils';

const frameRate = create();

Constants

• SECONDS_PER_HOUR
• SECONDS_PER_MINUTE
• MILLISECONDS_PER_SECOND
• TICKS_PER_SECOND

Functions

• create(rate = 24, numerator = 1, denominator = 1, dropFrame = false) - Creates a new FrameRate object
• secondsToSmpte(frameRate, seconds) - Returns seconds converted to SMPTE time.
• smpteToSeconds(frameRate, smtpe) - Returns SMPTE time converted to seconds.
• smpteToMs - Returns SMPTE time converted to milliseconds.
• msToSmpte - Returns milliseconds converted to SMPTE time.

For all functions view the src/index.ts file.

framerate-utils's Issues

Switch from webpack

Webpack consistently has breaking changes between releases which is great for fast moving projects, but this one is hardly ever updated. It should work every time and updating development dependencies should not always require fixing break changes.

Convert to TypeScript

Managing typings is getting too problematic and all of our internal video code will be using TypeScript moving forward.

Add `roundedRate` to FrameRate object

When parsing and working with SMPTE strings, it can be convenient to have the rounded rate handy for certain tasks.

For instance, at the moment I want to know if a given SMPTE input has a frame input within the limit, so that I can write a isValidSmpte function.

i.e.; for a framerate of 23.976, 00:00:00:23 would return true, but 00:00:00:24 would return false.

Drifting when converting back and forth

When converting a SMPTE time code to a frame manually, and then back again, it leads to a drift by 1 frame.

For instance, consider this code:

function smpteToSmpte(frameRate, smpte) {
  const pieces = input.split(':').reverse();

  const parts = {
    frames: pieces[0],
    seconds: pieces[1],
    minutes: pieces[2],
    hours: pieces[3],
  };

  const frame =
    Number(parts.frames) +
    secondsToFrame(frameRate, Number(parts.seconds)) +
    secondsToFrame(frameRate, Number(parts.minutes) * 60) +
    secondsToFrame(frameRate, Number(parts.hours) * 60 * 60);

  return frameToSmpte(frameRate, frame);
}

Inputting 00:00:11:16 with a 24fps FrameRate will return 00:00:11:15.

This function is necessary to write an algorithm that allows users to enter "invalid" SMPTEs, such as 00:00:00:25 and have it convert it to 00:00:01:01