Time Parsing and Conversion

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

(no submodules)

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

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

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.

2.3 KiB Raw Blame History