@adatechnology/conversations-ui 0.8.0 → 0.10.0

package/src/participant/failedMenuKeyboard.ts

@@ -0,0 +1,29 @@
+import type { Dispatch, KeyboardEvent, RefObject } from 'react'
+
+import { resolveFailedMenuKey, type FailedMenuAction } from './participantFailedMenuState'
+
+type MenuKeyParams = {
+  readonly event: KeyboardEvent<HTMLElement>
+  readonly menuRef: RefObject<HTMLElement | null>
+  readonly triggerRef: RefObject<HTMLElement | null>
+  readonly dispatch: Dispatch<FailedMenuAction>
+}
+
+/** Escape is consumed here so it does not also close a host dialog or drawer around the thread. */
+export function handleFailedMenuKeyDown({ event, menuRef, triggerRef, dispatch }: MenuKeyParams): void {
+  const items = Array.from(menuRef.current?.querySelectorAll<HTMLElement>('[role="menuitem"]') ?? [])
+  const index = items.findIndex((item) => item === document.activeElement)
+  const result = resolveFailedMenuKey({ key: event.key, index, count: items.length })
+  if (!result) return
+  if (result.type === 'focus') {
+    event.preventDefault()
+    items[result.index]?.focus()
+    return
+  }
+  if (result.shouldRestoreFocus) {
+    event.preventDefault()
+    event.stopPropagation()
+    triggerRef.current?.focus()
+  }
+  dispatch({ type: 'close' })
+}

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
+}

package/src/participant/participantAudioFormat.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'bun:test'
+
+import {
+  PLAYBACK_RATES,
+  formatAudioClock,
+  formatPlaybackRate,
+  formatPositionValueText,
+  nextRateIndex,
+  resolveMediaDurationSeconds,
+  resolveSeekKeyTarget,
+  resolveSeekMax,
+  resolveServerDurationSeconds,
+} from './participantAudioFormat'
+
+describe('formatAudioClock', () => {
+  it('formats m:ss and pads the seconds', () => {
+    expect(formatAudioClock(0)).toBe('0:00')
+    expect(formatAudioClock(12.9)).toBe('0:12')
+    expect(formatAudioClock(65)).toBe('1:05')
+    expect(formatAudioClock(300)).toBe('5:00')
+  })
+
+  it('shows a placeholder when the duration is unknown or infinite', () => {
+    expect(formatAudioClock(undefined)).toBe('--:--')
+    expect(formatAudioClock(Number.POSITIVE_INFINITY)).toBe('--:--')
+    expect(formatAudioClock(Number.NaN)).toBe('--:--')
+  })
+})
+
+describe('playback rate', () => {
+  it('cycles 1x, 1.5x, 2x and back', () => {
+    expect(PLAYBACK_RATES).toEqual([1, 1.5, 2])
+    expect(nextRateIndex(0)).toBe(1)
+    expect(nextRateIndex(1)).toBe(2)
+    expect(nextRateIndex(2)).toBe(0)
+  })
+
+  it('names the rate with the multiplication sign', () => {
+    expect(formatPlaybackRate(1.5)).toBe('1.5×')
+    expect(formatPlaybackRate(2)).toBe('2×')
+  })
+})
+
+describe('durations', () => {
+  it('takes the server duration in seconds only when positive and finite', () => {
+    expect(resolveServerDurationSeconds(65_000)).toBe(65)
+    expect(resolveServerDurationSeconds(undefined)).toBeUndefined()
+    expect(resolveServerDurationSeconds(0)).toBeUndefined()
+  })
+
+  it('ignores an infinite or NaN media duration (Chromium WebM without a header)', () => {
+    expect(resolveMediaDurationSeconds(42)).toBe(42)
+    expect(resolveMediaDurationSeconds(Number.POSITIVE_INFINITY)).toBeUndefined()
+    expect(resolveMediaDurationSeconds(Number.NaN)).toBeUndefined()
+  })
+})
+
+describe('keyboard step', () => {
+  it('moves 5 seconds with the arrows and clamps at the start and the end', () => {
+    expect(resolveSeekKeyTarget({ key: 'ArrowRight', position: 10, duration: 65 })).toBe(15)
+    expect(resolveSeekKeyTarget({ key: 'ArrowUp', position: 10, duration: 65 })).toBe(15)
+    expect(resolveSeekKeyTarget({ key: 'ArrowLeft', position: 10, duration: 65 })).toBe(5)
+    expect(resolveSeekKeyTarget({ key: 'ArrowDown', position: 2, duration: 65 })).toBe(0)
+    expect(resolveSeekKeyTarget({ key: 'ArrowRight', position: 63, duration: 65 })).toBe(65)
+  })
+
+  it('jumps to the start with Home and to the end with End', () => {
+    expect(resolveSeekKeyTarget({ key: 'Home', position: 30, duration: 65 })).toBe(0)
+    expect(resolveSeekKeyTarget({ key: 'End', position: 30, duration: 65 })).toBe(65)
+  })
+
+  it('does not know the end without a finite duration and leaves other keys alone', () => {
+    expect(resolveSeekKeyTarget({ key: 'End', position: 30, duration: undefined })).toBeUndefined()
+    expect(resolveSeekKeyTarget({ key: 'ArrowRight', position: 30, duration: undefined })).toBe(35)
+    expect(resolveSeekKeyTarget({ key: 'a', position: 30, duration: 65 })).toBeUndefined()
+  })
+})
+
+describe('range bounds and value text', () => {
+  it('uses the rounded-up duration as max when known', () => {
+    expect(resolveSeekMax({ duration: 64.2, maxSeen: 3, position: 3 })).toBe(65)
+  })
+
+  it('uses the largest position seen as a provisional max when the duration is unknown', () => {
+    expect(resolveSeekMax({ duration: undefined, maxSeen: 12, position: 12 })).toBe(12)
+    expect(resolveSeekMax({ duration: undefined, maxSeen: 0, position: 0 })).toBe(0)
+  })
+
+  it('writes position and duration, or only the position without a duration', () => {
+    expect(formatPositionValueText({ template: '{position} of {duration}', position: 12, duration: 65 })).toBe('0:12 of 1:05')
+    expect(formatPositionValueText({ template: '{position} of {duration}', position: 12, duration: undefined })).toBe('0:12')
+  })
+})

