Skip to content

Write HTML. Render video. Built for agents.

18.9 KB
Raw Blame
import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
/**
 * The voiceover carve, as one module in the FX rack.
 *
 * Carve is deliberately not an entry in the chain. It is a relationship between
 * two tracks — it analyses a voice and dips *this* bed where that voice sits —
 * so it gets its own card with a source picker, the way a sidechain control
 * lives on the track being processed. What it produces is an ordinary chain of
 * peaking filters, so it composes with whatever else is on the track.
 */

import {
  defaultAudioFxParams,
  getAudioFxDef,
  type HfAudioFxNode,
  type HfAudioFxParam,
} from "@hyperframes/core/audio-fx";
import { DEFAULT_CARVE, type HfCarveSettings } from "@hyperframes/core/audio-carve";
import { fxAutomationTarget } from "@hyperframes/core/audio-automation";
import { FxParamRow } from "./propertyPanelFxControls.js";
import { FX_FAMILY_TYPE, fxFamilyTint } from "./propertyPanelFxFamily.js";
import { fxTintWash } from "./propertyPanelFxPresetStyle.js";
// Shared with the timeline's lane labels: a band is named by its frequency in
// both places, and two formatters would drift.
import { formatHz } from "../../player/components/automationLaneData";

export interface AudioTrackOption {
  id: string;
  label: string;
}

/** What one effect inside the module is called: its own name, plus the band. */
function carveMemberName(node: HfAudioFxNode): string {
  const def = getAudioFxDef(node.type);
  const freq = node.params?.["frequency"];
  const label = def?.label ?? node.type;
  return typeof freq === "number" ? `${label} ${formatHz(freq)}` : label;
}

/** A parameter's value as the rack shows it: rounded to the step, with its unit. */
function formatParamValue(param: HfAudioFxParam, raw: number | string | undefined): string {
  if (param.kind !== "number" || typeof raw !== "number") return String(raw ?? "");
  const places = param.step >= 1 ? 0 : param.step >= 0.1 ? 1 : 2;
  return `${Number(raw.toFixed(places))}${param.unit ? ` ${param.unit}` : ""}`;
}

/**
 * Width to reserve for a parameter's value, in characters.
 *
 * Derived from what the parameter CAN read rather than what it currently reads, so
 * the column never moves: an automated value updates 30 times a second, and
 * `-1 dB` is two characters narrower than `-3.2 dB`, which was enough to shunt
 * everything after it sideways on every frame. `ch` is exact here because the
 * readouts are monospace and already `tabular-nums`.
 */
function paramValueWidthCh(param: HfAudioFxParam): number {
  if (param.kind === "enum") {
    return Math.max(1, ...param.options.map((option) => option.value.length));
  }
  const places = param.step >= 1 ? 0 : param.step >= 0.1 ? 1 : 2;
  const digits = Math.max(
    String(Math.floor(Math.abs(param.min))).length,
    String(Math.floor(Math.abs(param.max))).length,
  );
  const sign = param.min < 0 ? 1 : 0;
  const decimals = places > 0 ? places + 1 : 0;
  const unit = param.unit ? param.unit.length + 1 : 0;
  return sign + digits + decimals + unit;
}

/** One member of the module: what it is, and what every knob is set to. */
function FxCarveMember({
  node,
  automatedTargets,
  liveAutomationValues,
}: {
  node: HfAudioFxNode;
  automatedTargets?: ReadonlySet<string>;
  liveAutomationValues?: ReadonlyMap<string, number>;
}) {
  const def = getAudioFxDef(node.type);
  if (!def) return null;
  const params = node.params ?? defaultAudioFxParams(node.type);
  return (
    <div className="hf-fx-carve-member flex flex-col gap-0.5 py-1 pl-3 pr-1.5">
      <span className="hf-fx-carve-member-name truncate font-mono text-[9px] text-panel-text-1">
        {carveMemberName(node)}
      </span>
      <div className="flex flex-wrap gap-x-3 gap-y-0.5">
        {def.params.map((param) => {
          const target = node.id ? fxAutomationTarget(node.id, param.key) : null;
          const automated = Boolean(target && automatedTargets?.has(target));
          // The envelope's value at the playhead when there is one, which is what
          // the audio is using; the stored number is only the seed behind it.
          const live = target ? liveAutomationValues?.get(target) : undefined;
          const driven = automated && live !== undefined;
          const value = formatParamValue(param, driven ? live : params[param.key]);
          return (
            <span
              key={param.key}
              className="flex items-baseline gap-1 font-mono text-[9px] text-panel-text-2"
              {...(automated ? { "data-automated": "" } : {})}
              {...(driven ? { "data-automation-live": "" } : {})}
            >
              <span className="text-panel-text-2">{param.label}</span>
              <span
                className="tabular-nums text-panel-text-1"
                style={{ minWidth: `${paramValueWidthCh(param)}ch` }}
              >
                {value}
              </span>
              {/* The lane is where an automated value comes from, and where it is
                  edited — saying so is the difference between a stale readout and
                  a pointer to the thing that owns it. */}
              {automated ? <span className="text-accent-ink">A</span> : null}
            </span>
          );
        })}
      </div>
    </div>
  );
}

