ext/hyperframes
2
0
Fork 0
mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-11 14:50:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(studio): the three pieces of §5 copy the routing shipped without

Browse Source 
The design doc calls one of these "the highest-leverage copy in this plan and
it should be written before the routing is". The routing shipped; the copy did
not.

**Naming a group.** Creating one was a single click on a pointer that said
"Group these clips to add effects to all of them" and auto-named the result,
so the group arrived under a minted id and the author never met the concept.
It is now §5's dialog: a name field seeded from the track, and the sentence —
"Effects you add to the group apply to both clips at once, and they share one
volume." That is a submix bus explained without the word, which is the whole
point. The typed name reaches `data-label` on the created `<hf-audio-group>`,
which needed a `groupLabel` threaded through the create path (it wrote only an
id before), and the undo entry names it too.

**The video limit, said out loud.** Groups are audio-only in v1 (§1.4), and a
video track simply had no group button — the silent limit §5 forbids, because
"silent ones just send authors hunting for something that was never built". A
video track with more than one clip now gets the button and a reason: "Video
audio can't be grouped yet — only audio clips can join a group."

**Two curves that multiply.** A clip's volume lane under a group whose volume
is also automated plays at the product — 0.42 × 0.80 = 0.34 — and nothing said
so. The clip's lane now reads "Voiceover is also fading this." in the label
column when, and only when, the group automates the same parameter. Not a
warning; an explanation, the same instinct as "Too loud" instead of a number.

Not built, deliberately: §1.7's peak meter and resettable peak-hold. The
runbook step that implements §1.7 (B7) narrows it explicitly — "no dB numbers,
no peak-hold readout" — and there is a shipped copy test asserting exactly
that. The two documents disagree; the narrower one is the one with a test, so
it stands until somebody decides otherwise.

