Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

10.1 KB
Raw Blame
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import { parseTabSheet } from '../lib/tabNotation.js';
import {
  buildChordSchedule, createChordPlayer, resolveChordPlayhead, sheetChordOccurrences,
  DEFAULT_CHORD_TEMPO, DEFAULT_CHORD_BEATS_PER_BAR, CHORD_BEATS_MIN, CHORD_BEATS_MAX,
  CHORD_COUNT_IN_MAX,
} from '../lib/chordPlayback.js';
import { clampBpm } from '../lib/metronome.js';
import { useLocalStorageBool } from './useLocalStorageBool.js';
import { safeReadStorage, safeWriteStorage } from '../lib/safeStorage.js';

/**
 * Chord-sheet play-along transport for a SongBook `tab` / `chordpro` sheet
 * (#4104) — the React wrapper over `lib/chordPlayback.js`, and the chord-sheet
 * counterpart of `useDrumPlayer`. Owns the player lifecycle, the practice
 * settings (tempo / beats-per-chord / count-in / click) and the sounding-chord
 * highlight, so a host only renders controls.
 *
 * Practice tempo and beats-per-chord are PER-SONG, per-machine preferences (a
 * chord sheet carries no tempo of its own, and how long a chord is held is a
 * reading of the sheet rather than a property of it) — they persist to
 * `safeStorage` under the song id, exactly like the viewer's transpose offset,
 * and are never written into the record. The click is global to the machine: a
 * reference pulse you balance against your own playing, not a song property.
 *
 * A timing-critical edit (tempo, beats-per-chord, count-in) while playing STOPS
 * playback rather than re-timing a running schedule — already-scheduled audio
 * can't be moved. The click toggle is the exception: it gates future scheduling
 * only, so it applies live.
 *
 * THE HIGHLIGHT COMES FROM THE AUDIO CLOCK, not the player's `onChord` callback
 * — an event callback stands still through the count-in and cannot say WHERE in
 * a chord you are. One animation-frame loop polls the clock and commits to state
 * only when the sounding chord (or the beat) actually turns over, so the page
 * re-renders on chord changes rather than 60×/second.
 *
 * @param {string} text — the sheet source, already transposed by the caller.
 * @param {{ songId?: string }} [options] — `songId` keys the persisted settings.
 */
