@crievo/omni 0.0.0-stage → 0.1.1

package/studio/web/pages/VideoPage/components/SoundTimeline/Waveform.tsx

@@ -0,0 +1,97 @@
+/* The waveform of the source file, with the draggable trim (green edges). */
+
+import { useEffect, useRef, useState } from "react";
+import { loadBuffer } from "../../../../lib/sound-audio";
+
+export function Waveform({
+  url,
+  duration,
+  trim,
+  onChange,
+}: {
+  url: string | null;
+  duration: number;
+  trim: [number, number];
+  onChange: (t: [number, number]) => void;
+}) {
+  const canvas = useRef<HTMLCanvasElement>(null);
+  const [peaks, setPeaks] = useState<Float32Array | null>(null);
+  const dragging = useRef<null | 0 | 1>(null);
+  useEffect(() => {
+    setPeaks(null);
+    if (!url) return;
+    let alive = true;
+    loadBuffer(url)
+      .then(b => {
+        if (!alive) return;
+        const n = 600,
+          d = b.getChannelData(0),
+          step = Math.max(1, Math.floor(d.length / n));
+        const p = new Float32Array(n);
+        for (let i = 0; i < n; i++) {
+          let m = 0;
+          for (let k = i * step; k < Math.min(d.length, (i + 1) * step); k++) m = Math.max(m, Math.abs(d[k]));
+          p[i] = m;
+        }
+        setPeaks(p);
+      })
+      .catch(() => {});
+    return () => {
+      alive = false;
+    };
+  }, [url]);
+  useEffect(() => {
+    const c = canvas.current;
+    if (!c) return;
+    const w = c.clientWidth,
+      h = c.clientHeight,
+      dpr = devicePixelRatio || 1;
+    c.width = w * dpr;
+    c.height = h * dpr;
+    const g = c.getContext("2d")!;
+    g.scale(dpr, dpr);
+    const css = getComputedStyle(c);
+    g.clearRect(0, 0, w, h);
+    const x0 = (trim[0] / duration) * w,
+      x1 = (trim[1] / duration) * w;
+    g.fillStyle = css.getPropertyValue("--surface-3");
+    g.fillRect(x0, 0, x1 - x0, h);
+    if (peaks) {
+      const max = Math.max(...peaks) || 1;
+      for (let i = 0; i < peaks.length; i++) {
+        const x = (i / peaks.length) * w,
+          a = (peaks[i] / max) * (h / 2 - 2);
+        g.fillStyle = x >= x0 && x <= x1 ? css.getPropertyValue("--text-2") : css.getPropertyValue("--border-strong");
+        g.fillRect(x, h / 2 - a, Math.max(1, w / peaks.length - 0.5), a * 2);
+      }
+    }
+    g.fillStyle = css.getPropertyValue("--action");
+    g.fillRect(x0 - 1, 0, 2, h);
+    g.fillRect(x1 - 1, 0, 2, h);
+  }, [peaks, trim, duration]);
+  const position = (e: React.PointerEvent) => {
+    const r = canvas.current!.getBoundingClientRect();
+    return Math.min(duration, Math.max(0, ((e.clientX - r.left) / r.width) * duration));
+  };
+  return (
+    <canvas
+      ref={canvas}
+      className="sound-wave"
+      onPointerDown={e => {
+        const t = position(e);
+        dragging.current = Math.abs(t - trim[0]) < Math.abs(t - trim[1]) ? 0 : 1;
+        (e.target as HTMLElement).setPointerCapture(e.pointerId);
+      }}
+      onPointerMove={e => {
+        if (dragging.current == null) return;
+        const t = +position(e).toFixed(3);
+        const n: [number, number] = [...trim];
+        n[dragging.current] = t;
+        if (n[1] - n[0] >= 0.02) onChange(n);
+      }}
+      onPointerUp={() => {
+        dragging.current = null;
+      }}
+    />
+  );
+}

package/studio/web/pages/VideoPage/components/SoundTimeline/clipActions.ts

