@hyperframes/studio 0.8.108 → 0.8.109

package/src/player/components/audioClipLink.test.ts

@@ -1,34 +1,231 @@
+// @vitest-environment happy-dom
 import { describe, expect, it } from "vitest";
-import { audioPillFlags, isLinkedVideoAudio } from "./audioClipLink";
-
-const audio = { id: "bed", tag: "audio", src: "assets/City Ride.mp4?v=2" };
-
-describe("isLinkedVideoAudio", () => {
-  it("links an audio pill to a video of the same file", () => {
-    expect(
-      isLinkedVideoAudio(audio, [
-        audio,
-        { id: "picture", tag: "video", src: "/preview/assets/city ride.mp4" },
-      ]),
-    ).toBe(true);
-  });
-
-  it("greys a hidden clip and a muted group without dropping the link", () => {
-    expect(audioPillFlags({ ...audio, hidden: true }, [])).toEqual({
-      muted: true,
-      linked: false,
-    });
-    expect(audioPillFlags({ ...audio, audioGroupHidden: true }, [])).toEqual({
-      muted: true,
-      linked: false,
-    });
-  });
-
-  it("leaves a standalone audio file unlinked", () => {
-    expect(
-      isLinkedVideoAudio({ id: "vo", tag: "audio", src: "assets/voice.wav" }, [
-        { id: "picture", tag: "video", src: "assets/city.mp4" },
-      ]),
-    ).toBe(false);
+import {
+  audioPillFlags,
+  expandToLinkedMembers,
+  linkedGestureKeys,
+  linkedMembersOf,
+  mediaAssetIdentity,
+} from "./audioClipLink";
+import { createTimelineElementFromManifestClip, parseTimelineFromDOM } from "../lib/timelineDOM";
+
+const video = { id: "talk", link: "lk-1" };
+const audio = { id: "talk-audio", link: "lk-1" };
+const other = { id: "music", link: "lk-2" };
+const otherAudio = { id: "music-audio", link: "lk-2" };
+const plain = { id: "title" };
+const elements = [video, audio, other, otherAudio, plain];
+
+describe("audioPillFlags", () => {
+  it("greys a hidden clip and a muted group", () => {
+    expect(audioPillFlags({ hidden: true }).muted).toBe(true);
+    expect(audioPillFlags({ audioGroupHidden: true }).muted).toBe(true);
+  });
+});
+
+describe("mediaAssetIdentity", () => {
+  it("tells same-named files in different folders apart", () => {
+    expect(mediaAssetIdentity({ src: "assets/one/talk.mp4" })).not.toBe(
+      mediaAssetIdentity({ src: "assets/two/talk.mp4" }),
+    );
+  });
+
+  it("resolves a src against its own source file and drops query and hash", () => {
+    expect(mediaAssetIdentity({ src: "../assets/talk.mp4?v=2", sourceFile: "scenes/a.html" })).toBe(
+      mediaAssetIdentity({ src: "./assets/talk.mp4#t=1" }),
+    );
+    expect(mediaAssetIdentity({ src: "assets/City%20Ride.mp4" })).toBe(
+      mediaAssetIdentity({ src: "assets/City Ride.mp4" }),
+    );
+    expect(mediaAssetIdentity({ src: "" })).toBeNull();
+  });
+
+  it("keeps a remote url's query, since it can select a different file", () => {
+    expect(mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4?id=1" })).not.toBe(
+      mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4?id=2" }),
+    );
+    expect(mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4?clip=a%26x=b" })).not.toBe(
+      mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4?clip=a&x=b" }),
+    );
+    expect(mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4%3Fclip=a" })).not.toBe(
+      mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4?clip=a" }),
+    );
+    expect(mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4?id=1#t=3" })).toBe(
+      mediaAssetIdentity({ src: "https://cdn.example.com/v.mp4?id=1" }),
+    );
+  });
+});
+
+describe("expandToLinkedMembers", () => {
+  it("adds every partner of a linked clip", () => {
+    expect(expandToLinkedMembers(["talk"], elements)).toEqual(new Set(["talk", "talk-audio"]));
+  });
+
+  it("leaves unlinked clips alone and does not pull in other groups", () => {
+    expect(expandToLinkedMembers(["title"], elements)).toEqual(new Set(["title"]));
+    expect(expandToLinkedMembers(["talk-audio", "title"], elements)).toEqual(
+      new Set(["talk-audio", "talk", "title"]),
+    );
+  });
+
+  it("prefers the store key over the id", () => {
+    const keyed = [
+      { id: "a", key: "k-a", link: "lk-9" },
+      { id: "b", key: "k-b", link: "lk-9" },
+    ];
+    expect(expandToLinkedMembers(["k-a"], keyed)).toEqual(new Set(["k-a", "k-b"]));
+  });
+});
+
+describe("link groups stay inside their composition", () => {
+  const root = [
+    { id: "v", link: "lk-1", sourceFile: undefined },
+    { id: "a", link: "lk-1", sourceFile: undefined },
+  ];
+  const child = [
+    { id: "cv", key: "child.html#cv", link: "lk-1", sourceFile: "child.html" },
+    { id: "ca", key: "child.html#ca", link: "lk-1", sourceFile: "child.html" },
+  ];
+  const all = [...root, ...child];
+
+  it("does not pull a child file's same-id link into the root group", () => {
+    expect(linkedMembersOf(root[0] ?? video, all).map((el) => el.id)).toEqual(["v", "a"]);
+    expect(expandToLinkedMembers(["child.html#cv"], all)).toEqual(
+      new Set(["child.html#cv", "child.html#ca"]),
+    );
+  });
+
+  const media = (id: string, tag: string, start: number) =>
+    `<${tag} id="${id}" class="clip" src="${id}.mp4" data-link="lk-1" data-start="${start}" data-duration="4"></${tag}>`;
+  const inlineDoc = () => {
+    const doc = document.implementation.createHTMLDocument();
+    doc.body.innerHTML = `<div data-composition-id="main" data-duration="20">
+      ${media("v", "video", 0)}${media("a", "audio", 0)}
+      <div id="child" data-composition-id="child" data-start="0" data-duration="10">
+        ${media("cv", "video", 5)}${media("ca", "audio", 5)}
+      </div>
+    </div>`;
+    return doc;
+  };
+
+  it("does not pull an inline composition's same-id link into the root group", () => {
+    const rows = parseTimelineFromDOM(inlineDoc(), 20).filter((row) => row.link);
+    const byId = (id: string) => rows.find((row) => row.domId === id) ?? video;
+    expect(linkedMembersOf(byId("v"), rows).map((row) => row.domId)).toEqual(["v", "a"]);
+    expect(linkedMembersOf(byId("cv"), rows).map((row) => row.domId)).toEqual(["cv", "ca"]);
+  });
+
+  it("keeps the inline composition apart on rows built from the runtime manifest", () => {
+    const doc = inlineDoc();
+    const rows = ["v", "a", "cv", "ca"].map((id, fallbackIndex) =>
+      createTimelineElementFromManifestClip({
+        clip: {
+          ...{ id, label: id, start: 0, duration: 4, track: 0, kind: "video", tagName: "video" },
+          ...{
+            compositionId: null,
+            parentCompositionId: null,
+            compositionSrc: null,
+            assetUrl: null,
+          },
+        },
+        fallbackIndex,
+        doc,
+        hostEl: doc.getElementById(id),
+      }),
+    );
+    const [rootVideo] = rows;
+    expect(linkedMembersOf(rootVideo ?? video, rows).map((row) => row.domId)).toEqual(["v", "a"]);
+  });
+});
+
+describe("linkedMembersOf", () => {
+  it("returns the group, or the clip alone when unlinked", () => {
+    expect(linkedMembersOf(video, elements).map((el) => el.id)).toEqual(["talk", "talk-audio"]);
+    expect(linkedMembersOf(plain, elements)).toEqual([plain]);
+  });
+});
+
+describe("linkedGestureKeys", () => {
+  it("drags an unselected linked clip with its partner", () => {
+    expect(linkedGestureKeys(new Set(["title"]), video, elements, false)).toEqual(
+      new Set(["talk", "talk-audio"]),
+    );
+  });
+
+  it("keeps a selection that holds the grabbed clip and adds partners", () => {
+    expect(linkedGestureKeys(new Set(["talk", "title"]), video, elements, false)).toEqual(
+      new Set(["talk", "talk-audio", "title"]),
+    );
+  });
+
+  it("Linked Selection off edits the grabbed clip alone without Alt", () => {
+    expect(linkedGestureKeys(new Set(["talk"]), video, elements, false, false)).toEqual(
+      new Set(["talk"]),
+    );
+  });
+
+  it("Alt edits the grabbed clip alone", () => {
+    expect(linkedGestureKeys(new Set(["talk", "talk-audio"]), video, elements, true)).toEqual(
+      new Set(["talk"]),
+    );
+  });
+});
+
+describe("selectClipWithLinks", () => {
+  const linkedPair = [
+    { id: "talk", tag: "video", start: 0, duration: 4, track: 0, link: "lk-1" },
+    { id: "talk-audio", tag: "audio", start: 0, duration: 4, track: 1, link: "lk-1" },
+    { id: "title", tag: "div", start: 0, duration: 4, track: 2 },
+  ];
+
+  async function store() {
+    const { usePlayerStore } = await import("../store/playerStore");
+    const { selectClipWithLinks } = await import("./timelineLinkSelection");
+    usePlayerStore.getState().setElements(linkedPair);
+    const click = (key: string, alt = false) =>
+      selectClipWithLinks(key, alt, usePlayerStore.getState().setSelectedElementId);
+    return { usePlayerStore, click };
+  }
+
+  it("a click selects the whole pair; Alt-click then narrows to one member", async () => {
+    const { usePlayerStore, click } = await store();
+    click("talk");
+    expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["talk", "talk-audio"]));
+    click("talk-audio", true);
+    expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["talk-audio"]));
+  });
+
+  it("a plain click collapses a larger selection to the clicked clip's link group", async () => {
+    const { usePlayerStore, click } = await store();
+    usePlayerStore.getState().setSelection(["talk", "talk-audio", "title"], "title");
+    click("talk");
+    expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["talk", "talk-audio"]));
+    expect(usePlayerStore.getState().selectedElementId).toBe("talk");
+  });
+});
+
+describe("Linked Selection off", () => {
+  const linkedPair = [
+    { id: "talk", tag: "video", start: 0, duration: 4, track: 0, link: "lk-1" },
+    { id: "talk-audio", tag: "audio", start: 0, duration: 4, track: 1, link: "lk-1" },
+  ];
+
+  it("expands and lists nothing past the clip itself", () => {
+    expect(expandToLinkedMembers(["talk"], linkedPair, false)).toEqual(new Set(["talk"]));
+    expect(linkedMembersOf(linkedPair[0], linkedPair, false)).toEqual([linkedPair[0]]);
+  });
+
+  it("a click selects only the clicked clip", async () => {
+    const { usePlayerStore } = await import("../store/playerStore");
+    const { selectClipWithLinks } = await import("./timelineLinkSelection");
+    const { useLinkedClipPreferences } = await import("../../utils/linkedClipPreferences");
+    usePlayerStore.getState().setElements(linkedPair);
+    useLinkedClipPreferences.getState().setLinkedSelection(false);
+    try {
+      selectClipWithLinks("talk", false, usePlayerStore.getState().setSelectedElementId);
+      expect(usePlayerStore.getState().selectedElementIds).toEqual(new Set(["talk"]));
+    } finally {
+      useLinkedClipPreferences.getState().setLinkedSelection(true);
+    }
   });
 });

