@adatechnology/conversations-ui 0.9.0 → 0.10.0

package/src/participant/ParticipantAudioTranscription.tsx

@@ -0,0 +1,90 @@
+import { useState } from 'react'
+
+import type { ParticipantTranscription } from '@adatechnology/conversation-contracts'
+
+import type { ParticipantAudioLabels } from './participantAudioLabels'
+import { useTranscriptionOverflow } from './useTranscriptionOverflow'
+import { useTranscriptionReadyAnnouncement } from './useTranscriptionReadyAnnouncement'
+
+const MILLISECONDS_PER_MINUTE = 60_000
+
+export type ParticipantAudioTranscriptionProps = {
+  readonly attachmentId: string
+  readonly transcription: ParticipantTranscription | undefined
+  readonly labels: ParticipantAudioLabels
+}
+
+type ReadyTranscriptionBlockProps = {
+  readonly transcription: Extract<ParticipantTranscription, { status: 'ready' }>
+  readonly labels: ParticipantAudioLabels
+}
+
+function resolveTooLongMinutes(transcription: ParticipantTranscription | undefined): number | undefined {
+  if (transcription?.status !== 'failed' || transcription.reason !== 'too_long') return undefined
+  if (typeof transcription.maxDurationMs !== 'number') return undefined
+  const minutes = Math.floor(transcription.maxDurationMs / MILLISECONDS_PER_MINUTE)
+  return minutes >= 1 ? minutes : undefined
+}
+
+// A host that skipped validation can hand us a ready block without a string text: treat it as absent.
+function dropUnusableTranscription(transcription: ParticipantTranscription | undefined): ParticipantTranscription | undefined {
+  if (transcription?.status === 'ready' && typeof transcription.text !== 'string') return undefined
+  return transcription
+}
+
+export function ParticipantAudioTranscription({ attachmentId, transcription: received, labels }: ParticipantAudioTranscriptionProps) {
+  const transcription = dropUnusableTranscription(received)
+  useTranscriptionReadyAnnouncement({
+    attachmentId,
+    status: transcription?.status,
+    text: labels.transcriptionReady,
+  })
+  if (transcription?.status === 'pending') {
+    return <p className="cv-p-transcription cv-p-transcription--pending">{labels.transcribing}</p>
+  }
+  if (transcription?.status === 'ready') return <ReadyTranscriptionBlock transcription={transcription} labels={labels} />
+  const minutes = resolveTooLongMinutes(transcription)
+  if (minutes === undefined) return null
+  return (
+    <p className="cv-p-transcription cv-p-transcription--too-long">
+      {labels.transcriptionTooLong.replace('{minutes}', String(minutes))}
+    </p>
+  )
+}
+
+function ReadyTranscriptionBlock({ transcription, labels }: ReadyTranscriptionBlockProps) {
+  const [isExpanded, setIsExpanded] = useState(false)
+  const { textRef, isOverflowing } = useTranscriptionOverflow(transcription.text, isExpanded)
+  const hasText = transcription.text !== ''
+  const showsToggle = hasText && (isOverflowing || isExpanded)
+
+  return (
+    <div className="cv-p-transcription">
+      <p className="cv-p-transcription__notice">
+        {labels.machineTranscription}
+      </p>
+      {hasText ? (
+        <p
+          ref={textRef}
+          className="cv-p-transcription__text"
+          lang={transcription.language}
+          data-expanded={isExpanded ? 'true' : undefined}
+        >
+          {transcription.text}
+        </p>
+      ) : (
+        <p className="cv-p-transcription__empty">{labels.emptyTranscription}</p>
+      )}
+      {showsToggle ? (
+        <button
+          type="button"
+          className="cv-p-transcription__toggle"
+          aria-expanded={isExpanded}
+          onClick={() => setIsExpanded((current) => !current)}
+        >
+          {isExpanded ? labels.collapseTranscription : labels.showFullTranscription}
+        </button>
+      ) : null}
+    </div>
+  )
+}

package/src/participant/ParticipantComposer.tsx

@@ -4,7 +4,10 @@ import { channelCapabilityFor } from '../channelCapability'
 import type { ConversationChannel } from '../conversationChannel'
 import { formatFileSize } from '../lib/format'
 import type { QuickReply } from '../quickReplies/quickReply.types'
+import { ComposerAudioRow } from './ParticipantComposerAudio'
 import { AttachControl, MessageField, SendButton } from './ParticipantComposerControls'