@@ -0,0 +1,50 @@
+/* The clip edits (plain functions over this render's state, no hooks): razor, move and delete
+   pieces of animation (a scene's MP4) or of voice (a line's WAV). */
+
+import { quantizeOffset, splitClip } from "../../../../lib/sound-timeline";
+import type { Clip, ClipKind, ClipSelection, Draft, SoundData } from "./types";
+
+export function clipActions({
+  data,
+  draft,
+  changeDraft,
+  setClipSel,
+}: {
+  data: SoundData | null;
+  draft: Draft | null;
+  changeDraft: (f: (r: Draft) => void) => void;
+  setClipSel: (c: ClipSelection | null) => void;
+}) {
+  const clipsOf = (kind: ClipKind, id: string): Clip[] =>
+    (kind === "video" ? draft?.scene_clips[id] : draft?.line_clips[id]) ?? [];
+  /* where the clip's file starts in the video (without the `offset`): the scene start, or the line's */
+  const baseOf = (kind: ClipKind, id: string) =>
+    (kind === "video" ? data?.scenes.find(c => c.id === id)?.start : data?.lines.find(f => f.id === id)?.start) ?? 0;
+  /* the clip's grid: the frame in animation, 1 ms in voice */
+  const stepOf = (kind: ClipKind) => (kind === "video" ? 1 / (data?.format.fps ?? 30) : 0.001);
+  const changeClips = (kind: ClipKind, id: string, f: (cl: Clip[]) => Clip[]) =>
+    changeDraft(r => {
+      const m = kind === "video" ? r.scene_clips : r.line_clips;
+      m[id] = f(m[id] ?? []);
+    });
+  /* shifts a clip (seconds, on its grid) */
+  const moveClip = (kind: ClipKind, id: string, k: number, offset: number) => {
+    const next = quantizeOffset(offset, stepOf(kind));
+    if (next === clipsOf(kind, id)[k]?.offset) return;
+    changeClips(kind, id, cl => cl.map((c, i) => (i === k ? { ...c, offset: next } : c)));
+  };
+  const deleteClip = (kind: ClipKind, id: string, k: number) => {
+    changeClips(kind, id, cl => cl.filter((_, i) => i !== k));
+    setClipSel(null);
+  };
+  /* the razor: the clip becomes two at instant t (original time), each with the same `offset` */
+  const razorCut = (kind: ClipKind, id: string, k: number, t: number) => {
+    const c = clipsOf(kind, id)[k];
+    if (!c) return;
+    const halves = splitClip(c, t, baseOf(kind, id), stepOf(kind));
+    if (!halves) return;
+    changeClips(kind, id, cl => [...cl.slice(0, k), ...halves, ...cl.slice(k + 1)]);
+    setClipSel({ kind, id, k: k + 1 });
+  };
+  return { clipsOf, baseOf, stepOf, moveClip, deleteClip, razorCut };
+}

package/studio/web/pages/VideoPage/components/SoundTimeline/effectActions.ts

