Skip to content

Commit acfa7c5

Browse files
vanceingallsclaude
andauthored
feat(studio): group rows in the timeline, and a split disclosure (#3286)
* feat(core,studio): the character presets pitch shift unlocks Chipmunk, Giant, and Monster ship as presets on the pitchshift worklet P1 added: Chipmunk pitches up and adds sparkle, Giant pitches down with weight and a compressor to hold the extra low end together, Monster pitches down further with saturation growl and a close, tight reverb. Every param verified against the live effect registry rather than sketched — the compressor/reverb/saturate/shelf keys all match exactly. Each gets its own title treatment (font, size, tracking, hue) so the FX rack's per-preset styling coverage and hue-distance/background-uniqueness tests extend cleanly to the three new entries, and complaint-line copy in the non-voice vocabulary the audit test enforces (no speech words — "Giant" over CapCut's "Deep Voice", as the design doc records). Updates plans/audio-fx-presets.md's two limits paragraphs to record that pitch shift landed and this half of the character list now ships; Robot and Alien stay out of scope (ring modulation, still unbuilt). Co-Authored-By: Claude Sonnet 5 <[email protected]> * feat(core): the audio group model — element, membership, helpers Introduces <hf-audio-group> and data-audio-group as the group model B2–B7 and C1 build on: a non-rendering group element carries a label and (later) an FX chain, membership lives on the member's own data-audio-group attribute rather than DOM nesting, so a track removed from the document simply drops out of the group on the next resolve — nothing dangles. Groups do not nest: data-audio-group on the group element itself is ignored. A group with members but no <hf-audio-group> element still resolves, label falling back to the id, so hand-authored HTML degrades gracefully. Audio only in v1 — video members are ignored. Parse-only: nothing routes or sums audio yet (B3/B4). Adds the audio-groups canary at percentage: 0 gating the future Studio UI; the element and attribute parse and play regardless of enrollment. Verified rather than assumed per this plan's standing rule: the timeline's clip-collection selector ([data-start], [data-track-index], [data-composition-id], video, audio, img) already excludes the group element with zero changes, and no lint rule flags unknown elements or data-* attributes, so neither needed touching — confirmed by grep and by running `hyperframes lint` against a fixture containing the element (0 findings referencing it). The step doc's suggested display:none injection point (an existing base stylesheet in the runtime) does not exist in this codebase; skipped rather than inventing new infrastructure, since an empty, childless custom element already renders as a zero-size inline box with no visible output — the same reasoning the lint check above confirms empirically. Co-Authored-By: Claude Sonnet 5 <[email protected]> * feat(studio): group rows in the timeline, and a split disclosure A group renders as its own row with member rows beneath it, and disclosure splits into two independent controls: caret shows/hides a group's member rows (structural), `∿` shows/hides any row's automation-lane rows. Plain tracks lose their caret (nothing to disclose structurally) and keep only `∿`. `expandedClipIds` keeps its existing keyframe-lane-state job; `expandedGroupIds`/`expandedLaneOwnerIds` are new, independent sets. Groups get a real position in the row/geometry pipeline rather than a visual-only overlay: `useTimelineTrackDerivations` re-emits a group's member tracks contiguously under a synthetic fractional anchor key (firstMember - 0.5, the same fractional-key convention sub-composition expansion already uses), so `rowGeometry`/keyboard-nav/virtualization treat a group row as a first-class row without widening their key type away from number. `TimelineLogicalRow.level` widens `1 | 2` to `1 | 2 | 3` (group / member-under-group / lane), lanes always `owner.level + 1`. All of it — grouped row emission, the header, the new expansion state — is gated behind `isCanaryEnabled("audio-groups")`; disabled, `groups` resolves empty and every new code path no-ops. `TimelineElement.audioGroup` (+ `audioGroupLabel`, resolved once per document via `resolveAudioGroups` from B1) is parsed unconditionally, mirroring how `hidden`/`fxChain` already flow DOM → manifest → TimelineElement — inert without the canary. Co-Authored-By: Claude Sonnet 5 <[email protected]> --------- Co-authored-by: Claude Sonnet 5 <[email protected]>
1 parent 5240367 commit acfa7c5

