fix(studio): make the volume fader tell the truth about the gain it writes (#3305)

* fix(studio): make the volume fader tell the truth about the gain it writes

The fader travels in dB, so its stops are irrational values; serializing them
through the generic two-decimal numeric formatter collapsed the bottom quarter
of its travel onto "0" — a hard mute — and made the knob jump on release
everywhere below unity. Both panels now use the exact serializer, which
round-trips every integer stop back to itself.

Raise the volume automation lane to the same ceiling the fader reaches.
Clamping the lane at unity meant automating a boosted clip silently discarded
the boost, and the panel disables the fader while a lane owns the level, so
there was no way back. This rescales the lane's vertical axis: unity now sits
a quarter of the way up rather than at the top.

Add audio_volume_tween_overrides_gain. Tween values on `volume` are absolute —
they replace the authored gain rather than scaling it — so a clip carrying both
plays at whatever the tween names, and the fader gives no sign of it. The rule
reuses the tween detector the sibling lane/tween rule already has.

* fix(lint): treat a missing data-volume as unity, not as silence

readAttr returns null when the attribute is absent, and Number(null) is 0 —
finite, and not 1 — so a clip carrying NO data-volume cleared both filters and
was reported as authored at silence. Both halves of that were false: absent
means unity everywhere else in the runtime.

It fired on exactly the case the rule exists to bless. The docs this PR edits
say data-volume is the baseline for elements no tween touches, so a tweened
clip is expected not to carry one — the common audio fade. A warning does not
fail check, but an agent reading the fixHint would have written a gain to
correct a level that was never wrong.

Author: miguel-heygen

packages/core/src/audioAutomation.test.ts

@@ -18,6 +18,7 @@ import {
   type HfAutomationLane,
 } from "./audioAutomation.js";
 import { mintAudioFxNodeId, parseAudioFxChain, type HfAudioFxChain } from "./audioFx.js";
+import { MAX_AUDIO_GAIN } from "./audioGain.js";
 
 const chain: HfAudioFxChain = {
   version: 1,
@@ -116,7 +117,7 @@ describe("normalisation", () => {
     ]);
   });
 