/**
 * The carve, as one module in the rack.
 *
 * A carve is one thing the author switched on; the peaking filters and the level
 * stage are how it is built. Listed individually they read as hand-built effects —
 * removable one at a time, reorderable, each with knobs the next strength change
 * silently overwrites. So the rack shows the unit, and the unit owns everything
 * that means anything for it: which voice it listens to, how hard it works,
 * whether it follows that voice, and what the analysis made of it.
 *
 * The controls used to sit in their own block under the rack, which read as a
 * second, unrelated feature that happened to produce effects somewhere else. One
 * card, controls above the analysis they drive, is the same thing said once.
 *
 * Grouped is not hidden. Opening it lists every effect inside with all of its
 * settings, because an author has to be able to see where the analysis landed — as
 * readouts rather than controls, since strength is what sets them and a knob here
 * would be overwritten by the next adjustment.
 */
export function FxCarveModule({
  nodes,
  carve,
  sourceOptions,
  automatedTargets,
  liveAutomationValues,
  open,
  disabled,
  analysing,
  onToggleOpen,
  onCarveChange,
  onCarvePreview,
}: {
  nodes: HfAudioFxNode[];
  carve: HfCarveSettings;
  sourceOptions: AudioTrackOption[];
  automatedTargets?: ReadonlySet<string>;
  liveAutomationValues?: ReadonlyMap<string, number>;
  open: boolean;
  disabled?: boolean;
  analysing?: boolean;
  onToggleOpen(): void;
  onCarveChange(carve: HfCarveSettings): void;
  onCarvePreview(carve: HfCarveSettings): void;
}) {
  const on = carve.enabled;
  const trackInput = useTrackDesignInput();
  const soleVoice = soleCarveVoice(sourceOptions, carve.sources);
  const summary = carveSummary({ nodes, carve, analysing });
  // The carve's own colour, used three ways: the module's left edge, the title,
  // and the wash behind it. A preset gets a title treatment because it is a
  // character; the carve gets one because it is the only module in the rack
  // that LISTENS to another track, and a plain row understates that. It stays
  // in the smart family's monospace — what it shows is a readout, and a
  // display face would promise settings the author chose.
  const tint = fxFamilyTint({ type: "carve", fromCarve: true });
  const wash = fxTintWash(tint);
  return (
    <div
      className={`hf-fx-node hf-fx-carve-module hf-fx-carve rounded-[4px] border border-l-2 border-panel-border-input${
        on ? "" : " opacity-50"
      }`}
      data-fx-node="carve"
      data-fx-family="smart"
      // Smart, like the Tone EQ and the leveller: it measures the audio and
      // writes its own settings, and what it shows is a readout of what it
      // decided rather than controls the author set.
      style={{ borderLeftColor: tint, ...(wash ? { backgroundColor: wash } : {}) }}
      data-carve-enabled={on ? "" : undefined}
    >
      <div className="hf-fx-node-head flex min-h-7 items-center gap-1 px-1.5">
        <button
          type="button"
          className={`hf-fx-node-name min-w-0 flex-1 truncate text-left text-[13px] uppercase hover:opacity-80 ${FX_FAMILY_TYPE.smart}`}
          // Tracking goes here rather than in a class: the smart family already
          // sets `tracking-normal`, and two Tailwind tracking utilities on one
          // element resolve by stylesheet order, not by the order written.
          style={{ color: tint, letterSpacing: "0.16em" }}
          // Truncates in a narrow panel like every other name in the rack.
          title="Voiceover carve"
          aria-expanded={open}
          onClick={onToggleOpen}
        >
          Voiceover carve
        </button>
        <span className="hf-fx-carve-summary shrink-0 font-mono text-[9px] text-panel-text-2">
          {summary}
        </span>
        {/* One switch, not a bypass and a delete. Off drops the effects and the
            envelopes it wrote, and is remembered — otherwise the default would
            re-apply the carve the next time this clip was selected. */}
        <button
          type="button"
          className="hf-fx-bypass hf-fx-carve-toggle rounded-[3px] border border-panel-border-input px-1.5 py-0.5 font-mono text-[9px] text-panel-text-2 hover:text-panel-text-0 disabled:opacity-40"
          aria-pressed={on}
          title={on ? "Switch the carve off" : "Switch the carve on"}
          disabled={disabled}
          onClick={() => {
            onCarveChange({ ...carve, enabled: !on });
            trackInput("toggle", "carve-enabled");
          }}
        >
          {on ? "On" : "Off"}
        </button>
      </div>
      {open && on ? (
        <div className="hf-fx-carve-body border-t border-panel-border-input">
          <div className="hf-fx-carve-controls space-y-0.5 px-1.5 py-1.5">
            <CarveSourceRow
              carve={carve}
              sourceOptions={sourceOptions}
              soleVoice={soleVoice}
              disabled={disabled}
              onCarveChange={onCarveChange}
            />
            {/* One knob for the whole effect. Depth, band count, width, the
                intelligibility weighting and both level-match numbers move together
                anyway — a gentle carve is shallow in few bands with little ducking, a
                hard one is deeper in more with more — so the panel sets the strength
                and `carveProfile` derives the six numbers the analysis works in. */}
            <FxParamRow
              param={{
                kind: "number",
                key: "strength",
                label: "Strength",
                unit: "",
                min: 0,
                max: 1,
                step: 0.05,
                default: DEFAULT_CARVE.strength,
                hint: "How hard to carve: deeper cuts, in more bands, and more room made by dropping the bed's level under the voice. At 0 it carves frequencies only. Moving this re-runs the analysis on what is already here.",
              }}
              value={carve.strength}
              disabled={disabled || carve.sources.length === 0}
              onChange={(_k, v) => onCarvePreview({ ...carve, strength: Number(v) })}
              onCommit={(_k, v) => {
                onCarveChange({ ...carve, strength: Number(v) });
                trackInput("slider", "carve-strength");
              }}
            />
          </div>
          {/* What the analysis made of all that. Divided rather than boxed: these
              are parts of one module, and a border around each would read as the
              separate effects this replaced. */}
          {/* While the analysis runs, the previous filters are gone rather than
              stale. Every number in that list is about to be replaced — a strength
              change re-derives all of them — so leaving them up reads as the
              settings that are in force when they are already history, and the one
              honest thing to say is that the work is happening. */}
          <CarveAnalysis
            nodes={nodes}
            analysing={analysing}
            hasSources={carve.sources.length > 0}
            automatedTargets={automatedTargets}
            liveAutomationValues={liveAutomationValues}
          />
        </div>
      ) : null}
    </div>
  );
}