export default function useChordPlayer(text, { songId } = {}) {
  const { lines } = useMemo(() => parseTabSheet(text), [text]);
  const occurrences = useMemo(() => sheetChordOccurrences(lines), [lines]);
  const chordCount = occurrences.length;
  // A sheet can hold chord tokens that none of them voice ("N.C." alone) — Play
  // gates on something actually sounding, not on the token count.
  const hasChords = useMemo(
    () => buildChordSchedule(lines).events.some((ev) => !ev.rest),
    [lines],
  );

  const bpmKey = songId ? `songbook:chordBpm:${songId}` : null;
  const beatsKey = songId ? `songbook:chordBeats:${songId}` : null;

  const [bpm, setBpmState] = useState(DEFAULT_CHORD_TEMPO);
  const [beatsPerBar, setBeatsPerBarState] = useState(DEFAULT_CHORD_BEATS_PER_BAR);
  const [countInBars, setCountInBarsState] = useState(1);
  // Off by default: a strummed backing already lands on its own downbeats, so a
  // click over it is the deliberate choice rather than the resting state. The
  // hook's own default keeps "never chosen" distinct from "chosen off".
  const [clickEnabled, setClickEnabled] = useLocalStorageBool('songbook:chordClick', false);
  const [playing, setPlaying] = useState(false);
  const [pulse, setPulse] = useState(null);

  const playerRef = useRef(null);
  // Intent mirror of `playing`: during a first play the player's own flag only
  // flips after `await ctx.resume()`, so a rapid double-toggle read off the
  // player would start playback twice instead of netting out to a cancel.
  const playingRef = useRef(false);
  const setPlayingBoth = useCallback((v) => {
    playingRef.current = v;
    setPlaying(v);
  }, []);

  // Seed the per-song settings. `null` from safeReadStorage is "never set" —
  // distinct from a stored value — so a fresh song takes the defaults.
  useEffect(() => {
    setBpmState(clampBpm(bpmKey ? safeReadStorage(bpmKey) : null) ?? DEFAULT_CHORD_TEMPO);
  }, [bpmKey]);
  useEffect(() => {
    // `null` (never set) must not reach Number(), which would turn it into a 0
    // that then has to be rescued by the range check — the sentinel is tested
    // for explicitly instead.
    const raw = beatsKey ? safeReadStorage(beatsKey) : null;
    const stored = raw == null ? null : Number(raw);
    setBeatsPerBarState(
      stored != null && Number.isFinite(stored) && stored >= CHORD_BEATS_MIN && stored <= CHORD_BEATS_MAX
        ? Math.trunc(stored)
        : DEFAULT_CHORD_BEATS_PER_BAR,
    );
  }, [beatsKey]);

  // One player per sheet; torn down when the sheet changes or the host unmounts,
  // so no interval or scheduled tone outlives the view. Settings arrive from the
  // sync effect below, which runs right after this one.
  useEffect(() => {
    if (!chordCount) {
      playerRef.current = null;
      return undefined;
    }
    const player = createChordPlayer(lines, { onEnded: () => setPlayingBoth(false) });
    playerRef.current = player;
    return () => {
      player.stop();
      playerRef.current = null;
      setPlayingBoth(false);
    };
  }, [lines, chordCount, setPlayingBoth]);

  // Push the timing settings into whatever player is mounted. The player's own
  // setters rebuild only while idle, and every timing setter below stops
  // playback first — so this never re-times live audio.
  useEffect(() => {
    const player = playerRef.current;
    if (!player) return;
    player.setBpm(bpm);
    player.setBeatsPerBar(beatsPerBar);
    player.setCountIn(countInBars);
  }, [lines, bpm, beatsPerBar, countInBars]);

  // The click touches no timing, so it gets its own effect rather than joining
  // the one above — folding it in would rebuild the schedule to deliver what is
  // really a one-line assignment.
  useEffect(() => {
    playerRef.current?.setClick(clickEnabled);
  }, [lines, clickEnabled]);

  // Live read off the audio clock — the source both consumers below share.
  const getPlayhead = useCallback(() => {
    const player = playerRef.current;
    if (!player || !playingRef.current) return null;
    return resolveChordPlayhead(player.schedule(), player.position());
  }, []);

  // The sounding chord + beat readout, polled per frame and committed only when
  // it changes (see the header note).
  useEffect(() => {
    if (!playing || typeof requestAnimationFrame !== 'function') {
      setPulse(null);
      return undefined;
    }
    let raf = requestAnimationFrame(function tick() {
      raf = requestAnimationFrame(tick);
      const head = getPlayhead();
      const next = head && {
        index: head.countIn ? null : head.index,
        beat: head.beat,
        countingIn: !!head.countIn,
      };
      setPulse((prev) => (
        prev?.index === next?.index && prev?.beat === next?.beat && prev?.countingIn === next?.countingIn
          ? prev
          : next
      ));
    });
    return () => cancelAnimationFrame(raf);
  }, [playing, getPlayhead]);

  // Which sheet token to light. `null` while counting in and while stopped — a
  // stale highlight left on the last chord reads as "still playing".
  const sounding = useMemo(() => {
    if (!playing || pulse?.index == null) return null;
    const occurrence = occurrences[pulse.index];
    return occurrence ? { index: pulse.index, ...occurrence } : null;
  }, [playing, pulse?.index, occurrences]);

  const stop = useCallback(() => {
    playerRef.current?.stop();
    setPlayingBoth(false);
  }, [setPlayingBoth]);

  const toggle = useCallback(() => {
    const player = playerRef.current;
    if (!player) return;
    if (playingRef.current) { stop(); return; }
    // The same gate the Play button carries — a sheet with no voiceable chord
    // has nothing to sound, and a key binding must not route around a disabled
    // button.
    if (!hasChords) return;
    setPlayingBoth(true);
    // play() resolves once playback has STARTED; an autoplay-policy failure
    // lands here — reset the button rather than lying "playing".
    Promise.resolve(player.play()).catch((err) => {
      console.error(`🎸 Chord play-along failed to start: ${err.message}`);
      setPlayingBoth(false);
    });
  }, [setPlayingBoth, stop, hasChords]);

  // Timing-critical edits stop playback first (see the header note); the sync
  // effect above then hands the new value to the now-idle player.
  const stopIfPlaying = useCallback(() => {
    if (playingRef.current) stop();
  }, [stop]);

  const setBpm = useCallback((next) => {
    const clamped = clampBpm(next);
    if (clamped == null) return;
    stopIfPlaying();
    setBpmState(clamped);
    if (bpmKey) safeWriteStorage(bpmKey, String(clamped));
  }, [stopIfPlaying, bpmKey]);

  // Percent of the default reference tempo (the practice-slower control). A
  // chord sheet has no written tempo, so DEFAULT_CHORD_TEMPO is the 100% mark.
  const setBpmPercent = useCallback((percent) => {
    setBpm(Math.round((DEFAULT_CHORD_TEMPO * percent) / 100));
  }, [setBpm]);

  const setBeatsPerBar = useCallback((next) => {
    const n = Math.trunc(Number(next));
    if (!Number.isFinite(n) || n < CHORD_BEATS_MIN || n > CHORD_BEATS_MAX) return;
    stopIfPlaying();
    setBeatsPerBarState(n);
    if (beatsKey) safeWriteStorage(beatsKey, String(n));
  }, [stopIfPlaying, beatsKey]);

  // Unparseable input is REJECTED rather than falling through to 0 — 0 is the
  // legitimate "no count-in" choice, so a `|| 0` fallback would make a garbled
  // value indistinguishable from that choice (and silently stop playback for it).
  const setCountInBars = useCallback((next) => {
    const n = Math.trunc(Number(next));
    if (!Number.isFinite(n)) return;
    stopIfPlaying();
    setCountInBarsState(Math.max(0, Math.min(CHORD_COUNT_IN_MAX, n)));
  }, [stopIfPlaying]);

  return {
    chordCount,
    hasChords,
    writtenTempo: DEFAULT_CHORD_TEMPO,
    bpm,
    setBpm,
    setBpmPercent,
    beatsPerBar,
    setBeatsPerBar,
    countInBars,
    setCountInBars,
    clickEnabled,
    setClickEnabled,
    playing,
    pulse,
    sounding,
    getPlayhead,
    toggle,
    stop,
  };
}