arthur/frontend/src/arthur/clock.cljs

(ns arthur.clock
  "The audio clock. Lives OUTSIDE app-db, deliberately.

  THE FRAME IS DERIVED FROM THE AUDIO, never counted:

      frame = ⌊position · fps⌋

  A loop that counted frames and hoped to keep up would drift, and drift against
  a voice is the one artefact that cannot be fixed downstream — a lip-sync tool
  whose sync wanders is not a lip-sync tool. Deriving instead means a slow frame
  DROPS the frames it missed and the next one lands where the audio already is.
  The failure mode becomes a visible stutter rather than an invisible slide, and
  those are very different bugs to own.

  ½× and ¼× are the backend's playback rate and nothing else. The audio slows,
  the position advances proportionally, and the derived frame follows — so slow
  motion cannot desync by construction. Implementing rate as a multiplier on a
  counted frame would give the picture a rate and the sound another.

  It is outside app-db because the audio is the source of truth and copying it
  into the db every frame would make the db a lagging mirror of something
  authoritative elsewhere. What DOES belong in the db is the playhead as a piece
  of document state — see events/playback — and that is written from here, not
  read by here.

  TWO BACKENDS, ONE ARITHMETIC. `position` comes from either a Web Audio graph
  (`clock.graph`, the default) or an `<audio>` element (`clock.element`, kept
  switchable while the first earns trust). Everything below the position — the
  derivation, the clamp, the exposure grid — is here and is the same either way,
  so the two can be compared on the same take rather than swapped on faith.
  Build with `:closure-defines {arthur.clock/BACKEND \"element\"}`, or call
  `use-backend!` from the console, to put the element back."
  (:require [arthur.clock.element :as element]
            [arthur.clock.graph :as graph]
            [arthur.clock.transport :as t]
            [arthur.domain.node :as node]))

(goog-define ^String BACKEND "graph")

(defonce ^:private mode (atom (keyword BACKEND)))

;; `{:source x :backend b}`. The source is kept so that re-attaching the same
;; thing can be recognised as the no-op it is — see `install!`.
(defonce ^:private current (atom nil))

(defn graph?
  "Whether the app should wire up the graph backend. Read by `ui/shell`, which
  renders the audio element only when this is false, and by `events/playback`,
  which fetches a buffer rather than a WAV URL when it is true."
  []
  (and (= :graph @mode) (graph/available?)))

(defn use-backend!
  "Switch backends. Takes effect on the next thing that attaches one, which is
  the next tab switch or document open — nothing is torn down under a take
  that is already playing."
  [m]
  (reset! mode m))

(defn- install!
  "Put a backend on `source`, unless `source` is already the clock's.

  IDEMPOTENCE IS LOAD-BEARING HERE. The element's `:ref` is an inline closure,
  so React hands it the same node again on every re-render of the shell —
  rebuilding the clock there would mean a pane being dragged released whatever
  was playing. The source is the identity: the element, or the buffer and its
  length."
  [source make]
  (let [{:keys [backend] prev :source} @current]
    (when-not (and backend (= prev source))
      (when backend (t/-release! backend))
      (reset! current {:source source
                       :backend (when (some? source) (make))}))))

(defn attach!
  "Hand the clock an audio element. Idempotent. Element backend only — the
  `:ref` that calls this is on a node `ui/shell` renders only in that mode."
  [audio-el]
  (install! audio-el #(element/backend audio-el)))

(defn attach-buffer!
  "Hand the clock `seconds` of audio to run on, as an `AudioBuffer` or as nil
  for silence of that length. Graph backend only."
  [buffer seconds]
  ;; Keyed on the length as well as the buffer, because two silent clocks of
  ;; different lengths are two different clocks and both have a nil buffer.
  (install! [buffer seconds] #(graph/backend buffer seconds)))

(defn- clamp [f frames]
  (-> f (max 0) (min (dec frames))))

(defn frame
  "The clip frame the audio is currently on."
  [fps frames]
  (if-let [b (:backend @current)]
    (clamp (js/Math.floor (* (t/-position b) fps)) frames)
    0))

(defn playing? []
  (boolean (when-let [b (:backend @current)] (t/-playing? b))))

(defn rate []
  (if-let [b (:backend @current)] (t/-rate b) 1.0))

(defn set-rate! [r]
  (when-let [b (:backend @current)] (t/-set-rate! b r)))

(defn play! []
  (when-let [b (:backend @current)] (t/-play! b)))

(defn pause! []
  (when-let [b (:backend @current)] (t/-pause! b)))

(defn seek!
  "Put the audio at the start of frame f. Seeking to the frame's start rather
  than its middle keeps `frame` idempotent: seek to f, read back f."
  [fps frames f]
  (when-let [b (:backend @current)]
    (t/-seek! b (/ (clamp f frames) fps))))

(defn set-loop!
  "Wrap at the end instead of stopping. The frame stays derived — the position
  simply returns to zero — so nothing about the sync changes, which is the point
  of not counting frames.

  It earns its place at 2x and 4x, where the whole clip is gone in under four
  seconds and a profile wants more than that to look at."
  [on?]
  (when-let [b (:backend @current)] (t/-set-loop! b on?)))

(defn set-muted! [on?]
  (when-let [b (:backend @current)] (t/-set-muted! b on?)))

(defn duration-frames
  "How many frames the audio actually covers, which need not be the clip's
  length. Reported rather than assumed: a clip longer than its audio is a
  legitimate thing to be told about, not a thing to silently truncate."
  [fps]
  (when-let [b (:backend @current)]
    (let [d (t/-duration b)]
      (when (and d (js/isFinite d)) (js/Math.ceil (* d fps))))))

(defn exposed-frame
  "The frame a clip-level exposure grid holds `f` back onto. The player shows it
  as a readout so that `exposure 2` is visibly doing something at the transport
  rather than only inside the scene."
  [f expose]
  (node/expose f expose))