feat(soundboard): shared room/space packs (like emoji/stickers), grid picker, management

Soundboard v2 — a near-parallel of the custom-emoji image-pack system for
in-call audio clips.

- Data model: 3-tier packs mirroring MSC2545 — room/space pack (state event
  io.lotus.soundboard, inherited by child rooms via parent-space aggregation),
  global refs (io.lotus.soundboard_rooms), and the personal pack
  (io.lotus.soundboard account data; the v1 flat-list content is migrated to the
  pack shape on read). New plugins/soundboard/ (readers, SoundboardPack, utils) +
  hooks/useSoundboardPacks (useRelevantSoundboardPacks = user U global U room,
  deduped). Unit-tested (migration + slug).
- Management: reusable SoundboardPackEditor (name + emoji + per-clip volume +
  delete + upload + batched save), power-level-gated for room packs like emoji
  packs; a Soundboard page wired into Room + Space settings.
- In-call: CallSoundboard rewritten as a Discord-style grid grouped by pack
  (emoji + name tiles), sourcing room+parent-space U personal clips; a Manage
  toggle embeds the editors; per-clip volume x master volume on playback.
- Spam guard: host gates on a playing key (fork enforces one clip at a time).
- Control bar: Mute-Screenshare moved next to the Screenshare button.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/app/features/call/CallControls.tsx

