first commit

docs/media/audio/audio-transport/src/time/time.md

@@ -0,0 +1,59 @@
+# 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.