studio-engine 0.120.0 → 0.121.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 602092c1d8ddd3ce61cb6f192162ea1cae13af1313769742fa88d5f954327232
-  data.tar.gz: 6a2ca70d13097ebfe23e52c7b14d551b430f92ef07da51bed9c1b80f1baa522c
+  metadata.gz: 161d3e00f32dba8b6c36d769228b39815a79b85a702d76b80f89be4c4365b876
+  data.tar.gz: a56e3fe6902119b4e5ecba61c77347a95893c04c3d8a5543833246b0a674c38f
 SHA512:
-  metadata.gz: 5e8a55b6e21888c67df80712062478ae4b635a4a95d2e062771ab00570f5cd9ba417601e05ab39f14791be16619c3780799d965d2c02491952386001dd6b6f18
-  data.tar.gz: 7abef1323bfc65d590af8c5cef094d7136471e6f0356703b6a1fd73c1bb3137d76b70051b500f6ddab24c4d092d3812f3ae82e766123dbf728c15b28dbd410a4
+  metadata.gz: 4c9506dfec92c4174d85f3d03002d63d222b42c1be0866184a6551faa075471aec3440265e7623378d804e0b7f4dd6eb9e7978ab50f8403ce4edabb8be186df2
+  data.tar.gz: 9ec9cfde7907b0c5dd09a0c19cda518da4fc6341c32003bdda71debdd0ff8de4a13c4091936223d646713c98d7e87c7201550ff725f8f8aecedaf6e53563e962

data/CHANGELOG.md

@@ -4,6 +4,47 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.121.0 — 2026-11-01
+
+### Added
+
+- **Voice capture layer, ported from Voicebox.** `studio/voice/_microphone_chip`
+  names the microphone a page records from (the track's own label, with a live
+  level dot) and lists the others; a pick is remembered in `localStorage` under
+  `studio.microphone` (`storage_key:` to change it) and opened by exact device
+  id, a pick that is gone falls back to the system default, and with nothing
+  picked the system default is asked for by id rather than Chrome's per-site
+  preference. Its native `<dialog>` help shows Chrome's site-settings steps or a
+  generic line, and opens on a switch, a refusal, a second silent take in a row,
+  or the help link. `studio/voice/_recorder` (controller `voice-recorder`, tap or
+  hold to talk) refuses a take under -40 dBFS and hands a heard take to the page
+  as `studio:voice-recorder:take` with the blob; it uploads nothing. A recorder
+  that cannot start lets go of the microphone and the meter. New modules:
+  `studio/microphone`, `studio/level_meter` (the one meter),
+  `studio/voice_recorder`, `studio/microphone_chip`. docs/VOICE_CAPTURE.md is
+  the contract.
+- **Voice transcription: a take becomes `{text, speaker, score}`.**
+  `Studio::VoiceTranscription.hear(audio:, mime_type:, user:, embedding:, model:)`
+  transcribes a take with a mock-first adapter ported from Voicebox (`openai`:
+  `gpt-4o-transcribe`, one retry on `whisper-1`, told the language; `mock`
+  elsewhere) and names the speaker with `Studio::VoiceMatch` against the user's
+  own `users.voice_embedding`, same embedder revision only, else "Someone new".
+  Opt-in `POST /voice/takes` (`config.voice_transcription = true`) wraps it for a
+  signed-in, CSRF-protected page: 10 MB and 120 s caps, an allow-list of audio
+  types, a refused no-speech transcript, and a 503 with a showable line when the
+  app has no `OPENAI_API_KEY`. The real adapter raises `LiveCallAttempted`
+  before any socket while `VOICE_NO_LIVE_CALLS=1` and in every Rails test
+  environment. Nothing is stored; `voice[audio]` and `voice[embedding]` join the
+  parameter filter. docs/VOICE_TRANSCRIPTION.md is the contract.
+
+### Changed
+
+- The voice row on `/profile` (`studio/voice_profile`) runs on the shared meter
+  and recording format (`studio/level_meter`, `studio/voice_recorder`) instead
+  of its own copy; it still re-exports `SILENCE_RMS`, `meterLevel`,
+  `takeWasHeard`, `pickMimeType` and friends. Under reduced motion its ring now
+  steps in quarters, as the recorder's does.
+
 ## 0.120.0 — 2026-10-30
 
 ### Added