@@ -351,10 +351,6 @@ export function CallControls({ callEmbed }: CallControlsProps) {
           <Box shrink="No" alignItems="Inherit" justifyContent="Inherit" gap="200">
             <MicrophoneButton enabled={microphone} onToggle={handleMicrophoneToggle} />
             <SoundButton enabled={sound} onToggle={() => callEmbed.control.toggleSound()} />
-            <ScreenshareAudioButton
-              muted={screenshareAudioMuted}
-              onToggle={() => callEmbed.control.toggleScreenshareAudio()}
-            />
           </Box>
           {!compact && showVideoGroup && <ControlDivider />}
           {showVideoGroup && (
@@ -363,12 +359,20 @@ export function CallControls({ callEmbed }: CallControlsProps) {
                   user can stop it; once stopped it hides and can't be restarted. */}
               {showCamera && <VideoButton enabled={video} onToggle={handleVideoToggle} />}
               {showScreenshare && (
-                <ScreenShareButton
-                  enabled={screenshare}
-                  onToggle={() =>
-                    screenshare ? callEmbed.control.toggleScreenshare() : setShareConfirm(true)
-                  }
-                />
+                <>
+                  <ScreenShareButton
+                    enabled={screenshare}
+                    onToggle={() =>
+                      screenshare ? callEmbed.control.toggleScreenshare() : setShareConfirm(true)
+                    }
+                  />
+                  {/* Mute-screenshare-audio sits directly next to the screenshare
+                      control since they're the same concern. */}
+                  <ScreenshareAudioButton
+                    muted={screenshareAudioMuted}
+                    onToggle={() => callEmbed.control.toggleScreenshareAudio()}
+                  />
+                </>
               )}
               {!!document.fullscreenEnabled && (
                 <FullscreenButton isFullscreen={isFullscreen} onToggle={handleFullscreen} />

src/app/features/call/CallSoundboard.tsx

@@ -1,220 +1,254 @@
-import React, { MouseEventHandler, useCallback, useRef, useState } from 'react';
+import React, { MouseEventHandler, useCallback, useMemo, useState } from 'react';
 import {
   Box,
-  Chip,
   Icon,
   IconButton,
   Icons,
   Menu,
   PopOut,
   RectCords,
+  Scroll,
   Spinner,
+  Switch,
   Text,
   Tooltip,
   TooltipProvider,
   color,
   config,
+  toRem,
 } from 'folds';
 import FocusTrap from 'focus-trap-react';
+import { useAtomValue } from 'jotai';
 import { CallEmbed } from '../../plugins/call';
 import { useMatrixClient } from '../../hooks/useMatrixClient';
-import { useSoundboard } from '../../hooks/useSoundboard';
 import { useSetting } from '../../state/hooks/settings';
 import { settingsAtom } from '../../state/settings';
+import { roomToParentsAtom } from '../../state/room/roomToParents';
+import { useImagePackRooms } from '../../hooks/useImagePackRooms';
+import { useRelevantSoundboardPacks } from '../../hooks/useSoundboardPacks';
+import { SoundboardClipReader } from '../../plugins/soundboard';
+import { UserSoundboardPack, RoomSoundboardPack } from '../../components/soundboard-pack-view';
 import { stopPropagation } from '../../utils/keyboard';
-import {
-  SOUNDBOARD_ACCEPT,
-  SOUNDBOARD_MAX_CLIPS,
-  playClipLocally,
-  resolveClipObjectUrl,
-} from '../../utils/soundboardClips';
+import { playClipLocally, resolveClipObjectUrl } from '../../utils/soundboardClips';
 
 type CallSoundboardProps = {
   callEmbed: CallEmbed;
 };
 
+type FlatClip = {
+  key: string; // packId|shortcode
+  packId: string;
+  packName: string;
+  clip: SoundboardClipReader;
+};
+
 /**
- * [P5-15] In-call soundboard: trigger user-uploaded clips into the call. Each
- * clip is published to peers as a separate track by the EC fork
- * (`io.lotus.inject_audio`) and also played locally for the presser's feedback.
- * Clips are uploadable/managed here and synced across devices via the
- * `io.lotus.soundboard` account data (like custom emoji/sticker packs).
+ * [P5-15 v2] In-call soundboard. Clips come from the aggregated soundboard packs
+ * relevant to the call room (the room + parent spaces ∪ the user's personal
+ * pack), just like custom emoji. Playing a clip publishes it into the call via
+ * the EC fork (`io.lotus.inject_audio`, max one at a time) and plays it locally.
+ * A management toggle reveals the pack editors (personal + this room, if
+ * permitted). Space-wide packs are managed from Space settings.
  */
 export function CallSoundboard({ callEmbed }: CallSoundboardProps) {
   const mx = useMatrixClient();
-  const { clips, addClip, removeClip } = useSoundboard();
+  const { room } = callEmbed;
+  const roomToParents = useAtomValue(roomToParentsAtom);
+  const packRooms = useImagePackRooms(room.roomId, roomToParents);
+  const packs = useRelevantSoundboardPacks(packRooms);
   const [soundboardVolume] = useSetting(settingsAtom, 'soundboardVolume');
+  const master = Math.max(0, Math.min(1, soundboardVolume / 100));
 
   const [cords, setCords] = useState<RectCords>();
-  const [busyId, setBusyId] = useState<string>();
-  const [uploading, setUploading] = useState(false);
+  const [manage, setManage] = useState(false);
+  const [playingKey, setPlayingKey] = useState<string>(); // host-side spam guard
   const [error, setError] = useState<string>();
-  const fileInputRef = useRef<HTMLInputElement>(null);
 
-  const volume = Math.max(0, Math.min(1, soundboardVolume / 100));
+  const groups = useMemo(
+    () =>
+      packs
+        .map((pack) => ({
+          id: pack.id,
+          name: pack.meta.name ?? 'Soundboard',
+          clips: pack.getClips(),
+        }))
+        .filter((g) => g.clips.length > 0),
+    [packs],
+  );
 
   const handleOpen: MouseEventHandler<HTMLButtonElement> = (evt) => {
     setError(undefined);
     setCords(evt.currentTarget.getBoundingClientRect());
   };
 
-  const handlePlay = useCallback(
-    async (id: string, mxc: string) => {
-      setBusyId(id);
+  const play = useCallback(
+    async (flat: FlatClip) => {
+      if (playingKey) return; // one at a time (fork also enforces this)
+      setPlayingKey(flat.key);
       setError(undefined);
+      const done = () => setPlayingKey((k) => (k === flat.key ? undefined : k));
       try {
-        const objectUrl = await resolveClipObjectUrl(mx, mxc);
-        callEmbed.control.injectAudio(objectUrl, volume);
-        playClipLocally(objectUrl, volume);
+        const url = await resolveClipObjectUrl(mx, flat.clip.url);
+        const vol = (flat.clip.volume / 100) * master;
+        callEmbed.control.injectAudio(url, vol);
+        const audio = playClipLocally(url, vol);
+        if (audio) {
+          audio.addEventListener('ended', done, { once: true });
+          audio.addEventListener('error', done, { once: true });
+        } else {
+          done();
+        }
+        // Safety: clear the guard even if the audio never signals end.
+        window.setTimeout(done, 30_000);
       } catch {
         setError('Could not play that clip.');
-      } finally {
-        setBusyId(undefined);
+        done();
       }
     },
-    [mx, callEmbed, volume],
-  );
-
-  const handleFile = useCallback(
-    async (file: File | undefined) => {
-      if (!file) return;
-      setUploading(true);
-      setError(undefined);
-      try {
-        await addClip(file);
-      } catch (e) {
-        setError(e instanceof Error ? e.message : 'Upload failed.');
-      } finally {
-        setUploading(false);
-      }
-    },
-    [addClip],
+    [mx, callEmbed, master, playingKey],
   );
 
   return (
-    <>
-      <input
-        ref={fileInputRef}
-        type="file"
-        accept={SOUNDBOARD_ACCEPT}
-        hidden
-        onChange={(e) => {
-          handleFile(e.target.files?.[0]);
-          e.target.value = '';
-        }}
-      />
-      <PopOut
-        anchor={cords}
-        position="Top"
-        align="Center"
-        content={
-          <FocusTrap
-            focusTrapOptions={{
-              initialFocus: false,
-              onDeactivate: () => setCords(undefined),
-              clickOutsideDeactivates: true,
-              escapeDeactivates: stopPropagation,
-            }}
-          >
-            <Menu style={{ maxWidth: '320px' }}>
-              <Box direction="Column" gap="200" style={{ padding: config.space.S200 }}>
-                <Box alignItems="Center" justifyContent="SpaceBetween" gap="200">
-                  <Text size="L400">Soundboard</Text>
-                  <Chip
-                    variant="Secondary"
-                    radii="Pill"
-                    disabled={uploading || clips.length >= SOUNDBOARD_MAX_CLIPS}
-                    onClick={() => fileInputRef.current?.click()}
-                    before={
-                      uploading ? <Spinner size="100" /> : <Icon size="100" src={Icons.Plus} />
-                    }
-                  >
-                    <Text size="B300">Upload</Text>
-                  </Chip>
-                </Box>
-
-                {clips.length === 0 ? (
+    <PopOut
+      anchor={cords}
+      position="Top"
+      align="Center"
+      content={
+        <FocusTrap
+          focusTrapOptions={{
+            initialFocus: false,
+            onDeactivate: () => setCords(undefined),
+            clickOutsideDeactivates: true,
+            escapeDeactivates: stopPropagation,
+          }}
+        >
+          <Menu style={{ maxWidth: manage ? toRem(420) : toRem(340), maxHeight: '70vh' }}>
+            <Box direction="Column" style={{ maxHeight: '70vh' }}>
+              <Box
+                shrink="No"
+                alignItems="Center"
+                justifyContent="SpaceBetween"
+                gap="200"
+                style={{
+                  padding: config.space.S200,
+                  borderBottom: `${config.borderWidth.B300} solid ${color.Surface.ContainerLine}`,
+                }}
+              >
+                <Text size="L400">Soundboard</Text>
+                <Box as="label" alignItems="Center" gap="200" style={{ cursor: 'pointer' }}>
                   <Text size="T200" priority="300">
-                    No clips yet. Upload a short audio clip (max 1 MB) to play it into the call.
-                    Clips sync across your devices.
+                    Manage
                   </Text>
-                ) : (
-                  <Box wrap="Wrap" gap="200">
-                    {clips.map((clip) => (
-                      <Box
-                        key={clip.id}
-                        direction="Column"
-                        gap="100"
-                        style={{ position: 'relative' }}
-                      >
-                        <Chip
-                          variant="SurfaceVariant"
-                          radii="300"
-                          disabled={busyId === clip.id}
-                          onClick={() => handlePlay(clip.id, clip.url)}
-                          before={
-                            busyId === clip.id ? (
-                              <Spinner size="100" />
-                            ) : (
-                              <Icon size="100" src={Icons.Play} />
-                            )
-                          }
-                          after={
-                            <Icon
-                              size="50"
-                              src={Icons.Cross}
-                              style={{ cursor: 'pointer' }}
-                              onClick={(e: React.MouseEvent) => {
-                                e.stopPropagation();
-                                removeClip(clip.id);
-                              }}
-                            />
-                          }
-                        >
-                          <Text size="B300" truncate style={{ maxWidth: '120px' }}>
-                            {clip.name}
-                          </Text>
-                        </Chip>
-                      </Box>
-                    ))}
-                  </Box>
-                )}
-
-                {error && (
-                  <Text size="T200" style={{ color: color.Critical.Main }}>
-                    {error}
-                  </Text>
-                )}
+                  <Switch variant="Primary" value={manage} onChange={setManage} />
+                </Box>
               </Box>
-            </Menu>
-          </FocusTrap>
+
+              <Scroll size="300" hideTrack visibility="Hover">
+                <Box direction="Column" gap="300" style={{ padding: config.space.S200 }}>
+                  {manage ? (
+                    <>
+                      <RoomSoundboardPack room={room} stateKey="" />
+                      <UserSoundboardPack />
+                    </>
+                  ) : (
+                    <>
+                      {groups.length === 0 && (
+                        <Text size="T200" priority="300">
+                          No soundboard clips here yet. Turn on <b>Manage</b> to upload some, or add
+                          a pack in Space settings.
+                        </Text>
+                      )}
+                      {groups.map((g) => (
+                        <Box key={g.id} direction="Column" gap="100">
+                          <Text size="L400">{g.name}</Text>
+                          <Box wrap="Wrap" gap="200">
+                            {g.clips.map((clip) => {
+                              const key = `${g.id}|${clip.shortcode}`;
+                              const flat: FlatClip = {
+                                key,
+                                packId: g.id,
+                                packName: g.name,
+                                clip,
+                              };
+                              return (
+                                <Box
+                                  key={key}
+                                  as="button"
+                                  direction="Column"
+                                  alignItems="Center"
+                                  justifyContent="Center"
+                                  gap="100"
+                                  disabled={!!playingKey}
+                                  onClick={() => play(flat)}
+                                  aria-label={`Play ${clip.name}`}
+                                  style={{
+                                    width: toRem(76),
+                                    height: toRem(76),
+                                    padding: config.space.S100,
+                                    borderRadius: config.radii.R400,
+                                    border: `${config.borderWidth.B300} solid ${color.Surface.ContainerLine}`,
+                                    background:
+                                      playingKey === key
+                                        ? color.Primary.Container
+                                        : color.SurfaceVariant.Container,
+                                    cursor: playingKey ? 'default' : 'pointer',
+                                    opacity: playingKey && playingKey !== key ? 0.5 : 1,
+                                  }}
+                                >
+                                  <Text size="H4">
+                                    {playingKey === key ? (
+                                      <Spinner size="200" />
+                                    ) : (
+                                      clip.emoji || '🔊'
+                                    )}
+                                  </Text>
+                                  <Text size="T200" truncate style={{ maxWidth: '100%' }}>
+                                    {clip.name}
+                                  </Text>
+                                </Box>
+                              );
+                            })}
+                          </Box>
+                        </Box>
+                      ))}
+                    </>
+                  )}
+                  {error && (
+                    <Text size="T200" style={{ color: color.Critical.Main }}>
+                      {error}
+                    </Text>
+                  )}
+                </Box>
+              </Scroll>
+            </Box>
+          </Menu>
+        </FocusTrap>
+      }
+    >
+      <TooltipProvider
+        tooltip={
+          <Tooltip>
+            <Text>Soundboard</Text>
+          </Tooltip>
         }
       >
-        <TooltipProvider
-          tooltip={
-            <Tooltip>
-              <Text>Soundboard</Text>
-            </Tooltip>
-          }
-        >
-          {(triggerRef) => (
-            <IconButton
-              ref={triggerRef}
-              variant="Surface"
-              fill="Soft"
-              radii="400"
-              size="400"
-              onClick={handleOpen}
-              outlined
-              aria-label="Soundboard"
-              aria-expanded={!!cords}
-              aria-haspopup="menu"
-            >
-              <Icon size="400" src={Icons.BellRing} />
-            </IconButton>
-          )}
-        </TooltipProvider>
-      </PopOut>
-    </>
+        {(triggerRef) => (
+          <IconButton
+            ref={triggerRef}
+            variant="Surface"
+            fill="Soft"
+            radii="400"
+            size="400"
+            onClick={handleOpen}
+            outlined
+            aria-label="Soundboard"
+            aria-expanded={!!cords}
+            aria-haspopup="menu"
+          >
+            <Icon size="400" src={Icons.BellRing} />
+          </IconButton>
+        )}
+      </TooltipProvider>
+    </PopOut>
   );
 }

src/app/features/common-settings/soundboard/Soundboard.tsx

@@ -0,0 +1,61 @@
+import React from 'react';
+import { Box, Icon, IconButton, Icons, Scroll, Text } from 'folds';
+import { Page, PageContent, PageHeader } from '../../../components/page';
+import { useRoom } from '../../../hooks/useRoom';
+import { RoomSoundboardPack, UserSoundboardPack } from '../../../components/soundboard-pack-view';
+
+type SoundboardProps = {
+  requestClose: () => void;
+};
+
+/**
+ * Soundboard management page (Room/Space settings). Mirrors the Emojis &
+ * Stickers page: a shared room/space pack (admin-editable, inherited by child
+ * rooms like emoji packs) plus the user's personal pack. A single default room
+ * pack (state key "") is used per room/space.
+ */
+export function Soundboard({ requestClose }: SoundboardProps) {
+  const room = useRoom();
+
+  return (
+    <Page>
+      <PageHeader outlined={false}>
+        <Box grow="Yes" gap="200">
+          <Box grow="Yes" alignItems="Center" gap="200">
+            <Text as="h2" size="H3" truncate>
+              Soundboard
+            </Text>
+          </Box>
+          <Box shrink="No">
+            <IconButton onClick={requestClose} variant="Surface" aria-label="Close">
+              <Icon src={Icons.Cross} />
+            </IconButton>
+          </Box>
+        </Box>
+      </PageHeader>
+      <Box grow="Yes">
+        <Scroll hideTrack visibility="Hover">
+          <PageContent>
+            <Box direction="Column" gap="700">
+              <Box direction="Column" gap="200">
+                <Text size="L400">This room / space (shared)</Text>
+                <Text size="T200" priority="300">
+                  Clips here are shared with everyone, and inherited by every room under this space
+                  — just like emoji/sticker packs. Only members with permission can edit.
+                </Text>
+                {room && <RoomSoundboardPack room={room} stateKey="" />}
+              </Box>
+              <Box direction="Column" gap="200">
+                <Text size="L400">Personal</Text>
+                <Text size="T200" priority="300">
+                  Your own clips, available in every call and synced across your devices.
+                </Text>
+                <UserSoundboardPack />
+              </Box>
+            </Box>
+          </PageContent>
+        </Scroll>
+      </Box>
+    </Page>
+  );
+}

src/app/features/common-settings/soundboard/index.ts

@@ -0,0 +1 @@
+export * from './Soundboard';

src/app/features/room-settings/RoomSettings.tsx

@@ -13,6 +13,7 @@ import { RoomAvatar, RoomIcon } from '../../components/room-avatar';
 import { General } from './general';
 import { Members } from '../common-settings/members';
 import { EmojisStickers } from '../common-settings/emojis-stickers';
+import { Soundboard } from '../common-settings/soundboard';
 import { Permissions } from './permissions';
 import { RoomSettingsPage } from '../../state/roomSettings';
 import { useRoom } from '../../hooks/useRoom';
@@ -53,6 +54,11 @@ const BASE_MENU_ITEMS: RoomSettingsMenuItem[] = [
     name: 'Emojis & Stickers',
     icon: Icons.Smile,
   },
+  {
+    page: RoomSettingsPage.SoundboardPage,
+    name: 'Soundboard',
+    icon: Icons.Bell,
+  },
   {
     page: RoomSettingsPage.DeveloperToolsPage,
     name: 'Developer Tools',
@@ -226,6 +232,9 @@ export function RoomSettings({ initialPage, requestClose }: RoomSettingsProps) {
       {activePage === RoomSettingsPage.EmojisStickersPage && (
         <EmojisStickers requestClose={handlePageRequestClose} />
       )}
+      {activePage === RoomSettingsPage.SoundboardPage && (
+        <Soundboard requestClose={handlePageRequestClose} />
+      )}
       {activePage === RoomSettingsPage.DeveloperToolsPage && (
         <DeveloperTools requestClose={handlePageRequestClose} />
       )}

src/app/features/space-settings/SpaceSettings.tsx

@@ -13,6 +13,7 @@ import { RoomAvatar, RoomIcon } from '../../components/room-avatar';
 import { SpaceSettingsPage } from '../../state/spaceSettings';
 import { useRoom } from '../../hooks/useRoom';
 import { EmojisStickers } from '../common-settings/emojis-stickers';
+import { Soundboard } from '../common-settings/soundboard';
 import { Members } from '../common-settings/members';
 import { DeveloperTools } from '../common-settings/developer-tools';
 import { General } from './general';
@@ -48,6 +49,11 @@ const BASE_SPACE_MENU_ITEMS: SpaceSettingsMenuItem[] = [
     name: 'Emojis & Stickers',
     icon: Icons.Smile,
   },
+  {
+    page: SpaceSettingsPage.SoundboardPage,
+    name: 'Soundboard',
+    icon: Icons.Bell,
+  },
   {
     page: SpaceSettingsPage.DeveloperToolsPage,
     name: 'Developer Tools',
@@ -190,6 +196,9 @@ export function SpaceSettings({ initialPage, requestClose }: SpaceSettingsProps)
       {activePage === SpaceSettingsPage.EmojisStickersPage && (
         <EmojisStickers requestClose={handlePageRequestClose} />
       )}
+      {activePage === SpaceSettingsPage.SoundboardPage && (
+        <Soundboard requestClose={handlePageRequestClose} />
+      )}
       {activePage === SpaceSettingsPage.DeveloperToolsPage && (
         <DeveloperTools requestClose={handlePageRequestClose} />
       )}