feuerwerk/src/core/music/time.ts

/**
 * Musical time (#332): ticks, tempo and meter, and the seconds they come to. Ticks are whole numbers
 * of a quarter note's share, so a grid, a triplet and a quintuplet all land on one exactly.
 */

/** As MIDI files and most DAWs count: a 1/32 triplet is 40, a 1/16 quintuplet 96. */
export const TICKS_PER_QUARTER = 480;

/** A tempo always counts quarter notes per minute, in 6/8 as in 4/4. */
export const DEFAULT_TEMPO = 120;
export const MIN_TEMPO = 20;
export const MAX_TEMPO = 400;

/** A time signature: `beats` notes of the value `unit` to the bar – 3/4, 6/8, 7/8. */
export interface Meter {
  beats: number;
  unit: number;
}

export const COMMON_TIME: Meter = { beats: 4, unit: 4 };
const UNITS = [1, 2, 4, 8, 16, 32];
const MAX_BEATS = 32;

/** A meter as written, or 4/4 where it is not one: a beat is a power of two, a bar 1 to 32 of them. */
export function heldMeter(meter: Meter): Meter {
  const { beats, unit } = meter;
  if (!Number.isInteger(beats) || beats < 1 || beats > MAX_BEATS || !UNITS.includes(unit)) return COMMON_TIME;
  return { beats, unit };
}

/** The time signatures a song or a pattern is written in (#363, #364), one row for both numbers. */
const SIGNS: readonly string[] = [
  '1/2',
  '2/2',
  '3/2',
  '1/4',
  '2/4',
  '3/4',
  '4/4',
  '5/4',
  '6/4',
  '5/8',
  '6/8',
  '7/8',
  '8/8',
  '9/8',
];
export const DEFAULT_SIGN = '4/4';
export const SIGN_OPTIONS = SIGNS.map((sign) => ({ value: sign, label: sign }));

/** The meter of a sign; 4/4 where it is not one of `SIGNS`. */
export function signMeter(sign: string): Meter {
  const [beats, unit] = (SIGNS.includes(sign) ? sign : DEFAULT_SIGN).split('/');
  return heldMeter({ beats: Number(beats), unit: Number(unit) });
}

export function signOf(meter: Meter): string {
  return `${meter.beats}/${meter.unit}`;
}

/** A tempo between `MIN_TEMPO` and `MAX_TEMPO`; 0 and anything that is not a number is the default. */
export function heldTempo(tempo: number): number {
  if (!Number.isFinite(tempo) || tempo <= 0) return DEFAULT_TEMPO;
  return Math.max(MIN_TEMPO, Math.min(MAX_TEMPO, tempo));
}

export function ticksPerBeat(meter: Meter): number {
  return (TICKS_PER_QUARTER * 4) / meter.unit;
}

export function ticksPerBar(meter: Meter): number {
  return meter.beats * ticksPerBeat(meter);
}

export function secondsOfTicks(ticks: number, tempo: number): number {
  return (ticks * 60) / (tempo * TICKS_PER_QUARTER);
}

export function ticksOfSeconds(seconds: number, tempo: number): number {
  return (seconds * tempo * TICKS_PER_QUARTER) / 60;
}

/** Seconds of a number of quarter notes: 1 is a quarter, 0.5 an eighth, 0.75 a dotted eighth. */
export function secondsOfQuarters(quarters: number, tempo: number): number {
  return (quarters * 60) / tempo;
}

/** Where a tick stands as a musician counts it: bar and beat from 1, the tick inside the beat from 0. */
export interface Position {
  bar: number;
  beat: number;
  tick: number;
}

export function positionOf(ticks: number, meter: Meter): Position {
  const at = Math.max(0, Math.floor(ticks));
  const bar = ticksPerBar(meter);
  const beat = ticksPerBeat(meter);
  const inBar = at % bar;
  return { bar: Math.floor(at / bar) + 1, beat: Math.floor(inBar / beat) + 1, tick: inBar % beat };
}