package/src/participant/participantAudioFormat.ts

@@ -0,0 +1,72 @@
+export const PLAYBACK_RATES = [1, 1.5, 2] as const
+export const SEEK_STEP_SECONDS = 5
+
+const UNKNOWN_CLOCK = '--:--'
+
+export function formatAudioClock(seconds: number | undefined): string {
+  if (seconds === undefined || !Number.isFinite(seconds) || seconds < 0) return UNKNOWN_CLOCK
+  const wholeSeconds = Math.floor(seconds)
+  const remainder = String(wholeSeconds % 60).padStart(2, '0')
+  return `${Math.floor(wholeSeconds / 60)}:${remainder}`
+}
+
+export function nextRateIndex(index: number): number {
+  return (index + 1) % PLAYBACK_RATES.length
+}
+
+export function formatPlaybackRate(rate: number): string {
+  return `${rate}×`
+}
+
+export function resolveServerDurationSeconds(durationMs: number | undefined): number | undefined {
+  if (durationMs === undefined || !Number.isFinite(durationMs) || durationMs <= 0) return undefined
+  return durationMs / 1000
+}
+
+export function resolveMediaDurationSeconds(duration: number): number | undefined {
+  return Number.isFinite(duration) && duration > 0 ? duration : undefined
+}
+
+export type SeekKeyParams = {
+  readonly key: string
+  readonly position: number
+  readonly duration: number | undefined
+}
+
+function clampPosition(position: number, duration: number | undefined): number {
+  const floored = Math.max(0, position)
+  return duration === undefined ? floored : Math.min(duration, floored)
+}
+
+/** The position a key moves the bar to, or undefined when the key is not ours to handle. */
+export function resolveSeekKeyTarget({ key, position, duration }: SeekKeyParams): number | undefined {
+  if (key === 'ArrowRight' || key === 'ArrowUp') return clampPosition(position + SEEK_STEP_SECONDS, duration)
+  if (key === 'ArrowLeft' || key === 'ArrowDown') return clampPosition(position - SEEK_STEP_SECONDS, duration)
+  if (key === 'Home') return 0
+  if (key === 'End') return duration
+  return undefined
+}
+
+export type SeekMaxParams = {
+  readonly duration: number | undefined
+  readonly maxSeen: number
+  readonly position: number
+}
+
+/** Known duration wins; otherwise the largest position seen so far keeps the bar coherent while it grows. */
+export function resolveSeekMax({ duration, maxSeen, position }: SeekMaxParams): number {
+  if (duration !== undefined) return Math.ceil(duration)
+  return Math.ceil(Math.max(maxSeen, position))
+}
+
+export type PositionValueTextParams = {
+  readonly template: string
+  readonly position: number
+  readonly duration: number | undefined
+}
+
+export function formatPositionValueText({ template, position, duration }: PositionValueTextParams): string {
+  const positionText = formatAudioClock(position)
+  if (duration === undefined) return positionText
+  return template.replace('{position}', positionText).replace('{duration}', formatAudioClock(duration))
+}

