@modernized/osmd-audio-player 1.0.1

package/src/PlaybackEngine.ts

@@ -0,0 +1,294 @@
+import PlaybackScheduler from "./PlaybackScheduler";
+import {
+  Cursor,
+  OpenSheetMusicDisplay,
+  MusicSheet,
+  Note,
+  Instrument,
+  Voice,
+} from "opensheetmusicdisplay";
+import { SoundfontPlayer } from "./players/SoundfontPlayer";
+import { InstrumentPlayer, PlaybackInstrument } from "./players/InstrumentPlayer";
+import { NotePlaybackInstruction } from "./players/NotePlaybackOptions";
+import { getNoteDuration, getNoteVolume, getNoteArticulationStyle } from "./internals/noteHelpers";
+import { EventEmitter } from "./internals/EventEmitter";
+import { AudioContext, IAudioContext } from "standardized-audio-context";
+
+interface VoiceWithMidi extends Voice {
+  midiInstrumentId: number;
+}
+
+export enum PlaybackState {
+  INIT = "INIT",
+  PLAYING = "PLAYING",
+  STOPPED = "STOPPED",
+  PAUSED = "PAUSED",
+}
+
+export enum PlaybackEvent {
+  STATE_CHANGE = "state-change",
+  ITERATION = "iteration",
+}
+
+interface PlaybackSettings {
+  bpm: number;
+  masterVolume: number;
+}
+
+export default class PlaybackEngine {
+  private ac: IAudioContext;
+  private defaultBpm: number = 100;
+  private cursor: Cursor;
+  private sheet: MusicSheet;
+  private scheduler: PlaybackScheduler;
+  private instrumentPlayer: InstrumentPlayer;
+  private events: EventEmitter<PlaybackEvent>;
+
+  private iterationSteps: number;
+  private currentIterationStep: number;
+
+  private timeoutHandles: number[];
+
+  public playbackSettings: PlaybackSettings;
+  public state: PlaybackState;
+  public availableInstruments: PlaybackInstrument[];
+  public scoreInstruments: Instrument[] = [];
+  public ready: boolean = false;
+
+  constructor(
+    context: IAudioContext = new AudioContext(),
+    instrumentPlayer: InstrumentPlayer = new SoundfontPlayer(),
+  ) {
+    this.ac = context;
+    this.ac.suspend();
+
+    this.instrumentPlayer = instrumentPlayer;
+    this.instrumentPlayer.init(this.ac);
+
+    this.availableInstruments = this.instrumentPlayer.instruments;
+
+    this.events = new EventEmitter();
+
+    this.cursor = null;
+    this.sheet = null;
+
+    this.scheduler = null;
+
+    this.iterationSteps = 0;
+    this.currentIterationStep = 0;
+
+    this.timeoutHandles = [];
+
+    this.playbackSettings = {
+      bpm: this.defaultBpm,
+      masterVolume: 1,
+    };
+
+    this.setState(PlaybackState.INIT);
+  }
+
+  get wholeNoteLength(): number {
+    return Math.round((60 / this.playbackSettings.bpm) * 4000);
+  }
+
+  public getPlaybackInstrument(voiceId: number): PlaybackInstrument {
+    if (!this.sheet) return null;
+    const voice = this.sheet.Instruments.flatMap((i) => i.Voices).find(
+      (v) => v.VoiceId === voiceId,
+    );
+    return this.availableInstruments.find((i) => i.midiId === (voice as VoiceWithMidi).midiInstrumentId);
+  }
+
+  public async setInstrument(voice: Voice, midiInstrumentId: number): Promise<void> {
+    await this.instrumentPlayer.load(midiInstrumentId);
+    (voice as VoiceWithMidi).midiInstrumentId = midiInstrumentId;
+  }
+
+  async loadScore(osmd: OpenSheetMusicDisplay): Promise<void> {
+    this.ready = false;
+    this.sheet = osmd.Sheet;
+    this.scoreInstruments = this.sheet.Instruments;
+    this.cursor = osmd.cursor;
+    if (this.sheet.HasBPMInfo) {
+      this.setBpm(this.sheet.DefaultStartTempoInBpm);
+    }
+
+    await this.loadInstruments();
+    this.initInstruments();
+
+    this.scheduler = new PlaybackScheduler(this.wholeNoteLength, this.ac, (delay, notes) =>
+      this.notePlaybackCallback(delay, notes),
+    );
+
+    this.countAndSetIterationSteps();
+    this.ready = true;
+    this.setState(PlaybackState.STOPPED);
+  }
+
+  private initInstruments() {
+    for (const i of this.sheet.Instruments) {
+      for (const v of i.Voices) {
+        (v as VoiceWithMidi).midiInstrumentId = i.MidiInstrumentId;
+      }
+    }
+  }
+
+  private async loadInstruments() {
+    const playerPromises: Promise<void>[] = [];
+    for (const i of this.sheet.Instruments) {
+      const pbInstrument = this.availableInstruments.find(
+        (pbi) => pbi.midiId === i.MidiInstrumentId,
+      );
+      if (pbInstrument == null) {
+        this.fallbackToPiano(i);
+      }
+      playerPromises.push(this.instrumentPlayer.load(i.MidiInstrumentId));
+    }
+    await Promise.all(playerPromises);
+  }
+
+  private fallbackToPiano(i: Instrument) {
+    console.warn(
+      `Can't find playback instrument for midiInstrumentId ${i.MidiInstrumentId}. Falling back to piano`,
+    );
+    i.MidiInstrumentId = 0;
+
+    if (this.availableInstruments.find((i) => i.midiId === 0) == null) {
+      throw new Error("Piano fallback failed, grand piano not supported");
+    }
+  }
+
+  async play() {
+    await this.ac.resume();
+
+    if (this.state === PlaybackState.INIT || this.state === PlaybackState.STOPPED) {
+      this.cursor.show();
+    }
+
+    this.setState(PlaybackState.PLAYING);
+    this.scheduler.start();
+  }
+
+  async stop() {
+    this.setState(PlaybackState.STOPPED);
+    this.stopPlayers();
+    this.clearTimeouts();
+    this.scheduler.reset();
+    this.cursor.reset();
+    this.currentIterationStep = 0;
+    this.cursor.hide();
+  }
+
+  pause() {
+    this.setState(PlaybackState.PAUSED);
+    this.ac.suspend();
+    this.stopPlayers();
+    this.scheduler.setIterationStep(this.currentIterationStep);
+    this.scheduler.pause();
+    this.clearTimeouts();
+  }
+
+  jumpToStep(step: number) {
+    this.pause();
+    if (this.currentIterationStep > step) {
+      this.cursor.reset();
+      this.currentIterationStep = 0;
+    }
+    while (this.currentIterationStep < step) {
+      this.cursor.next();
+      ++this.currentIterationStep;
+    }
+    let schedulerStep = this.currentIterationStep;
+    if (this.currentIterationStep > 0 && this.currentIterationStep < this.iterationSteps)
+      ++schedulerStep;
+    this.scheduler.setIterationStep(schedulerStep);
+  }
+
+  setBpm(bpm: number) {
+    this.playbackSettings.bpm = bpm;
+    if (this.scheduler) this.scheduler.wholeNoteLength = this.wholeNoteLength;
+  }
+
+  public on(event: PlaybackEvent, cb: (...args: unknown[]) => void) {
+    this.events.on(event, cb);
+  }
+
+  private countAndSetIterationSteps() {
+    this.cursor.reset();
+    let steps = 0;
+    while (!this.cursor.Iterator.EndReached) {
+      if (this.cursor.Iterator.CurrentVoiceEntries) {
+        this.scheduler.loadNotes(this.cursor.Iterator.CurrentVoiceEntries);
+      }
+      this.cursor.next();
+      ++steps;
+    }
+    this.iterationSteps = steps;
+    this.cursor.reset();
+  }
+
+  private notePlaybackCallback(audioDelay: number, notes: Note[]) {
+    if (this.state !== PlaybackState.PLAYING) return;
+    const scheduledNotes: Map<number, NotePlaybackInstruction[]> = new Map();
+
+    for (const note of notes) {
+      if (note.isRest()) {
+        continue;
+      }
+      const noteDuration = getNoteDuration(note, this.wholeNoteLength);
+      if (noteDuration === 0) continue;
+      const noteVolume = getNoteVolume(note);
+      const noteArticulation = getNoteArticulationStyle(note);
+
+      const midiPlaybackInstrument = (note.ParentVoiceEntry.ParentVoice as VoiceWithMidi).midiInstrumentId;
+      const fixedKey = note.ParentVoiceEntry.ParentVoice.Parent.SubInstruments[0].fixedKey || 0;
+
+      if (!scheduledNotes.has(midiPlaybackInstrument)) {
+        scheduledNotes.set(midiPlaybackInstrument, []);
+      }
+
+      scheduledNotes.get(midiPlaybackInstrument).push({
+        note: note.halfTone - fixedKey * 12,
+        duration: noteDuration / 1000,
+        gain: noteVolume,
+        articulation: noteArticulation,
+      });
+    }
+
+    for (const [midiId, notes] of scheduledNotes) {
+      this.instrumentPlayer.schedule(midiId, this.ac.currentTime + audioDelay, notes);
+    }
+
+    this.timeoutHandles.push(
+      window.setTimeout(() => this.iterationCallback(), Math.max(0, audioDelay * 1000 - 35)), // Subtracting 35 milliseconds to compensate for update delay
+      window.setTimeout(() => this.events.emit(PlaybackEvent.ITERATION, notes), audioDelay * 1000),
+    );
+  }
+
+  private setState(state: PlaybackState) {
+    this.state = state;
+    this.events.emit(PlaybackEvent.STATE_CHANGE, state);
+  }
+
+  private stopPlayers() {
+    for (const i of this.sheet.Instruments) {
+      for (const v of i.Voices) {
+        this.instrumentPlayer.stop((v as VoiceWithMidi).midiInstrumentId);
+      }
+    }
+  }
+
+  // Used to avoid duplicate cursor movements after a rapid pause/resume action
+  private clearTimeouts() {
+    for (const h of this.timeoutHandles) {
+      clearTimeout(h);
+    }
+    this.timeoutHandles = [];
+  }
+
+  private iterationCallback() {
+    if (this.state !== PlaybackState.PLAYING) return;
+    if (this.currentIterationStep > 0) this.cursor.next();
+    ++this.currentIterationStep;
+  }
+}