data/README.md

@@ -46,6 +46,8 @@ resolved.
 - **Site footer**: `<%= studio_site_footer %>` in the layout renders the public site's footer. It is on by default: with nothing configured it prints the app's name, logo and the legal links the app has routes for, and no address. `config.site_footer` declares the app's own facts (brand, social profiles, link columns, an address with a live map, legal links), every part optional; `config.site_footer_address` adds a location in one setting; `config.site_footer = false` turns the footer off. Leaflet is vendored and served by the engine. See [`docs/SITE_FOOTER.md`](docs/SITE_FOOTER.md).
 - **Booking**: a simple scheduler on Google Calendar appointment schedules, with or without the footer. With `config.booking_url`, `studio_booking_frame` embeds Google's booking page, `studio_booking_link` opens it in a popup, and `config.draw_booking_routes = true` draws `/schedule` (or name the app's own page with `config.booking_path`). `config.booking_crop` crops the frame to the slot picker at rest, from numbers `bin/booking-crop-measure` reads off the app's own schedule. See [`docs/BOOKING.md`](docs/BOOKING.md).
 - **Voice profile**: an opt-in row on `/profile` ("Set up your voice"): the person reads three phrases with a live level meter, their device turns each take into a speaker embedding (WeSpeaker via transformers.js), and only the averaged vector is saved on their user, never audio. `Studio::VoiceMatch.identify(embedding, among: User.all, model:)` answers who is speaking. Turn it on with `config.voice_profile = true` after installing the migration. See [`docs/VOICE_PROFILE.md`](docs/VOICE_PROFILE.md).
+- **Voice capture**: the microphone chip (names the microphone a page records from, picks another, Chrome help dialog), one level meter, and a record button that refuses a silent take and hands a heard one to the page as a `studio:voice-recorder:take` event with the blob; it uploads nothing. Render `studio/voice/microphone_chip` and `studio/voice/recorder`. See [`docs/VOICE_CAPTURE.md`](docs/VOICE_CAPTURE.md).
+- **Voice transcription**: `POST /voice/takes` (opt-in, `config.voice_transcription = true`) turns a signed-in user's take into `{text, speaker, score}`: a mock-first transcriber (OpenAI `gpt-4o-transcribe` in production, a mock elsewhere, a no-live-calls trap in every test environment) and `Studio::VoiceMatch` against the user's own saved voice. Nothing is kept. See [`docs/VOICE_TRANSCRIPTION.md`](docs/VOICE_TRANSCRIPTION.md).
 - **Surveys**: define a survey in app code (`config/surveys/*.rb`, `Studio.define_survey`) with six question types — emoji scale, 1–5 rating, single and multiple choice, short and long text — and the engine serves it at `/surveys/:slug`: one question per screen, autosave, resume, keyboard shortcuts, and a no-JavaScript fallback. `config.on_survey_completed` and `config.survey_ref_resolver` let the app fire its own goals and attribute email arrivals. An admin panel at `/admin/surveys` breaks results down per question and exports CSV. Opt in with `config.draw_survey_routes = true` and `config.draw_admin_survey_routes = true`. See [`docs/SURVEYS.md`](docs/SURVEYS.md).
 
 ## Tailwind

