> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heliosrender.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Timecode

> Timecode conversion utilities for Helios

## framesToTimecode

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

```typescript theme={null}
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

```typescript theme={null}
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.

```typescript theme={null}
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

```typescript theme={null}
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).

```typescript theme={null}
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

```typescript theme={null}
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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.