Simple conversion utility for human-readable Timecodes.

Changelogs

v2.0.0

Released on April 20, 2026, this update improves the readability of inputs and outputs, adds several important helpers, and makes several quality-of-life improvements.

Breaking Changes

• Timecode.mod() now mutates the Timecode object and returns this.
• Timecode.toClock() now displays days.
• TimeStrings with trailing numbers without a unit may be treated as a different unit depending on the previous unit.
• Timecode.toTimecode() is now deprecated and should no longer be used. It may be removed in a future update.
• Default minimum value is now Number.MIN_SAFE_INTEGER.
• Default maximum value is now Number.MAX_SAFE_INTEGER.

Major Changes

• Added Timecode[Symbol.toPrimitive](), Timecode.toTimeString(), Timecode.new(), Timecode.subtract(), Timecode.divide(), and Timecode.from().
• The Timecode can now accept 0-1 arguments. new Timecode() is equal to new Timecode(0).

Minor Changes

• Added JSDoc to all exported values.

Installation and setup example

npm install @ethanblaisalarms/timecode

// ESM (default export)
import Timecode from "@ethanblaisalarms/timecode";

// ESM (non-default export)
import {TimecodeError} from "@ethanblaisalarms/timecode";

// ESM (both)
import {default as Timecode, TimecodeError} from "@ethanblaisalarms/timecode";

// CommonJS (default export)
const {default: Timecode} = require("@ethanblaisalarms/timecode");

// CommonJS (non-default export)
const {TimecodeError} = require("@ethanblaisalarms/timecode");

// CommonJS (both)
const {default: Timecode, TimecodeError} = require("@ethanblaisalarms/timecode");

TypeScript types

type TMakeTimecode = null|undefined|number|string|Timecode

| TypeScript | A union of types which may be converted to a Timecode. |------------|- | JavaScript | Equal to null, undefined, number, string, or Timecode.

Timecode

default class Timecode

This class simplifies Timecode conversion by holding a value, allowing you to perform operations and tests on that value, and allowing you to choose in what format the data is returned.

Constructor

constructor(input?:TMakeTimecode):Timecode;
static Timecode.from(input:TMakeTimecode):Timecode;

Parses the value as a number of seconds (using Timecode.parse(input)), and stores the result for later use within a Timecode.

Arguments (Timecode.from):

| Name | Type | Description |----------|---------------|------------ | input | TMakeTimecode | required: The initial value of the Timecode. | @returns | Timecode | The newly-constructed Timecode.

Arguments:

| Name | Type | Description |----------|---------------|------------ | input | TMakeTimecode | The initial value of the Timecode. Defaults to undefined. | @returns | Timecode | The newly-constructed Timecode.

Example:

const x = new Timecode();
const y = new Timecode(60);
const z = new Timecode("1m");

Convert to Number

this[Symbol.toPrimitive](hint:"number"):number;
this.valueOf():number;
this.toSeconds():number;

Returns the number of seconds stored within the Timecode.

Arguments (Symbol.toPrimitive):

| Name | Type | Description |----------|----------|------------ | hint | "number" | required: Indicates the result should be a number. Automatically specified during normal conversion to primitive. | @returns | number | The number of seconds within this.

Arguments:

| Name | Type | Description |----------|----------|------------ | @returns | number | The number of seconds within this.

Example:

const x = new Timecode("1m");
const y = x.toSeconds();

// Expected value of y:
60;

Convert to String

this[Symbol.toPrimitive](hint:"string"|"default"):string;
this.toJSON():string;
this.toString():string;
this.toTimeString():string;

Returns the TimeString representation of the Timecode.

Warning:

Previously, this.toTimecode() performed the same function. To prevent confusion regarding the name, this method has been deprecated. Do not use this.toTimecode() in new applications; it may be removed in the future. Use this.toTimeString() instead.

Arguments (Symbol.toPrimitive):

| Name | Type | Description |----------|-----------------------|------------ | hint | "string" or "default" | required: Indicates the result should be a string. Automatically specified during normal conversion to primitive. | @returns | string | The TimeString representation of the Timecode.

Arguments:

| Name | Type | Description |----------|----------|------------ | @returns | string | The TimeString representation of the Timecode.

Example:

const x = new Timecode("1m");
const y = x.toTimeString();

// Expected value of y:
"1m";

Convert to Clock

this.toClock():string;

Returns the clock representation of the Timecode.

Arguments:

| Name | Type | Description |----------|----------|------------ | @returns | string | The clock representation of the Timecode.

Example:

const x = new Timecode("1m");
const y = x.toClock();

// Expected value of y:
"1:00";

Clone Timecode

this.clone():Timecode;
this.new():Timecode;

Returns a copy of the Timecode.

Arguments:

| Name | Type | Description |----------|----------|------------ | @returns | Timecode | A copy of the Timecode.

Example:

const x = new Timecode("1m");
const y = x.clone();

// Expected value of x == y:
false;

Negate Timecode

this.negate():Timecode;

Negates the value of the Timecode.

This function will mutate this and may overwrite properties.

Arguments:

| Name | Type | Description |----------|----------|------------ | @returns | Timecode | this

Example:

const x = new Timecode("1m");
x.negate();
const y = x.toTimeString();

// Expected value of y:
"-1m";

Replace Timecode

this.replace(input:TMakeTimecode):Timecode;

Replaces the value of the Timecode with a new value.

This function will mutate this and may overwrite properties.

Arguments:

| Name | Type | Description |----------|---------------|------------ | input | TMakeTimecode | required: The value to replace the Timecode's value. | @returns | Timecode | this

Example:

const x = new Timecode("1m");
x.replace("2m");
const y = x.toTimeString();

// Expected value of y:
"2m";

Add to Timecode

this.add(input:TMakeTimecode):Timecode;

Adds the input to the value of the Timecode.

This function will mutate this and may overwrite properties.

Arguments:

| Name | Type | Description |----------|---------------|------------ | input | TMakeTimecode | required: The value to add to the Timecode. | @returns | Timecode | this

Example:

const x = new Timecode("1m");
x.add("2m");
const y = x.toTimeString();

// Expected value of y:
"3m";

Subtract from Timecode

this.subtract(input:TMakeTimecode):Timecode;

Subtracts the input from the value of the Timecode.

This function will mutate this and may overwrite properties.

Arguments:

| Name | Type | Description |----------|---------------|------------ | input | TMakeTimecode | required: The value to subtract from the Timecode. | @returns | Timecode | this

Example:

const x = new Timecode("3m");
x.subtract("2m");
const y = x.toTimeString();

// Expected value of y:
"1m";

Multiply Timecode

this.multiply(input:number):Timecode;

Multiplies the value of the Timecode by the input.

This function will mutate this and may overwrite properties.

Arguments:

| Name | Type | Description |----------|----------|------------ | input | number | required: The value to multiply the Timecode by. | @returns | Timecode | this

Example:

const x = new Timecode("2m");
x.multiply(5);
const y = x.toTimeString();

// Expected value of y:
"10m";

Divide Timecode

this.divide(input:number):Timecode;

Divides the value of the Timecode by the input.

This function will mutate this and may overwrite properties.

Arguments:

| Name | Type | Description |----------|----------|------------ | input | number | required: The number to divide the Timecode by. | @returns | Timecode | this

Example:

const x = new Timecode("10m");
x.divide(5);
const y = x.toTimeString();

// Expected value of y:
"2m";

Modulus Timecode

this.mod(input:TMakeTimecode):Timecode;

Modulo the value of the Timecode by the input.

This function will mutate this and may overwrite properties.

Arguments:

| Name | Type | Description |----------|---------------|------------ | input | TMakeTimecode | required: The number to modulo the Timecode by. | @returns | Timecode | this

Example:

const x = new Timecode("10m");
x.mod("3m");
const y = x.toTimeString();

// Expected value of y:
"1m";

Is Timecode Greater Than

this.greaterThan(input:TMakeTimecode):boolean;

Tests if input is greater than Timecode and returns the result of the test.

Arguments:

| Name | Type | Description |----------|---------------|------------ | input | TMakeTimecode | required: The value to test against the Timecode. | @returns | boolean | Whether the test passed or failed.

Example:

const x = new Timecode("10m");
const y = x.greaterThan("11m");

// Expected value of y:
false;

Is Timecode Greater Than or Equal To

this.greaterThanOrEqual(input:TMakeTimecode):boolean;

Tests if input is greater than or equal to Timecode and returns the result of the test.

Arguments:

| Name | Type | Description |----------|---------------|------------ | input | TMakeTimecode | required: The value to test against the Timecode. | @returns | boolean | Whether the test passed or failed.

Example:

const x = new Timecode("10m");
const y = x.greaterThanOrEqual("10m");

// Expected value of y:
true;

Is Timecode Less Than

this.lessThan(input:TMakeTimecode):boolean;

Tests if input is less than Timecode and returns the result of the test.

Arguments:

| Name | Type | Description |----------|---------------|------------ | input | TMakeTimecode | required: The value to test against the Timecode. | @returns | boolean | Whether the test passed or failed.

Example:

const x = new Timecode("10m");
const y = x.lessThan("10m");

// Expected value of y:
false;

Is Timecode Less Than or Equal To

this.lessThanOrEqual(input:TMakeTimecode):boolean;

Tests if input is less than or equal to Timecode and returns the result of the test.

Arguments:

| Name | Type | Description |----------|---------------|------------ | input | TMakeTimecode | required: The value to test against the Timecode. | @returns | boolean | Whether the test passed or failed.

Example:

const x = new Timecode("10m");
const y = x.lessThanOrEqual("11m");

// Expected value of y:
true;

Is Timecode Between

this.between(
	min:TMakeTimecode,
	max:TMakeTimecode,
):boolean;

Tests if the Timecode is between the two input values (inclusive) and returns the result of the test.

Arguments:

| Name | Type | Description |----------|---------------|------------ | min | TMakeTimecode | required: The minimum value to test against the Timecode. | max | TMakeTimecode | required: The maximum value to test against the Timecode. | @returns | boolean | Whether the test passed or failed.

Example:

const x = new Timecode("10m");
const y = [
	x.between("10m", "11m"),
	x.between("9m", "11m"),
	x.between("11m", "12m"),
];

// Expected value of y:
[true, true, false];

Is Timecode Equal To

this.matches(input:TMakeTimecode):boolean;

Tests if input is equal to the Timecode and returns the result of the test.

Arguments:

| Name | Type | Description |----------|---------------|------------ | input | TMakeTimecode | required: The value to test against the Timecode. | @returns | boolean | Whether the test passed or failed.

Example:

const x = new Timecode("10m");
const y = x.matches(600);

// Expected value of y:
true;

Generate TimeString

static generate(input:TMakeTimecode):string;

Returns the TimeString representation of the input.

Arguments:

| Name | Type | Description |----------|---------------|------------ | input | TMakeTimecode | required: The value to convert to a TimeString. | @returns | string | The TimeString representation of input. | @throws | TimecodeError | If the input is out-of-bounds.

Example:

const x = Timecode.generate(600);

// Expected value of x:
"10m";

Parse Timecode

static parse(input:TMakeTimecode):number;

Returns the number of seconds within the input.

Arguments:

| Name | Type | Description |----------|---------------|------------ | input | TMakeTimecode | required: The value to convert to a number of seconds. | @returns | number | The number of seconds within input. | @throws | TimecodeError | If the result is out-of-bounds or if the Timecode cannot be parsed.

Example:

const x = Timecode.parse("10m");

// Expected value of x:
600;

Timecode Units

static units:Record<string, number>;
static implicitUnits:Record<string, number>;

Contains the units used within a TimeString.

Warning:

These properties should not be modified. Modification of these properties can cause undefined behavior; especially when Timecodes are referenced in multiple places.

Timecode Bounds

static min:number;
static max:number;

Contains the bounds for a valid Timecode.

Warning:

These properties should not be modified. Modification of these properties can cause undefined behavior; especially when Timecodes are referenced in multiple places.

Timecode Error

class TimecodeError extends Error

This error can be thrown when a Timecode operation fails.

Constructor

constructor(input:string):TimecodeError;

Example:

throw new TimecodeError("The Timecode is not valid.");