/**
 * The only track this bed could be listening to, when there is exactly one.
 *
 * A picker with one entry is a question with one answer: it asks the author to
 * confirm something already decided. So the voice reads out instead.
 *
 * Not when the stored source is some OTHER track, though — a name that no longer
 * classifies as a voice, or a track since renamed. Reading out the one remaining
 * candidate there would quietly claim the carve listens to something it does not,
 * so the picker comes back and shows the mismatch.
 */
function soleCarveVoice(
  sourceOptions: AudioTrackOption[],
  sources: readonly string[],
): AudioTrackOption | null {
  if (sourceOptions.length !== 1) return null;
  const only = sourceOptions[0];
  if (!only) return null;
  if (sources.length === 0) return only;
  return sources.length === 1 && sources[0] === only.id ? only : null;
}

/**
 * What the module is worth right now, for its head, so a collapsed card still
 * says whether it is doing anything: the analysis it produced, or why not.
 */
function carveSummary(input: {
  nodes: HfAudioFxNode[];
  carve: HfCarveSettings;
  analysing?: boolean;
}): string {
  const { nodes, carve, analysing } = input;
  if (!carve.enabled) return "off";
  if (analysing) return "analysing…";
  const bands = nodes.filter((n) => n.type === "peaking").length;
  if (bands === 0) return carve.sources.length > 0 ? "no analysis yet" : "pick a voice";
  return [
    `${bands} band${bands === 1 ? "" : "s"}`,
    ...(nodes.some((n) => n.type === "gain") ? ["level"] : []),
    // Worth saying when it is more than one: the cuts follow whoever is
    // speaking, and that is not obvious from a band count.
    ...(carve.sources.length > 1 ? [`${carve.sources.length} voices`] : []),
  ].join(" + ");
}

/** Which voices the bed makes room for: a readout when there is only one to
 *  choose, otherwise a set of checkboxes. */