+import type { ParticipantAudioRecordingOptions } from './participantAudio.types'
+import { resolveComposerAudio } from './participantAudioSupport'
 import { maxBytesForChannel, reduceFilesSelection, type ParticipantFileRejection } from './participantFileValidation'
 import type { ParticipantConversationsLabels } from './participantLabels'
 import { applyQuickReply } from './participantQuickReply'
@@ -26,6 +29,10 @@ export type ParticipantComposerProps = {
   readonly acceptedTypes?: readonly string[]
   /** Tapping a chip fills the text; it never sends. Absent or empty means no strip. */
   readonly quickReplies?: readonly QuickReply[]
+  /** Present turns the microphone on (an empty field, a browser and a channel that record); `{}` takes the defaults. */
+  readonly audioRecording?: ParticipantAudioRecordingOptions
+  /** Receives the recorded audio, already checked; sent as a message of its own, never through the draft. */
+  readonly onSendAudio?: (file: File) => void
 }
 
 type QuickReplyStripProps = {
@@ -95,8 +102,49 @@ function useFileSelection(props: ParticipantComposerProps) {
   return { rejection, handleFilesChosen, handleRemoveFile }
 }
 
+type ComposerRowProps = {
+  readonly composer: ParticipantComposerProps
+  readonly canSend: boolean
+  readonly onFilesChosen: (event: ChangeEvent<HTMLInputElement>) => void
+}
+
+function ComposerRow({ composer, canSend, onFilesChosen }: ComposerRowProps) {
+  const { value, onChange, files, labels, channel = 'app', disabled = false } = composer
+  const attach = channelCapabilityFor(channel).attachments.accepted ? (
+    <AttachControl labels={labels} disabled={disabled} acceptedTypes={composer.acceptedTypes} onChosen={onFilesChosen} />
+  ) : null
+  const field = (
+    <MessageField
+      value={value}
+      label={labels.messageInputLabel}
+      placeholder={labels.messageInputPlaceholder}
+      disabled={disabled}
+      maxLength={composer.maxLength}
+      onChange={onChange}
+    />
+  )
+  const sendButton = <SendButton label={labels.send} disabled={!canSend} />
+  const audio = resolveComposerAudio(composer)
+  if (!audio) {
+    return (
+      <div className="cv-p-composer__row">
+        {attach}
+        {field}
+        {sendButton}
+      </div>
+    )
+  }
+  const isDraftEmpty = value.trim().length === 0 && files.length === 0
+  return (
+    <ComposerAudioRow settings={audio} labels={labels} disabled={disabled} isDraftEmpty={isDraftEmpty} sendButton={sendButton}>
+      {attach}
+      {field}
+    </ComposerAudioRow>
+  )
+}
+
 export function ParticipantComposer(props: ParticipantComposerProps) {
-  const { value, onChange, files, onSend, labels, channel = 'app', disabled = false, isSending = false } = props
+  const { value, onChange, files, onSend, labels, disabled = false, isSending = false } = props
   const { rejection, handleFilesChosen, handleRemoveFile } = useFileSelection(props)
   const canSend = !disabled && !isSending && (value.trim().length > 0 || files.length > 0)
 
@@ -116,20 +164,7 @@ export function ParticipantComposer(props: ParticipantComposerProps) {
           {rejectionText(rejection, labels)}
         </p>
       ) : null}
-      <div className="cv-p-composer__row">
-        {channelCapabilityFor(channel).attachments.accepted ? (
-          <AttachControl labels={labels} disabled={disabled} acceptedTypes={props.acceptedTypes} onChosen={handleFilesChosen} />
-        ) : null}
-        <MessageField
-          value={value}
-          label={labels.messageInputLabel}
-          placeholder={labels.messageInputPlaceholder}
-          disabled={disabled}
-          maxLength={props.maxLength}
-          onChange={onChange}
-        />
-        <SendButton label={labels.send} disabled={!canSend} />
-      </div>
+      <ComposerRow composer={props} canSend={canSend} onFilesChosen={handleFilesChosen} />
     </form>
   )
 }

package/src/participant/ParticipantComposerAudio.tsx

