audiocn

Soundboard

Sound pads with hotkeys, modes, volume, stop all and drag-and-drop.

Preparing sounds…

Installation

$ pnpm dlx shadcn@latest add @audiocn/soundboard

What it does

  • Pads play on click or with hotkeys 1–9 anywhere on the page, except while typing in a field. Hotkeys can be turned off.
  • Right-click a pad to change its mode (one shot, toggle, hold, loop), its volume, or remove it.
  • Removing a pad shows an inline Undo action that restores it in its original position. The most recent removal stays undoable until another pad is removed.
  • A master volume and a "Stop all" button.
  • Drop audio files onto the board, or use the Add pad, to add sounds. Each file is held as an object URL, which the board releases once its removal can no longer be undone.
  • Inline status messages announce additions, rejected or duplicate files, removals and stopping playback. There is no global toast provider.

Pass output to route the board into a mixer channel instead of the speakers.

Props

Prop

Type

Files

components/blocks/soundboard/soundboard.tsx
"use client";

import {
  PlusIcon,
  SpeakerHighIcon,
  StopIcon,
  WaveformIcon,
} from "@phosphor-icons/react";
import { useId, useImperativeHandle, useMemo, useRef, useState } from "react";
import type { DragEvent, Ref } from "react";

import { Alert, AlertDescription } from "@/components/ui/alert";
import { Button } from "@/components/ui/button";
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuGroup,
  ContextMenuItem,
  ContextMenuLabel,
  ContextMenuRadioGroup,
  ContextMenuRadioItem,
  ContextMenuSeparator,
  ContextMenuTrigger,
} from "@/components/ui/context-menu";
import {
  Empty,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "@/components/ui/empty";
import { Label } from "@/components/ui/label";
import {
  SoundPad,
  SoundPadGrid,
  SoundPadLabel,
  SoundPadProgress,
  SoundPadShortcut,
} from "@/components/ui/sound-pad";
import type { SoundPadMode } from "@/components/ui/sound-pad";
import { Switch } from "@/components/ui/switch";
import {
  VolumeControl,
  VolumeControlMute,
  VolumeControlSlider,
} from "@/components/ui/volume-control";
import { useGainNode } from "@/hooks/use-gain-node";
import { useSound } from "@/hooks/use-sound";

export interface SoundboardSound {
  id: string;
  label: string;
  src: string | AudioBuffer;
  hotkey?: string;
  mode?: SoundPadMode;
  /** 0..1. Default 1. */
  volume?: number;
  accent?: string;
}

export interface SoundboardProps {
  sounds?: SoundboardSound[];
  defaultSounds?: SoundboardSound[];
  onSoundsChange?: (sounds: SoundboardSound[]) => void;
  /** Route pads into a mixer instead of the speakers. */
  output?: AudioNode | null;
  /** Default 4. */
  columns?: number;
  className?: string;
}

const MODES: { value: SoundPadMode; label: string }[] = [
  { label: "One shot", value: "one-shot" },
  { label: "Toggle", value: "toggle" },
  { label: "Hold", value: "hold" },
  { label: "Loop", value: "loop" },
];

const VOLUMES = [1, 0.75, 0.5, 0.25];

interface PadHandle {
  stop: () => void;
}

interface PadProps {
  ref?: Ref<PadHandle>;
  sound: SoundboardSound;
  bus: AudioNode | null;
  onChange: (sound: SoundboardSound) => void;
  onRemove: () => void;
}

const Pad = ({ ref, sound, bus, onChange, onRemove }: PadProps) => {
  const mode = sound.mode ?? "one-shot";
  const player = useSound(sound.src, {
    destination: bus,
    interrupt: mode !== "one-shot",
    loop: mode === "loop",
    volume: sound.volume ?? 1,
  });
  const { stop } = player;
  useImperativeHandle(ref, () => ({ stop }), [stop]);

  return (
    <ContextMenu>
      <ContextMenuTrigger
        render={
          <SoundPad
            accent={sound.accent}
            hotkey={sound.hotkey}
            loading={!player.isLoaded}
            mode={mode}
            onStop={() => player.stop()}
            onTrigger={() => player.play()}
            playing={player.isPlaying}
          />
        }
      >
        <SoundPadLabel>{sound.label}</SoundPadLabel>
        <SoundPadShortcut />
        <SoundPadProgress source={player.progress} />
      </ContextMenuTrigger>
      <ContextMenuContent className="w-48">
        <ContextMenuGroup>
          <ContextMenuLabel>Mode</ContextMenuLabel>
          <ContextMenuRadioGroup
            onValueChange={(value) =>
              onChange({ ...sound, mode: value as SoundPadMode })
            }
            value={mode}
          >
            {MODES.map((option) => (
              <ContextMenuRadioItem key={option.value} value={option.value}>
                {option.label}
              </ContextMenuRadioItem>
            ))}
          </ContextMenuRadioGroup>
        </ContextMenuGroup>
        <ContextMenuSeparator />
        <ContextMenuGroup>
          <ContextMenuLabel>Volume</ContextMenuLabel>
          <ContextMenuRadioGroup
            onValueChange={(value) =>
              onChange({ ...sound, volume: Number(value) })
            }
            value={String(sound.volume ?? 1)}
          >
            {VOLUMES.map((volume) => (
              <ContextMenuRadioItem key={volume} value={String(volume)}>
                {Math.round(volume * 100)}%
              </ContextMenuRadioItem>
            ))}
          </ContextMenuRadioGroup>
        </ContextMenuGroup>
        <ContextMenuSeparator />
        <ContextMenuGroup>
          <ContextMenuItem onClick={onRemove} variant="destructive">
            Remove
          </ContextMenuItem>
        </ContextMenuGroup>
      </ContextMenuContent>
    </ContextMenu>
  );
};

const AUDIO_FILE = /^audio\//u;
const FILE_EXTENSION = /\.[^.]+$/u;
const NO_SOUNDS: SoundboardSound[] = [];

const fileToSound = (
  file: File,
  index: number
): SoundboardSound & { src: string } => ({
  hotkey: index < 9 ? String(index + 1) : undefined,
  id: `${file.name}-${file.lastModified}`,
  label: file.name.replace(FILE_EXTENSION, ""),
  src: URL.createObjectURL(file),
});

export const Soundboard = ({
  sounds: soundsProp,
  defaultSounds = NO_SOUNDS,
  onSoundsChange,
  output,
  columns = 4,
  className,
}: SoundboardProps) => {
  const [soundsState, setSoundsState] = useState(defaultSounds);
  const sounds = soundsProp ?? soundsState;
  const [volume, setVolume] = useState(1);
  const [muted, setMuted] = useState(false);
  const bus = useGainNode({
    destination: output,
    gain: muted ? 0 : volume ** 2,
  });
  const [hotkeys, setHotkeys] = useState(true);
  const [dragging, setDragging] = useState(false);
  const [feedback, setFeedback] = useState("");
  const [removedSound, setRemovedSound] = useState<{
    sound: SoundboardSound;
    index: number;
  } | null>(null);
  const hotkeysId = useId();
  const fileInputRef = useRef<HTMLInputElement>(null);
  const padsRef = useRef(new Map<string, PadHandle>());
  // Object URLs this board created for dropped files.
  const objectUrlsRef = useRef(new Set<string>());

  const update = (next: SoundboardSound[]) => {
    setSoundsState(next);
    onSoundsChange?.(next);
  };

  const addFiles = (files: FileList | null) => {
    if (!files || files.length === 0) {
      return;
    }
    const existingIds = new Set(sounds.map((sound) => sound.id));
    const added = [...files]
      .filter((file) => AUDIO_FILE.test(file.type))
      .filter((file) => {
        const id = `${file.name}-${file.lastModified}`;
        if (existingIds.has(id)) {
          return false;
        }
        existingIds.add(id);
        return true;
      })
      .map((file, index) => fileToSound(file, sounds.length + index));
    if (added.length === 0) {
      setFeedback(
        "No new sounds added. Choose audio files that aren't already on the board."
      );
      return;
    }
    for (const sound of added) {
      objectUrlsRef.current.add(sound.src);
    }
    update([...sounds, ...added]);
    setFeedback(
      `Added ${added.length} ${added.length === 1 ? "sound" : "sounds"}.`
    );
  };

  // Frees a dropped file once no pad uses it and its removal can't be undone.
  const releaseObjectUrl = ({ src }: SoundboardSound) => {
    const inUse = sounds.some((item) => item.src === src);
    if (
      typeof src === "string" &&
      !inUse &&
      objectUrlsRef.current.delete(src)
    ) {
      URL.revokeObjectURL(src);
    }
  };

  const removeSound = (sound: SoundboardSound) => {
    if (removedSound) {
      releaseObjectUrl(removedSound.sound);
    }
    setRemovedSound({
      index: sounds.findIndex((item) => item.id === sound.id),
      sound,
    });
    update(sounds.filter((item) => item.id !== sound.id));
    setFeedback(`Removed ${sound.label}. You can undo this removal.`);
  };

  const undoRemoval = () => {
    if (!removedSound) {
      return;
    }
    const { sound, index } = removedSound;
    if (!sounds.some((item) => item.id === sound.id)) {
      update([...sounds.slice(0, index), sound, ...sounds.slice(index)]);
    }
    setRemovedSound(null);
    setFeedback(`Restored ${sound.label}.`);
  };

  const dropProps = useMemo(
    () => ({
      onDragLeave: () => setDragging(false),
      onDragOver: (event: DragEvent<HTMLDivElement>) => {
        event.preventDefault();
        setDragging(true);
      },
    }),
    []
  );

  return (
    <div
      className={className}
      data-dragging={dragging ? "" : undefined}
      data-slot="soundboard"
      {...dropProps}
      onDrop={(event) => {
        event.preventDefault();
        setDragging(false);
        addFiles(event.dataTransfer.files);
      }}
    >
      <div className="mb-3 flex flex-wrap items-center gap-3">
        <h3 className="font-heading mr-auto font-medium">Soundboard</h3>
        <div className="flex items-center gap-2">
          <Switch
            checked={hotkeys}
            id={hotkeysId}
            onCheckedChange={setHotkeys}
            size="sm"
          />
          <Label htmlFor={hotkeysId}>Hotkeys</Label>
        </div>
        <VolumeControl
          className="w-36"
          muted={muted}
          onMutedChange={setMuted}
          onValueChange={setVolume}
          value={volume}
        >
          <VolumeControlMute>
            <SpeakerHighIcon />
          </VolumeControlMute>
          <VolumeControlSlider />
        </VolumeControl>
        <Button
          onClick={() => {
            for (const pad of padsRef.current.values()) {
              pad.stop();
            }
            setFeedback("Stopped all sounds.");
          }}
          size="sm"
          variant="outline"
        >
          <StopIcon data-icon="inline-start" />
          Stop all
        </Button>
      </div>
      {feedback && (
        <output aria-live="polite" className="mb-3 block">
          <Alert role="none">
            <AlertDescription>{feedback}</AlertDescription>
            {removedSound && (
              <div className="mt-2">
                <Button onClick={undoRemoval} size="sm" variant="outline">
                  Undo removal
                </Button>
              </div>
            )}
          </Alert>
        </output>
      )}
      {sounds.length === 0 ? (
        <div className="rounded-xl border border-dashed">
          <Empty>
            <EmptyHeader>
              <EmptyMedia variant="icon">
                <WaveformIcon />
              </EmptyMedia>
              <EmptyTitle>No sounds yet</EmptyTitle>
              <EmptyDescription>
                Drop audio files here, or add them from your computer.
              </EmptyDescription>
            </EmptyHeader>
            <Button
              onClick={() => fileInputRef.current?.click()}
              size="sm"
              variant="outline"
            >
              <PlusIcon data-icon="inline-start" />
              Add sounds
            </Button>
          </Empty>
        </div>
      ) : (
        <SoundPadGrid
          className="data-dragging:ring-2"
          columns={columns}
          hotkeyScope="global"
          hotkeys={hotkeys}
        >
          {sounds.map((sound) => (
            <Pad
              bus={bus}
              key={sound.id}
              onChange={(next) =>
                update(
                  sounds.map((item) => (item.id === sound.id ? next : item))
                )
              }
              onRemove={() => removeSound(sound)}
              ref={(pad) => {
                if (!pad) {
                  return;
                }
                padsRef.current.set(sound.id, pad);
                return () => {
                  padsRef.current.delete(sound.id);
                };
              }}
              sound={sound}
            />
          ))}
          <SoundPad
            aria-label="Add sounds"
            className="text-muted-foreground items-center justify-center border-dashed"
            onTrigger={() => fileInputRef.current?.click()}
            variant="outline"
          >
            <PlusIcon className="size-5" />
            <SoundPadLabel>Add</SoundPadLabel>
          </SoundPad>
        </SoundPadGrid>
      )}
      <input
        accept="audio/*"
        aria-label="Add audio files"
        className="hidden"
        multiple
        onChange={(event) => {
          addFiles(event.target.files);
          event.target.value = "";
        }}
        ref={fileInputRef}
        type="file"
      />
    </div>
  );
};