> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/BintzGavin/helios/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
```

<ParamField path="frame" type="number" required>
  Frame number to convert (will be floored to nearest integer and clamped to non-negative)
</ParamField>

<ParamField path="fps" type="number" required>
  Frames per second (must be greater than 0)
</ParamField>

<ResponseField name="return" type="string">
  Timecode string in HH:MM:SS:FF format
</ResponseField>

### 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
```

<ParamField path="timecode" type="string" required>
  Timecode string in HH:MM:SS:FF format
</ParamField>

<ParamField path="fps" type="number" required>
  Frames per second (must be greater than 0)
</ParamField>

<ResponseField name="return" type="number">
  The corresponding frame number
</ResponseField>

### 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
```

<ParamField path="frame" type="number" required>
  Frame number to convert (will be clamped to non-negative)
</ParamField>

<ParamField path="fps" type="number" required>
  Frames per second (must be greater than 0)
</ParamField>

<ResponseField name="return" type="string">
  Timestamp string in HH:MM:SS.mmm format with milliseconds
</ResponseField>

### 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