-  it("clamps volume into 0..1 at parse time", () => {
+  it("clamps volume into the authoring gain range at parse time", () => {
     const parsed = parseAutomation(
       JSON.stringify({
         version: 1,
@@ -131,7 +132,9 @@ describe("normalisation", () => {
         ],
       }),
     );
-    expect(parsed.lanes[0]!.points.map((p) => p.v)).toEqual([1, 0]);
+    // The lane shares the fader's ceiling. Clamping it at unity discarded the
+    // boost of any clip authored above 0 dB the moment it was automated.
+    expect(parsed.lanes[0]!.points.map((p) => p.v)).toEqual([MAX_AUDIO_GAIN, 0]);
   });
 
   it("refuses malformed input instead of silently losing an envelope", () => {

packages/core/src/audioAutomation.ts

@@ -12,6 +12,7 @@
  */
 
 import { getAudioFxDef, type HfAudioFxChain } from "./audioFx.js";
+import { MAX_AUDIO_GAIN } from "./audioGain.js";
 
 export const HF_AUDIO_AUTOMATION_ATTR = "data-automation";
 
@@ -135,8 +136,9 @@ export const PRESET_RANGE: AutomationRange = {
 /**
  * The value range a lane is drawn and clamped against.
  *
- * Volume is linear 0..1, matching `data-volume` and the existing volume
- * envelope machinery — no dB conversion enters the volume path. Everything
+ * Volume is linear over the full authoring gain range, matching `data-volume`
+ * and the existing volume envelope machinery — no dB conversion enters the
+ * volume path. Everything
  * else is read from the effect registry, so a lane can never offer a value the
  * renderer would reject, and the log-scaled knobs sweep the way a DAW's do.
  */
@@ -151,9 +153,15 @@ export interface AutomationRange {
   default: number;
 }
 
+/**
+ * One ceiling for the fader, the lane, the preview transport and the render
+ * mixer. Capping the lane at unity while the fader reached +12 dB made
+ * automating a boosted clip silently discard the boost — and the panel
+ * disables the fader while a lane owns it, so there was no way back.
+ */
 export const VOLUME_RANGE: AutomationRange = {
   min: 0,
-  max: 1,
+  max: MAX_AUDIO_GAIN,
   step: 0.01,
   unit: "",
   label: "Volume",

packages/lint/src/rules/media.test.ts

@@ -429,6 +429,61 @@ describe("media_variable_src_no_fallback", () => {
   });
 });
 
+describe("audio_volume_tween_overrides_gain", () => {
+  const withScript = (audioAttrs: string, script: string) => `<!DOCTYPE html><html><body>
+    <div id="root" data-composition-id="main" data-start="0" data-width="1920" data-height="1080" data-duration="10">
+      <audio id="bgm" src="a.wav" data-start="0" data-duration="10" ${audioAttrs}></audio>
+    </div>
+    <script>${script}</script>
+  </body></html>`;
+
+  it("warns that the tween's values win over an authored gain", async () => {
+    const res = await lintHyperframeHtml(
+      withScript(`data-volume="1.949845"`, `tl.fromTo("#bgm", { volume: 0 }, { volume: 1 });`),
+    );
+    const finding = res.findings.find((f) => f.code === "audio_volume_tween_overrides_gain");
+    expect(finding?.severity).toBe("warning");
+    expect(finding?.elementId).toBe("bgm");
+    expect(finding?.message).toMatch(/5\.8 dB/);
+  });
+
+  it("warns about an attenuation the tween overrides, not just a boost", async () => {
+    const res = await lintHyperframeHtml(
+      withScript(`data-volume="0.3"`, `tl.to("#bgm", { volume: 1 });`),
+    );
+    expect(res.findings.some((f) => f.code === "audio_volume_tween_overrides_gain")).toBe(true);
+  });
+
+  it("stays quiet on the fade the docs recommend, which carries no data-volume", async () => {
+    // `Number(null)` is 0 — finite and not 1 — so a clip with NO `data-volume`
+    // was reported as authored at silence. Both halves were false, and this is
+    // the shape the docs recommend for a tweened clip: the baseline attribute is
+    // for elements no tween touches. The rule fired on exactly the common fade.
+    const res = await lintHyperframeHtml(
+      withScript("", `tl.fromTo("#bgm", { volume: 0 }, { volume: 1 });`),
+    );
+    expect(res.findings.some((f) => f.code === "audio_volume_tween_overrides_gain")).toBe(false);
+  });
+
+  it("stays quiet at unity, without a tween, or when a lane already owns the level", async () => {
+    const unity = await lintHyperframeHtml(
+      withScript(`data-volume="1"`, `tl.to("#bgm", { volume: 0 });`),
+    );
+    const noTween = await lintHyperframeHtml(
+      withScript(`data-volume="2"`, `tl.to("#bgm", { x: 1 });`),
+    );
+    const lane = await lintHyperframeHtml(
+      withScript(
+        `data-volume="2" data-automation='{"version":1,"lanes":[{"target":"volume","points":[{"t":0,"v":1}]}]}'`,
+        `tl.to("#bgm", { volume: 0 });`,
+      ),
+    );
+    for (const res of [unity, noTween, lane]) {
+      expect(res.findings.some((f) => f.code === "audio_volume_tween_overrides_gain")).toBe(false);
+    }
+  });
+});
+
 describe("audio_volume_double_automation", () => {
   const withScript = (audioAttrs: string, script: string) => `<!DOCTYPE html><html><body>
     <div id="root" data-composition-id="main" data-start="0" data-width="1920" data-height="1080" data-duration="10">

packages/lint/src/rules/media.ts

@@ -629,8 +629,55 @@ export const mediaRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> =
 
   // audio_volume_double_automation
   findVolumeDoubleAutomationFindings,
+
+  // audio_volume_tween_overrides_gain
+  findVolumeTweenOverridesGainFindings,
 ];
 
+/**
+ * Tween values on `volume` are ABSOLUTE gains, not multipliers of the authored
+ * `data-volume`: the probed keyframes replace that baseline outright, in
+ * preview and in the render alike. So a clip carrying both plays at whatever
+ * the tween names — `{ volume: 1 }` is 0 dB even on a clip the fader says is
+ * at +5.8 dB, and Studio's fader gives no sign of it.
+ *
+ * Silent before this rule, and easier to hit since the fader gained +12 dB of
+ * boost and `normalize-audio` writes into the very same attribute.
+ */
+function findVolumeTweenOverridesGainFindings(ctx: LintContext): HyperframeLintFinding[] {
+  const boosted = ctx.tags
+    .filter((tag) => isMediaTag(tag.name))
+    // Absent means unity, as it does everywhere else. Reading it raw gave
+    // `Number(null)` — 0, finite and not 1, so a clip with NO `data-volume`
+    // cleared both filters and was reported as authored at silence. That is the
+    // shape the docs recommend for a tweened clip, so the rule fired on exactly
+    // the case it exists to bless.
+    .map((tag) => ({ tag, volume: Number(readAttr(tag.raw, "data-volume") ?? "1") }))
+    .filter((entry) => Number.isFinite(entry.volume) && entry.volume !== 1)
+    // A lane already has its own rule, and it wins over both of these.
+    .filter((entry) => !readDecodedAttr(entry.tag.raw, "data-automation"))
+    .map((entry) => ({ ...entry, id: readAttr(entry.tag.raw, "id") }))
+    .filter((entry): entry is typeof entry & { id: string } => Boolean(entry.id));
+  if (boosted.length === 0) return [];
+
+  const script = ctx.scripts.map((block) => stripJsComments(block.content)).join("\n");
+  const findings: HyperframeLintFinding[] = [];
+  for (const { tag, id, volume } of boosted) {
+    if (!tweensVolumeInSameCall(script, id)) continue;
+    const db = volume > 0 ? `${(20 * Math.log10(volume)).toFixed(1)} dB` : "silence";
+    findings.push({
+      code: "audio_volume_tween_overrides_gain",
+      severity: "warning",
+      message: `#${id} has data-volume="${volume}" (${db}) and a GSAP tween on \`volume\`. Tween values are absolute — they REPLACE this gain rather than scale it — so wherever the tween names a value the clip plays at that value, not at ${db}.`,
+      elementId: id,
+      fixHint:
+        "Write the tween's targets in the same absolute gain (e.g. `volume: 1.95`, not `volume: 1`), or reset data-volume to 1 and let the tween carry the level on its own.",
+      snippet: truncateSnippet(tag.raw),
+    });
+  }
+  return findings;
+}
+
 /**
  * A track can have its volume shaped by an automation lane or by a GSAP tween,
  * and only the lane is heard: the runtime reads `data-automation` first and

packages/studio/src/components/editor/propertyPanelFlatMediaSection.test.tsx

@@ -131,9 +131,9 @@ describe("FlatMediaSection — cutout", () => {
 });
 
 describe("FlatMediaSection — volume/rate/media-start", () => {
-  it("renders volume at its stored percentage and commits a new value on drag", () => {
+  it("renders unity volume as neutral 0 dB at the slider midpoint", () => {
     const onSetAttribute = vi.fn();
-    const element = makeVideoElement({ dataAttributes: { volume: "0.5" } });
+    const element = makeVideoElement({ dataAttributes: { volume: "1" } });
     const host = document.createElement("div");
     document.body.append(host);
     const root = createRoot(host);
@@ -149,48 +149,16 @@ describe("FlatMediaSection — volume/rate/media-start", () => {
         />,
       );
     });
-    expect(host.textContent).toContain("50%");
+    expect(host.textContent).toContain("0.0 dB");
+    expect(
+      host.querySelector('[data-flat-slider-track="true"]')?.getAttribute("aria-valuenow"),
+    ).toBe("0");
     act(() => root.unmount());
   });
 
-  it("refuses to commit from the percent slider on a clip authored above unity", () => {
-    // The control tops out at 100%, so any commit from it would cap a boosted
-    // clip and silently drop up to 12 dB that now genuinely renders. Held until
-    // the dB fader that can represent these levels replaces it.
+  it("commits +12 dB of boost from the upper half of the volume fader", () => {
     const onSetAttribute = vi.fn();
-    const element = makeVideoElement({ dataAttributes: { volume: "1.949845" } });
-    const host = document.createElement("div");
-    document.body.append(host);
-    const root = createRoot(host);
-    act(() => {
-      root.render(
-        <FlatMediaSection
-          projectDir={null}
-          element={element}
-          styles={{}}
-          onSetStyle={vi.fn()}
-          onSetAttribute={onSetAttribute}
-          onSetHtmlAttribute={vi.fn()}
-        />,
-      );
-    });
-
-    const volumeTrack = host.querySelectorAll('[data-flat-slider-track="true"]')[0];
-    Object.defineProperty(volumeTrack, "getBoundingClientRect", {
-      value: () => ({ left: 0, width: 100, top: 0, height: 2, right: 100, bottom: 2 }),
-    });
-    act(() => {
-      volumeTrack.dispatchEvent(new MouseEvent("pointerdown", { bubbles: true, clientX: 50 }));
-      volumeTrack.dispatchEvent(new MouseEvent("pointerup", { bubbles: true, clientX: 50 }));
-    });
-
-    expect(onSetAttribute).not.toHaveBeenCalled();
-    act(() => root.unmount());
-  });
-
-  it("commits a new volume value on slider track pointerdown", () => {
-    const onSetAttribute = vi.fn();
-    const element = makeVideoElement({ dataAttributes: { volume: "0.2" } });
+    const element = makeVideoElement({ dataAttributes: { volume: "1" } });
     const host = document.createElement("div");
     document.body.append(host);
     const root = createRoot(host);
@@ -211,11 +179,13 @@ describe("FlatMediaSection — volume/rate/media-start", () => {
       value: () => ({ left: 0, width: 100, top: 0, height: 2, right: 100, bottom: 2 }),
     });
     act(() => {
-      volumeTrack.dispatchEvent(new MouseEvent("pointerdown", { bubbles: true, clientX: 50 }));
-      volumeTrack.dispatchEvent(new MouseEvent("pointerup", { bubbles: true, clientX: 50 }));
+      volumeTrack.dispatchEvent(new MouseEvent("pointerdown", { bubbles: true, clientX: 100 }));
+      volumeTrack.dispatchEvent(new MouseEvent("pointerup", { bubbles: true, clientX: 100 }));
     });
-    // starting volume 0.2 (draft=20); min=0, max=100, ratio=0.5 -> raw=50 -> commit(50) -> 50/100=0.5 -> "0.5"
-    expect(onSetAttribute).toHaveBeenCalledWith("volume", "0.5");
+    // Six decimals, not two: at two the bottom of the dB fader collapses onto
+    // "0" (a hard mute) and every stop below unity writes a value the knob then
+    // jumps away from.
+    expect(onSetAttribute).toHaveBeenCalledWith("volume", "3.981072");
     act(() => root.unmount());
   });
 

packages/studio/src/components/editor/propertyPanelFlatMediaSection.tsx

@@ -13,6 +13,14 @@ import {
 import { FlatSelectRow, FlatSlider } from "./propertyPanelFlatPrimitives";
 import { FlatToggle } from "./propertyPanelFlatToggle";
 import { AutomationToggle } from "./propertyPanelFxControls";
+import {
+  AUDIO_GAIN_FADER_MAX,
+  AUDIO_GAIN_FADER_MIN,
+  audioFaderPositionToGain,
+  formatAudioGain,
+  audioGainToFaderPosition,
+  audioGainToText,
+} from "@hyperframes/core/audio-gain";
 
 // fallow-ignore-next-line complexity
 export function FlatMediaSection({
@@ -54,7 +62,7 @@ export function FlatMediaSection({
   const el = element.element;
 
   const volume = parseNumericValue(element.dataAttributes.volume ?? "") ?? 1;
-  const volumePercent = Math.round(volume * 100);
+  const volumeFaderPosition = audioGainToFaderPosition(volume);
   const mediaStart =
     Number.parseFloat(
       element.dataAttributes["media-start"] ?? element.dataAttributes["playback-start"] ?? "0",
@@ -207,27 +215,24 @@ export function FlatMediaSection({
         <>
           {/* The slider is disabled while a lane owns the level: a value set
               here would be overwritten by the envelope on the next tick. The
-              toggle beside it carries the tooltip.
-
-              It is also disabled above unity, for the same reason in a
-              different guise — this control tops out at 100%, so committing
-              from it would silently cap a boosted clip and drop up to 12 dB
-              that now genuinely renders. A hold, not a fix: the dB fader that
-              can represent these levels replaces this control outright. */}
+              toggle beside it carries the tooltip. */}
           <div
             className="hf-volume-row flex items-center gap-1"
             data-volume-automated={volumeAutomated ? "" : undefined}
           >
             <div className="min-w-0 flex-1">
               <FlatSlider
                 label="Volume"
-                value={volumePercent}
-                min={0}
-                max={100}
-                tier={volumePercent === 100 ? "default" : "explicitCustom"}
-                displayValue={`${volumePercent}%`}
-                disabled={volumeAutomated || volume > 1}
-                onCommit={(next) => void onSetAttribute("volume", formatNumericValue(next / 100))}
+                value={volumeFaderPosition}
+                min={AUDIO_GAIN_FADER_MIN}
+                max={AUDIO_GAIN_FADER_MAX}
+                tier={volume === 1 ? "default" : "explicitCustom"}
+                displayValue={audioGainToText(volume)}
+                disabled={volumeAutomated}
+                centerTick
+                onCommit={(next) =>
+                  void onSetAttribute("volume", formatAudioGain(audioFaderPositionToGain(next)))
+                }
               />
             </div>
             <AutomationToggle

packages/studio/src/components/editor/propertyPanelMediaSection.tsx

@@ -13,6 +13,14 @@ import {
 } from "./propertyPanelHelpers";
 import { Section, SegmentedControl, SelectField, SliderControl } from "./propertyPanelPrimitives";
 import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
+import {
+  AUDIO_GAIN_FADER_MAX,
+  AUDIO_GAIN_FADER_MIN,
+  audioFaderPositionToGain,
+  formatAudioGain,
+  audioGainToFaderPosition,
+  audioGainToText,
+} from "@hyperframes/core/audio-gain";
 
 // fallow-ignore-next-line complexity
 export function MediaSection({
@@ -47,7 +55,7 @@ export function MediaSection({
   const el = element.element;
 
   const volume = parseNumericValue(element.dataAttributes.volume ?? "") ?? 1;
-  const volumePercent = Math.round(volume * 100);
+  const volumeFaderPosition = audioGainToFaderPosition(volume);
 
   const mediaStart =
     Number.parseFloat(
@@ -246,23 +254,18 @@ export function MediaSection({
 
         {(isVideo || isAudio) && (
           <>
-            {/* Held above unity: this control tops out at 100%, so committing
-                from it would silently cap a boosted clip and drop up to 12 dB
-                that now genuinely renders. The dB fader that can represent
-                these levels replaces this control outright. */}
             <div className="grid min-w-0 gap-1.5">
               <span className={LABEL}>Volume</span>
               <SliderControl
                 trackName="Volume"
-                value={volumePercent}
-                min={0}
-                max={100}
+                value={volumeFaderPosition}
+                min={AUDIO_GAIN_FADER_MIN}
+                max={AUDIO_GAIN_FADER_MAX}
                 step={1}
-                disabled={volume > 1}
-                displayValue={`${volumePercent}%`}
-                formatDisplayValue={(next) => `${Math.round(next)}%`}
+                displayValue={audioGainToText(volume)}
+                formatDisplayValue={(next) => audioGainToText(audioFaderPositionToGain(next))}
                 onCommit={(next) => {
-                  void onSetAttribute("volume", formatNumericValue(next / 100));
+                  void onSetAttribute("volume", formatAudioGain(audioFaderPositionToGain(next)));
                 }}
               />
             </div>