package/src/participant/participantAudioGolden.test.tsx

@@ -0,0 +1,168 @@
+/**
+ * Goldens of the participant thread (264, contract.md §2.4, §3): the empty composer must not change, and the
+ * audio player and transcription blocks are pinned byte for byte. The composer goldens live in
+ * `participantComposerAudioGolden.test.tsx`.
+ */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { afterEach, beforeAll, describe, expect, it } from 'bun:test'
+import type { ComponentType } from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+import { ParticipantConversations } from './ParticipantConversations'
+import { ParticipantThread } from './ParticipantThread'
+import {
+  buildThreadProps,
+  renderGoldenScenarios,
+  type GoldenComponents,
+} from './participantGoldenScenarios.test-helper'
+import { buildMessage } from './participantFixtures.test-helper'
+import { DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS } from './participantLabels'
+import { installFakeRecording } from './participantRecorderFakes.test-helper'
+
+const FIXTURES_DIRECTORY = join(import.meta.dir, 'test-fixtures')
+const PRE_EXISTING_GOLDENS = [
+  'thread-default',
+  'thread-plain',
+  'thread-avatars-initials',
+  'thread-tail-off',
+  'thread-error',
+  'thread-loading',
+  'thread-closed',
+  'conversations-list',
+  'conversations-selected',
+]
+
+function readGolden(name: string): string {
+  return readFileSync(join(FIXTURES_DIRECTORY, `${name}.golden.html`), 'utf8')
+}
+
+const UntypedThread = ParticipantThread as unknown as ComponentType<Record<string, unknown>>
+
+function renderThread(extra: Record<string, unknown>): string {
+  const props = { ...buildThreadProps(DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS), ...extra }
+  return renderToStaticMarkup(<UntypedThread {...props} />)
+}
+
+describe('empty composer stays byte-identical to origin/main a7c5c85 (contract 2.4)', () => {
+  let restoreEnvironment: (() => void) | undefined
+
+  beforeAll(() => {
+    process.env.TZ = 'UTC'
+  })
+
+  afterEach(() => {
+    restoreEnvironment?.()
+    restoreEnvironment = undefined
+  })
+
+  it('(a) without the audioRecording prop', () => {
+    expect(renderThread({ draft: { value: '', onChange: () => undefined, files: [], onFilesChange: () => undefined } })).toBe(
+      readGolden('thread-empty-draft'),
+    )
+  })
+
+  it('(b) with audioRecording={{}} on the server render (no MediaRecorder)', () => {
+    const markup = renderThread({
+      draft: { value: '', onChange: () => undefined, files: [], onFilesChange: () => undefined },
+      audioRecording: {},
+    })
+    expect(markup).toBe(readGolden('thread-empty-draft'))
+  })
+
+  it('(c) with audioRecording={{}}, a fake MediaRecorder and channel portal (portal never records)', () => {
+    restoreEnvironment = installFakeRecording().restore
+    const markup = renderThread({
+      draft: { value: '', onChange: () => undefined, files: [], onFilesChange: () => undefined },
+      audioRecording: {},
+      channel: 'portal',
+    })
+    expect(markup).toBe(readGolden('thread-empty-draft'))
+  })
+})
+
+describe('the existing goldens carry no audio; the audio goldens document the player that replaced the native one', () => {
+  it('none of the 9 recorded goldens has an <audio> element', () => {
+    expect(PRE_EXISTING_GOLDENS).toHaveLength(9)
+    for (const name of PRE_EXISTING_GOLDENS) expect(readGolden(name).match(/<audio/g)?.length ?? 0).toBe(0)
+  })
+
+  it('thread-audio-native was regrouped by 264 T1.5: same attachment without durationMs, now the player (no native controls)', () => {
+    const markup = readGolden('thread-audio-native')
+    expect(markup.match(/<audio/g)).toHaveLength(1)
+    expect(markup).not.toContain('controls')
+    expect(markup).not.toContain('cv-p-attachment__audio')
+    expect(markup).toContain('0:00 / --:--')
+  })
+
+  it('the helper renders the new scenarios and the 9 existing ones', () => {
+    const rendered = renderGoldenScenarios({
+      ParticipantThread,
+      ParticipantConversations,
+      labels: DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS,
+    } as unknown as GoldenComponents)
+    for (const name of [...PRE_EXISTING_GOLDENS, 'thread-empty-draft', 'thread-audio-native', 'thread-audio-player'])
+      expect(rendered[name]).toBe(readGolden(name))
+  })
+})
+
+function renderThreadGoldens(): Record<string, string> {
+  return renderGoldenScenarios({
+    ParticipantThread,
+    ParticipantConversations,
+    labels: DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS,
+  } as unknown as GoldenComponents)
+}
+
+const AUDIO_ATTACHMENT = { id: 'att-1', kind: 'audio', filename: 'voice.webm', mimeType: 'audio/webm', sizeBytes: 2048, durationMs: 65_000 }
+const GENERATED_AT = '2026-10-01T12:01:00.000Z'
+
+function audioItems(transcription?: Record<string, unknown>): Record<string, unknown>[] {
+  const attachments = [{ ...AUDIO_ATTACHMENT, ...(transcription === undefined ? {} : { transcription }) }]
+  return [{ kind: 'server', message: buildMessage({ id: 'au', direction: 'inbound', text: '', attachments: attachments as never, createdAt: '2026-10-01T12:00:00.000Z' }) }]
+}
+
+describe('[T1.5] thread-audio-player: the custom player replaces <audio controls> (contract 3.1-3.2)', () => {
+  it('thread-audio-player is byte-identical to its golden', () => {
+    expect(renderThread({ items: audioItems() })).toBe(readGolden('thread-audio-player'))
+  })
+
+  it('renders the contract 3.1 markup: group, toggle, range, time, rate and a preload="none" audio after which comes the file name', () => {
+    const markup = readGolden('thread-audio-player')
+    expect(markup).toContain('<div class="cv-p-audio" role="group" aria-label="Audio: voice.webm">')
+    expect(markup).toContain('type="range" class="cv-p-audio__seek"')
+    expect(markup).toContain('0:00 / 1:05')
+    expect(markup).toContain('<audio class="cv-p-audio__media" preload="none"></audio>')
+    expect(markup.indexOf('cv-p-audio__media')).toBeLessThan(markup.indexOf('cv-p-attachment__name'))
+  })
+
+  it('no other recorded golden changes: the 9 old ones and the empty draft stay without the player', () => {
+    for (const name of [...PRE_EXISTING_GOLDENS, 'thread-empty-draft']) expect(readGolden(name)).not.toContain('cv-p-audio')
+    expect(Object.keys(renderThreadGoldens()).sort()).toEqual(
+      [...PRE_EXISTING_GOLDENS, 'thread-empty-draft', 'thread-audio-native', 'thread-audio-player'].sort(),
+    )
+  })
+})
+
+describe('[T1.6] thread-audio-transcription-*: the block under the player (contract 3.3)', () => {
+  const scenarios: ReadonlyArray<readonly [string, Record<string, unknown>]> = [
+    ['pending', { status: 'pending' }],
+    ['ready', { status: 'ready', text: 'Chego em dez minutos.', language: 'pt', engine: 'whisper-local', generatedAt: GENERATED_AT }],
+    ['empty', { status: 'ready', text: '', generatedAt: GENERATED_AT }],
+    ['too_long', { status: 'failed', reason: 'too_long', maxDurationMs: 300_000 }],
+  ]
+
+  for (const [state, transcription] of scenarios) {
+    it(`thread-audio-transcription-${state} is byte-identical to its golden`, () => {
+      expect(renderThread({ items: audioItems(transcription) })).toBe(readGolden(`thread-audio-transcription-${state}`))
+    })
+  }
+
+  it('absent, disabled and plain failed transcriptions render only the player', () => {
+    const playerOnly = renderThread({ items: audioItems() })
+    for (const transcription of [{ status: 'disabled' }, { status: 'failed' }]) {
+      expect(renderThread({ items: audioItems(transcription) })).toBe(playerOnly)
+    }
+  })
+})

