| name | timebase |
| description | Pulp musical/media time primitives, immutable compiled tempo maps, monotonic transport beats, exact sample anchors, corrected inverse conversion, and shared transport quantization arithmetic. |
Timebase
Use this skill when changing core/timebase, tempo conversion, or the transport
quantizer's beat/frame arithmetic.
Contracts
kTicksPerQuarter is 705,600. Musical positions are stored and accumulated as
integer TickPosition; samples use integer SamplePosition. Tick-position,
duration, and MonotonicBeat arithmetic saturates at the signed 64-bit
endpoints; it must not invoke signed-overflow UB.CompiledTempoMap is immutable and sample-rate-specific. Its first tempo point
is tick zero, points are strictly ordered, and BPM is finite in [1, 1000].- Tempo ramps are BPM-linear in tick position. Integrate them analytically; do not
approximate ramps block-by-block or accumulate floating-point deltas.
- Every segment begins at an integer sample anchor.
samples_to_ticks() returns
the first canonical tick mapping to that sample when one exists. Exact sample
-> tick -> sample requires a tick grid at least as dense as samples. On a
sparser grid, use resolve_sample() and inspect represented_sample,
absolute_error_samples, and exact; the nearest tick is returned.
- Arbitrary tick -> sample -> tick cannot be identity because many ticks share an
integer sample. Test monotonicity and canonical-sample preservation instead.
- Keep
TransportQuantizer's public behavior stable. Generic beat/frame/grid
arithmetic belongs in <pulp/timebase/quantize.hpp> and the format wrapper
delegates to it.
Validation
Build and run pulp-test-timebase and the existing
pulp-test-transport-quantizer oracle. Keep at least 1,000,000 deterministic
randomized constant/ramp cases, plus tempo-point boundary cases.
MonotonicBeat is the strong type for the transport's non-looping musical
clock; the transport owns how it advances while timeline positions seek or
wrap. MeterMap is not part of the initial module.