data/app/controllers/studio/voice_takes_controller.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Studio
+  # POST /voice/takes: one recorded take in, {text, speaker, score} out
+  # (docs/VOICE_TRANSCRIPTION.md). Drawn by Studio.routes only when the app
+  # sets Studio.voice_transcription.
+  #
+  # The page posts the recorder's take (studio:voice-recorder:take) as
+  # multipart/form-data:
+  #
+  #   voice[audio]        the blob (required, at most VoiceTranscription::MAX_BYTES)
+  #   voice[mime_type]    its mimeType, e.g. "audio/webm;codecs=opus" (else the
+  #                       part's own Content-Type)
+  #   voice[duration_ms]  durationMs (required, 1..MAX_DURATION_MS)
+  #   voice[embedding]    the take's speaker vector, JSON (optional)
+  #   voice[model]        the embedder id that made it (optional)
+  #
+  # SIGNED-IN ONLY (the host's require_authentication: a JSON 401 otherwise),
+  # CSRF-protected (send the page's token as X-CSRF-Token), JSON, no-store.
+  # The speaker is matched only against the signed-in user's own saved voice.
+  #
+  # NOTHING IS KEPT: the upload is read once, handed to the transcriber, and its
+  # tempfile is deleted before the answer; no audio or vector is stored or
+  # logged (voice[audio] and voice[embedding] are in the engine's parameter
+  # filter).
+  class VoiceTakesController < ::ApplicationController
+    before_action :require_authentication
+    protect_from_forgery with: :exception
+    before_action :no_store
+
+    CANT_HEAR = "I couldn't hear any words in that. Check your microphone and try again."
+    UNAVAILABLE = "I couldn't transcribe that just now. Try again in a moment."
+
+    def create
+      voice = params[:voice]
+      audio = voice.respond_to?(:[]) ? voice[:audio] : nil
+      return refuse("Record something first.") unless audio.respond_to?(:read) && audio.respond_to?(:size)
+
+      begin
+        return refuse("That recording is too long to send.", 413) if audio.size > VoiceTranscription::MAX_BYTES
+        return refuse("That recording was empty.") if audio.size.zero?
+
+        duration = voice[:duration_ms].to_s
+        unless duration.match?(/\A\d{1,9}\z/) && duration.to_i.between?(1, VoiceTranscription::MAX_DURATION_MS)
+          return refuse("That recording is too long, or has no length.")
+        end
+
+        mime = VoiceTranscription.mime_type(voice[:mime_type].presence ||
+                                            (audio.content_type if audio.respond_to?(:content_type)))
+        return refuse("That kind of recording isn't supported.", 415) if mime.nil?
+
+        heard = VoiceTranscription.hear(audio: audio, mime_type: mime, user: current_user,
+                                        embedding: voice[:embedding].presence, model: voice[:model].presence)
+        reason = VoiceTranscription.no_speech_reason(heard.text)
+        return refuse(CANT_HEAR, :unprocessable_entity, reason: "no_speech") if reason
+
+        render json: heard.to_h.merge("duration_ms" => duration.to_i), status: :ok
+      rescue VoiceTranscription::NotConfigured => e
+        capture(e)
+        refuse(VoiceTranscription::NOT_CONFIGURED_MESSAGE, :service_unavailable, reason: "not_configured")
+      rescue VoiceTranscription::HttpError => e
+        capture(e)
+        refuse(UNAVAILABLE, :service_unavailable, reason: "transcriber_failed", retry: true)
+      ensure
+        discard(audio)
+      end
+    end
+
+    private
+
+    def refuse(message, status = :unprocessable_entity, **extra)
+      render json: { error: message, **extra }, status: status
+    end
+
+    def no_store
+      response.headers["Cache-Control"] = "no-store"
+    end
+
+    # The upload's tempfile goes now, not at the next GC.
+    def discard(audio)
+      file = audio.respond_to?(:tempfile) ? audio.tempfile : nil
+      file.close! if file.respond_to?(:close!)
+    rescue StandardError
+      nil
+    end
+
+    def capture(error)
+      ::ErrorLog.capture!(error) if defined?(::ErrorLog) && ::ErrorLog.respond_to?(:capture!)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/app/javascript/studio/controllers/microphone_chip_controller.js

@@ -0,0 +1,21 @@
+// microphone-chip: the microphone chip (studio/voice/_microphone_chip), on the
+// engine's Stimulus application (studio/stimulus registers it lazily, the
+// first time a page renders a chip):
+//
+//   <div data-studio-controller="microphone-chip" data-microphone-copy='{...}'>
+//
+// The listing, the pick, the live dot and the help dialog are
+// studio/microphone_chip; which device opens is studio/microphone.
+import { Controller } from "@hotwired/stimulus"
+import { mountMicrophoneChip } from "studio/microphone_chip"
+
+export default class extends Controller {
+  connect() {
+    this.chip = mountMicrophoneChip(this.element)
+  }
+
+  disconnect() {
+    if (this.chip) this.chip.destroy()
+    this.chip = null
+  }
+}