package/src/participant/participantAudioLabels.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'bun:test'
+
+import { DEFAULT_PARTICIPANT_AUDIO_LABELS, formatRecordingElapsedLabel, resolveParticipantAudioLabels } from './participantAudioLabels'
+import { DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS } from './participantLabels'
+
+describe('participant audio labels', () => {
+  it('fills every missing key with the English default', () => {
+    expect(resolveParticipantAudioLabels(undefined)).toEqual(DEFAULT_PARTICIPANT_AUDIO_LABELS)
+    expect(resolveParticipantAudioLabels({ sendAudio: 'Enviar áudio' }).stopRecording).toBe('Stop recording')
+    expect(resolveParticipantAudioLabels({ sendAudio: 'Enviar áudio' }).sendAudio).toBe('Enviar áudio')
+  })
+
+  it('is carried by the default map of the whole view', () => {
+    for (const key of Object.keys(DEFAULT_PARTICIPANT_AUDIO_LABELS) as (keyof typeof DEFAULT_PARTICIPANT_AUDIO_LABELS)[]) {
+      expect(DEFAULT_PARTICIPANT_CONVERSATIONS_LABELS[key]).toBe(DEFAULT_PARTICIPANT_AUDIO_LABELS[key])
+    }
+  })
+
+  it('fills the elapsed and limit placeholders', () => {
+    expect(formatRecordingElapsedLabel('{elapsed} of {limit}', '0:12', '5:00')).toBe('0:12 of 5:00')
+  })
+})

