# Time Parsing and Conversion

This module parses musical time tokens and converts between ticks, seconds, and bars:beats:sixteenths notation.

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

Musical time is expressed in many forms: subdivision notation, measure counts, bar positions, and raw seconds. `parseTimeToken` turns all of these into a canonical `{ ticks, seconds }` representation. The conversion helpers then provide round-tripping between ticks, seconds, and human-readable bar positions.

## Features

- Subdivision notation (`"4n"`, `"8n"`, `"16n"`, `"8t"`, `"16t"`)
- Measure notation (`"1m"`)
- Bars:beats:sixteenths (`"2:1:0"`)
- Relative seconds (`"+1"`)
- Absolute measures (`"@4m"`)
- Raw numeric ticks
- Bidirectional conversion helpers

## Usage: Basic

```ts
import { parseTimeToken } from "@suaveplan/audio-transport";

const ctx = { ppq: 192, timeSignature: 4, bpm: 120 };
const result = parseTimeToken("4n", ctx);
console.log(result.ticks); // 192
console.log(result.seconds); // 0.5
```

## Usage: Advanced

```ts
import {
    parseTimeToken,
    toBarsBeatsSixteenths,
    fromBarsBeatsSixteenths,
} from "@suaveplan/audio-transport";

const ctx = { ppq: 192, timeSignature: 4, bpm: 120 };
const ticks = fromBarsBeatsSixteenths("1:2:3", ctx);
const bbs = toBarsBeatsSixteenths(ticks, ctx);
console.log(bbs); // "1:2:3"
```

## API Reference

- `parseTimeToken(token, ctx)` → `{ ticks, seconds }`
- `ticksToSeconds(ticks, ctx)` → `number`
- `secondsToTicks(seconds, ctx)` → `number`
- `toBarsBeatsSixteenths(ticks, ctx)` → `string`
- `fromBarsBeatsSixteenths(token, ctx)` → `number`

## Implementation Notes

All conversions assume constant tempo. `parseTimeToken` throws `AUDIO_TRANSPORT_INVALID_TIME` for unrecognised tokens. Numeric tokens are treated as raw ticks and returned directly. The regex-based parsers are ordered from most specific to least specific so that subdivision tokens are tried before relative tokens, avoiding ambiguity. The `bars:beats:sixteenths` format uses zero-based indexing for all three components. `toBarsBeatsSixteenths` floors each component rather than rounding, which is the conventional behaviour for DAW-style position displays. `fromBarsBeatsSixteenths` validates the input format with a strict regex and throws `AUDIO_TRANSPORT_INVALID_TIME` for malformed strings.