@@ -0,0 +1,161 @@
+/* The effect edits (plain functions over this render's state, no hooks): a layer's settings, a new
+   layer with the default sound, a library sound dropped or placed on the timeline, and moving or
+   duplicating the selected effects. */
+
+import type React from "react";
+import type { ActionResult } from "../../../../lib/api";
+import { toOriginal } from "../../../../../../tools/cuts.mjs";
+import { clone, defaultSoundName, findPlanItem, nearestPlace, shiftOriginal } from "../../../../lib/sound-timeline";
+import type { Bed, Cut, Draft, EffectInfo, Place, Plan, Selection, Sound, SoundData } from "./types";
+
+export function effectActions({
+  data,
+  draft,
+  plan,
+  cuts,
+  zoom,
+  tracks,
+  changeDraft,
+  setSel,
+  setMulti,
+  setArmed,
+  setResponse,
+  instantOf,
+  effectOf,
+}: {
+  data: SoundData | null;
+  draft: Draft | null;
+  plan: Plan | null;
+  cuts: Cut[];
+  zoom: number;
+  tracks: React.RefObject<HTMLDivElement | null>;
+  changeDraft: (f: (r: Draft) => void) => void;
+  setSel: (s: Selection) => void;
+  setMulti: (m: string[]) => void;
+  setArmed: (n: string | null) => void;
+  setResponse: (r: ActionResult) => void;
+  instantOf: (l: Place) => number | null;
+  effectOf: (name: string) => EffectInfo | undefined;
+}) {
+  const changeSound = (place: number, layer: number, change: Partial<Sound> | ((s: Sound) => Sound)) =>
+    changeDraft(r => {
+      const s = r.places[place].sounds[layer];
+      r.places[place].sounds[layer] = typeof change === "function" ? change(s) : { ...s, ...change };
+    });
+
+  const defaultSound = (type: Place["type"]): string => defaultSoundName(data?.catalog, type);
+  const addSound = (i: number) => {
+    const name = defaultSound(draft!.places[i].type);
+    if (!name) return;
+    changeDraft(r => {
+      r.places[i].sounds.push({ name });
+    });
+    setSel({ place: i, layer: draft!.places[i].sounds.length });
+  };
+
+  /* a library sound dropped (or clicked, while armed) on the timeline: on a
+     diamond it becomes a layer of that beat; on an effect, it replaces its sound; on
+     the bed row, it becomes the bed; on empty space, it goes to the nearest beat, with
+     the `offset` that puts the peak where it was dropped */
+  const arm = (n: string | null) => {
+    setArmed(n);
+    setResponse(null);
+  };
+  const placeSound = (name: string, el: HTMLElement, clientX: number) => {
+    if (!draft || !data) return;
+    const e = effectOf(name);
+    const onBed = !!el.closest("[data-bed]");
+    if (e?.music && !onBed) {
+      setResponse({ ok: false, error: `“${name}” é trilha: solte na linha da música de fundo` });
+      return;
+    }
+    if (onBed) {
+      changeDraft(r => {
+        r.bed = { ...(r.bed ?? {}), name } as NonNullable<Bed>;
+      });
+      setSel("bed");
+      return;
+    }
+    const ef = el.closest<HTMLElement>("[data-layer]");
+    if (ef) {
+      const place = Number(ef.dataset.place),
+        layer = Number(ef.dataset.layer);
+      changeSound(place, layer, s => ({ ...s, name, trim: undefined }));
+      setSel({ place, layer });
+      return;
+    }
+    const mark = el.closest<HTMLElement>("[data-place]");
+    let place: number,
+      offset = 0;
+    if (mark) place = Number(mark.dataset.place);
+    else {
+      const tDropped = toOriginal((clientX - tracks.current!.getBoundingClientRect().left) / zoom, cuts);
+      const nearest = nearestPlace(draft.places, tDropped, instantOf);
+      if (nearest == null) return;
+      place = nearest;
+      offset = +(tDropped - instantOf(draft.places[place])!).toFixed(2);
+    }
+    const layer = draft.places[place].sounds.length;
+    changeDraft(r => {
+      r.places[place].sounds.push(offset ? { name, offset } : { name });
+    });
+    setSel({ place, layer });
+  };
+  /* the plan item of a "place:layer" key */
+  const itemOf = (k: string) => {
+    const [l, c] = k.split(":").map(Number);
+    const place = draft?.places[l];
+    return place ? findPlanItem(plan?.items ?? [], place, c) : undefined;
+  };
+  /* Shift + drag: each selected effect gets a copy, with the same settings (same
+     duration), shifted by the same amount; each copy goes to the beat nearest to
+     where it landed, with the `offset` that leaves it exactly there. The copies
+     stay selected. */
+  const duplicate = (keys: string[], dt: number) => {
+    if (!draft) return;
+    const added: { k: number; sound: Sound }[] = [];
+    for (const key of keys) {
+      const [l, c] = key.split(":").map(Number);
+      const source = draft.places[l]?.sounds[c],
+        it = itemOf(key);
+      if (!source || !it) continue;
+      const base = source.anchor === "start" ? it.start : it.peak;
+      const point = shiftOriginal(base, dt, cuts);
+      const nearest = nearestPlace(draft.places, point, instantOf);
+      if (nearest == null) continue;
+      const offset = +(point - instantOf(draft.places[nearest])!).toFixed(2);
+      const { offset: _, ...rest } = source;
+      added.push({ k: nearest, sound: offset ? { ...clone(rest), offset } : clone(rest) });
+    }
+    if (!added.length) return;
+    const sizes = draft.places.map(l => l.sounds.length);
+    const newKeys = added.map(n => `${n.k}:${sizes[n.k]++}`);
+    changeDraft(r => {
+      for (const n of added) r.places[n.k].sounds.push(n.sound);
+    });
+    setMulti(newKeys);
+    const [l, c] = newKeys.at(-1)!.split(":").map(Number);
+    setSel({ place: l, layer: c });
+  };
+  /* drag without Shift: the selected ones move together (each one's `offset`); the
+     on-screen shift is in edited time, and the `offset` in original time */
+  const move = (keys: string[], dt: number) => {
+    const shift = new Map(
+      keys.map(key => {
+        const [l, c] = key.split(":").map(Number);
+        const it = itemOf(key),
+          so = draft?.places[l]?.sounds[c];
+        const base = !it ? 0 : so?.anchor === "start" ? it.start : it.peak;
+        return [key, it ? shiftOriginal(base, dt, cuts) - base : dt];
+      }),
+    );
+    changeDraft(r => {
+      for (const key of keys) {
+        const [l, c] = key.split(":").map(Number);
+        const so = r.places[l]?.sounds[c];
+        if (so) r.places[l].sounds[c] = { ...so, offset: +((so.offset ?? 0) + shift.get(key)!).toFixed(2) };
+      }
+    });
+  };
+  return { changeSound, defaultSound, addSound, arm, placeSound, duplicate, move };
+}

