studio-engine 0.119.1 → 0.121.0

data/app/javascript/studio/voice_recorder.js

@@ -0,0 +1,352 @@
+// studio/voice_recorder: one record button that captures a take and hands the
+// finished audio to the page. It never uploads: the page listens for the take
+// event and decides where the audio goes (a chat message, a transcript, an
+// embedding). Ported from Voicebox's recorder_controller.js; the contract is in
+// docs/VOICE_CAPTURE.md.
+//
+//   <div data-studio-controller="voice-recorder" data-voice-recorder-state="idle"
+//        data-voice-recorder-max-ms="60000" data-voice-recorder-mode="toggle"
+//        data-voice-recorder-copy='{"idle":{"button":"Talk"}}'>
+//     <button type="button" data-voice-recorder-button>
+//       <span data-voice-recorder-label>Record</span></button>
+//     <span data-voice-recorder-timer>0:00</span>
+//     <p data-voice-recorder-status role="status"></p>
+//   </div>
+//
+// STATES, on data-voice-recorder-state: idle -> starting -> recording ->
+// captured | silent | failed, plus denied (the microphone was refused) and
+// unsupported (no MediaRecorder). Any of idle, captured, silent, failed and
+// denied takes a new press.
+//
+// EVENTS, dispatched on the root (they bubble):
+//   studio:voice-recorder:take    detail { blob, mimeType, durationMs, peakRms, microphone: { label, deviceId } }
+//   studio:voice-recorder:silent  detail { durationMs, microphone }  (nothing heard: no blob is handed over)
+//   studio:voice-recorder:state   detail { state }
+// and, on window, studio/microphone's EVENTS, which the chip listens to.
+//
+// MODES: "toggle" (tap to start, tap to stop) or "hold" (press and hold to
+// talk; letting go stops). While it records, --studio-recorder-level (0..1) on
+// the root drives the ring (studio/level_meter), and data-voice-recorder-heard
+// turns "true" once a frame clears SILENCE_RMS.
+import { openMicrophone, announce, silentMessage, EVENTS as MICROPHONE_EVENTS } from "studio/microphone"
+import { createLevelMeter, SILENCE_RMS } from "studio/level_meter"
+
+export const EVENTS = {
+  take: "studio:voice-recorder:take",
+  silent: "studio:voice-recorder:silent",
+  state: "studio:voice-recorder:state"
+}
+
+// What to ask MediaRecorder for, in order: webm/opus on Chrome and Firefox,
+// mp4/aac on iOS Safari. The first the browser supports wins.
+export const MIME_CANDIDATES = [
+  "audio/webm;codecs=opus",
+  "audio/webm",
+  "audio/mp4;codecs=mp4a.40.2",
+  "audio/mp4",
+  "audio/ogg;codecs=opus"
+]
+
+export const READY = ["idle", "captured", "silent", "failed", "denied"]
+
+// How long a take may stay silent before the status asks whether the
+// microphone is on.
+export const QUIET_HINT_MS = 2500
+
+export const COPY = {
+  idle: { button: "Record", status: "" },
+  starting: { button: "Starting...", status: "" },
+  recording: { button: "Stop", status: "Listening...", quiet: "I can't hear anything yet. Is your microphone on?", heard: "Listening..." },
+  captured: { button: "Record again", status: "Got it." },
+  silent: { button: "Record", status: "I couldn't hear anything. Check your microphone and try again.",
+            named: "I couldn't hear anything from %{microphone}. Pick another microphone and try again." },
+  failed: { button: "Try again", status: "That didn't record. Try again.", start: "I couldn't start recording. Try again.",
+            missing: "I couldn't find a microphone. Plug one in and try again." },
+  denied: { button: "Record", status: "Allow the microphone to record." },
+  unsupported: { button: "Record", status: "This browser can't record here. Try Safari or Chrome." }
+}
+
+export function pickMimeType(isTypeSupported) {
+  if (typeof isTypeSupported !== "function") return ""
+  return MIME_CANDIDATES.find((type) => {
+    try { return isTypeSupported(type) } catch (_) { return false }
+  }) || ""
+}
+
+export function formatElapsed(ms) {
+  const seconds = Math.max(0, Math.floor(ms / 1000))
+  return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`
+}
+
+// The page's words over the defaults, one state at a time.
+export function mergeCopy(overrides) {
+  const merged = {}
+  Object.keys(COPY).forEach((state) => { merged[state] = { ...COPY[state] } })
+  if (overrides && typeof overrides === "object") {
+    Object.entries(overrides).forEach(([state, words]) => {
+      if (words && typeof words === "object") merged[state] = { ...(merged[state] || {}), ...words }
+    })
+  }
+  return merged
+}
+
+function parseJson(text) {
+  try { return JSON.parse(text || "null") } catch (_) { return null }
+}
+
+// Binds one recorder. Returns { start, stop, toggle, destroy, get state }.
+// options.open and options.meter replace openMicrophone and createLevelMeter
+// (the unit tests pass stubs).
+export function mountVoiceRecorder(root, { win = window, open = openMicrophone, meter: makeMeter = createLevelMeter } = {}) {
+  const one = (selector) => root.querySelector(selector)
+  const copy = mergeCopy(parseJson(root.getAttribute("data-voice-recorder-copy")))
+  const maxMs = parseInt(root.getAttribute("data-voice-recorder-max-ms") || "0", 10) || 0
+  const mode = root.getAttribute("data-voice-recorder-mode") === "hold" ? "hold" : "toggle"
+  const now = () => win.performance.now()
+
+  let state = null
+  let stream = null
+  let recorder = null
+  let meter = null
+  let chunks = []
+  let timer = null
+  let startedAt = 0
+  let microphone = { label: "", deviceId: null }
+  let hinted = null
+  let stopWanted = false
+  let destroyed = false
+
+  function setState(next, message = null) {
+    state = next
+    root.dataset.voiceRecorderState = next
+    const words = copy[next] || {}
+    const label = one("[data-voice-recorder-label]")
+    if (label && words.button) label.textContent = words.button
+    const status = one("[data-voice-recorder-status]")
+    if (status) status.textContent = message || words.status || ""
+    const button = one("[data-voice-recorder-button]")
+    if (button) {
+      button.setAttribute("aria-pressed", next === "recording" ? "true" : "false")
+      button.disabled = next === "unsupported"
+    }
+    if (next === "idle") paintTimer(0)
+    root.dispatchEvent(new win.CustomEvent(EVENTS.state, { bubbles: true, detail: { state: next } }))
+  }
+
+  function supported() {
+    return !!(win.MediaRecorder && win.navigator && win.navigator.mediaDevices && win.navigator.mediaDevices.getUserMedia)
+  }
+
+  function paintLevel(level) {
+    root.style.setProperty("--studio-recorder-level", level.toFixed(3))
+    root.dataset.voiceRecorderLevel = level.toFixed(2)
+  }
+
+  function paintTimer(ms) {
+    const el = one("[data-voice-recorder-timer]")
+    if (el) el.textContent = formatElapsed(ms)
+  }
+
+  function hint(kind) {
+    if (state !== "recording" || hinted === kind || !copy.recording[kind]) return
+    hinted = kind
+    const status = one("[data-voice-recorder-status]")
+    if (status) status.textContent = copy.recording[kind]
+  }
+
+  function onSample(rms) {
+    announce(MICROPHONE_EVENTS.level, { rms }, win)
+    if (rms >= SILENCE_RMS && root.dataset.voiceRecorderHeard !== "true") {
+      root.dataset.voiceRecorderHeard = "true"
+      hint("heard")
+    } else if (root.dataset.voiceRecorderHeard !== "true" && startedAt && now() - startedAt > QUIET_HINT_MS) {
+      hint("quiet")
+    }
+    root.dataset.voiceRecorderPeak = meter ? meter.peak.toFixed(4) : "0"
+  }
+
+  function stopTimer() {
+    if (timer) win.clearInterval(timer)
+    timer = null
+  }
+
+  // Lets go of the meter and the microphone, and tells the chip.
+  function release() {
+    stopTimer()
+    if (meter) meter.close()
+    meter = null
+    if (stream) {
+      stream.getTracks().forEach((track) => track.stop())
+      announce(MICROPHONE_EVENTS.closed, {}, win)
+    }
+    stream = null
+  }
+
+  async function start() {
+    if (destroyed || !READY.includes(state)) return
+    stopWanted = false
+    setState("starting")
+    let opened
+    try {
+      opened = await open(win.navigator.mediaDevices)
+    } catch (error) {
+      if (destroyed) return
+      const denied = error && error.name === "NotAllowedError"
+      if (denied) announce(MICROPHONE_EVENTS.denied, {}, win)
+      setState(denied ? "denied" : "failed", denied ? null : copy.failed.missing)
+      return
+    }
+    stream = opened.stream
+    microphone = { label: opened.label || "", deviceId: opened.deviceId || null }
+    // Destroyed, or let go of (hold mode) before the microphone opened.
+    if (destroyed || stopWanted) {
+      release()
+      if (!destroyed) setState("idle")
+      return
+    }
+    chunks = []
+    try {
+      begin(stream)
+    } catch (_) {
+      // MediaRecorder refused the stream: let go of the microphone, the meter
+      // and its frames rather than leave them running.
+      recorder = null
+      release()
+      setState("failed", copy.failed.start)
+    }
+  }
+
+  function begin(source) {
+    root.dataset.voiceRecorderHeard = "false"
+    root.dataset.voiceRecorderPeak = "0"
+    hinted = null
+    meter = makeMeter(source, { win, onSample, onPaint: paintLevel })
+    const MediaRecorderClass = win.MediaRecorder
+    const mimeType = pickMimeType(MediaRecorderClass.isTypeSupported && MediaRecorderClass.isTypeSupported.bind(MediaRecorderClass))
+    try {
+      recorder = mimeType ? new MediaRecorderClass(source, { mimeType }) : new MediaRecorderClass(source)
+    } catch (_) {
+      recorder = new MediaRecorderClass(source)
+    }
+    recorder.addEventListener("dataavailable", (event) => {
+      if (event.data && event.data.size > 0) chunks.push(event.data)
+    })
+    recorder.addEventListener("stop", () => finish())
+    recorder.start(250)
+    startedAt = now()
+    paintTimer(0)
+    timer = win.setInterval(() => {
+      const elapsed = now() - startedAt
+      paintTimer(elapsed)
+      if (maxMs && elapsed >= maxMs) stop()
+    }, 250)
+    setState("recording")
+  }
+
+  function stop() {
+    if (state === "starting") { stopWanted = true; return }
+    if (recorder && recorder.state !== "inactive") recorder.stop()
+  }
+
+  function finish() {
+    const durationMs = Math.round(now() - startedAt)
+    stopTimer()
+    if (meter) meter.sample()
+    const heard = meter ? meter.heard() : true
+    const peakRms = meter ? meter.peak : 0
+    const type = (recorder && recorder.mimeType) || (chunks[0] && chunks[0].type) || "audio/webm"
+    const blob = new win.Blob(chunks, { type })
+    chunks = []
+    recorder = null
+    release()
+    if (destroyed) return
+    if (blob.size === 0 || !heard) {
+      setState("silent", silentMessage(copy.silent.named, microphone.label))
+      announce(MICROPHONE_EVENTS.silent, { label: microphone.label }, win)
+      root.dispatchEvent(new win.CustomEvent(EVENTS.silent, { bubbles: true, detail: { durationMs, microphone: { ...microphone } } }))
+      return
+    }
+    setState("captured")
+    root.dispatchEvent(new win.CustomEvent(EVENTS.take, {
+      bubbles: true,
+      detail: { blob, mimeType: type, durationMs, peakRms, microphone: { ...microphone } }
+    }))
+  }
+
+  function toggle() {
+    if (state === "recording" || state === "starting") stop()
+    else start()
+  }
+
+  // Buttons inside the root: the record button follows the mode.
+  function onClick(event) {
+    if (mode !== "toggle") return
+    const button = event.target.closest && event.target.closest("[data-voice-recorder-button]")
+    if (!button || !root.contains(button)) return
+    event.preventDefault()
+    toggle()
+  }
+
+  function onPointerDown(event) {
+    if (mode !== "hold") return
+    const button = event.target.closest && event.target.closest("[data-voice-recorder-button]")
+    if (!button || !root.contains(button)) return
+    event.preventDefault()
+    if (button.setPointerCapture && event.pointerId != null) {
+      try { button.setPointerCapture(event.pointerId) } catch (_) { /* a synthetic pointer */ }
+    }
+    start()
+  }
+
+  function onPointerUp() {
+    if (mode === "hold" && (state === "recording" || state === "starting")) stop()
+  }
+
+  // Hold mode by keyboard: Space or Enter held down records.
+  function onKeyDown(event) {
+    if (mode !== "hold" || event.repeat || ![" ", "Enter"].includes(event.key)) return
+    if (!event.target.closest || !event.target.closest("[data-voice-recorder-button]")) return
+    event.preventDefault()
+    start()
+  }
+
+  function onKeyUp(event) {
+    if (mode !== "hold" || ![" ", "Enter"].includes(event.key)) return
+    event.preventDefault()
+    onPointerUp()
+  }
+
+  root.addEventListener("click", onClick)
+  root.addEventListener("pointerdown", onPointerDown)
+  root.addEventListener("pointerup", onPointerUp)
+  root.addEventListener("pointercancel", onPointerUp)
+  root.addEventListener("keydown", onKeyDown)
+  root.addEventListener("keyup", onKeyUp)
+  root.dataset.voiceRecorderMode = mode
+  paintLevel(0)
+  if (supported()) setState("idle")
+  else setState("unsupported")
+  root.dataset.voiceRecorderReady = "true"
+
+  return {
+    start,
+    stop,
+    toggle,
+    get state() { return state },
+    destroy() {
+      destroyed = true
+      root.removeEventListener("click", onClick)
+      root.removeEventListener("pointerdown", onPointerDown)
+      root.removeEventListener("pointerup", onPointerUp)
+      root.removeEventListener("pointercancel", onPointerUp)
+      root.removeEventListener("keydown", onKeyDown)
+      root.removeEventListener("keyup", onKeyUp)
+      if (recorder && recorder.state !== "inactive") {
+        try { recorder.stop() } catch (_) { /* already stopped */ }
+      }
+      recorder = null
+      release()
+      delete root.dataset.voiceRecorderReady
+    }
+  }
+}

data/app/views/studio/profiles/_voice_section.html.erb

@@ -0,0 +1,108 @@
+<%# The voice row: "Set up your voice". Rendered only when Studio.voice_profile
+    is on and the user has the voice columns (lib/studio/profile_sections.rb).
+
+    Locals: user (required); embedder (optional, defaults to
+    Studio.voice_embedder: the browser e2e lab passes "fake" rather than write
+    the process-wide setting).
+
+    THE DEVICE DOES THE LISTENING. Three phrases are recorded one at a time;
+    studio/voice_profile turns each take into a speaker embedding in the browser,
+    drops the audio, and Save posts only the vectors to /profile/voice, where
+    Studio::VoiceMatch averages them into one voice on this user. Nothing here
+    uploads a recording.
+
+    WITHOUT JAVASCRIPT the row still says whether a voice is saved and still
+    deletes it: the summary and the Delete form are plain HTML. Only recording
+    needs the controller (lazy, studio/stimulus). If it fails to load, the row
+    carries data-studio-controller-failed="voice-profile" and says so.
+
+    SCOPED CSS rather than utilities, as in _identity_styles: the meter ring and
+    the phrase marks must render in an app whose Tailwind build never saw this
+    file. The ring reads --studio-voice-level (0..1), which the module writes
+    while a take records. %>
+<% embedder = local_assigns.fetch(:embedder, Studio.voice_embedder).to_s %>
+<% config = Studio::VoiceMatch.browser_config(embedder) %>
+<% saved = user.voice_embedding.present? %>
+<% current = saved && user.voice_embedding_model.to_s == config["id"] %>
+
+<style>
+  .studio-voice-consent { font-size: .8125rem; color: var(--color-text-secondary, inherit); margin-bottom: 1rem; }
+  .studio-voice-lead { margin-bottom: .5rem; }
+  .studio-voice-row { display: flex; align-items: center; justify-content: space-between; gap: .75rem; flex-wrap: wrap; }
+  .studio-voice-actions { display: flex; align-items: center; gap: .5rem; flex-wrap: wrap; }
+  .studio-voice-phrases { list-style: none; padding: 0; margin: 0 0 1rem; display: grid; gap: .5rem; }
+  .studio-voice-phrase { display: flex; align-items: center; gap: .75rem; padding: .75rem; border-radius: .75rem;
+    border: 1px solid var(--color-border, rgb(127 127 127 / .25)); }
+  .studio-voice-phrase[data-phrase-state="current"] { outline: 2px solid rgb(var(--color-primary-500-rgb, 99 102 241)); outline-offset: 1px; }
+  .studio-voice-mark { flex-shrink: 0; width: 1.75rem; height: 1.75rem; border-radius: 9999px; display: flex;
+    align-items: center; justify-content: center; font-size: .8125rem; font-weight: 700;
+    border: 1px solid var(--color-border, rgb(127 127 127 / .25)); color: var(--color-text-secondary, inherit); }
+  .studio-voice-phrase[data-phrase-state="done"] .studio-voice-mark { background: #10b981; border-color: #10b981; color: #fff; }
+  .studio-voice-controls { display: flex; flex-direction: column; align-items: center; gap: .75rem; text-align: center; }
+  .studio-voice-record { min-width: 12rem; border-radius: 9999px; padding: .875rem 1.75rem; font-weight: 700;
+    color: #fff; background: rgb(var(--color-primary-500-rgb, 99 102 241));
+    box-shadow: 0 0 0 calc(var(--studio-voice-level, 0) * 14px) rgb(var(--color-primary-500-rgb, 99 102 241) / .3);
+    transition: box-shadow 80ms linear; }
+  .studio-voice-record:disabled { opacity: .5; cursor: not-allowed; }
+  [data-voice-state="recording"] .studio-voice-record { background: #dc2626; }
+  @media (prefers-reduced-motion: reduce) { .studio-voice-record { transition: none; } }
+  .studio-voice-status { min-height: 2.5rem; max-width: 24rem; color: var(--color-text-body, inherit); }
+  .studio-voice-failed { display: none; font-size: .8125rem; color: var(--color-text-secondary, inherit); }
+  [data-studio-controller-failed~="voice-profile"] .studio-voice-failed { display: block; }
+</style>
+
+<div data-studio-controller="voice-profile"
+     data-voice-state="idle"
+     data-voice-save-url="<%= profile_voice_path %>"
+     data-voice-embedder="<%= config.to_json %>">
+  <p class="studio-voice-consent" data-voice-consent>
+    This saves a voice pattern, not a recording. Your device listens to three short phrases and keeps
+    only numbers that describe how you sound, so your agent can tell it's you. Delete it any time.
+  </p>
+
+  <div class="studio-voice-row" data-voice-summary>
+    <p class="text-body min-w-0" data-voice-saved="<%= current ? "current" : (saved ? "stale" : "none") %>">
+      <% if current %>
+        Your voice is set up<% if user.voice_embedding_updated_at %> (<%= user.voice_embedding_updated_at.to_date.to_fs(:long) %>)<% end %>.
+      <% elsif saved %>
+        Your saved voice came from an older model. Record it again to keep using it.
+      <% else %>
+        Read three short phrases so your agent knows your voice.
+      <% end %>
+    </p>
+    <div class="studio-voice-actions">
+      <button type="button" class="btn btn-primary btn-sm" data-voice-action="open">
+        <%= saved ? "Re-record" : "Set up your voice" %>
+      </button>
+      <% if saved %>
+        <%= button_to "Delete", profile_voice_path, method: :delete,
+                      class: "btn btn-sm", form: { class: "inline", data: { voice_delete: true } } %>
+      <% end %>
+    </div>
+  </div>
+  <p class="studio-voice-failed">Recording didn't load on this page. Reload to try again.</p>
+
+  <div data-voice-setup hidden>
+    <p class="studio-voice-lead text-sm font-semibold text-heading">Read each one out loud</p>
+    <ol class="studio-voice-phrases">
+      <% Studio::VoiceMatch::PHRASES.each_with_index do |phrase, i| %>
+        <li class="studio-voice-phrase" data-voice-phrase data-phrase-state="waiting">
+          <span class="studio-voice-mark" aria-hidden="true"><%= i + 1 %></span>
+          <span class="text-body">&ldquo;<%= phrase %>&rdquo;</span>
+        </li>
+      <% end %>
+    </ol>
+
+    <div class="studio-voice-controls">
+      <button type="button" class="studio-voice-record" data-voice-action="record" data-voice-record
+              aria-pressed="false" disabled>
+        <span data-voice-record-label>Record phrase 1</span>
+      </button>
+      <p class="studio-voice-status" data-voice-status role="status" aria-live="polite"></p>
+      <div class="studio-voice-actions">
+        <button type="button" class="btn btn-primary btn-sm" data-voice-action="save" data-voice-save disabled>Save</button>
+        <button type="button" class="btn btn-sm" data-voice-action="cancel">Cancel</button>
+      </div>
+    </div>
+  </div>
+</div>

data/app/views/studio/voice/_microphone_chip.html.erb

@@ -0,0 +1,45 @@
+<%# The microphone chip (docs/VOICE_CAPTURE.md): names the microphone the page
+    records from, and a tap lists every microphone, the one in use marked, to
+    pick from (studio/microphone_chip, studio/microphone). While a take records
+    the dot beside the name shows the live level, so a dead microphone is
+    visible at a glance. Help: studio/voice/_microphone_help, inside it.
+
+    Locals, all optional:
+      copy:        overrides merged over Studio::VoiceCapture::MICROPHONE_COPY
+      storage_key: where the pick is remembered (default "studio.microphone")
+      id:          the picker's id, for aria-controls (one chip per page needs
+                   none; two chips need two ids)
+
+    The chip never opens the microphone: a recorder (studio/voice/_recorder or
+    any studio/voice_recorder) does, and the chip listens on window. The
+    controller is lazy (studio/stimulus); if it fails to load, the root carries
+    data-studio-controller-failed="microphone-chip" and says that picking a
+    microphone did not load (the recorder still uses the system default). %>
+<% copy = Studio::VoiceCapture.microphone_copy(local_assigns[:copy]) %>
+<% picker_id = local_assigns.fetch(:id, "studio-microphone-picker") %>
+<% storage_key = local_assigns.fetch(:storage_key, Studio::VoiceCapture::STORAGE_KEY) %>
+<%= render "studio/voice/styles" %>
+<div class="studio-mic"
+     data-studio-controller="microphone-chip"
+     data-microphone-state="prompt"
+     data-microphone-storage-key="<%= storage_key %>"
+     data-microphone-copy="<%= copy.to_json %>">
+  <button type="button" class="studio-mic-chip" data-microphone-chip aria-expanded="false" aria-controls="<%= picker_id %>">
+    <svg class="studio-mic-icon" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+      <path d="M12 2a3.5 3.5 0 0 0-3.5 3.5v6a3.5 3.5 0 0 0 7 0v-6A3.5 3.5 0 0 0 12 2Z"/>
+      <path d="M6 10.5a1 1 0 1 0-2 0 8 8 0 0 0 7 7.94V21H8.5a1 1 0 1 0 0 2h7a1 1 0 1 0 0-2H13v-2.56a8 8 0 0 0 7-7.94 1 1 0 1 0-2 0 6 6 0 0 1-12 0Z"/>
+    </svg>
+    <span class="studio-mic-dot" data-microphone-dot aria-hidden="true"></span>
+    <span class="studio-mic-name" data-microphone-label><%= copy.dig("prompt", "chip") %></span>
+    <svg class="studio-mic-caret" viewBox="0 0 12 12" fill="currentColor" aria-hidden="true">
+      <path d="M2.2 4.2a.75.75 0 0 1 1.06 0L6 6.94l2.74-2.74a.75.75 0 1 1 1.06 1.06L6.53 8.53a.75.75 0 0 1-1.06 0L2.2 5.26a.75.75 0 0 1 0-1.06Z"/>
+    </svg>
+  </button>
+  <div id="<%= picker_id %>" class="studio-mic-panel card" data-microphone-panel hidden>
+    <p class="studio-mic-note" data-microphone-note role="status"><%= copy.dig("prompt", "note") %></p>
+    <ul class="studio-mic-list" data-microphone-list aria-label="Microphones"></ul>
+    <button type="button" class="studio-mic-help-link" data-microphone-help-link><%= copy.dig("help", "link") %></button>
+  </div>
+  <p class="studio-mic-failed"><%= copy["unavailable"] %></p>
+  <%= render "studio/voice/microphone_help", copy: copy, title_id: "#{picker_id}-help-title" %>
+</div>

data/app/views/studio/voice/_microphone_help.html.erb

@@ -0,0 +1,63 @@
+<%# "How to change your microphone in Chrome": a native modal <dialog> inside
+    the microphone chip (studio/voice/_microphone_chip). showModal() makes the
+    page behind it inert, so focus stays inside; Esc and Close shut it, and
+    focus goes back where it was (studio/microphone_chip). It opens after a
+    switch, on a refused microphone, on the second silent take in a row on one
+    microphone, and from the picker's help link. The lead line on top says
+    which; the browser decides between Chrome's steps and one generic line
+    (browserFamily, studio/microphone). The picture is a drawn, simplified
+    address bar, never a screenshot.
+
+    Locals: copy (the chip's merged copy), title_id. %>
+<% help = copy.fetch("help") %>
+<dialog class="studio-mic-help" data-microphone-dialog aria-labelledby="<%= title_id %>">
+  <div class="studio-mic-help-body">
+    <div class="studio-mic-help-lead" data-microphone-help-lead hidden>
+      <p class="studio-mic-help-headline" data-microphone-help-headline></p>
+      <p class="studio-mic-help-tip" data-microphone-help-tip></p>
+    </div>
+
+    <h2 id="<%= title_id %>" class="studio-mic-help-title" data-microphone-help-title><%= help.fetch("title_chrome") %></h2>
+
+    <div class="studio-mic-help-chrome" data-microphone-help-chrome>
+      <svg class="studio-mic-mock" viewBox="0 0 320 168" role="img" aria-label="A drawing of Chrome's address bar: the site settings icon left of the address is circled, and below it the Microphone setting is on with its list of microphones.">
+        <rect x="4" y="6" width="312" height="36" rx="18" class="mock-bar"/>
+        <circle cx="26" cy="24" r="14" class="mock-ring"/>
+        <g class="mock-ink" stroke-width="2" stroke-linecap="round">
+          <line x1="19" y1="20" x2="33" y2="20"/><circle cx="23" cy="20" r="2.5" class="mock-knob"/>
+          <line x1="19" y1="28" x2="33" y2="28"/><circle cx="29" cy="28" r="2.5" class="mock-knob"/>
+        </g>
+        <text x="48" y="29" class="mock-text" font-size="13"><%= request.host %></text>
+        <rect x="12" y="54" width="232" height="106" rx="10" class="mock-panel"/>
+        <g class="mock-ink" stroke-width="2" fill="none" stroke-linecap="round" stroke-linejoin="round">
+          <rect x="26" y="68" width="8" height="13" rx="4"/><path d="M23 77a7 7 0 0 0 14 0M30 84v4"/>
+        </g>
+        <text x="46" y="82" class="mock-text" font-size="13" font-weight="600">Microphone</text>
+        <rect x="196" y="70" width="34" height="18" rx="9" class="mock-on"/>
+        <circle cx="221" cy="79" r="6" class="mock-knob-on"/>
+        <rect x="26" y="102" width="204" height="44" rx="8" class="mock-ring"/>
+        <text x="38" y="129" class="mock-text" font-size="12">MacBook Pro Microphone</text>
+        <path d="M212 120l5 5 5-5" class="mock-ink" stroke-width="2" fill="none" stroke-linecap="round"/>
+        <g font-size="11" font-weight="700" text-anchor="middle">
+          <circle cx="50" cy="8" r="8" class="mock-badge"/><text x="50" y="12" class="mock-badge-text">1</text>
+          <circle cx="252" cy="70" r="8" class="mock-badge"/><text x="252" y="74" class="mock-badge-text">2</text>
+          <circle cx="252" cy="118" r="8" class="mock-badge"/><text x="252" y="122" class="mock-badge-text">3</text>
+        </g>
+      </svg>
+      <ol class="studio-mic-help-steps" data-microphone-help-steps>
+        <% help.fetch("steps_chrome").each_with_index do |step, i| %>
+          <li>
+            <span class="studio-mic-step" aria-hidden="true"><%= i + 1 %></span>
+            <span><%= step %></span>
+          </li>
+        <% end %>
+      </ol>
+    </div>
+
+    <p class="studio-mic-help-other" data-microphone-help-other hidden><%= help.fetch("other") %></p>
+
+    <form method="dialog" class="studio-mic-help-actions">
+      <button type="submit" class="btn btn-primary studio-mic-help-close" data-microphone-help-close><%= help.fetch("close") %></button>
+    </form>
+  </div>
+</dialog>

data/app/views/studio/voice/_recorder.html.erb

@@ -0,0 +1,34 @@
+<%# The record button (docs/VOICE_CAPTURE.md): studio/voice_recorder opens the
+    microphone through studio/microphone (so it records from what the chip
+    names), runs the engine's one level meter (studio/level_meter) as the ring
+    around the button, refuses a silent take, and hands a heard take to the page
+    as a studio:voice-recorder:take event with the blob. It uploads nothing:
+    the page that renders it decides where the audio goes.
+
+    Locals, all optional:
+      copy:   per-state words merged over studio/voice_recorder's COPY
+              (e.g. { "idle" => { "button" => "Talk" } })
+      mode:   "toggle" (tap to start, tap to stop; the default) or "hold"
+              (press and hold to talk)
+      max_ms: stop a take on its own after this long (default 60000)
+      id:     an id for the root, for a page's own listener
+
+    The controller is lazy (studio/stimulus); if it fails to load, the root
+    carries data-studio-controller-failed="voice-recorder" and says so. %>
+<% copy = Studio::VoiceCapture.recorder_copy(local_assigns[:copy]) %>
+<% mode = local_assigns.fetch(:mode, "toggle").to_s == "hold" ? "hold" : "toggle" %>
+<%= render "studio/voice/styles" %>
+<div class="studio-recorder"
+     <%= tag.attributes(id: local_assigns[:id]) %>
+     data-studio-controller="voice-recorder"
+     data-voice-recorder-state="idle"
+     data-voice-recorder-mode="<%= mode %>"
+     data-voice-recorder-max-ms="<%= local_assigns.fetch(:max_ms, 60_000).to_i %>"
+     data-voice-recorder-copy="<%= copy.except("unavailable").to_json %>">
+  <button type="button" class="studio-recorder-button" data-voice-recorder-button aria-pressed="false">
+    <span data-voice-recorder-label><%= copy.dig("idle", "button") %></span>
+  </button>
+  <span class="studio-recorder-timer" data-voice-recorder-timer aria-hidden="true">0:00</span>
+  <p class="studio-recorder-status" data-voice-recorder-status role="status" aria-live="polite"></p>
+  <p class="studio-recorder-failed"><%= copy["unavailable"] %></p>
+</div>