23 files changed

Lines changed: 707 additions & 113 deletions

‎packages/studio/src/hooks/useMusicBeatAnalysis.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ import { resolveBeatSourceTrack } from "../utils/timelineInspector";
44
import { analyzeMusicFromUrl } from "@hyperframes/core/beats";
55
import { useFileManagerContextOptional } from "../contexts/FileManagerContext";
66
import { mergeUserBeats } from "../utils/beatEditing";
7+
import { getTimelineElementIndexes } from "../player/lib/timelineElementIndexes";
8+
import { remapBeatAnalysisToComposition } from "../utils/beatEditActions";
79
import {
810
audioRelPathForSrc,
911
beatFilePathForSrc,
@@ -90,6 +92,17 @@ async function loadBeatAnalysis(
9092
}
9193
}
9294

95+
/** The current beat analysis, remapped onto the composition's edited beat grid. */
96+
export function useAdjustedBeatAnalysis() {
97+
const beatAnalysis = usePlayerStore((s) => s.beatAnalysis);
98+
const musicElement = usePlayerStore((s) => getTimelineElementIndexes(s.elements).musicElement);
99+
const beatEdits = usePlayerStore((s) => s.beatEdits);
100+
return useMemo(
101+
() => remapBeatAnalysisToComposition(beatAnalysis, musicElement, beatEdits),
102+
[beatAnalysis, musicElement, beatEdits],
103+
);
104+
}
105+
93106
export function useMusicBeatAnalysis(): void {
94107
const elements = usePlayerStore((s) => s.elements);
95108
const setBeatAnalysis = usePlayerStore((s) => s.setBeatAnalysis);

‎packages/studio/src/player/components/LayerDisclosureRow.tsx‎

Lines changed: 12 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
1-
import { CaretRight } from "@phosphor-icons/react";
21
import { TRACK_H } from "./timelineLayout";
32
import { TrackClipCount } from "./TrackClipCount";
43

5-
// Layer row (Figma order: disclosure ▸/▾, diamond, name) — the disclosure lives
6-
// here, not on the clip bar, and re-expands a collapsed layer.
4+
// Layer row (Figma order: disclosure ∿, diamond, name) — the disclosure lives
5+
// here, not on the clip bar, and re-expands a collapsed layer. `∿` (not a
6+
// caret) because a group's own row keeps the caret for its structural
7+
// disclosure (member rows) — this button only ever means "show this row's
8+
// lanes", so it needs its own distinct glyph.
79
export function LayerDisclosureRow({
810
name,
911
clipCount,
@@ -49,23 +51,20 @@ export function LayerDisclosureRow({
4951
tabIndex={-1}
5052
aria-expanded={isExpanded}
5153
aria-controls={lanesId}
52-
aria-label={`${isExpanded ? "Collapse" : "Expand"} ${name} keyframes`}
53-
title={`${isExpanded ? "Collapse" : "Expand"} keyframe lanes`}
54-
// h-6 w-6 = the 24x24 WCAG 2.2 minimum target. The caret glyph stays 11px;
54+
aria-label={`${isExpanded ? "Hide" : "Show"} ${name} lanes`}
55+
title={`${isExpanded ? "Hide" : "Show"} lanes`}
56+
// h-6 w-6 = the 24x24 WCAG 2.2 minimum target. The glyph stays 11px;
5557
// only the hit box grows.
56-
className="flex h-6 w-6 shrink-0 items-center justify-center rounded border-0 bg-transparent p-0 text-white/55 hover:text-white focus-visible:outline focus-visible:outline-1 focus-visible:outline-[#3CE6AC]"
58+
className={`flex h-6 w-6 shrink-0 items-center justify-center rounded border-0 bg-transparent p-0 text-[11px] leading-none focus-visible:outline focus-visible:outline-1 focus-visible:outline-[#3CE6AC] ${
59+
isExpanded ? "text-[#3CE6AC]" : "text-white/55 hover:text-white"
60+
}`}
5761
onPointerDown={(event) => event.stopPropagation()}
5862
onClick={(event) => {
5963
event.stopPropagation();
6064
onToggleClipExpanded();
6165
}}
6266
>
63-
<CaretRight
64-
size={11}
65-
weight="bold"
66-
aria-hidden="true"
67-
style={{ transform: isExpanded ? "rotate(90deg)" : undefined }}
68-
/>
67+
<span aria-hidden="true">∿</span>
6968
</button>
7069
{/* Decorative: the disclosure button above already names the row's keyframe
7170
state, and aria-label on a plain span is not exposed reliably anyway. */}

‎packages/studio/src/player/components/Timeline.test.ts‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -556,11 +556,11 @@ describe("Timeline provider boundary", () => {
556556
// Keyframed clip-1 is expanded by default (AE/Figma default); its disclosure
557557
// lives in the left column. clip-2 has no keyframes so it never shows one.
558558
const collapseButton = host.querySelector<HTMLButtonElement>(
559-
'button[aria-label="Collapse clip-1 keyframes"]',
559+
'button[aria-label="Hide clip-1 lanes"]',
560560
);
561561
expect(collapseButton).not.toBeNull();
562-
expect(host.querySelector('button[aria-label="Expand clip-2 keyframes"]')).toBeNull();
563-
expect(host.querySelector('button[aria-label="Collapse clip-2 keyframes"]')).toBeNull();
562+
expect(host.querySelector('button[aria-label="Show clip-2 lanes"]')).toBeNull();
563+
expect(host.querySelector('button[aria-label="Hide clip-2 lanes"]')).toBeNull();
564564

565565
const clip = host.querySelector<HTMLElement>('[data-el-id="clip-1"]');
566566
const row = clip?.parentElement?.parentElement;
@@ -571,7 +571,7 @@ describe("Timeline provider boundary", () => {
571571
expectTrackExpansion(row, [], TRACK_H);
572572

573573
const expandButton = host.querySelector<HTMLButtonElement>(
574-
'button[aria-label="Expand clip-1 keyframes"]',
574+
'button[aria-label="Show clip-1 lanes"]',
575575
);
576576
expect(expandButton).not.toBeNull();
577577
act(() => expandButton?.click());
@@ -603,8 +603,8 @@ describe("Timeline provider boundary", () => {
603603
const row = host.querySelector<HTMLElement>('[data-el-id="narration-1"]')?.parentElement
604604
?.parentElement;
605605
// A row of several clips is named for the track, so the caret is too.
606-
const caret = () => host.querySelector<HTMLButtonElement>('button[aria-label$=" keyframes"]');
607-
expect(caret()?.getAttribute("aria-label")).toBe("Expand Track 1 keyframes");
606+
const caret = () => host.querySelector<HTMLButtonElement>('button[aria-label$=" lanes"]');
607+
expect(caret()?.getAttribute("aria-label")).toBe("Show Track 1 lanes");
608608

609609
act(() => caret()?.click());
610610
// One shared volume row, and BOTH clips hold it open.
@@ -647,7 +647,7 @@ describe("Timeline provider boundary", () => {
647647
});
648648
const root = createRoot(host);
649649
act(() => root.render(React.createElement(Timeline)));
650-
act(() => host.querySelector<HTMLButtonElement>('button[aria-label$=" keyframes"]')?.click());
650+
act(() => host.querySelector<HTMLButtonElement>('button[aria-label$=" lanes"]')?.click());
651651

652652
const before = [...host.querySelectorAll(".hf-automation-lane")];
653653
expect(before).toHaveLength(2);

‎packages/studio/src/player/components/Timeline.tsx‎

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
import { useRef, useMemo, useCallback, useState, memo } from "react";
2-
import { useMusicBeatAnalysis } from "../../hooks/useMusicBeatAnalysis";
3-
import { remapBeatAnalysisToComposition } from "../../utils/beatEditActions";
2+
import { useAdjustedBeatAnalysis, useMusicBeatAnalysis } from "../../hooks/useMusicBeatAnalysis";
43
import { usePlayerStore, type TimelineElement } from "../store/playerStore";
54
import { useExpandedTimelineElements } from "../hooks/useExpandedTimelineElements";
65
import { defaultTimelineTheme } from "./timelineTheme";
@@ -39,7 +38,6 @@ import {
3938
import { useTimelineSelectionLifecycle } from "./useTimelineSelectionLifecycle";
4039
import { useTimelineShiftModifier } from "./useTimelineShiftModifier";
4140
import { useTimelineTicks } from "./useTimelineTicks";
42-
import { getTimelineElementIndexes } from "../lib/timelineElementIndexes";
4341
import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
4442
import { useTimelineClipRenderWindow } from "./useTimelineClipRenderWindow";
4543
import { useTimelineActiveClips } from "./useTimelineActiveClips";
@@ -109,13 +107,7 @@ export const Timeline = memo(function Timeline({
109107
useMusicBeatAnalysis();
110108
const rawElements = usePlayerStore((s) => s.elements);
111109
const expandedElements = useExpandedTimelineElements();
112-
const beatAnalysis = usePlayerStore((s) => s.beatAnalysis);
113-
const musicElement = usePlayerStore((s) => getTimelineElementIndexes(s.elements).musicElement);
114-
const beatEdits = usePlayerStore((s) => s.beatEdits);
115-
const adjustedBeatAnalysis = useMemo(
116-
() => remapBeatAnalysisToComposition(beatAnalysis, musicElement, beatEdits),
117-
[beatAnalysis, musicElement, beatEdits],
118-
);
110+
const adjustedBeatAnalysis = useAdjustedBeatAnalysis();
119111
const duration = usePlayerStore((s) => s.duration);
120112
const timeDisplayMode = usePlayerStore((s) => s.timeDisplayMode);
121113
const timelineReady = usePlayerStore((s) => s.timelineReady);
@@ -158,6 +150,8 @@ export const Timeline = memo(function Timeline({
158150
laneCounts,
159151
rowGeometry,
160152
rowGeometryRef,
153+
groups,
154+
trackGroupOf,
161155
} = useTimelineTrackLayout(
162156
expandedElements,
163157
gsapAnimations,
@@ -289,6 +283,8 @@ export const Timeline = memo(function Timeline({
289283
laneCounts,
290284
selectedElementId,
291285
selectedElementIds,
286+
groups,
287+
trackGroupOf,
292288
gsapAnimations,
293289
elements: expandedElements,
294290
pixelsPerSecond: pps,
@@ -509,6 +505,7 @@ export const Timeline = memo(function Timeline({
509505
trackOrder={trackOrder}
510506
tracks={tracks}
511507
trackStyles={trackStyles}
508+
groups={groups}
512509
laneCounts={laneCounts}
513510
selectedElementId={selectedElementId}
514511
selectedElementIds={selectedElementIds}
Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
import { TRACK_H } from "./timelineLayout";
2+
import type { TimelineTheme } from "./timelineTheme";
3+
4+
interface TimelineGroupHeaderProps {
5+
label: string;
6+
memberCount: number;
7+
/** Caret: shows/hides the member rows beneath this group (structural). */
8+
isExpanded: boolean;
9+
onToggleExpanded: () => void;
10+
/** `∿`: shows/hides the group's own automation-lane rows. */
11+
laneCount: number;
12+
isLaneOpen: boolean;
13+
onToggleLanes: () => void;
14+
columnWidth: number;
15+
theme: TimelineTheme;
16+
}
17+
18+
/**
19+
* A group's own row header: caret (member disclosure) + `▤` + label + `∿ n`
20+
* (lane disclosure). Mute/solo (B5) and the FX entry point (C1) land here as
21+
* siblings once those steps exist — nothing to reserve for them yet.
22+
*/
23+
export function TimelineGroupHeader({
24+
label,
25+
memberCount,
26+
isExpanded,
27+
onToggleExpanded,
28+
laneCount,
29+
isLaneOpen,
30+
onToggleLanes,
31+
columnWidth,
32+
theme,
33+
}: TimelineGroupHeaderProps) {
34+
return (
35+
<div
36+
role="rowheader"
37+
aria-colindex={1}
38+
className="sticky left-0 z-[12] flex shrink-0 items-center gap-1.5 overflow-hidden px-1.5 text-[11px]"
39+
style={{
40+
width: columnWidth,
41+
height: TRACK_H,
42+
color: "#ffffff",
43+
background: theme.gutterBackground,
44+
borderRight: `1px solid ${theme.gutterBorder}`,
45+
}}
46+
>
47+
<button
48+
type="button"
49+
tabIndex={-1}
50+
aria-expanded={isExpanded}
51+
aria-label={`${isExpanded ? "Hide" : "Show"} ${label} tracks`}
52+
title={`${isExpanded ? "Hide" : "Show"} tracks`}
53+
className={`flex h-6 w-6 shrink-0 items-center justify-center rounded border-0 bg-transparent p-0 text-[11px] focus-visible:outline focus-visible:outline-1 focus-visible:outline-[#3CE6AC] ${
54+
isExpanded ? "text-white" : "text-white/55 hover:text-white"
55+
}`}
56+
onPointerDown={(event) => event.stopPropagation()}
57+
onClick={(event) => {
58+
event.stopPropagation();
59+
onToggleExpanded();
60+
}}
61+
>
62+
<span aria-hidden="true" style={{ transform: isExpanded ? "rotate(90deg)" : undefined }}>
63+
▸
64+
</span>
65+
</button>
66+
<span aria-hidden="true" className="shrink-0 text-[12px] leading-none text-white/50">
67+
▤
68+
</span>
69+
<span className="min-w-0 flex-1 truncate font-medium" title={label}>
70+
{label}
71+
</span>
72+
<span
73+
className="shrink-0 rounded-full bg-white/10 px-1 text-[9px] leading-[14px] tabular-nums text-white/55"
74+
aria-hidden="true"
75+
title={`${memberCount} tracks`}
76+
>
77+
{memberCount}
78+
</span>
79+
<button
80+
type="button"
81+
tabIndex={-1}
82+
aria-expanded={isLaneOpen}
83+
aria-label={`${isLaneOpen ? "Hide" : "Show"} ${label} lanes`}
84+
title={`${isLaneOpen ? "Hide" : "Show"} lanes`}
85+
className={`flex h-6 items-center justify-center gap-0.5 rounded border-0 bg-transparent px-1 text-[11px] leading-none focus-visible:outline focus-visible:outline-1 focus-visible:outline-[#3CE6AC] ${
86+
isLaneOpen ? "text-[#3CE6AC]" : "text-white/55 hover:text-white"
87+
}`}
88+
onPointerDown={(event) => event.stopPropagation()}
89+
onClick={(event) => {
90+
event.stopPropagation();
91+
onToggleLanes();
92+
}}
93+
>
94+
<span aria-hidden="true">∿</span>
95+
{laneCount > 0 && (
96+
<span className="text-[9px] tabular-nums text-white/55">{laneCount}</span>
97+
)}
98+
</button>
99+
</div>
100+
);
101+
}
Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
import type { TimelineElement } from "../store/playerStore";
2+
import type { TimelineTheme } from "./timelineTheme";
3+
import type { TimelineTrackGroupInfo } from "./useTimelineTrackDerivations";
4+
import type { TimelineLogicalRow } from "./timelineKeyboardNavigation";
5+
import { TimelineTrackRow } from "./TimelineTrackRow";
6+
import { TimelineGroupHeader } from "./TimelineGroupHeader";
7+
import { groupAutomationLanes } from "./automationLaneData";
8+
import { LABEL_COL_W } from "./timelineLayout";
9+
10+
interface TimelineGroupRowProps {
11+
index: number;
12+
rowKey: number;
13+
group: TimelineTrackGroupInfo;
14+
logicalRow: TimelineLogicalRow;
15+
tracks: readonly (readonly [number, readonly TimelineElement[]])[];
16+
top: number;
17+
height: number;
18+
virtualized: boolean;
19+
contentOrigin: number;
20+
theme: TimelineTheme;
21+
rovingTargetId?: string | null;
22+
expandedGroupIds: ReadonlySet<string>;
23+
expandedLaneOwnerIds: ReadonlySet<string>;
24+
toggleGroupExpanded: (id: string) => void;
25+
toggleLaneOwnerExpanded: (id: string) => void;
26+
}
27+
28+
/** A group's own row: the accessible shell (shared with track rows) plus the group header. */
29+
export function TimelineGroupRow({
30+
index,
31+
rowKey,
32+
group,
33+
logicalRow,
34+
tracks,
35+
top,
36+
height,
37+
virtualized,
38+
contentOrigin,
39+
theme,
40+
rovingTargetId = null,
41+
expandedGroupIds,
42+
expandedLaneOwnerIds,
43+
toggleGroupExpanded,
44+
toggleLaneOwnerExpanded,
45+
}: TimelineGroupRowProps) {
46+
const memberElements = group.memberTracks.flatMap(
47+
(track) => tracks.find(([t]) => t === track)?.[1] ?? [],
48+
);
49+
return (
50+
<TimelineTrackRow
51+
index={index}
52+
rowKey={rowKey}
53+
logicalRow={logicalRow}
54+
propertyRows={[]}
55+
lanesId=""
56+
headerLanesId=""
57+
top={top}
58+
height={height}
59+
virtualized={virtualized}
60+
background={theme.rowBackground}
61+
borderColor={theme.rowBorder}
62+
rovingTargetId={rovingTargetId}
63+
>
64+
<TimelineGroupHeader
65+
label={group.label}
66+
memberCount={group.memberTracks.length}
67+
isExpanded={expandedGroupIds.has(group.id)}
68+
onToggleExpanded={() => toggleGroupExpanded(group.id)}
69+
laneCount={groupAutomationLanes(memberElements).length}
70+
isLaneOpen={expandedLaneOwnerIds.has(group.id)}
71+
onToggleLanes={() => toggleLaneOwnerExpanded(group.id)}
72+
columnWidth={contentOrigin >= LABEL_COL_W ? LABEL_COL_W : contentOrigin}
73+
theme={theme}
74+
/>
75+
</TimelineTrackRow>
76+
);
77+
}

‎packages/studio/src/player/components/TimelineLanes.test.tsx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,10 @@ function renderLanes(options: RenderLanesOptions = {}): {
118118
selectedElementId: null,
119119
selectedElementIds: next.selectedElementIds ?? new Set(),
120120
expandedClipIds: new Set(next.expandedClipIds ?? []),
121+
expandedGroupIds: new Set(),
122+
expandedLaneOwnerIds: new Set(),
123+
groups: [],
124+
trackGroupOf: new Map(),
121125
gsapAnimations,
122126
})}
123127
clipIndex={createTimelineClipIndex(tracks)}
@@ -127,6 +131,7 @@ function renderLanes(options: RenderLanesOptions = {}): {
127131
trackOrder={displayTrackOrder}
128132
tracks={tracks}
129133
trackStyles={new Map()}
134+
groups={[]}
130135
laneCounts={laneCounts}
131136
selectedElementId={null}
132137
selectedElementIds={next.selectedElementIds ?? new Set()}

0 commit comments

Comments
 (0)