package/studio/web/pages/VideoPage/components/SoundTimeline/index.tsx

@@ -0,0 +1,161 @@
+/* Sound timeline: the effects of beats and transitions and the video's bed, over
+   the voice. Each change goes to the server, which plans with tools/sound.mjs
+   itself (volume relative to the voice, ducking, trim, stretch, pitch) and
+   returns the ready WAVs; the UI plays those WAVs and the voice in Web Audio, with
+   the muted export on top only for the picture. What you hear here is what
+   assemble mixes. Saving writes to scenes.json; the export changes on reassembly.
+
+   Tools: Select (V) moves the effects; Area cut (C) marks a span and removes
+   everything inside it from the export (tools/cuts.mjs). The timeline shows the
+   video already cut: what comes after moves back, and what crosses the cut
+   loses only the inside part. Cuts live in `cuts` in scenes.json, in scenes.json
+   time; the UI converts.
+
+   Animation and voice are separate tracks made of clips (tools/soundtrack.mjs):
+   Razor (B) splits an animation or a line in two at the clicked point, and each
+   piece drags (changes its `offset`) or is deleted on its own. Beat effects move
+   with the animation piece; the caption, with the voice piece. While the export
+   doesn't have that arrangement, the preview plays the scene MP4s (no captions). */
+
+import type React from "react";
+import { useEffect } from "react";
+import { toEdited, toOriginal } from "../../../../../../tools/cuts.mjs";
+import { SessionPanel } from "../../../../components/SessionPanel";
+import type { VideoDetail } from "../../../../types/api";
+import { EditorTabBar } from "./EditorTabBar";
+import { captionEditor } from "../CaptionPositionEditor/captionEditor";
+import { useCaptionPosition } from "../CaptionPositionEditor/useCaptionPosition";
+import { CaptionsPanel } from "./CaptionsPanel";
+import { CutsPanel } from "./CutsPanel";
+import { PlanWarnings } from "./PlanWarnings";
+import { PlayerResizeHandle } from "./PlayerResizeHandle";
+import { SettingsPanel } from "./SettingsPanel";
+import { SoundLibrary } from "./SoundLibrary";
+import { SoundPreview } from "./SoundPreview";
+import { TimelineDock } from "./TimelineDock";
+import { TimelineSkeleton } from "./TimelineSkeleton";
+import { timelineGeometry } from "./timelineGeometry";
+import { useSoundTimeline } from "./useSoundTimeline";
+import { useOmniHandle } from "../../../../lib/omni-ui";
+
+export function SoundTimeline({
+  video,
+  sidebar,
+  drawerButton,
+}: {
+  video: VideoDetail;
+  sidebar?: React.ReactNode;
+  drawerButton?: React.ReactNode;
+}) {
+  const st = useSoundTimeline(video);
+  /* Omni drives the player and the tabs (lib/omni-ui: control_editor, add_epidemic_sound) */
+  useOmniHandle(`editor:${video.slug}`, {
+    ...(st.plan
+      ? {
+          play: async (at?: number) => {
+            await st.play(at ?? (st.t >= st.editedTotal - 0.05 ? 0 : st.t));
+            return { ok: true };
+          },
+        }
+      : {}),
+    pause: () => st.stop(),
+    status: () => ({ playing: st.playing, at: st.t, total: st.editedTotal }),
+    openTab: st.setTab,
+  });
+  /* the caption editor lives here, not in its tab: an unsaved change survives switching tabs. While
+     the tab is open the preview shows the captions at the playhead's instant */
+  const onCaptions = st.tab === "captions";
+  const cap = useCaptionPosition(video, onCaptions ? toOriginal(st.t, st.cuts) : null);
+  const { sel: capSel, caption: capCaption } = cap;
+  const { seek: seekTo, cuts: stCuts } = st;
+  /* choosing a caption in the list puts the playhead on it */
+  useEffect(() => {
+    if (!onCaptions || !capCaption) return;
+    seekTo(toEdited((capCaption.s + capCaption.e) / 2, stCuts));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [capSel, onCaptions]);
+  const { data, draft, dataError, sel, root, side, height, manualWidth, tab, armed, arm, setDraggingSound } = st;
+
+  if (dataError) return <p className="response error">{dataError}</p>;
+  if (!data || !draft) return <TimelineSkeleton />;
+
+  /* saving the caption also renders the export again, with the sound saved so far */
+  const captions = cap.data && cap.draft ? captionEditor(cap, cap.data, cap.draft, st.render) : null;
+  const geo = timelineGeometry(st, data, draft);
+  const selPlace = sel && sel !== "bed" ? draft.places[sel.place] : null;
+
+  /* vertical video: the player goes to the right column, full height, and the panels and the
+     sounds move up to where it was; in landscape, the player stays wide above the timeline */
+  const vertical = data.format.h > data.format.w;
+  /* the video takes the full height (the controls float over it); at least 400 px, so the controls fit on one line */
+  const autoWidth = height ? Math.round(Math.min(600, Math.max(400, (height * data.format.w) / data.format.h))) : 400;
+  /* the player edge drags: it grows and the left column shrinks, down to 480 px */
+  const clampWidth = (w: number) => {
+    const total = root.current?.clientWidth ?? 1200;
+    return Math.round(Math.max(300, Math.min(total - 12 - 480, w)));
+  };
+  const playerWidth = manualWidth ? clampWidth(manualWidth) : autoWidth;
+  const preview = <SoundPreview st={st} data={data} captions={captions} />;
+  const dock = <TimelineDock st={st} geo={geo} data={data} draft={draft} selPlace={selPlace} />;
+  const warnings = <PlanWarnings st={st} data={data} />;
+  const tabBar = <EditorTabBar st={st} hasScenes={!!sidebar} drawerButton={drawerButton} />;
+  const tabContent =
+    tab === "agent" ? (
+      <SessionPanel type="edit" target={video.slug} before={st.beforeAgent} chat />
+    ) : tab === "settings" ? (
+      <SettingsPanel st={st} data={data} draft={draft} selPlace={selPlace} E={geo.E} fps={geo.fps} />
+    ) : tab === "captions" ? (
+      <CaptionsPanel editor={captions} busy={st.rendering} />
+    ) : tab === "cuts" ? (
+      <CutsPanel st={st} data={data} E={geo.E} />
+    ) : tab === "scenes" && sidebar ? (
+      <section className="sound-renders">{sidebar}</section>
+    ) : (
+      <SoundLibrary
+        catalog={data.catalog}
+        slug={video.slug}
+        armed={armed}
+        onArm={arm}
+        onDrag={setDraggingSound}
+        onAdd={st.reloadCatalog}
+      />
+    );
+
+  if (vertical)
+    return (
+      <div
+        ref={root}
+        className="sound-timeline vertical"
+        style={{ ...(height ? { height } : {}), ["--player-width" as string]: `${playerWidth}px` }}
+      >
+        <div className="sound-main">
+          <div className="sound-top">
+            {warnings}
+            {tabBar}
+            <section ref={side} className="sound-side">
+              {tabContent}
+            </section>
+          </div>
+          {dock}
+        </div>
+        <aside className="sound-column-player">
+          {/* handle on the left edge: dragging changes the player width; double click returns to automatic */}
+          <PlayerResizeHandle st={st} playerWidth={playerWidth} clampWidth={clampWidth} />
+          {preview}
+        </aside>
+      </div>
+    );
+  return (
+    <div ref={root} className="sound-timeline" style={height ? { height } : undefined}>
+      <div className="sound-main">
+        {preview}
+        {dock}
+      </div>
+      <aside ref={side} className="sound-side">
+        {warnings}
+        {tabBar}
+        {tabContent}
+      </aside>
+    </div>
+  );
+}

package/studio/web/pages/VideoPage/components/SoundTimeline/timelineGeometry.ts

@@ -0,0 +1,45 @@
+/* The timeline's geometry for one render: seconds ↔ px at the current zoom, original ↔ edited
+   time, and the pointer snapped (area cut, razor) or the clip edges a drag snaps to. */
+
+import type React from "react";
+import { clipEdgesOf, snapPointer, snapRazor, timelineScale } from "../../../../lib/sound-timeline";
+import type { SoundTimelineState } from "./useSoundTimeline";
+import type { ClipKind, Draft, SoundData } from "./types";
+
+export function timelineGeometry(st: SoundTimelineState, data: SoundData, draft: Draft) {
+  const { zoom, cuts, tracks, editedTotal, t, animScenes } = st;
+  const width = Math.max(600, editedTotal * zoom);
+  /* original time → edited (the timeline's), and the box of an original span; empty if it fell in a cut */
+  const { x, E, boxOf } = timelineScale(zoom, cuts);
+  const fps = data.format.fps;
+  /* the pointer on the timeline, in edited time; snapping to the edges of lines, scenes and the
+     playhead (Alt releases the snap), aligned to the frame */
+  const pointerTime = (e: React.PointerEvent) =>
+    snapPointer((e.clientX - tracks.current!.getBoundingClientRect().left) / zoom, {
+      alt: e.altKey,
+      zoom,
+      fps,
+      total: editedTotal,
+      targets: [
+        0,
+        editedTotal,
+        t,
+        ...data.lines.flatMap(f => [E(f.start), E(f.end)]),
+        ...data.scenes.map(c => E(c.start)),
+      ],
+    });
+  /* the razor: the pointer in edited time, snapping only to the playhead (Alt releases), on the frame */
+  const razorTime = (e: React.PointerEvent) =>
+    snapRazor((e.clientX - tracks.current!.getBoundingClientRect().left) / zoom, {
+      alt: e.altKey,
+      zoom,
+      fps,
+      total: editedTotal,
+      t,
+    });
+  /* the edges of all clips (edited time), for the drag snap; without the clip itself */
+  const clipEdges = (kind: ClipKind, id: string, k: number) =>
+    clipEdgesOf(kind, id, k, { scenes: animScenes, lines: data.lines, lineClips: draft.line_clips, E });
+  return { width, x, E, boxOf, fps, pointerTime, razorTime, clipEdges };
+}
+export type TimelineGeometry = ReturnType<typeof timelineGeometry>;

package/studio/web/pages/VideoPage/components/SoundTimeline/types.ts

@@ -0,0 +1,43 @@
+/* SoundTimeline's types: the API's (shared/types/api.ts) under the short names the editor uses,
+   and the editor's own UI state. */
+
+import type {
+  SoundBed,
+  SoundBedItem,
+  SoundCatalog,
+  SoundClip,
+  SoundCut,
+  SoundData,
+  SoundDraft,
+  SoundDraftPlan,
+  SoundEffectInfo,
+  SoundLayer,
+  SoundPlace,
+  SoundPlanItem,
+} from "../../../../types/api";
+
+export type { SoundCatalog, SoundData };
+export type Sound = SoundLayer;
+export type Place = SoundPlace;
+export type Bed = SoundBed;
+export type Cut = SoundCut;
+export type EffectInfo = SoundEffectInfo;
+export type Clip = SoundClip;
+export type PlanItem = SoundPlanItem;
+export type BedItem = SoundBedItem;
+export type Plan = SoundDraftPlan;
+export type Draft = SoundDraft;
+
+export type EditorTab = "agent" | "settings" | "sounds" | "cuts" | "captions" | "scenes";
+export type AudioRow = "voice" | "effects" | "bed";
+export type EditorTool = "select" | "razor" | "cut";
+export type ClipKind = "video" | "voice";
+export type ClipSelection = { kind: ClipKind; id: string; k: number };
+export type Selection = { place: number; layer: number } | "bed" | null;
+/* a clip being dragged: its offset while the pointer moves */
+export type ClipDragOffset = { kind: ClipKind; id: string; k: number; offset: number };
+/* effects being dragged ("place:layer" keys), the shift in px and whether it copies (Shift) */
+export type EffectDragOffset = { keys: string[]; dx: number; copy: boolean };
+/* a scene with the draft's clips (the animation track) */
+export type AnimScene = SoundData["scenes"][number];
+export type SoundLine = SoundData["lines"][number];

package/studio/web/pages/VideoPage/components/SoundTimeline/useAutosave.ts

@@ -0,0 +1,107 @@
+/* Autosave and render: 5 s after the last edit, the draft goes to scenes.json. Saving doesn't
+   render: the export only changes with the Renderizar button, which lights up when there is a
+   saved edit it doesn't have yet. Before the edit chat runs, the hand edits are saved; leaving the
+   screen with an edit waiting saves it on the way out; the new export arriving reloads the data. */
+
+import { type RefObject, useCallback, useEffect, useRef } from "react";
+import type { ActionResult } from "../../../../lib/api";
+import { soundRoutes } from "../../../../hooks/useSound";
+import type { Draft } from "./types";
+
+export function useAutosave({
+  slug,
+  draft,
+  dirty,
+  planError,
+  agentEditing,
+  agentEditingRef,
+  assembledAt,
+  loadData,
+  setSaving,
+  setResponse,
+  setDirty,
+  setSavedAt,
+  setPending,
+  setRendering,
+}: {
+  slug: string;
+  draft: Draft | null;
+  dirty: boolean;
+  planError: string | null;
+  agentEditing: boolean;
+  agentEditingRef: RefObject<boolean>;
+  assembledAt: unknown;
+  loadData: () => void;
+  setSaving: (s: boolean) => void;
+  setResponse: (r: ActionResult) => void;
+  setDirty: (d: boolean) => void;
+  setSavedAt: (d: Date) => void;
+  setPending: (p: boolean) => void;
+  setRendering: (r: boolean) => void;
+}) {
+  /* autosave: 5 s after the last edit, the draft goes to scenes.json. Saving
+     doesn't render: the export only changes with the Renderizar button, which
+     lights up when there is a saved edit it doesn't have yet */
+  const draftRef = useRef<Draft | null>(null);
+  draftRef.current = draft;
+  const dirtyRef = useRef(false);
+  dirtyRef.current = dirty;
+  const save = useCallback(async () => {
+    const r0 = draftRef.current;
+    if (!r0) return false;
+    setSaving(true);
+    const r = await soundRoutes(slug).save(r0);
+    setSaving(false);
+    if (!r.ok) {
+      setResponse(r);
+      return false;
+    }
+    /* only clears if nothing changed while saving; otherwise the next debounce saves the rest */
+    if (draftRef.current === r0) setDirty(false);
+    setSavedAt(new Date());
+    setPending(true);
+    return true;
+  }, [slug]);
+  useEffect(() => {
+    if (!dirty || planError || agentEditing) return;
+    const id = setTimeout(() => {
+      save();
+    }, 5000);
+    return () => clearTimeout(id);
+  }, [draft, dirty, planError, save, agentEditing]);
+  /* before sending a request to the edit chat: what was changed by hand goes to scenes.json */
+  const beforeAgent = useCallback(async () => (dirtyRef.current ? await save() : true), [save]);
+  /* left the screen with an edit waiting for the debounce: save on the way out
+     (raw fetch: keepalive, so the request survives the page going away) */
+  useEffect(() => {
+    const leave = () => {
+      if (!dirtyRef.current || !draftRef.current || agentEditingRef.current) return;
+      soundRoutes(slug).save(draftRef.current, true);
+    };
+    addEventListener("pagehide", leave);
+    return () => {
+      removeEventListener("pagehide", leave);
+      leave();
+    };
+  }, [slug]);
+
+  const render = async () => {
+    if (dirty && !(await save())) return;
+    const r = await soundRoutes(slug).reassemble();
+    setResponse(r.ok ? { ok: true, output: "Renderizando o export com o som novo (acompanhe na fila)" } : r);
+    if (r.ok) {
+      setPending(false);
+      setRendering(true);
+    }
+  };
+  /* the new export arrived (assembly.json changed): the preview picture becomes it */
+  const assembledBefore = useRef(assembledAt);
+  useEffect(() => {
+    if (assembledAt === assembledBefore.current) return;
+    assembledBefore.current = assembledAt;
+    setRendering(false);
+    if (!dirtyRef.current) loadData();
+  }, [assembledAt, loadData]);
+
+  return { draftRef, beforeAgent, render };
+}