function CarveSourceRow({
  carve,
  sourceOptions,
  soleVoice,
  disabled,
  onCarveChange,
}: {
  carve: HfCarveSettings;
  sourceOptions: AudioTrackOption[];
  soleVoice: AudioTrackOption | null;
  disabled?: boolean;
  onCarveChange(carve: HfCarveSettings): void;
}) {
  const trackInput = useTrackDesignInput();
  return (
    <div className="hf-fx-row flex min-h-6 items-center gap-2">
      {/* Wraps like every other name in this column (see FxParamRow) — one
          truncating row beside wrapping ones reads as a rendering bug. */}
      <span className="hf-fx-label w-[86px] shrink-0 wrap-break-word text-[10px] leading-tight text-panel-text-2">
        Listen to
      </span>
      {soleVoice ? (
        <span
          className="hf-fx-carve-source min-w-0 flex-1 truncate font-mono text-[10px] text-panel-text-1"
          data-carve-source={soleVoice.id}
        >
          {soleVoice.label}
        </span>
      ) : (
        /* Every voice, not one of them. A bed usually runs under a whole
           sequence — a narrator, an answer, a second presenter — and they are
           analysed together, so the cuts follow whoever is speaking. Which
           makes this a set of things to include, not a choice between them. */
        <div className="hf-fx-carve-sources flex min-w-0 flex-1 flex-wrap gap-x-2.5 gap-y-0.5">
          {sourceOptions.map((o) => (
            <label
              key={o.id}
              className="flex min-w-0 items-center gap-1 font-mono text-[9px] text-panel-text-1"
              title={`Make room for ${o.label}`}
            >
              <input
                type="checkbox"
                className="hf-fx-carve-source h-2.5 w-2.5 accent-panel-accent"
                data-carve-source={o.id}
                checked={carve.sources.includes(o.id)}
                disabled={disabled}
                onChange={(e) => {
                  onCarveChange({
                    ...carve,
                    sources: e.target.checked
                      ? [...carve.sources, o.id]
                      : carve.sources.filter((id) => id !== o.id),
                  });
                  trackInput("toggle", "carve-source");
                }}
              />
              <span className="truncate">{o.label}</span>
            </label>
          ))}
        </div>
      )}
    </div>
  );
}

/**
 * What the analysis made of all that. Divided rather than boxed: these are parts
 * of one module, and a border around each would read as the separate effects
 * this replaced.
 *
 * While the analysis runs the previous filters are gone rather than stale. Every
 * number in that list is about to be replaced — a strength change re-derives all
 * of them — so leaving them up reads as the settings that are in force when they
 * are already history, and the one honest thing to say is that the work is
 * happening.
 */
function CarveAnalysis({
  nodes,
  analysing,
  hasSources,
  automatedTargets,
  liveAutomationValues,
}: {
  nodes: HfAudioFxNode[];
  analysing?: boolean;
  hasSources: boolean;
  automatedTargets?: ReadonlySet<string>;
  liveAutomationValues?: ReadonlyMap<string, number>;
}) {
  if (analysing) {
    return (
      <p className="hf-fx-carve-working flex items-center justify-center gap-1.5 border-t border-panel-border-input py-2 text-[10px] text-panel-text-2">
        <svg
          className="hf-fx-carve-spinner h-3 w-3 animate-spin motion-reduce:animate-none"
          viewBox="0 0 24 24"
          fill="none"
          aria-hidden="true"
        >
          <circle
            className="opacity-25"
            cx="12"
            cy="12"
            r="10"
            stroke="currentColor"
            strokeWidth="4"
          />
          <path
            className="opacity-75"
            fill="currentColor"
            d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"
          />
        </svg>
        Analysing…
      </p>
    );
  }
  if (nodes.length === 0) {
    return (
      <p className="hf-fx-carve-working border-t border-panel-border-input py-1.5 text-center text-[10px] text-panel-text-2">
        {hasSources ? "Nothing analysed yet." : "Pick the voices this bed should make room for."}
      </p>
    );
  }
  return (
    <div className="hf-fx-carve-members divide-y divide-panel-border-input/60 border-t border-panel-border-input">
      <div className="hf-fx-carve-members-label px-1.5 pt-1 font-mono text-[9px] uppercase tracking-wide text-panel-text-2">
        analysed
      </div>
      {nodes.map((node, i) => (
        <FxCarveMember
          key={node.id ?? `${node.type}-${i}`}
          node={node}
          automatedTargets={automatedTargets}
          liveAutomationValues={liveAutomationValues}
        />
      ))}
    </div>
  );
}