data/app/javascript/studio/controllers/voice_recorder_controller.js

@@ -0,0 +1,29 @@
+// voice-recorder: one record button (studio/voice/_recorder, or a page's own
+// markup), on the engine's Stimulus application (studio/stimulus registers it
+// lazily, the first time a page renders one):
+//
+//   <div data-studio-controller="voice-recorder" data-voice-recorder-mode="toggle">
+//
+// The take, the meter and the events are studio/voice_recorder. A page reads
+// the finished audio from the studio:voice-recorder:take event; this
+// controller uploads nothing. Pages that drive it from their own controls call
+// the actions: data-studio-action="voice-recorder#start" (or #stop, #toggle).
+import { Controller } from "@hotwired/stimulus"
+import { mountVoiceRecorder } from "studio/voice_recorder"
+
+export default class extends Controller {
+  connect() {
+    this.recorder = mountVoiceRecorder(this.element)
+  }
+
+  disconnect() {
+    if (this.recorder) this.recorder.destroy()
+    this.recorder = null
+  }
+
+  start() { if (this.recorder) this.recorder.start() }
+
+  stop() { if (this.recorder) this.recorder.stop() }
+
+  toggle() { if (this.recorder) this.recorder.toggle() }
+}

data/app/javascript/studio/level_meter.js