@@ -0,0 +1,95 @@
+import { useEffect, useRef, type ReactNode, type RefObject } from 'react'
+
+import { maxBytesForChannel } from './participantFileValidation'
+import { resolveParticipantAudioLabels } from './participantAudioLabels'
+import type { ComposerAudioSettings } from './participantAudioSupport'
+import type { RecorderStatus } from './participantAudioRecorderState'
+import type { ParticipantConversationsLabels } from './participantLabels'
+import { ParticipantAudioRecorderView, resolveRecorderErrorMessage } from './ParticipantAudioRecorderView'
+import { RecordAudioButton, RecorderError } from './ParticipantRecorderParts'
+import { useParticipantAudioRecorder, type ParticipantAudioRecorder } from './useParticipantAudioRecorder'
+
+export type ComposerAudioRowProps = {
+  readonly settings: ComposerAudioSettings
+  readonly labels: ParticipantConversationsLabels
+  readonly disabled: boolean
+  readonly isDraftEmpty: boolean
+  /** The send button of the text path; the microphone only takes its place while the draft is empty. */
+  readonly sendButton: ReactNode
+  /** Attach control and message field, drawn only while no recording is in progress. */
+  readonly children: ReactNode
+}
+
+function isCapturingStatus(status: RecorderStatus): boolean {
+  return status === 'recording' || status === 'review'
+}
+
+function useRestoreMicrophoneFocus(status: RecorderStatus): RefObject<HTMLButtonElement | null> {
+  const microphoneRef = useRef<HTMLButtonElement>(null)
+  const wasCapturingRef = useRef(false)
+  useEffect(() => {
+    const isCapturing = isCapturingStatus(status)
+    if (wasCapturingRef.current && !isCapturing) microphoneRef.current?.focus()
+    wasCapturingRef.current = isCapturing
+  }, [status])
+  return microphoneRef
+}
+
+type RecorderLineProps = {
+  readonly recorder: ParticipantAudioRecorder
+  readonly labels: ParticipantConversationsLabels
+  readonly onSendAudio: (file: File) => void
+  readonly disabled: boolean
+}
+
+function RecorderLine({ recorder, labels, onSendAudio, disabled }: RecorderLineProps) {
+  function handleSendAudio(): void {
+    const file = recorder.confirm()
+    if (file) onSendAudio(file)
+  }
+
+  return (
+    <ParticipantAudioRecorderView
+      state={recorder.status}
+      elapsedMs={recorder.elapsedMs}
+      labels={labels}
+      disabled={disabled}
+      maxDurationMs={recorder.limits.maxDurationMs}
+      review={{ url: recorder.recorded?.objectUrl, audioRef: recorder.audioRef, durationMs: recorder.recorded?.durationMs }}
+      actions={{ onStop: recorder.stop, onSend: handleSendAudio, onDiscard: recorder.discard }}
+    />
+  )
+}
+
+export function ComposerAudioRow({ settings, labels, disabled, isDraftEmpty, sendButton, children }: ComposerAudioRowProps) {
+  const recorder = useParticipantAudioRecorder({
+    options: settings.audioRecording,
+    channelMaxBytes: maxBytesForChannel(settings.channel),
+  })
+  const microphoneRef = useRestoreMicrophoneFocus(recorder.status)
+  const audioLabels = resolveParticipantAudioLabels(labels)
+  const errorMessage = resolveRecorderErrorMessage(recorder.status, audioLabels)
+
+  if (isCapturingStatus(recorder.status)) {
+    return <RecorderLine recorder={recorder} labels={labels} onSendAudio={settings.onSendAudio} disabled={disabled} />
+  }
+  return (
+    <>
+      {errorMessage ? <RecorderError message={errorMessage} /> : null}
+      <div className="cv-p-composer__row">
+        {children}
+        {isDraftEmpty ? (
+          <RecordAudioButton
+            label={audioLabels.recordAudio}
+            isBusy={recorder.status === 'requesting'}
+            disabled={disabled}
+            onClick={() => void recorder.start()}
+            buttonRef={microphoneRef}
+          />
+        ) : (
+          sendButton
+        )}
+      </div>
+    </>
+  )
+}

package/src/participant/ParticipantConversations.tsx

@@ -13,6 +13,7 @@ import type {
   ParticipantSubjectIconRenderer,
 } from './participant.types'
 import type { ParticipantConversationsApi, ParticipantPendingMessage } from './participantApi.types'
+import type { ParticipantAudioRecordingOptions } from './participantAudio.types'
 import type { ParticipantConversationsLabels } from './participantLabels'
 import { useParticipantInbox } from './useParticipantInbox'
 
