@hraness/dawg 0.0.0-stage → 0.3.0

package/core/loop.ts

@@ -0,0 +1,78 @@
+import {
+  SCORE_VERSION,
+  TrackScore,
+  ScoreValidationError,
+  scoreFromJSON,
+  type Note,
+  type Track,
+} from "./score.ts";
+
+export const LOOP_FORMAT = "track.loop/v1" as const;
+
+export type TrackLoopV1 = Readonly<{
+  format: typeof LOOP_FORMAT;
+  version: typeof SCORE_VERSION;
+  tempoBpm: number;
+  beatsPerBar: number;
+  bars: number;
+  ticksPerBeat: number;
+  key: string | null;
+  tracks: readonly Track[];
+  notes: readonly Note[];
+}>;
+
+/** Return the stable object form used by files and IPC messages. */
+export function encodeLoopDocument(score: TrackScore): TrackLoopV1 {
+  if (!(score instanceof TrackScore))
+    throw new ScoreValidationError("encodeLoop requires a TrackScore");
+  return Object.freeze({
+    format: LOOP_FORMAT,
+    version: SCORE_VERSION,
+    tempoBpm: score.tempoBpm,
+    beatsPerBar: score.beatsPerBar,
+    bars: score.bars,
+    ticksPerBeat: score.ticksPerBeat,
+    key: score.key,
+    tracks: score.tracks,
+    notes: score.notes,
+  });
+}
+
+/** Encode with deterministic property and note ordering. */
+export function encodeLoop(score: TrackScore): string {
+  return JSON.stringify(encodeLoopDocument(score));
+}
+
+export function decodeLoopDocument(value: unknown): TrackScore {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new ScoreValidationError("track.loop/v1 must be an object");
+  }
+  const envelope = value as Record<string, unknown>;
+  if (envelope.format !== LOOP_FORMAT)
+    throw new ScoreValidationError(
+      `unsupported loop format: ${String(envelope.format)}`,
+    );
+  if (envelope.version !== SCORE_VERSION)
+    throw new ScoreValidationError(
+      `unsupported loop version: ${String(envelope.version)}`,
+    );
+  return scoreFromJSON(envelope);
+}
+
+export function decodeLoop(serialized: unknown): TrackScore {
+  let value: unknown = serialized;
+  if (typeof serialized === "string") {
+    try {
+      value = JSON.parse(serialized) as unknown;
+    } catch (error) {
+      throw new ScoreValidationError(
+        `invalid track.loop/v1 JSON: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+  return decodeLoopDocument(value);
+}
+
+// Explicit aliases make the format boundary easy to discover from callers.
+export const encodeTrackLoop = encodeLoop;
+export const decodeTrackLoop = decodeLoop;

package/core/pitch.ts

@@ -0,0 +1,60 @@
+/**
+ * Pitch-name helpers shared by the command parser, the SDK and the printer.
+ *
+ * Names are scientific pitch notation: a letter `A`–`G`, an optional `#` or
+ * `b`, and an octave from -1 to 9 (`C4` = 60, `A4` = 69). Parsing is
+ * case-insensitive; printing always uses sharps so a name round-trips to the
+ * same MIDI number.
+ */
+
+const SEMITONES: Readonly<Record<string, number>> = Object.freeze({
+  c: 0,
+  d: 2,
+  e: 4,
+  f: 5,
+  g: 7,
+  a: 9,
+  b: 11,
+});
+
+const NAMES = Object.freeze([
+  "C",
+  "C#",
+  "D",
+  "D#",
+  "E",
+  "F",
+  "F#",
+  "G",
+  "G#",
+  "A",
+  "A#",
+  "B",
+] as const);
+
+/** MIDI number for a pitch name, or NaN when the name is malformed or out of range. */
+export function pitchToMidi(value: string): number {
+  if (typeof value !== "string") return Number.NaN;
+  const match = value.trim().match(/^([a-gA-G])([#b]?)(-?\d{1,2})$/);
+  if (!match) return Number.NaN;
+  const accidental = match[2] === "#" ? 1 : match[2] === "b" ? -1 : 0;
+  const midi =
+    (Number(match[3]) + 1) * 12 +
+    (SEMITONES[match[1]!.toLowerCase()] ?? 0) +
+    accidental;
+  return midi >= 0 && midi <= 127 ? midi : Number.NaN;
+}
+
+/** Pitch name with sharps for a MIDI number 0..127 (`60` → `C4`). */
+export function midiToPitch(midi: number): string {
+  if (!Number.isInteger(midi) || midi < 0 || midi > 127)
+    throw new RangeError(`MIDI pitch out of range: ${String(midi)}`);
+  return `${NAMES[midi % 12]}${Math.floor(midi / 12) - 1}`;
+}
+
+/** True when `value` is a MIDI integer 0..127 or a parseable pitch name. */
+export function isPitch(value: unknown): value is number | string {
+  if (typeof value === "number")
+    return Number.isInteger(value) && value >= 0 && value <= 127;
+  return typeof value === "string" && Number.isFinite(pitchToMidi(value));
+}