package/src/player/components/audioClipLink.ts

@@ -1,33 +1,80 @@
-import type { TimelineElement } from "../store/timelineElement";
+import { sameCompositionScope, type TimelineElement } from "../store/timelineElement";
 
-function mediaFileKey(src: string | undefined): string | null {
+type LinkScoped = Pick<TimelineElement, "sourceFile" | "compositionScope">;
+type LinkedElement = Pick<TimelineElement, "id" | "key" | "link"> & LinkScoped;
+
+const keyOf = (element: Pick<TimelineElement, "id" | "key">) => element.key ?? element.id;
+
+const SOURCE_BASE = "https://project.invalid/";
+const SOURCE_ORIGIN = new URL(SOURCE_BASE).origin;
+
+export function mediaAssetIdentity(
+  element: Pick<TimelineElement, "src" | "sourceFile">,
+): string | null {
+  const src = element.src?.trim();
   if (!src) return null;
-  const path = src.split(/[?#]/, 1)[0] ?? "";
-  const segment = path.split(/[/\\]/).pop()?.trim().toLowerCase() ?? "";
-  return segment.length > 0 ? segment : null;
+  try {
+    const url = new URL(src, new URL(element.sourceFile ?? "index.html", SOURCE_BASE));
+    if (url.origin !== SOURCE_ORIGIN) return `${url.origin}${url.pathname}${url.search}`;
+    return decodeURIComponent(`${url.origin}${url.pathname}`);
+  } catch {
+    return null;
+  }
 }
 
-export function audioPillFlags(
-  audio: Pick<TimelineElement, "id" | "tag" | "src" | "hidden" | "audioGroupHidden">,
-  elements: readonly Pick<TimelineElement, "id" | "tag" | "src">[],
-): { muted: boolean; linked: boolean } {
-  return {
-    muted: audio.hidden === true || audio.audioGroupHidden === true,
-    linked: isLinkedVideoAudio(audio, elements),
-  };
+function isLinked(element: Pick<TimelineElement, "link">): boolean {
+  return typeof element.link === "string" && element.link.length > 0;
 }
 
-/** An audio pill whose file is also a video clip on this timeline. */
-export function isLinkedVideoAudio(
-  audio: Pick<TimelineElement, "id" | "tag" | "src">,
-  elements: readonly Pick<TimelineElement, "id" | "tag" | "src">[],
+export function sharesLinkGroup(
+  a: Pick<TimelineElement, "link"> & LinkScoped,
+  b: Pick<TimelineElement, "link"> & LinkScoped,
 ): boolean {
-  if (audio.tag.trim().toLowerCase() !== "audio") return false;
-  const key = mediaFileKey(audio.src);
-  if (!key) return false;
-  return elements.some((element) => {
-    if (element.id === audio.id) return false;
-    if (element.tag.trim().toLowerCase() !== "video") return false;
-    return mediaFileKey(element.src) === key;
-  });
+  return isLinked(a) && a.link === b.link && sameCompositionScope(a, b);
+}
+
+export function audioPillFlags(
+  audio: Pick<TimelineElement, "hidden" | "audioGroupHidden">,
+  _elements?: readonly unknown[],
+): { muted: boolean } {
+  return { muted: audio.hidden === true || audio.audioGroupHidden === true };
+}
+
+export function linkedMembersOf<T extends LinkedElement>(
+  element: T,
+  elements: readonly T[],
+  linked = true,
+): T[] {
+  if (!linked || !isLinked(element)) return [element];
+  const members = elements.filter((candidate) => sharesLinkGroup(candidate, element));
+  return members.some((member) => keyOf(member) === keyOf(element))
+    ? members
+    : [element, ...members];
+}
+
+export function expandToLinkedMembers(
+  keys: Iterable<string>,
+  elements: readonly LinkedElement[],
+  linked = true,
+): Set<string> {
+  const expanded = new Set(keys);
+  if (!linked) return expanded;
+  const seeds = elements.filter((el) => expanded.has(keyOf(el)) && isLinked(el));
+  for (const element of elements) {
+    if (seeds.some((seed) => sharesLinkGroup(seed, element))) expanded.add(keyOf(element));
+  }
+  return expanded;
+}
+
+export function linkedGestureKeys(
+  selected: ReadonlySet<string>,
+  grabbed: LinkedElement,
+  elements: readonly LinkedElement[],
+  altKey: boolean,
+  linked = true,
+): Set<string> {
+  const grabbedKey = keyOf(grabbed);
+  if (altKey) return new Set([grabbedKey]);
+  const base = selected.has(grabbedKey) ? selected : [grabbedKey];
+  return expandToLinkedMembers(base, elements, linked);
 }

package/src/player/components/clipMenuAudioItems.noShell.test.tsx

@@ -0,0 +1,78 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createHappyDomRootHarness } from "./testRootHarness";
+import { ClipMenuAudioItems } from "./clipMenuAudioItems";
+import { usePlayerStore } from "../store/playerStore";
+import { usePreviewIframeStore } from "../store/previewIframeStore";
+import type { TimelineElement } from "../store/timelineElement";
+
+const onNotice = vi.fn();
+const setQuiet = vi.fn(async () => {});
+
+vi.mock("../../contexts/StudioContext", () => ({
+  useStudioShellContextOptional: () => null,
+}));
+vi.mock("../../contexts/TimelineEditContext", () => ({
+  useTimelineEditContextOptional: () => ({ onSetElementAttributeQuiet: setQuiet, onNotice }),
+}));
+
+const harness = createHappyDomRootHarness();
+const tour: TimelineElement = {
+  id: "tour",
+  tag: "video",
+  start: 0,
+  duration: 4,
+  track: 0,
+  hasAudio: true,
+  src: "tour.mp4",
+};
+
+function mountPreview(): void {
+  const iframe = document.createElement("iframe");
+  document.body.appendChild(iframe);
+  const doc = iframe.contentDocument;
+  if (!doc) throw new Error("iframe has no document");
+  doc.body.innerHTML =
+    '<video id="tour" src="tour.mp4" data-has-audio="true" data-start="0" data-duration="4"></video><audio id="voiceover" src="vo.wav" data-start="1" data-duration="2"></audio>';
+  usePreviewIframeStore.getState().setIframe(iframe);
+}
+
+function render(part: "normalize" | "duck") {
+  const host = document.createElement("div");
+  document.body.appendChild(host);
+  act(() =>
+    harness
+      .mount(host)
+      .render(<ClipMenuAudioItems part={part} element={tour} onClose={() => {}} />),
+  );
+  return host;
+}
+
+afterEach(() => {
+  usePreviewIframeStore.getState().setIframe(null);
+  vi.unstubAllGlobals();
+});
+
+describe("ClipMenuAudioItems in a host without Studio's shell", () => {
+  it("offers Normalize and Duck from the timeline session and the live preview", () => {
+    usePlayerStore.getState().beginTimelineSession("p1");
+    mountPreview();
+    expect(render("normalize").textContent).toContain("Normalize loudness");
+    expect(render("duck").textContent).toContain("Duck under voice");
+  });
+
+  it("normalizes through the session's project and reports through onNotice", async () => {
+    usePlayerStore.getState().beginTimelineSession("p1");
+    mountPreview();
+    const plan = { targetLufs: -16, projectedLufs: -16, volume: 2, changeDb: 6, limitedBy: null };
+    const fetchSpy = vi.fn(async (_url: string) => Response.json({ plan }));
+    vi.stubGlobal("fetch", fetchSpy);
+    const button = render("normalize").querySelector("button");
+    await act(async () => button?.click());
+    await vi.waitFor(() => expect(onNotice).toHaveBeenCalled());
+    expect(String(fetchSpy.mock.calls[0]?.[0])).toContain("/api/projects/p1/loudness/normalize");
+    expect(setQuiet).toHaveBeenCalledWith(tour, "data-volume", "2", "Normalize loudness");
+    expect(onNotice).toHaveBeenCalledWith("Normalized to −16 LUFS (+6.0 dB)", "info");
+  });
+});

package/src/player/components/clipMenuAudioItems.test.tsx

@@ -7,7 +7,12 @@ import type { TimelineElement } from "../store/timelineElement";
 
 const showToast = vi.fn();
 const setQuiet = vi.fn<(...args: unknown[]) => Promise<unknown>>(async () => {});
-const iframe = document.createElement("iframe");
+let previewDoc: Document | null = null;
+const iframe = {
+  get contentDocument() {
+    return previewDoc;
+  },
+};
 
 vi.mock("../../contexts/StudioContext", () => ({
   useStudioShellContextOptional: () => ({
@@ -22,11 +27,13 @@ vi.mock("../../contexts/TimelineEditContext", () => ({
 
 const harness = createHappyDomRootHarness();
 
-function render(element: TimelineElement) {
+function render(element: TimelineElement, part: "normalize" | "duck" = "normalize") {
   const host = document.createElement("div");
   document.body.appendChild(host);
   act(() =>
-    harness.mount(host).render(<ClipMenuAudioItems element={element} onClose={() => {}} />),
+    harness
+      .mount(host)
+      .render(<ClipMenuAudioItems part={part} element={element} onClose={() => {}} />),
   );
   return host;
 }
@@ -50,6 +57,44 @@ describe("ClipMenuAudioItems", () => {
     expect(host.textContent).toBe("");
   });
 
+  describe("Duck under voice", () => {
+    const duckLabel = (host: HTMLElement) =>
+      [...host.querySelectorAll("button")].find((b) => b.textContent?.includes("Duck under voice"));
+    const compose = (body: string) => {
+      previewDoc = document.implementation.createHTMLDocument("c");
+      previewDoc.body.innerHTML = body;
+    };
+    const music: TimelineElement = { ...base, id: "music", tag: "audio", src: "music.mp3" };
+
+    it("is hidden on a lone video with sound", () => {
+      compose(
+        `<video id="a-roll" src="a.mp4" data-start="0" data-duration="4" data-has-audio="true"></video>`,
+      );
+      const host = render(
+        { ...base, id: "a-roll", tag: "video", hasAudio: true, src: "a.mp4" },
+        "duck",
+      );
+      expect(duckLabel(host)).toBeUndefined();
+    });
+
+    it("shows for a music bed with an overlapping voice", () => {
+      compose(`<audio id="music" src="music.mp3" data-start="0" data-duration="4"></audio>
+        <audio id="voiceover" src="vo.wav" data-start="1" data-duration="2"></audio>`);
+      const host = render(music, "duck");
+      expect(duckLabel(host)?.getAttribute("aria-checked")).toBe("false");
+    });
+
+    it("stays available, checked, once ducked even with the voice gone", () => {
+      compose(
+        `<audio id="music" src="music.mp3" data-start="0" data-duration="4" data-fx-carve='{"enabled":true,"sources":["voiceover"],"strength":0.25}'></audio>`,
+      );
+      const host = render(music, "duck");
+      const item = duckLabel(host);
+      expect(item?.getAttribute("aria-checked")).toBe("true");
+      expect(item?.textContent).toBe("Duck under voice✓");
+    });
+  });
+
   it("normalizes a video with sound by writing data-volume as one edit", async () => {
     const plan = { targetLufs: -16, projectedLufs: -16, volume: 2, changeDb: 6, limitedBy: null };
     vi.stubGlobal(
@@ -104,22 +149,20 @@ describe("ClipMenuAudioItems", () => {
   });
 
   it("stops ducking at the first refused save and says why", async () => {
-    document.body.appendChild(iframe);
-    const doc = iframe.contentDocument;
-    if (!doc) throw new Error("fixture");
-    doc.body.innerHTML = `<audio id="music" src="music.mp3" data-start="0" data-duration="10"></audio>
+    previewDoc = document.implementation.createHTMLDocument("c");
+    previewDoc.body.innerHTML = `<audio id="music" src="music.mp3" data-start="0" data-duration="10"></audio>
       <audio id="voiceover" src="vo.wav" data-start="1" data-duration="3"></audio>`;
     setQuiet.mockResolvedValue({
       status: "refused",
       reason: "Cannot edit timeline while recording",
     });
-    const host = render({ ...base, id: "music", tag: "audio", src: "music.mp3" });
+    const host = render({ ...base, id: "music", tag: "audio", src: "music.mp3" }, "duck");
     await clickItem(host, "Duck under voice");
     await vi.waitFor(() =>
       expect(showToast).toHaveBeenCalledWith("Cannot edit timeline while recording", "error"),
     );
     expect(setQuiet).toHaveBeenCalledTimes(1);
     expect(showToast).not.toHaveBeenCalledWith(expect.stringContaining("Ducks under"), "info");
-    iframe.remove();
+    previewDoc = null;
   });
 });

package/src/player/components/clipMenuAudioItems.tsx

@@ -2,6 +2,8 @@ import { formatAudioGain } from "@hyperframes/core/audio-gain";
 import type { TimelineElement } from "../store/timelineElement";
 import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
 import { useStudioShellContextOptional } from "../../contexts/StudioContext";
+import { usePlayerStore } from "../store/playerStore";
+import { useLivePreviewIframe } from "../store/previewIframeStore";
 import {
   clipHasSound,
   normalizeToastText,
@@ -11,7 +13,7 @@ import {
   VOLUME_LANE_REFUSAL,
   volumeLaneOwnsGain,
 } from "./clipMenuNormalize";
-import { isDuckableBed, readBedCarve, setDuckUnderVoice, type DuckOutcome } from "./clipMenuDuck";
+import { offersDuck, readBedCarve, setDuckUnderVoice, type DuckOutcome } from "./clipMenuDuck";
 
 const ITEM_CLASS =
   "w-full flex items-center justify-between px-3 py-1.5 text-xs text-left outline-hidden text-neutral-300 hover:bg-neutral-800 focus-visible:bg-neutral-800 cursor-pointer";
@@ -23,21 +25,28 @@ const DUCK_TOAST: Record<DuckOutcome, string> = {
   aborted: "Could not group the voices to duck under.",
 };
 
-/** Sound group of the clip menu: Normalize loudness (one-shot) and Duck under voice (toggle). */
+/** Normalize loudness (one-shot) or Duck under voice (toggle), placed separately in the sound group. */
 export function ClipMenuAudioItems({
+  part,
   element,
   onClose,
 }: {
+  part: "normalize" | "duck";
   element: TimelineElement;
   onClose: () => void;
 }) {
   const shell = useStudioShellContextOptional();
-  const { onSetElementAttributeQuiet, onGroupClips } = useTimelineEditContextOptional();
-  const doc = shell?.previewIframeRef.current?.contentDocument ?? null;
+  const { onSetElementAttributeQuiet, onGroupClips, onNotice } = useTimelineEditContextOptional();
+  const liveIframe = useLivePreviewIframe();
+  const sessionProjectId = usePlayerStore((s) => s.timelineProjectId);
+  const projectId = shell?.projectId ?? sessionProjectId;
+  const showToast = shell?.showToast ?? onNotice;
+  const doc = (shell?.previewIframeRef.current ?? liveIframe)?.contentDocument ?? null;
   const bed = doc?.getElementById(element.domId ?? element.id) ?? null;
   const ducked = bed ? readBedCarve(bed)?.enabled === true : false;
-  if (!clipHasSound(element) || !shell || !onSetElementAttributeQuiet) return null;
-  const { showToast, projectId } = shell;
+  if (!clipHasSound(element) || !projectId || !showToast || !onSetElementAttributeQuiet) {
+    return null;
+  }
 
   const normalize = async () => {
     onClose();
@@ -84,25 +93,24 @@ export function ClipMenuAudioItems({
     showToast(DUCK_TOAST[outcome], outcome === "aborted" ? "error" : "info");
   };
 
-  return (
-    <>
+  if (part === "normalize") {
+    return (
       <button type="button" role="menuitem" className={ITEM_CLASS} onClick={() => void normalize()}>
         <span>Normalize loudness</span>
       </button>
-      {isDuckableBed(bed) && (
-        <button
-          type="button"
-          role="menuitemcheckbox"
-          aria-checked={ducked}
-          className={ITEM_CLASS}
-          onClick={() => void toggleDuck()}
-        >
-          <span>
-            <span className="inline-block w-3">{ducked ? "✓" : ""}</span>Duck under voice
-          </span>
-        </button>
-      )}
-      <div className="my-1 border-t border-neutral-700/60" />
-    </>
+    );
+  }
+  if (!offersDuck(doc, bed)) return null;
+  return (
+    <button
+      type="button"
+      role="menuitemcheckbox"
+      aria-checked={ducked}
+      className={ITEM_CLASS}
+      onClick={() => void toggleDuck()}
+    >
+      <span>Duck under voice</span>
+      <span aria-hidden="true">{ducked ? "✓" : ""}</span>
+    </button>
   );
 }

package/src/player/components/clipMenuDuck.ts

@@ -83,6 +83,11 @@ export function duckVoiceSources(doc: Document, bed: Element): string[] {
     .map((candidate) => candidate.id);
 }
 
+export function offersDuck(doc: Document | null, bed: Element | null): boolean {
+  if (!doc || !isDuckableBed(bed)) return false;
+  return readBedCarve(bed)?.enabled === true || duckVoiceSources(doc, bed).length > 0;
+}
+
 async function writeMeasuredCarve(
   doc: Document,
   bed: Element,