@@ -0,0 +1,167 @@
+// studio/level_meter: the ONE level meter every engine recorder uses (the voice
+// recorder, studio/voice_recorder, and the voice row, studio/voice_profile). It
+// reads a live microphone stream through a Web Audio AnalyserNode, keeps the
+// take's loudest frame, and paints a 0..1 level the page draws as a ring or a
+// dot. Voicebox carried two copies of this (its recorder and its voice setup);
+// the engine carries one (docs/VOICE_CAPTURE.md).
+//
+//   const meter = createLevelMeter(stream, { onPaint: (level) => ..., onSample: (rms) => ... })
+//   ... meter.sample() ...       // the recorder also samples on its own timer
+//   const heard = meter.heard()  // before close: did the take clear SILENCE_RMS?
+//   meter.close()                // stops frames and the timer, closes the context, paints 0
+//
+// WHY A TAKE IS JUDGED. A muted or wrong microphone records perfect silence,
+// and a speech model handed silence makes a word up. A take whose loudest frame
+// stayed under SILENCE_RMS is refused by the recorder before it goes anywhere.
+//
+// It imports nothing, so test/javascript/level_meter.test.mjs loads it as a
+// data: module.
+
+// The loudest frame (RMS of the samples, 0..1) a take must reach to count as
+// heard: 0.01 is -40 dBFS. A muted or absent microphone sits at 0, a quiet room
+// on a laptop microphone near 0.002-0.006, and speech at arm's length peaks
+// well above 0.05, so a real voice clears it many times over. Measured in
+// Voicebox.
+export const SILENCE_RMS = 0.01
+
+// How often the meter samples on a timer as well as on animation frames: a
+// background tab stops frames, and a take recorded there is still measured.
+export const SAMPLE_INTERVAL_MS = 100
+
+// Reduced motion: the level steps four times a second, in quarters, instead
+// of gliding.
+export const REDUCED_PAINT_MS = 250
+
+export function rootMeanSquare(samples) {
+  if (!samples || samples.length === 0) return 0
+  let sum = 0
+  for (let i = 0; i < samples.length; i++) sum += samples[i] * samples[i]
+  return Math.sqrt(sum / samples.length)
+}
+
+// The loudest window's RMS, 0..1 (800 samples is 50 ms at 16 kHz): the same
+// silence rule applied to decoded samples rather than a live stream.
+export function peakWindowRms(samples, windowSize = 800) {
+  let peak = 0
+  if (!samples) return peak
+  for (let start = 0; start < samples.length; start += windowSize) {
+    const end = Math.min(samples.length, start + windowSize)
+    let sum = 0
+    for (let i = start; i < end; i++) sum += samples[i] * samples[i]
+    const rms = Math.sqrt(sum / Math.max(1, end - start))
+    if (rms > peak) peak = rms
+  }
+  return peak
+}
+
+// The meter's reading, 0..1, for an RMS level: speech lives between about
+// 0.01 and 0.3, so the scale is logarithmic from -40 dBFS to -10 dBFS.
+export function meterLevel(rms) {
+  if (!(rms > 0)) return 0
+  const db = 20 * Math.log10(rms)
+  return Math.min(1, Math.max(0, (db + 40) / 30))
+}
+
+// Heard, unless the meter measured the take and it stayed under SILENCE_RMS. A
+// take the meter never measured (no Web Audio, a context that never ran) is let
+// through, and whatever receives it (a server, an embedder) decides.
+export function takeWasHeard(peakRms, framesMeasured) {
+  if (!framesMeasured) return true
+  return peakRms >= SILENCE_RMS
+}
+
+// The level as painted: in quarters under reduced motion.
+export function steppedLevel(level, reduced) {
+  return reduced ? Math.round(level * 4) / 4 : level
+}
+
+export function prefersReducedMotion(win = globalThis) {
+  try { return !!(win.matchMedia && win.matchMedia("(prefers-reduced-motion: reduce)").matches) } catch (_) { return false }
+}
+
+// Starts measuring a live stream. Opened after the microphone prompt resolves,
+// so a strict autoplay rule (iOS) can leave the context suspended: those frames
+// read zeros and prove nothing, so they are not counted, and an unmeasured take
+// is let through (takeWasHeard). Without Web Audio the meter measures nothing
+// and paints nothing beyond 0; the take still records.
+//
+// onSample(rms) runs on every counted frame (the recorder tells the chip);
+// onPaint(level) runs with the 0..1 level to draw.
+export function createLevelMeter(stream, { win = globalThis, onSample = () => {}, onPaint = () => {}, intervalMs = SAMPLE_INTERVAL_MS } = {}) {
+  let audioContext = null
+  let analyser = null
+  let buffer = null
+  let frame = null
+  let timer = null
+  let peak = 0
+  let frames = 0
+  let lastPaint = 0
+  let closed = false
+  const reduced = prefersReducedMotion(win)
+  const now = () => (win.performance && win.performance.now ? win.performance.now() : Date.now())
+
+  function paint(level) {
+    try { onPaint(steppedLevel(level, reduced)) } catch (_) { /* a painter's error never stops the take */ }
+  }
+
+  function sample() {
+    if (closed || !analyser || !audioContext || audioContext.state !== "running") return null
+    analyser.getFloatTimeDomainData(buffer)
+    const rms = rootMeanSquare(buffer)
+    frames += 1
+    if (rms > peak) peak = rms
+    try { onSample(rms) } catch (_) { /* as above */ }
+    const t = now()
+    if (!reduced || t - lastPaint >= REDUCED_PAINT_MS) {
+      lastPaint = t
+      paint(meterLevel(rms))
+    }
+    return rms
+  }
+
+  function close() {
+    if (frame != null && win.cancelAnimationFrame) win.cancelAnimationFrame(frame)
+    if (timer != null && win.clearInterval) win.clearInterval(timer)
+    frame = null
+    timer = null
+    analyser = null
+    if (audioContext && audioContext.state !== "closed" && audioContext.close) {
+      try { audioContext.close().catch(() => {}) } catch (_) { /* already gone */ }
+    }
+    audioContext = null
+    closed = true
+    paint(0)
+  }
+
+  paint(0)
+  const AudioContextClass = win.AudioContext || win.webkitAudioContext
+  if (AudioContextClass && stream) {
+    try {
+      audioContext = new AudioContextClass()
+      const source = audioContext.createMediaStreamSource(stream)
+      analyser = audioContext.createAnalyser()
+      analyser.fftSize = 1024
+      buffer = new Float32Array(analyser.fftSize)
+      source.connect(analyser)
+      if (audioContext.state === "suspended" && audioContext.resume) audioContext.resume().catch(() => {})
+      if (win.requestAnimationFrame) {
+        const loop = () => {
+          sample()
+          if (!closed) frame = win.requestAnimationFrame(loop)
+        }
+        frame = win.requestAnimationFrame(loop)
+      }
+      if (win.setInterval) timer = win.setInterval(sample, intervalMs)
+    } catch (_) {
+      close() // measured nothing: heard() lets the take through
+    }
+  }
+
+  return {
+    sample,
+    close,
+    heard: () => takeWasHeard(peak, frames),
+    get peak() { return peak },
+    get frames() { return frames }
+  }
+}