package/src/participant/participantAudioLabels.ts

@@ -0,0 +1,76 @@
+import type { ParticipantConversationsLabels } from './participantLabels'
+
+export type ParticipantAudioLabels = {
+  readonly recordAudio: string
+  readonly recordingInProgress: string
+  readonly stopRecording: string
+  /** Uses the `{elapsed}` and `{limit}` placeholders. */
+  readonly recordingElapsed: string
+  readonly reviewAudio: string
+  readonly sendAudio: string
+  readonly discardAudio: string
+  readonly microphoneDenied: string
+  readonly recordingUnsupported: string
+  readonly audioEmpty: string
+  readonly audioTooLarge: string
+  readonly audioPlayer: string
+  readonly playAudio: string
+  readonly pauseAudio: string
+  readonly audioPosition: string
+  /** Uses the `{position}` and `{duration}` placeholders; without a duration only the position is spoken. */
+  readonly audioPositionValue: string
+  /** Uses the `{rate}` placeholder. */
+  readonly playbackRate: string
+  readonly audioUnavailable: string
+  readonly transcribing: string
+  /** Spoken by the thread's live region when a transcription finishes. */
+  readonly transcriptionReady: string
+  readonly machineTranscription: string
+  readonly emptyTranscription: string
+  /** Uses the `{minutes}` placeholder, filled from the limit the server applied. */
+  readonly transcriptionTooLong: string
+  readonly showFullTranscription: string
+  readonly collapseTranscription: string
+}
+
+export const DEFAULT_PARTICIPANT_AUDIO_LABELS: ParticipantAudioLabels = {
+  recordAudio: 'Record audio',
+  recordingInProgress: 'Recording',
+  stopRecording: 'Stop recording',
+  recordingElapsed: '{elapsed} of {limit}',
+  reviewAudio: 'Listen before sending',
+  sendAudio: 'Send audio',
+  discardAudio: 'Discard audio',
+  microphoneDenied: 'No permission to use the microphone.',
+  recordingUnsupported: 'This device cannot record audio.',
+  audioEmpty: 'Nothing was captured by the microphone.',
+  audioTooLarge: 'Audio too large to send.',
+  audioPlayer: 'Audio',
+  playAudio: 'Play audio',
+  pauseAudio: 'Pause audio',
+  audioPosition: 'Audio position',
+  audioPositionValue: '{position} of {duration}',
+  playbackRate: 'Playback speed {rate}',
+  audioUnavailable: 'Audio unavailable',
+  transcribing: 'Transcribing…',
+  transcriptionReady: 'Transcription ready',
+  machineTranscription: 'Transcription generated by machine',
+  emptyTranscription: 'Nothing was said in the audio',
+  transcriptionTooLong: 'Transcription only for audios shorter than {minutes} minutes',
+  showFullTranscription: 'Show all',
+  collapseTranscription: 'Show less',
+}
+
+export function resolveParticipantAudioLabels(
+  labels: Partial<ParticipantAudioLabels> | ParticipantConversationsLabels | undefined,
+): ParticipantAudioLabels {
+  const resolved = { ...DEFAULT_PARTICIPANT_AUDIO_LABELS }
+  for (const key of Object.keys(resolved) as (keyof ParticipantAudioLabels)[]) {
+    resolved[key] = labels?.[key] ?? DEFAULT_PARTICIPANT_AUDIO_LABELS[key]
+  }
+  return resolved
+}
+
+export function formatRecordingElapsedLabel(template: string, elapsed: string, limit: string): string {
+  return template.replace('{elapsed}', elapsed).replace('{limit}', limit)
+}