@@ -41,6 +42,8 @@ export type ParticipantConversationsProps = {
   renderAuthorAvatar?: ParticipantAuthorAvatarRenderer
   /** Speech-bubble tail on the bottom corner; false removes it. Default true. */
   tail?: boolean
+  /** Absent draws no microphone. Present lets the user record and send an audio as a message of its own. */
+  audioRecording?: ParticipantAudioRecordingOptions
 }
 
 export function ParticipantConversations(props: ParticipantConversationsProps) {

package/src/participant/ParticipantRecorderParts.tsx

@@ -0,0 +1,118 @@
+import type { Ref } from 'react'
+
+import { Mic, Send, Square, Trash2 } from 'lucide-react'
+
+import { ParticipantAudioPlayer } from './ParticipantAudioPlayer'
+import type { ParticipantAudioLabels } from './participantAudioLabels'
+
+export type RecordAudioButtonProps = {
+  readonly label: string
+  readonly isBusy: boolean
+  readonly disabled: boolean
+  readonly onClick?: () => void
+  readonly buttonRef?: Ref<HTMLButtonElement>
+}
+
+export function RecordAudioButton({ label, isBusy, disabled, onClick, buttonRef }: RecordAudioButtonProps) {
+  return (
+    <button
+      ref={buttonRef}
+      type="button"
+      className="cv-p-button cv-p-button--primary cv-p-composer__record"
+      aria-label={label}
+      data-cv-tooltip={label}
+      aria-busy={isBusy ? true : undefined}
+      disabled={disabled || isBusy}
+      onClick={onClick}
+    >
+      <Mic size={20} aria-hidden="true" focusable="false" />
+    </button>
+  )
+}
+
+export function RecorderError({ message }: { readonly message: string }) {
+  return (
+    <p className="cv-p-composer__error" role="alert">
+      {message}
+    </p>
+  )
+}
+
+function focusOnMount(element: HTMLElement | null): void {
+  element?.focus()
+}
+
+type RecorderGroupProps = {
+  readonly labels: ParticipantAudioLabels
+  readonly onDiscard?: () => void
+}
+
+function DiscardButton({ labels, onDiscard }: RecorderGroupProps) {
+  return (
+    <button
+      type="button"
+      className="cv-p-button cv-p-recorder__discard"
+      aria-label={labels.discardAudio}
+      data-cv-tooltip={labels.discardAudio}
+      onClick={onDiscard}
+    >
+      <Trash2 size={20} aria-hidden="true" focusable="false" />
+    </button>
+  )
+}
+
+export type RecordingGroupProps = RecorderGroupProps & {
+  readonly clockText: string
+  readonly onStop?: () => void
+}
+
+export function RecordingGroup({ labels, clockText, onStop, onDiscard }: RecordingGroupProps) {
+  return (
+    <div className="cv-p-recorder" role="group" aria-label={labels.recordingInProgress}>
+      <DiscardButton labels={labels} onDiscard={onDiscard} />
+      <span className="cv-p-recorder__dot" aria-hidden="true" />
+      <span className="cv-p-recorder__elapsed" role="timer">
+        {clockText}
+      </span>
+      <button
+        type="button"
+        ref={focusOnMount}
+        className="cv-p-button cv-p-button--primary cv-p-recorder__stop"
+        aria-label={labels.stopRecording}
+        data-cv-tooltip={labels.stopRecording}
+        onClick={onStop}
+      >
+        <Square size={20} aria-hidden="true" focusable="false" />
+      </button>
+    </div>
+  )
+}
+
+export type ReviewGroupProps = RecorderGroupProps & {
+  readonly url?: string
+  readonly audioRef?: Ref<HTMLAudioElement>
+  readonly durationMs?: number | undefined
+  readonly onSend?: () => void
+  readonly disabled?: boolean
+}
+
+export function ReviewGroup({ labels, url, audioRef, durationMs, onSend, onDiscard, disabled = false }: ReviewGroupProps) {
+  return (
+    <div className="cv-p-recorder cv-p-recorder--review" role="group" aria-label={labels.reviewAudio}>
+      <p className="cv-p-recorder__hint" aria-hidden="true">{labels.reviewAudio}</p>
+      <DiscardButton labels={labels} onDiscard={onDiscard} />
+      <ParticipantAudioPlayer labels={labels} url={url} durationMs={durationMs} mediaRef={audioRef} />
+      <button
+        type="button"
+        ref={focusOnMount}
+        className="cv-p-button cv-p-button--primary cv-p-recorder__send"
+        aria-label={labels.sendAudio}
+        data-cv-tooltip={labels.sendAudio}
+        disabled={disabled}
+        onClick={onSend}
+      >
+        <Send size={20} aria-hidden="true" focusable="false" />
+      </button>
+    </div>
+  )
+}

package/src/participant/ParticipantThread.tsx

@@ -21,6 +21,7 @@ import { ParticipantScrollToLatest } from './ParticipantScrollToLatest'
 import { ParticipantTimeline } from './ParticipantTimeline'
 import { ParticipantThreadHeader } from './ParticipantThreadHeader'
 import type { ParticipantSubjectGroup, ParticipantSubjectIconRenderer } from './participant.types'
+import type { ParticipantAudioRecordingOptions } from './participantAudio.types'
 
 export type ParticipantThreadDraft = {
   readonly value: string
@@ -71,6 +72,10 @@ export type ParticipantThreadProps = {
   readonly counterpartLabel?: string
   /** Host slot at the end of the header bar (close, reopen...). */
   readonly headerActions?: ReactNode
+  /** Absent draws no microphone. Present turns it on when the field is empty and the browser and channel record. */
+  readonly audioRecording?: ParticipantAudioRecordingOptions
+  /** Receives the recorded audio; the controller sends it as a message of its own. */
+  readonly onSendAudio?: (file: File) => void
 }
 
 function Footer({ props }: { readonly props: ParticipantThreadProps }) {
@@ -91,6 +96,8 @@ function Footer({ props }: { readonly props: ParticipantThreadProps }) {
       maxLength={props.maxLength}
       acceptedTypes={props.acceptedTypes}
       quickReplies={props.quickReplies}
+      audioRecording={props.audioRecording}
+      onSendAudio={props.onSendAudio}
     />
   )
 }

package/src/participant/ParticipantThreadScreen.tsx

@@ -104,6 +104,7 @@ function LoadedThread(props: LoadedThreadProps) {
       avatars={props.avatars}
       renderAuthorAvatar={props.renderAuthorAvatar}
       tail={props.tail}
+      audioRecording={props.audioRecording}
     />
   )
 }

package/src/participant/index.ts

@@ -4,6 +4,8 @@ export type { ConversationThreadApi } from './conversationThreadApi'
 export type { ParticipantPerspective } from './participantPerspective'
 export type { ParticipantAuthorAvatarRenderer } from './ParticipantAuthorAvatar'
 export { groupParticipantConversations } from './participantGrouping'
+export { DEFAULT_MAX_RECORDING_BYTES, type ParticipantAudioRecordingOptions } from './participantAudio.types'
+export { DEFAULT_PARTICIPANT_AUDIO_LABELS, type ParticipantAudioLabels } from './participantAudioLabels'
 export { DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS, type ParticipantConversationsLabels } from './participantLabels'
 export type {
   ParticipantConversationsClassNames,
@@ -27,4 +29,5 @@ export type {
   ParticipantConversationSummary,
   ParticipantMessage,
   ParticipantSubjectRef,
+  ParticipantTranscription,
 } from '@adatechnology/conversation-contracts'

package/src/participant/participantAudio.types.ts

@@ -0,0 +1,10 @@
+export type ParticipantAudioRecordingOptions = {
+  /** Only lowers the default: a larger value is cut to DEFAULT_MAX_RECORDING_MILLISECONDS (5 min). */
+  readonly maxDurationMs?: number
+  /** Only lowers the default: a larger value is cut to DEFAULT_MAX_RECORDING_BYTES (16 MiB, the app audio policy). */
+  readonly maxSizeBytes?: number
+  /** True from `requesting` until it leaves `review`; the host feeds its capture registry. Never receives the audio. */
+  readonly onCaptureChange?: (isCapturing: boolean) => void
+}
+
+export const DEFAULT_MAX_RECORDING_BYTES = 16 * 1024 * 1024

package/src/participant/participantAudioCapture.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'bun:test'
+
+import { buildRecordedFile, formatRecordedFileName } from './participantAudioCapture'
+
+describe('recorded file naming', () => {
+  it('names the file audio-YYYYMMDD-HHmmss.<ext> in UTC', () => {
+    expect(formatRecordedFileName(new Date('2026-10-11T09:05:03.999Z'), 'm4a')).toBe('audio-20261011-090503.m4a')
+  })
+
+  it('keeps the upload mime type of the chosen format', () => {
+    const file = buildRecordedFile(new Blob(['x']), { mimeType: 'audio/ogg;codecs=opus', uploadMimeType: 'audio/ogg', extension: 'ogg' }, new Date('2026-01-02T03:04:05Z'))
+    expect(file.name).toBe('audio-20260102-030405.ogg')
+    expect(file.type).toBe('audio/ogg')
+  })
+})

package/src/participant/participantAudioCapture.ts

@@ -0,0 +1,85 @@
+import type { RecordingFormat } from '../audioRecorderFormat'
+import { MUTE_INTERRUPTION_DELAY_MS } from './participantAudioRecorderState'
+
+export type CaptureSession = {
+  readonly format: RecordingFormat
+  readonly startedAt: number
+  readonly requestStop: () => void
+  readonly release: () => void
+}
+
+export type OpenCaptureSessionParams = {
+  readonly stream: MediaStream
+  readonly format: RecordingFormat
+  readonly onInterrupt: () => void
+  readonly onStopped: (blob: Blob, durationMs: number) => void
+}
+
+export function stopStream(stream: MediaStream): void {
+  for (const track of stream.getTracks()) track.stop()
+}
+
+export function formatRecordedFileName(moment: Date, extension: string): string {
+  const iso = moment.toISOString()
+  const day = iso.slice(0, 10).replace(/-/g, '')
+  const time = iso.slice(11, 19).replace(/:/g, '')
+  return `audio-${day}-${time}.${extension}`
+}
+
+export function buildRecordedFile(blob: Blob, format: RecordingFormat, moment: Date = new Date()): File {
+  return new File([blob], formatRecordedFileName(moment, format.extension), { type: format.uploadMimeType })
+}
+
+function createMuteWatch(onPersistentMute: () => void): { arm: () => void; clear: () => void } {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const clear = (): void => {
+    if (timer !== undefined) clearTimeout(timer)
+    timer = undefined
+  }
+  const arm = (): void => {
+    clear()
+    timer = setTimeout(onPersistentMute, MUTE_INTERRUPTION_DELAY_MS)
+  }
+  return { arm, clear }
+}
+
+export function openCaptureSession({ stream, format, onInterrupt, onStopped }: OpenCaptureSessionParams): CaptureSession {
+  const recorder = new MediaRecorder(stream, { mimeType: format.mimeType })
+  const chunks: Blob[] = []
+  const startedAt = Date.now()
+  const muteWatch = createMuteWatch(onInterrupt)
+  for (const track of stream.getTracks()) {
+    track.onended = onInterrupt
+    track.onmute = muteWatch.arm
+    track.onunmute = muteWatch.clear
+  }
+  recorder.ondataavailable = (event) => {
+    if (event.data.size > 0) chunks.push(event.data)
+  }
+  recorder.onerror = onInterrupt
+  recorder.onstop = () => onStopped(new Blob(chunks, { type: format.uploadMimeType }), Date.now() - startedAt)
+  recorder.start()
+
+  let isStopRequested = false
+  // stop() makes the state inactive at once and the real `stop` event arrives later, so only that event may finish the capture
+  function requestStop(): void {
+    if (isStopRequested || recorder.state === 'inactive') return
+    isStopRequested = true
+    recorder.stop()
+  }
+
+  function release(): void {
+    muteWatch.clear()
+    recorder.ondataavailable = null
+    recorder.onerror = null
+    recorder.onstop = null
+    for (const track of stream.getTracks()) {
+      track.onended = null
+      track.onmute = null
+      track.onunmute = null
+    }
+    stopStream(stream)
+  }
+
+  return { format, startedAt, requestStop, release }
+}

package/src/participant/participantAudioCoordinator.ts

@@ -0,0 +1,13 @@
+export type AudioPlaybackHandle = { readonly pause: () => void }
+
+let activeHandle: AudioPlaybackHandle | undefined
+
+/** One audio at a time on the page: whoever starts pauses the previous one. No provider, no context. */
+export function claimAudioPlayback(handle: AudioPlaybackHandle): void {
+  if (activeHandle && activeHandle !== handle) activeHandle.pause()
+  activeHandle = handle
+}
+
+export function releaseAudioPlayback(handle: AudioPlaybackHandle): void {
+  if (activeHandle === handle) activeHandle = undefined
+}