data/app/javascript/studio/microphone.js

@@ -0,0 +1,250 @@
+// studio/microphone: which microphone a page records from. The one the person
+// picked on the microphone chip (studio/microphone_chip), remembered on this
+// device, or the system default when they never picked one or the picked one
+// is gone. Ported from Voicebox's microphone.js (docs/VOICE_CAPTURE.md).
+//
+// Every recorder opens the microphone through openMicrophone, so the recorder
+// and the chip never disagree about the device. The recorder then tells the
+// chip what it opened, how loud the take is, and when it let go, with EVENTS on
+// window; the chip only listens.
+//
+// Why it exists: Chrome's site setting can pick a microphone that is switched
+// off (a wireless headset) instead of the system's own, and every take then
+// records silence with nothing on the page saying which microphone was used.
+//
+// It imports nothing, so test/javascript/microphone.test.mjs loads it as a
+// data: module.
+
+// Where the pick is remembered (localStorage). One key for every engine page
+// on an origin, so the chip on the hub's chat and on /profile agree. A host
+// that wants its own key calls configureMicrophone({ storageKey }) or renders
+// the chip with storage_key: (studio/voice/_microphone_chip).
+export const STORAGE_KEY = "studio.microphone"
+
+let currentKey = STORAGE_KEY
+
+export function configureMicrophone({ storageKey } = {}) {
+  currentKey = storageKey ? String(storageKey) : STORAGE_KEY
+  return currentKey
+}
+
+export function storageKey() { return currentKey }
+
+export const EVENTS = {
+  opened: "studio:microphone:opened", // detail: { label, deviceId, fellBack }
+  level: "studio:microphone:level", // detail: { rms }
+  closed: "studio:microphone:closed",
+  denied: "studio:microphone:denied",
+  chosen: "studio:microphone:chosen", // detail: { deviceId }
+  silent: "studio:microphone:silent" // detail: { label }: a take came back silent
+}
+
+// Which help to show: Chrome's (and Chromium Edge's, Opera's) site-settings
+// steps, or one generic line for Safari and Firefox. Only desktop and Android
+// Chromium carry "Chrome/" (or Edge's "Edg/"); Chrome and Edge on iOS say
+// "CriOS/" and "EdgiOS/", WebKit underneath with no site-settings icon by the
+// address, so they get the generic line too.
+export function browserFamily(userAgent) {
+  return /(Chrome|Chromium|Edg)\//.test(String(userAgent || "")) ? "chrome" : "other"
+}
+
+// Chrome's two stand-ins for "whatever the system picks". They repeat a real
+// device under another id, so the picker leaves them out when real ones exist.
+const PSEUDO_IDS = ["default", "communications"]
+
+// "Arctis Nova Pro Wireless (1038:12e0)" -> "Arctis Nova Pro Wireless", and
+// Chrome's "Default - MacBook Pro Microphone (Built-in)" ->
+// "MacBook Pro Microphone". The USB vendor:product pair and the "(Built-in)"
+// tag mean nothing to a person.
+export function trimLabel(label) {
+  return String(label || "")
+    .replace(/^(Default|Communications)\s+-\s+/i, "")
+    .replace(/\s*\([0-9a-f]{4}:[0-9a-f]{4}\)/gi, "")
+    .replace(/\s*\(Built-in\)/gi, "")
+    .replace(/\s+/g, " ")
+    .trim()
+}
+
+export function audioInputs(devices) {
+  return Array.from(devices || []).filter((device) => device && device.kind === "audioinput")
+}
+
+// Before the person allows the microphone the browser lists inputs with empty
+// labels (and often empty ids): there is nothing to show yet.
+export function permissionGranted(inputs) {
+  return (inputs || []).some((device) => !!device.label)
+}
+
+// The devices worth offering in the picker: real ones, named, once each.
+export function pickerChoices(inputs) {
+  const named = (inputs || []).filter((device) => device.label && device.deviceId)
+  const real = named.filter((device) => !PSEUDO_IDS.includes(device.deviceId))
+  const seen = new Set()
+  return (real.length ? real : named).flatMap((device) => {
+    if (seen.has(device.deviceId)) return []
+    seen.add(device.deviceId)
+    return [{ deviceId: device.deviceId, label: trimLabel(device.label) }]
+  })
+}
+
+// The remembered device, if it is still plugged in; null means "let the
+// browser pick". Before permission the ids are blank and nothing can be
+// checked, so the remembered one is tried and openMicrophone falls back if the
+// browser says it is gone.
+export function chooseDeviceId(inputs, rememberedId) {
+  if (!rememberedId) return null
+  if (inputs.some((device) => device.deviceId === rememberedId)) return rememberedId
+  if (inputs.every((device) => !device.deviceId)) return rememberedId
+  return null
+}
+
+// The system default, as a device to ask for by id. Chrome lists it as the
+// "default" entry, and a bare { audio: true } does NOT open it: Chrome opens
+// its per-site preference instead, which can be a headset switched off in a
+// drawer. So with nothing picked the page asks for the system default by id,
+// and the chip, which names the system default, names what is opened. The
+// real twin's id when there is one (the track then reports that id), else
+// "default" itself; null where the browser lists no "default" (Safari,
+// Firefox), and there the browser's own choice stands and the opened track
+// corrects the chip.
+export function systemDefaultId(inputs) {
+  const entry = inputs.find((device) => device.deviceId === "default" && device.label)
+  if (!entry) return null
+  const name = trimLabel(entry.label)
+  const twin = inputs.find((device) => device.deviceId && !PSEUDO_IDS.includes(device.deviceId) &&
+                                       trimLabel(device.label) === name)
+  return twin ? twin.deviceId : "default"
+}
+
+export function audioConstraints(deviceId) {
+  return deviceId ? { audio: { deviceId: { exact: deviceId } } } : { audio: true }
+}
+
+// The errors getUserMedia gives when an exact device is not there.
+export function isMissingDevice(error) {
+  return !!error && ["OverconstrainedError", "NotFoundError"].includes(error.name)
+}
+
+// What the chip names before a take has opened anything: the picked device,
+// else the system default's name, else the first input. After a take, the
+// track's own label wins (activeLabel), because that is the device that was
+// actually recorded from.
+export function displayedLabel(inputs, rememberedId, activeLabel) {
+  if (activeLabel) return trimLabel(activeLabel)
+  if (!permissionGranted(inputs)) return null
+  const remembered = rememberedId && inputs.find((device) => device.deviceId === rememberedId && device.label)
+  if (remembered) return trimLabel(remembered.label)
+  const fallback = inputs.find((device) => device.deviceId === "default" && device.label) ||
+                   inputs.find((device) => device.label)
+  return fallback ? trimLabel(fallback.label) : null
+}
+
+// ---- Remembering the choice (localStorage can throw: private mode, blocked
+// site data), so every touch is guarded and a failure means "no choice". ----
+
+function storageOf(storage) {
+  if (storage !== undefined) return storage
+  try { return globalThis.localStorage || null } catch (_) { return null }
+}
+
+export function rememberedDeviceId(storage, key = currentKey) {
+  try { return storageOf(storage)?.getItem(key) || null } catch (_) { return null }
+}
+
+export function rememberDevice(deviceId, storage, key = currentKey) {
+  try {
+    const store = storageOf(storage)
+    if (!store) return
+    if (deviceId) store.setItem(key, deviceId)
+    else store.removeItem(key)
+  } catch (_) { /* nothing remembered: the browser picks next time */ }
+}
+
+export function forgetDevice(storage, key = currentKey) { rememberDevice(null, storage, key) }
+
+export function trackOf(stream) {
+  return (stream && stream.getAudioTracks && stream.getAudioTracks()[0]) || null
+}
+
+// Opens the microphone the person picked, or the system default. A picked
+// device that has gone away is forgotten and the default opened instead
+// (fellBack), so a headset left in a drawer never blocks recording. Other
+// errors (NotAllowedError above all) are the caller's to word.
+//
+// With nothing picked it asks for the system default by id (systemDefaultId),
+// so Chrome's per-site preference never silently wins. Before permission the
+// ids are blank and only a bare request can ask; once that grants permission,
+// a stream that landed on another device is closed and the system default
+// opened in its place, so even the first take records from what the chip will
+// name.
+export async function openMicrophone(mediaDevices = globalThis.navigator && globalThis.navigator.mediaDevices, storage) {
+  const remembered = rememberedDeviceId(storage)
+  const inputs = await listInputs(mediaDevices)
+  const picked = chooseDeviceId(inputs, remembered)
+  let fellBack = !!remembered && !picked
+  if (fellBack) forgetDevice(storage)
+  let deviceId = picked || systemDefaultId(inputs)
+
+  let stream
+  try {
+    stream = await mediaDevices.getUserMedia(audioConstraints(deviceId))
+  } catch (error) {
+    if (!deviceId || !isMissingDevice(error)) throw error
+    if (picked) {
+      forgetDevice(storage)
+      fellBack = true
+    }
+    deviceId = null
+    stream = await mediaDevices.getUserMedia(audioConstraints(null))
+  }
+
+  if (!deviceId && !permissionGranted(inputs)) stream = await reopenSystemDefault(mediaDevices, stream)
+
+  const track = trackOf(stream)
+  const settings = settingsOf(track)
+  const opened = { label: trimLabel(track && track.label), deviceId: settings.deviceId || deviceId || null, fellBack }
+  announce(EVENTS.opened, opened)
+  return { stream, ...opened }
+}
+
+async function listInputs(mediaDevices) {
+  if (!mediaDevices || !mediaDevices.enumerateDevices) return []
+  try { return audioInputs(await mediaDevices.enumerateDevices()) } catch (_) { return [] }
+}
+
+function settingsOf(track) {
+  try { return (track && track.getSettings && track.getSettings()) || {} } catch (_) { return {} }
+}
+
+// After the permission prompt: is the bare request's stream the system
+// default? If it landed elsewhere (Chrome's site preference), let it go and
+// open the system default by id. Any doubt keeps the stream it has.
+export async function reopenSystemDefault(mediaDevices, stream) {
+  const inputs = await listInputs(mediaDevices)
+  const wanted = systemDefaultId(inputs)
+  const track = trackOf(stream)
+  if (!wanted || !track) return stream
+  const got = settingsOf(track).deviceId
+  const wantedLabel = trimLabel((inputs.find((device) => device.deviceId === wanted) || {}).label)
+  if (got === wanted || got === "default" || (wantedLabel && trimLabel(track.label) === wantedLabel)) return stream
+  try {
+    const replacement = await mediaDevices.getUserMedia(audioConstraints(wanted))
+    stream.getTracks().forEach((t) => t.stop())
+    return replacement
+  } catch (_) {
+    return stream
+  }
+}
+
+// Tells the chip (and anything else listening on window).
+export function announce(name, detail = {}, win = globalThis) {
+  try { win.dispatchEvent(new CustomEvent(name, { detail })) } catch (_) { /* no listeners to tell */ }
+}
+
+// The silent-take line that names the microphone, or null when the track had
+// no name to give (then the page's general line stands).
+export function silentMessage(template, label) {
+  const name = trimLabel(label)
+  if (!template || !name) return null
+  return template.replace("%{microphone}", name)
+}