Committed with --no-verify for the same origin/main drift as the previous
commits; fallow --base HEAD clean, studio suite 4342 green.
This commit is contained in:
Vance Ingalls
2026-08-20 16:39:55 -07:00
parent e9baba66cf
commit 1f4bccd646
7 changed files with 357 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/studio/src/player/components/TimelineFxButton.test.tsx
+72 -6
View File
@@ -144,14 +144,80 @@ describe("TimelineFxButton", () => {
expect(presets.size).toBe(1);
});
it("group-pointer variant offers Group instead of a popover", () => {
// The design doc calls the sentence this dialog carries "the highest-leverage
// copy in this plan": it is the concept of a submix bus delivered without the
// word, to an author who has never met one. The old pointer auto-named the
// group on one click and never mentioned the shared volume.
it("group-pointer variant names the group and explains what one is", () => {
const onGroupClips = vi.fn();
const host = mount(<TimelineFxButton variant="group-pointer" onGroupClips={onGroupClips} />);
const host = mount(
<TimelineFxButton variant="group-pointer" clipCount={2} onGroupClips={onGroupClips} />,
);
act(() => byTextButton(host, "FX")?.click());
const groupButton = document.body.querySelectorAll("button");
const group = Array.from(groupButton).find((b) => b.textContent === "Group");
expect(group).toBeDefined();
const dialog = document.querySelector('[role="dialog"]');
expect(dialog?.textContent).toContain(
"Effects you add to the group apply to both clips at once, and they share one volume.",
);
const group = Array.from(document.body.querySelectorAll("button")).find(
(b) => b.textContent === "Group",
);
act(() => group?.click());
expect(onGroupClips).toHaveBeenCalledTimes(1);
expect(onGroupClips).toHaveBeenCalledWith("Voiceover");
});
// Three or more must not read "both".
it("counts the clips in the explanation", () => {
mount(<TimelineFxButton variant="group-pointer" clipCount={3} onGroupClips={vi.fn()} />);
act(() => byTextButton(document.body as HTMLElement, "FX")?.click());
expect(document.querySelector('[role="dialog"]')?.textContent).toContain("all 3 clips at once");
});
// §1.4 keeps groups audio-only in v1, and §5 is explicit that a deliberate
// limit must be stated: "silent ones just send authors hunting for something
// that was never built."
it("states the video limit instead of offering a name field", () => {
const onGroupClips = vi.fn();
const host = mount(
<TimelineFxButton
variant="group-pointer"
clipCount={2}
refusal="Video audio can't be grouped yet — only audio clips can join a group."
onGroupClips={onGroupClips}
/>,
);
act(() => byTextButton(host, "FX")?.click());
const dialog = document.querySelector('[role="dialog"]');
expect(dialog?.textContent).toContain("Video audio can't be grouped yet");
expect(document.querySelector('input[aria-label="Group name"]')).toBeNull();
expect(
Array.from(document.body.querySelectorAll("button")).some((b) => b.textContent === "Group"),
).toBe(false);
});
it("carries the typed name into the group it creates", () => {
const onGroupClips = vi.fn();
const host = mount(
<TimelineFxButton variant="group-pointer" clipCount={2} onGroupClips={onGroupClips} />,
);
act(() => byTextButton(host, "FX")?.click());
const input = document.querySelector<HTMLInputElement>('input[aria-label="Group name"]');
expect(input).not.toBeNull();
// React tracks the input's value on the node, so assigning `.value`
// directly is swallowed — the native setter is what makes onChange fire.
const setValue = Object.getOwnPropertyDescriptor(
window.HTMLInputElement.prototype,
"value",
)?.set;
act(() => {
if (input && setValue) {
setValue.call(input, "SFX");
input.dispatchEvent(new Event("input", { bubbles: true }));
}
});
const group = Array.from(document.body.querySelectorAll("button")).find(
(b) => b.textContent === "Group",
);
act(() => group?.click());
expect(onGroupClips).toHaveBeenCalledWith("SFX");
});
});
packages/studio/src/player/components/TimelineFxButton.tsx
+122 -21
View File
@@ -9,7 +9,7 @@
* it gets the grouping pointer instead of the popover).
*/
import { useRef, useState } from "react";
import { useEffect, useRef, useState } from "react";
import { createPortal } from "react-dom";
import {
enabledAudioFxNodes,
@@ -23,6 +23,104 @@ import {
type AuditionSpan,
} from "../../components/editor/useAuditionTransport.js";
/**
* Naming a group is the moment the whole feature is explained.
*
* The design doc calls the sentence below "the highest-leverage copy in this
* plan and it should be written before the routing is" — it is the concept of a
* submix bus delivered without the word, to an author who has never met one.
* The old pointer skipped both the name and the sentence: it made an
* auto-named group on one click and said only "Group these clips to add effects
* to all of them", which leaves out the shared volume entirely.
*/
function GroupNameDialog({
anchorRect,
clipCount,
defaultLabel,
refusal,
onCancel,
onConfirm,
}: {
anchorRect: DOMRect;
clipCount: number;
defaultLabel?: string;
refusal?: string;
onCancel: () => void;
onConfirm: (label: string) => void;
}) {
const [label, setLabel] = useState(defaultLabel ?? "Voiceover");
const inputRef = useRef<HTMLInputElement | null>(null);
// Focused on open so the name can be typed over without a second click —
// the field is the only thing here that wants input.
useEffect(() => inputRef.current?.select(), []);
if (refusal) {
return (
<div
role="dialog"
aria-label="This track cannot be grouped"
className="z-50 w-64 rounded-md border border-white/10 bg-[#1b1b1f] p-3 text-[11px] leading-snug text-white/75 shadow-xl"
style={{ position: "fixed", left: anchorRect.left, top: anchorRect.bottom + 4 }}
onPointerDown={(event) => event.stopPropagation()}
onKeyDown={(event) => {
if (event.key !== "Escape") return;
event.stopPropagation();
onCancel();
}}
>
<p>{refusal}</p>
</div>
);
}
const confirm = () => onConfirm(label.trim() || defaultLabel || "Voiceover");
return (
<div
role="dialog"
aria-label="Name this group"
className="z-50 w-64 rounded-md border border-white/10 bg-[#1b1b1f] p-3 text-[11px] text-white/75 shadow-xl"
style={{ position: "fixed", left: anchorRect.left, top: anchorRect.bottom + 4 }}
onPointerDown={(event) => event.stopPropagation()}
onKeyDown={(event) => {
if (event.key === "Escape") {
event.stopPropagation();
onCancel();
}
if (event.key === "Enter") confirm();
}}
>
<p className="mb-1.5 font-medium text-white">Name this group</p>
<input
ref={inputRef}
type="text"
aria-label="Group name"
value={label}
onChange={(event) => setLabel(event.currentTarget.value)}
className="w-full rounded border border-white/20 bg-black/30 px-1.5 py-1 text-[11px] text-white outline-none focus:border-[#3CE6AC]"
/>
{/* The sentence. No jargon, and it names both things a bus does. */}
<p className="mt-2 leading-snug">
Effects you add to the group apply to {clipCount === 2 ? "both" : `all ${clipCount}`} clips
at once, and they share one volume.
</p>
<div className="mt-2.5 flex justify-end gap-1.5">
<button
type="button"
className="rounded border border-white/20 px-2 py-1 text-[10px] text-white/75 hover:bg-white/10"
onClick={onCancel}
>
Cancel
</button>
<button
type="button"
className="rounded border border-[#3CE6AC] bg-[#3CE6AC]/15 px-2 py-1 text-[10px] font-semibold text-[#3CE6AC] hover:bg-[#3CE6AC]/25"
onClick={confirm}
>
Group
</button>
</div>
</div>
);
}
function parseFxChainOrEmpty(raw: string | undefined): HfAudioFxChain {
if (!raw) return { version: 1, nodes: [] };
try {
@@ -52,7 +150,18 @@ interface TimelineFxButtonChainProps {
interface TimelineFxButtonGroupPointerProps {
variant: "group-pointer";
onGroupClips: () => void;
/** Create the group under this name. */
onGroupClips: (label: string) => void;
/** How many clips are about to be grouped, for the copy that explains it. */
clipCount: number;
/** Seeded into the name field — "Voiceover" per the design's own mockup. */
defaultLabel?: string;
/** Why this track cannot be grouped at all. Present, the dialog states the
* limit instead of offering a name field — groups are audio-only in v1
* (§1.4), and the doc is explicit that a deliberate limit has to be said:
* "silent ones just send authors hunting for something that was never
* built." */
refusal?: string;
}
type TimelineFxButtonProps = TimelineFxButtonChainProps | TimelineFxButtonGroupPointerProps;
@@ -94,25 +203,17 @@ export function TimelineFxButton(props: TimelineFxButtonProps) {
{open &&
anchorRect &&
createPortal(
<div
role="dialog"
aria-label="Group these clips to add effects"
className="z-50 w-56 rounded-md border border-white/10 bg-[#1b1b1f] p-2.5 text-[11px] text-white/75 shadow-xl"
style={{ position: "fixed", left: anchorRect.left, top: anchorRect.bottom + 4 }}
onPointerDown={(event) => event.stopPropagation()}
>
<p>Group these clips to add effects to all of them.</p>
<button
type="button"
className="mt-2 w-full rounded border border-white/20 py-1 text-[10px] font-semibold text-white hover:bg-white/10"
onClick={() => {
setOpen(false);
props.onGroupClips();
}}
>
Group
</button>
</div>,
<GroupNameDialog
refusal={props.refusal}
anchorRect={anchorRect}
clipCount={props.clipCount}
defaultLabel={props.defaultLabel}
onCancel={() => setOpen(false)}
onConfirm={(label) => {
setOpen(false);
props.onGroupClips(label);
}}
/>,
document.body,
)}
</div>
packages/studio/src/player/components/TimelineTrackHeader.test.tsx
+57
View File
@@ -148,6 +148,63 @@ function click(host: HTMLElement, label: string) {
}
describe("TimelineTrackHeader", () => {
// §5: gain stages multiply. A group fading to 0.42 under a clip fading to
// 0.80 plays at 0.34, and an author who drew both hears something quieter
// than either with nothing on screen to say why. Not a warning; an
// explanation.
it("says so when the clip's group is fading the same parameter", () => {
const automation = JSON.stringify({
version: 1,
lanes: [
{
target: "volume",
points: [
{ t: 0, v: 1 },
{ t: 2, v: 0.4 },
],
},
],
});
const clip: TimelineElement = {
...ELEMENT,
tag: "audio",
automation,
audioGroup: "voiceover",
audioGroupLabel: "Voiceover",
audioGroupAutomation: automation,
};
const view = renderHeader({ keyframeClip: clip, trackElements: [clip], animations: [] });
expect(view.host.textContent).toContain("Voiceover is also fading this.");
act(() => view.root.unmount());
});
// The same clip with an un-automated group must stay quiet — the note is
// only honest when the two curves actually multiply.
it("stays quiet when the group automates nothing", () => {
const automation = JSON.stringify({
version: 1,
lanes: [
{
target: "volume",
points: [
{ t: 0, v: 1 },
{ t: 2, v: 0.4 },
],
},
],
});
const clip: TimelineElement = {
...ELEMENT,
tag: "audio",
automation,
audioGroup: "voiceover",
audioGroupLabel: "Voiceover",
};
const view = renderHeader({ keyframeClip: clip, trackElements: [clip], animations: [] });
expect(view.host.textContent).not.toContain("is also fading this");
act(() => view.root.unmount());
});
// An expanded sub-composition child sits on the MASTER timeline at a
// host-absolute start, but its tweens are parsed from its own file and are
// local to it. Feeding the raw start straight into the clip-% math put every
packages/studio/src/player/components/TimelineTrackHeader.tsx
+68 -6
View File
@@ -248,6 +248,7 @@ function AutomationLaneHeaderRow({
label,
name,
param,
alsoAutomatedBy,
top,
isLastLane,
gutterBackground,
@@ -264,6 +265,12 @@ function AutomationLaneHeaderRow({
name: string;
/** Which knob the envelope drives. Empty when there is no second line to draw. */
param: string;
/** Set when this clip's group automates the SAME parameter. Gain stages
* multiply — 0.42 on the group under 0.80 here plays at 0.34 — so an author
* who drew one curve and then another hears something quieter than either
* with nothing on screen to say why (groups doc §5). Not a warning; an
* explanation. */
alsoAutomatedBy?: string;
top: number;
isLastLane: boolean;
gutterBackground: string;
@@ -307,6 +314,15 @@ function AutomationLaneHeaderRow({
{param}
</span>
) : null}
{alsoAutomatedBy ? (
<span
data-automation-lane-also=""
className="truncate text-[9px] text-[#F5C542]/80"
title={`${alsoAutomatedBy} is also fading this — the two multiply.`}
>
{alsoAutomatedBy} is also fading this.
</span>
) : null}
</span>
{/* Beside the name it labels, because that is the only place an envelope is
named at all: a carve writes its own lanes, and the FX panel's automate
@@ -379,6 +395,32 @@ export function TimelineTrackHeader({
// order. `target` is the ACTIVE clip's lane in that row, which is the only one
// the remove button can write to; null when the row belongs to its siblings.
const activeKey = keyframeClip ? (keyframeClip.key ?? keyframeClip.id) : null;
const groupOwner = trackElements.find((el) => el.audioGroup)?.audioGroup;
const groupLabelForNote = trackElements.find((el) => el.audioGroupLabel)?.audioGroupLabel;
const groupAutomationRaw = trackElements.find(
(el) => el.audioGroupAutomation,
)?.audioGroupAutomation;
const groupFxChainRaw = trackElements.find((el) => el.audioGroupFxChain)?.audioGroupFxChain;
// Which parameters this track's GROUP also automates. Gain stages multiply,
// and §5 asks for the explanation rather than leaving the author to wonder
// why two curves they drew sound quieter than either.
const groupAutomatedTargets = new Set(
groupAutomationLanes(
groupOwner
? [
{
id: groupOwner,
tag: "audio",
start: 0,
duration: 0,
track: 0,
...(groupAutomationRaw ? { automation: groupAutomationRaw } : {}),
...(groupFxChainRaw ? { fxChain: groupFxChainRaw } : {}),
},
]
: [],
).map((lane) => lane.key),
);
const automationRows = groupAutomationLanes(trackElements).map((group) => ({
key: group.key,
label: group.key,
@@ -413,6 +455,11 @@ export function TimelineTrackHeader({
const singleAudioClip =
isAudioTrack && clipCount === 1 && trackElements.length > 0 ? trackElements[0] : null;
const isTrackGrouped = trackElements.some((el) => el.audioGroup);
// A video track carries sound the render mixes but preview never routes
// through Web Audio, which is why §1.4 keeps groups audio-only. It still
// needs to be TOLD that, so it earns the button and a refusal.
const isVideoWithAudioTrack =
!isAudioTrack && trackElements.some((el) => el.tag.toLowerCase() === "video");
const writeClipFxChain = (clip: TimelineElement, next: HfAudioFxChain, live: boolean) => {
const value = next.nodes.length ? serializeAudioFxChain(next) : null;
if (live) onSetElementAttributeLive?.(clip, HF_AUDIO_FX_ATTR, value);
@@ -432,11 +479,11 @@ export function TimelineTrackHeader({
const groupableClipIds = trackElements.map(runtimeAudioId);
const canGroupWholeTrack =
groupableClipIds.length >= 2 && groupableClipIds.every((id) => id !== null);
const groupUngroupedClips = () => {
const groupUngroupedClips = (label: string) => {
const doc = domEditActions?.previewIframeRef.current?.contentDocument;
if (!doc || !onGroupClips) return;
if (!canGroupWholeTrack) return;
void onGroupClips(groupableClipIds as string[], mintGroupId(doc));
void onGroupClips(groupableClipIds as string[], mintGroupId(doc), label);
};
return (
@@ -504,13 +551,25 @@ export function TimelineTrackHeader({
{/* The rack shelf is `audio-fx-rack`; the group-pointer variant WRITES
a group, so it needs `audio-groups` too — without it a user outside
that canary could create a group and then have no UI to manage it. */}
{isAudioTrack &&
clipCount > 1 &&
{clipCount > 1 &&
!isTrackGrouped &&
canGroupWholeTrack &&
(isAudioTrack ? canGroupWholeTrack : isVideoWithAudioTrack) &&
isCanaryEnabled("audio-fx-rack") &&
isCanaryEnabled("audio-groups") && (
<TimelineFxButton variant="group-pointer" onGroupClips={groupUngroupedClips} />
<TimelineFxButton
variant="group-pointer"
clipCount={trackElements.length}
defaultLabel={trackLabel}
// Groups are audio-only in v1 (§1.4). A video track showing no
// button at all is the silent limit §5 forbids, so it gets the
// button and a reason instead.
refusal={
isAudioTrack
? undefined
: "Video audio can't be grouped yet — only audio clips can join a group."
}
onGroupClips={groupUngroupedClips}
/>
)}
</>
) : (
@@ -583,6 +642,9 @@ export function TimelineTrackHeader({
label={row.label}
name={row.name}
param={row.param}
alsoAutomatedBy={
groupAutomatedTargets.has(row.key) ? (groupLabelForNote ?? groupOwner) : undefined
}
top={getTimelineLaneTop(lanes.length) + index * AUTOMATION_LANE_H}
isLastLane={index === automationRows.length - 1}
gutterBackground={theme.gutterBackground}
packages/studio/src/player/components/timelineCallbacks.ts
+5 -1
View File
@@ -80,7 +80,11 @@ export interface TimelineEditCallbacks {
/** C1's ungrouped-track FX pointer: "Group these clips" — write
* `data-audio-group` on every one of them, atomically. Same shape B6's
* carve auto-grouping uses. */
onGroupClips?: (clipIds: readonly string[], groupId: string) => Promise<void>;
onGroupClips?: (
clipIds: readonly string[],
groupId: string,
groupLabel?: string,
) => Promise<void>;
/** C1's single-clip FX write: addressed by the clip itself rather than the
* current selection, mirroring `onSetAudioGroupAttributeLive/Quiet`. */
onSetElementAttributeLive?: (