Timecode

Timecode conversion utilities for Helios

framesToTimecode

Converts a frame number to timecode format (HH:MM:SS:FF).

function framesToTimecode(frame: number, fps: number): string

frame · number · required

Frame number to convert (will be floored to nearest integer and clamped to non-negative)

fps · number · required

Frames per second (must be greater than 0)

return · string

Timecode string in HH:MM:SS:FF format

Example

import { framesToTimecode } from '@helios-project/core';

const timecode = framesToTimecode(150, 30);
console.log(timecode); // '00:00:05:00'

const longer = framesToTimecode(7200, 24);
console.log(longer); // '00:05:00:00'

// Negative frames are clamped to 0
const clamped = framesToTimecode(-10, 30);
console.log(clamped); // '00:00:00:00'

Errors

Throws HeliosError with code INVALID_FPS if fps is less than or equal to 0.

timecodeToFrames

Converts a timecode string to a frame number.

function timecodeToFrames(timecode: string, fps: number): number

timecode · string · required

Timecode string in HH:MM:SS:FF format

fps · number · required

Frames per second (must be greater than 0)

return · number

The corresponding frame number

Example

import { timecodeToFrames } from '@helios-project/core';

const frame = timecodeToFrames('00:00:05:00', 30);
console.log(frame); // 150

const longer = timecodeToFrames('00:05:00:00', 24);
console.log(longer); // 7200

const exact = timecodeToFrames('01:30:45:12', 30);
console.log(exact); // 163512

Errors

Throws HeliosError with:

• INVALID_FPS if fps is less than or equal to 0
• INVALID_TIMECODE_FORMAT if timecode is not in HH:MM:SS:FF format

framesToTimestamp

Converts a frame number to a timestamp format (HH:MM:SS.mmm).

function framesToTimestamp(frame: number, fps: number): string

frame · number · required

Frame number to convert (will be clamped to non-negative)

fps · number · required

Frames per second (must be greater than 0)

return · string

Timestamp string in HH:MM:SS.mmm format with milliseconds

Example

import { framesToTimestamp } from '@helios-project/core';

const timestamp = framesToTimestamp(150, 30);
console.log(timestamp); // '00:00:05.000'

const withMs = framesToTimestamp(75, 30);
console.log(withMs); // '00:00:02.500'

const longer = framesToTimestamp(7200, 24);
console.log(longer); // '00:05:00.000'

Errors

Throws HeliosError with code INVALID_FPS if fps is less than or equal to 0.

Format differences

• Timecode (HH:MM:SS:FF): Uses frame numbers (00-fps), suitable for video editing
• Timestamp (HH:MM:SS.mmm): Uses milliseconds, suitable for web standards like WebVTT