Skip to content

Commit 0d26072

Browse files
vanceingallsclaude
andauthored
feat(studio,core): mute groups, and hear-only-this that cannot reach the export (#3291)
B5: mute and solo, on groups and tracks (track mute already shipped by A2 — nothing to build there). Group mute — persisted as data-hidden on the <hf-audio-group> element itself (never written onto members, per design doc §2.1's state-restoration warning). Studio action reuses B7's generic setAudioGroupAttribute (setQuiet/setLive split) rather than duplicating toggleTimelineTrackHidden's shape — same one-atomic-patch/one-undo-entry contract, already built for exactly this purpose. Render: B4 already drops every member of a data-hidden group (confirmed by a new audioMixer.test.ts case — no production change needed there). Preview: a dedicated muteGain node (groupInput -> [fx] -> muteGain -> output -> master) so a mute toggle never fights scheduleVolumeLane's ramps on the same param — the same hazard B7's volume fader was split out to avoid. Mid-playback toggles sync via a new syncAudioGroupMute pass in init.ts (a group carries no data-start, so it's invisible to the existing visibility-node query). Members of a muted group render the strikethrough label treatment (TimelineTrackPlainHeader's isGroupMuted, sourced from TimelineElement.audioGroupHidden) — display only, no attribute touched. Solo — "Hear only this": a new session-only store slice (audioSoloSlice, soloed: ReadonlySet<string> of clip/group ids, never track numbers, never serialized). Predicate (isAudibleUnderSolo, packages/core/src/audioGroups.ts so both the store and the preview transport share one definition): an element is audible while any solo is active only if it or its own group is soloed. "Siblings, never ancestors" lives in the graph, not the predicate — solo gain is a per-element stage only; group buses are never attenuated by solo, so a soloed member's path through its group stays open by construction. Preview: a dedicated per-element soloGain in webAudioTransport.ts (parallel to the mute mechanics), pushed via window.__hf.setAudioSolo — a direct call, not an attribute write, so it can't ride the visibility-diff path mute uses. media.ts's HTMLMedia fallback folds the same predicate into its per-tick volume computation (the same seam A2 used for data-hidden). Half-lit group indicator (isGroupHalfLitUnderSolo) for "not soloed itself, but a member is". Exclusive-by-default toggle, ⌘/Ctrl-click to add/remove, TimelineSoloButton (⌗) beside mute on both track and group headers. Transport-bar banner ("Hearing only <label> — your export is not affected", Clear button) added in PlayerControls.tsx, reading labels straight off the live preview DOM. Export-safety, the most important property here: toggling/adding/clearing solo never calls setAttribute/removeAttribute on any element and never invokes the project save path (both asserted directly via spies in audioSoloSlice.test.ts) — solo cannot reach an export by construction, not by convention. Also: extracted useHydrateActiveCompPathFromUrl out of App.tsx (a pre-existing, unrelated effect) to stay under the 600-line filesize cap after wiring useAudioSoloBridge in; and fixed a circular dependency the solo-banner wiring introduced (useAudioSoloBridge.ts now imports usePlayerStore from its concrete module instead of the player/ barrel, which re-exports PlayerControls.tsx — the barrel path is what closed the cycle). Gates: bun run build clean; packages/core full suite 2379/2379; packages/ studio full suite 4276/4294 (18 pre-existing todo); packages/engine audioMixer.grouping.test.ts 5/5; oxfmt/oxlint clean on all 23 touched files; fallow clean (0 new circular deps, 0 new filesize/complexity findings). Co-authored-by: Claude Sonnet 5 <[email protected]>
1 parent a01a5d7 commit 0d26072

24 files changed

Lines changed: 1058 additions & 266 deletions

‎packages/core/src/audioGroups.ts‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -172,3 +172,35 @@ export function ensureAudioGroupInertStyle(doc: Document): void {
172172
style.textContent = `${HF_AUDIO_GROUP_TAG}{display:none!important}`;
173173
doc.head.appendChild(style);
174174
}
175+
176+
/**
177+
* Solo ("Hear only this") predicate — shared by the studio store (which owns
178+
* the `soloed` set and the UI's lit/half-lit state) and the preview transport
179+
* (which turns it into gain). An element is audible while any solo is active
180+
* only if IT is soloed, or its OWN group is soloed (group solo = members
181+
* solo). There is no "ancestor" to reach up to in this data model — a group
182+
* bus is never itself attenuated by solo, so a soloed member's path through
183+
* its group stays open by construction; this predicate only ever gates the
184+
* member's own gain. No solo active at all is the one path that returns true
185+
* unconditionally.
186+
*/
187+
export function isAudibleUnderSolo(
188+
soloed: ReadonlySet<string>,
189+
id: string,
190+
groupId?: string | null,
191+
): boolean {
192+
if (soloed.size === 0) return true;
193+
if (soloed.has(id)) return true;
194+
return Boolean(groupId && soloed.has(groupId));
195+
}
196+
197+
/** Half-lit: this group itself isn't soloed, but at least one of its members
198+
* is — the display-only signal that "some of what's under here still plays". */
199+
export function isGroupHalfLitUnderSolo(
200+
soloed: ReadonlySet<string>,
201+
groupId: string,
202+
memberIds: readonly string[],
203+
): boolean {
204+
if (soloed.size === 0 || soloed.has(groupId)) return false;
205+
return memberIds.some((id) => soloed.has(id));
206+
}

‎packages/core/src/runtime/init.ts‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ import { ensureAudioGroupInertStyle } from "../audioGroups.js";
4343
import { createColorGradingRuntime, type RuntimeColorGradingApi } from "./colorGrading";
4444
import { TransportClock } from "./clock";
4545
import { WebAudioTransport } from "./webAudioTransport";
46+
import { HF_AUDIO_GROUP_TAG, audioGroupOf, isAudibleUnderSolo } from "../audioGroups";
4647
import { quantizeTimeToFrame } from "../inline-scripts/parityContract";
4748
import { STUDIO_MANUAL_EDIT_GESTURE_ATTR } from "../editing/draftMarkers";
4849
import type {
@@ -182,6 +183,20 @@ export function initSandboxRuntimeModular(): void {
182183
void webAudio.init().then((ok) => {
183184
webAudioReady = ok;
184185
});
186+
// Studio's "Hear only this" push channel — session-only, so it rides a
187+
// dedicated `__hf` field (mirrors `colorGrading`'s lazy-init pattern) rather
188+
// than a DOM attribute: solo must never be written to the document (design
189+
// doc §2.2 / the export-safety guarantee), so there is nothing here for
190+
// `syncTimedElementVisibility`'s attribute-diffing to key off. Kept in this
191+
// closure too (not just inside `webAudio`) so `syncRuntimeMedia`'s
192+
// HTMLMedia-fallback path (video/non-transport audio) can apply the same
193+
// predicate per tick, the same split A2 used for `data-hidden`.
194+
let soloedIds: ReadonlySet<string> = new Set();
195+
window.__hf = window.__hf || {};
196+
window.__hf.setAudioSolo = (ids) => {
197+
soloedIds = new Set(ids);
198+
webAudio.setSolo(soloedIds);
199+
};
185200
// `_auto` is a Studio-internal keyframe marker (an auto-tracked endpoint the
186201
// parser reads back), NOT an animatable property. Register it as a no-op GSAP
187202
// plugin so GSAP doesn't log "Invalid property _auto" on every tween build —
@@ -1929,6 +1944,21 @@ export function initSandboxRuntimeModular(): void {
19291944
const nodeAffectsAudio = (node: HTMLElement): boolean =>
19301945
node.matches("audio[data-start]") || node.querySelector("audio[data-start]") !== null;
19311946

1947+
// An `<hf-audio-group>` carries no `data-start`, so it is never among
1948+
// `visibilityNodes` above — group mute needs its own small diff pass.
1949+
// Preview-side only (render reads the group's `data-hidden` directly at
1950+
// export time, per B4); this just keeps the live WebAudio group bus in
1951+
// sync with a `data-hidden` toggle made mid-playback.
1952+
const groupHiddenLast = new WeakMap<Element, boolean>();
1953+
const syncAudioGroupMute = () => {
1954+
for (const groupEl of document.querySelectorAll(HF_AUDIO_GROUP_TAG)) {
1955+
const hidden = groupEl.hasAttribute("data-hidden");
1956+
if (groupHiddenLast.get(groupEl) === hidden) continue;
1957+
groupHiddenLast.set(groupEl, hidden);
1958+
if (groupEl.id) webAudio.setGroupMuted(groupEl.id, hidden);
1959+
}
1960+
};
1961+
19321962
const syncTimedElementVisibility = (
19331963
currentTime: number,
19341964
visibilityNodes: Element[] = Array.from(document.querySelectorAll("[data-start]")),
@@ -1993,6 +2023,7 @@ export function initSandboxRuntimeModular(): void {
19932023
scheduleWebAudioForActiveClips();
19942024
}
19952025
hiddenAudioDirty = false;
2026+
syncAudioGroupMute();
19962027
};
19972028

19982029
const syncMediaForCurrentState = () => {
@@ -2053,6 +2084,7 @@ export function initSandboxRuntimeModular(): void {
20532084
webAudio.setElementVolume(el, authorVolume),
20542085
isWebAudioOwned: (el) => webAudio.ownsElement(el),
20552086
isWebAudioRouted: (el) => webAudio.routesElement(el),
2087+
isAudibleUnderSolo: (el) => isAudibleUnderSolo(soloedIds, el.id, audioGroupOf(el)),
20562088
onAutoplayBlocked: () => {
20572089
if (state.mediaAutoplayBlockedPosted) return;
20582090
state.mediaAutoplayBlockedPosted = true;

‎packages/core/src/runtime/media.ts‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -223,6 +223,11 @@ export function syncRuntimeMedia(params: {
223223
/** Native media routed through WebAudio keeps its upstream element volume at
224224
* unity; do not mistake that transport write for an authored volume edit. */
225225
isWebAudioRouted?: (el: HTMLMediaElement) => boolean;
226+
/** "Hear only this" gate for the HTMLMedia fallback path (video / any audio
227+
* not owned by the Web Audio transport, which applies its own dedicated
228+
* solo gain instead — see `WebAudioTransport.setSolo`). Absent when solo
229+
* isn't wired up at all, which reads as "always audible". */
230+
isAudibleUnderSolo?: (el: HTMLMediaElement) => boolean;
226231
forceSync?: boolean;
227232
}): void {
228233
const forceMuteAll = !!(params.outputMuted || params.userMuted);
@@ -332,7 +337,11 @@ export function syncRuntimeMedia(params: {
332337
// A data-hidden ancestor is silent in the export (audioMixer.ts drops
333338
// it); preview must match. Folded into the per-tick volume, not
334339
// el.muted (RULES trap: el.muted is the transport's ownership flag).
335-
const effectiveVolume = el.closest("[data-hidden]") ? 0 : clampVolume(authorVolume * userVol);
340+
// Solo rides the same fold for the same reason — never el.muted, and
341+
// never touching any attribute (it is session-only, unlike hidden).
342+
const silencedBySolo = params.isAudibleUnderSolo ? !params.isAudibleUnderSolo(el) : false;
343+
const effectiveVolume =
344+
el.closest("[data-hidden]") || silencedBySolo ? 0 : clampVolume(authorVolume * userVol);
336345
el.volume = effectiveVolume;
337346
lastRuntimeAppliedVolume.set(el, effectiveVolume);
338347
params.onElementVolume?.(el, effectiveVolume, authorVolume);

0 commit comments

Comments
 (0)