package/src/PlaybackScheduler.ts

@@ -0,0 +1,146 @@
+import StepQueue from "./internals/StepQueue";
+import { Note, VoiceEntry } from "opensheetmusicdisplay";
+import { IAudioContext } from "standardized-audio-context";
+
+type NoteSchedulingCallback = (delay: number, notes: Note[]) => void;
+
+export default class PlaybackScheduler {
+  public wholeNoteLength: number;
+
+  private stepQueue = new StepQueue();
+  private stepQueueIndex = 0;
+  private scheduledTicks = new Set<number>();
+
+  private currentTick = 0;
+  private currentTickTimestamp = 0;
+
+  private audioContext: IAudioContext;
+  private audioContextStartTime: number = 0;
+
+  private schedulerIntervalHandle: number = null;
+  private scheduleInterval: number = 200; // Milliseconds
+  private schedulePeriod: number = 500;
+  private tickDenominator: number = 1024;
+
+  private lastTickOffset: number = 300; // Hack to get the initial notes play better
+  private playing: boolean = false;
+
+  private noteSchedulingCallback: NoteSchedulingCallback;
+
+  constructor(
+    wholeNoteLength: number,
+    audioContext: IAudioContext,
+    noteSchedulingCallback: NoteSchedulingCallback,
+  ) {
+    this.noteSchedulingCallback = noteSchedulingCallback;
+    this.wholeNoteLength = wholeNoteLength;
+    this.audioContext = audioContext;
+  }
+
+  get schedulePeriodTicks() {
+    return this.schedulePeriod / this.tickDuration;
+  }
+
+  get audioContextTime() {
+    if (!this.audioContext) return 0;
+    return (this.audioContext.currentTime - this.audioContextStartTime) * 1000;
+  }
+
+  get tickDuration() {
+    return this.wholeNoteLength / this.tickDenominator;
+  }
+
+  private get calculatedTick() {
+    return (
+      this.currentTick +
+      Math.round((this.audioContextTime - this.currentTickTimestamp) / this.tickDuration)
+    );
+  }
+
+  start() {
+    this.playing = true;
+    this.stepQueue.sort();
+    this.audioContextStartTime = this.audioContext.currentTime;
+    this.currentTickTimestamp = this.audioContextTime;
+    if (!this.schedulerIntervalHandle) {
+      this.schedulerIntervalHandle = window.setInterval(
+        () => this.scheduleIterationStep(),
+        this.scheduleInterval,
+      );
+    }
+  }
+
+  setIterationStep(step: number) {
+    step = Math.min(this.stepQueue.steps.length - 1, step);
+    this.stepQueueIndex = step;
+    this.currentTick = this.stepQueue.steps[this.stepQueueIndex].tick;
+  }
+
+  pause() {
+    this.playing = false;
+  }
+
+  resume() {
+    this.playing = true;
+    this.currentTickTimestamp = this.audioContextTime;
+  }
+
+  reset() {
+    this.playing = false;
+    this.currentTick = 0;
+    this.currentTickTimestamp = 0;
+    this.stepQueueIndex = 0;
+    clearInterval(this.scheduleInterval);
+    this.schedulerIntervalHandle = null;
+  }
+
+  loadNotes(currentVoiceEntries: VoiceEntry[]) {
+    let thisTick = this.lastTickOffset;
+    if (this.stepQueue.steps.length > 0) {
+      thisTick = this.stepQueue.getFirstEmptyTick();
+    }
+
+    for (const entry of currentVoiceEntries) {
+      if (!entry.IsGrace) {
+        for (const note of entry.Notes) {
+          this.stepQueue.addNote(thisTick, note);
+          this.stepQueue.createStep(thisTick + note.Length.RealValue * this.tickDenominator);
+        }
+      }
+    }
+  }
+
+  private scheduleIterationStep() {
+    if (!this.playing) return;
+    this.currentTick = this.calculatedTick;
+    this.currentTickTimestamp = this.audioContextTime;
+
+    let nextTick = this.stepQueue.steps[this.stepQueueIndex]?.tick;
+    while (this.nextTickAvailableAndWithinSchedulePeriod(nextTick)) {
+      const step = this.stepQueue.steps[this.stepQueueIndex];
+
+      let timeToTick = (step.tick - this.currentTick) * this.tickDuration;
+      if (timeToTick < 0) timeToTick = 0;
+
+      this.scheduledTicks.add(step.tick);
+      this.noteSchedulingCallback(timeToTick / 1000, step.notes);
+
+      this.stepQueueIndex++;
+      nextTick = this.stepQueue.steps[this.stepQueueIndex]?.tick;
+    }
+
+    for (const tick of this.scheduledTicks) {
+      if (tick <= this.currentTick) {
+        this.scheduledTicks.delete(tick);
+      }
+    }
+  }
+
+  private nextTickAvailableAndWithinSchedulePeriod(nextTick: number | undefined) {
+    return (
+      nextTick &&
+      this.currentTickTimestamp + (nextTick - this.currentTick) * this.tickDuration <=
+        this.currentTickTimestamp + this.schedulePeriod
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+import PlaybackEngine from "./PlaybackEngine";
+
+export default PlaybackEngine;

package/src/internals/EventEmitter.test.ts

@@ -0,0 +1,57 @@
+import { describe, test, expect, vi } from "vitest";
+import { EventEmitter } from "./EventEmitter";
+
+describe("EventEmitter", () => {
+  test("Single subscriber", () => {
+    const emitter = new EventEmitter();
+    const cb = vi.fn(() => {});
+
+    emitter.on("test-event", cb);
+    emitter.emit("test-event");
+
+    expect(cb).toHaveBeenCalledTimes(1);
+  });
+
+  test("Single subscriber, with arguments", () => {
+    const emitter = new EventEmitter();
+    const cb = vi.fn(() => {});
+
+    emitter.on("test-event", cb);
+    emitter.emit("test-event", 1, 2);
+
+    expect(cb).toHaveBeenCalledTimes(1);
+    expect(cb).toHaveBeenCalledWith(1, 2);
+  });
+
+  test("Multiple subscribers", () => {
+    const emitter = new EventEmitter();
+    const cb1 = vi.fn(() => {});
+    const cb2 = vi.fn(() => {});
+
+    emitter.on("test-event", cb1);
+    emitter.on("test-event", cb2);
+
+    emitter.emit("test-event");
+
+    expect(cb1).toHaveBeenCalledTimes(1);
+    expect(cb2).toHaveBeenCalledTimes(1);
+  });
+
+  test("Multiple events", () => {
+    const emitter = new EventEmitter();
+    const cb1 = vi.fn(() => {});
+    const cb2 = vi.fn(() => {});
+    const cb3 = vi.fn(() => {});
+
+    emitter.on("event1", cb1);
+    emitter.on("event2", cb2);
+    emitter.on("event3", cb3);
+
+    emitter.emit("event1");
+    emitter.emit("event2");
+
+    expect(cb1).toHaveBeenCalledTimes(1);
+    expect(cb2).toHaveBeenCalledTimes(1);
+    expect(cb3).toHaveBeenCalledTimes(0);
+  });
+});

package/src/internals/EventEmitter.ts

@@ -0,0 +1,19 @@
+type Callback = (...args: unknown[]) => void;
+
+export class EventEmitter<T> {
+  private subscribers: Map<T, Callback[]> = new Map();
+
+  public on(event: T, callback: Callback) {
+    if (!this.subscribers.get(event)) {
+      this.subscribers.set(event, []);
+    }
+    this.subscribers.get(event)!.push(callback);
+  }
+
+  public emit(event: T, ...args: unknown[]) {
+    const subscribers = this.subscribers.get(event) || [];
+    for (const sub of subscribers) {
+      sub(...args);
+    }
+  }
+}

package/src/internals/StepQueue.ts

@@ -0,0 +1,45 @@
+import { Note } from "opensheetmusicdisplay";
+
+type ScheduledNotes = {
+  tick: number;
+  notes: Note[];
+};
+
+export default class StepQueue {
+  steps: ScheduledNotes[] = [];
+
+  constructor() {}
+
+  [Symbol.iterator]() {
+    return this.steps.values();
+  }
+
+  createStep(tick: number): ScheduledNotes {
+    let step = this.steps.find((s) => s.tick === tick);
+    if (!step) {
+      step = { tick, notes: [] };
+      this.steps.push(step);
+    }
+
+    return step;
+  }
+
+  addNote(tick: number, note: Note): void {
+    const step = this.steps.find((s) => s.tick === tick) ?? this.createStep(tick);
+    step.notes.push(note);
+  }
+
+  delete(value: ScheduledNotes): void {
+    const index = this.steps.findIndex((v) => v.tick === value.tick);
+    if (index != null) this.steps.splice(index, 1);
+  }
+
+  sort(): StepQueue {
+    this.steps.sort((a, b) => a.tick - b.tick);
+    return this;
+  }
+
+  getFirstEmptyTick(): number {
+    return this.sort().steps.filter((s) => !s.notes.length)[0].tick;
+  }
+}

package/src/internals/noteHelpers.ts

@@ -0,0 +1,26 @@
+import { Note } from "opensheetmusicdisplay";
+import { ArticulationStyle } from "../players/NotePlaybackOptions";
+
+export function getNoteArticulationStyle(note: Note): ArticulationStyle {
+  if (note.ParentVoiceEntry.isStaccato()) {
+    return ArticulationStyle.Staccato;
+  } else {
+    return ArticulationStyle.None;
+  }
+}
+
+export function getNoteDuration(note: Note, wholeNoteLength) {
+  let duration = note.Length.RealValue * wholeNoteLength;
+  if (note.NoteTie) {
+    if (Object.is(note.NoteTie.StartNote, note) && note.NoteTie.Notes[1]) {
+      duration += note.NoteTie.Notes[1].Length.RealValue * wholeNoteLength;
+    } else {
+      duration = 0;
+    }
+  }
+  return duration;
+}
+
+export function getNoteVolume(note: Note) {
+  return note.ParentVoiceEntry.ParentVoice.Volume;
+}