studio-engine 0.119.1 → 0.121.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 327664450f0c0b1de0a01b75231b2f2fa470ab66d865f3b585eb55281e3318d3
-  data.tar.gz: 0634a4d5e519e0a808558cd3341d192ab7c0162373ad46d376e6cd6753a1f432
+  metadata.gz: 161d3e00f32dba8b6c36d769228b39815a79b85a702d76b80f89be4c4365b876
+  data.tar.gz: a56e3fe6902119b4e5ecba61c77347a95893c04c3d8a5543833246b0a674c38f
 SHA512:
-  metadata.gz: 75317c813644a660eb548ddd2ee7727371b7df3520867ef0037449a7d68bb57a72c5e0c87eb767b56426459f627809f17dd2dacd8d56baf9ffd41226337c7368
-  data.tar.gz: ba9ee2c20c1edf6659186b89a30a44a80c5cc3e4c4afd3b44910bdc934922c82d0250995996746b8ecc12976690d6ca5f8880dcae6f1caab7a149471a8808307
+  metadata.gz: 4c9506dfec92c4174d85f3d03002d63d222b42c1be0866184a6551faa075471aec3440265e7623378d804e0b7f4dd6eb9e7978ab50f8403ce4edabb8be186df2
+  data.tar.gz: 9ec9cfde7907b0c5dd09a0c19cda518da4fc6341c32003bdda71debdd0ff8de4a13c4091936223d646713c98d7e87c7201550ff725f8f8aecedaf6e53563e962

data/CHANGELOG.md

@@ -4,6 +4,67 @@ 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
+
+- **Voice profile on `/profile`, opt-in.** `config.voice_profile = true` adds a
+  "Your voice" row: the signed-in user reads three phrases while a live level
+  meter shows the microphone being heard, silent takes are refused, and each
+  take becomes a speaker embedding on the device (WeSpeaker ResNet34 int8 from
+  Hugging Face at a pinned revision, through transformers.js 3.7.6 from
+  jsDelivr). Save posts only the three vectors (`POST /profile/voice`); the
+  server averages them onto the user's own record. Re-record and Delete
+  (`DELETE /profile/voice`) are on the row, with a consent line saying what is
+  stored. A new host-table migration, `add_voice_profile_to_users`, adds
+  `voice_embedding`, `voice_embedding_model` and `voice_embedding_updated_at`.
+  `Studio::VoiceMatch.identify(embedding, among:, model:)` returns the closest
+  user at or above 0.6 cosine, else nil, comparing only voices from the same
+  model. `config.voice_embedder = "fake"` is the test embedder
+  (`window.studioFakeVoice`). docs/VOICE_PROFILE.md lists the CSP and privacy
+  changes a host makes first.
+
 ## 0.119.1 — 2026-10-29
 
 ### Fixed

data/README.md

@@ -45,6 +45,9 @@ resolved.
 - **Transactional emails**: `Studio::EmailCatalog` — every email an app sends, its type, a live preview, and its banner — plus the shared `/admin/emails` page. Every app inherits the standard emails and their artwork on day one, and can register its own workflows and upload its own banners. See [Transactional emails](#transactional-emails).
 - **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/profiles_controller.rb

@@ -202,8 +202,64 @@ module Studio
       end
     end
 
+    # POST /profile/voice — save (or replace) the signed-in user's voice.
+    #
+    # THE BODY IS VECTORS, NEVER AUDIO. The page records three phrases, turns
+    # each into a speaker embedding on the device (studio/voice_profile) and
+    # drops the takes; this receives `voice[model]` and `voice[embeddings]` (a
+    # JSON array of Studio::VoiceMatch::TAKES vectors) and averages them here.
+    #
+    # The model must be the one this app runs (Studio.voice_embedder), so a page
+    # cannot save vectors from an embedder the matcher would never compare, and
+    # the test embedder can never be saved where the real one runs. A take that
+    # embedded to all zeros (silence the browser let through) is refused by
+    # VoiceMatch.enrol.
+    #
+    # Answers JSON for the page's fetch and redirects for anything else.
+    def save_voice
+      return voice_refused("This app has no voice profile to set up.", :not_found) unless row_rendered?(:voice)
+
+      embedder = Studio.voice_embedder.to_s
+      model = params.dig(:voice, :model).to_s
+      unless model == Studio::VoiceMatch.model_id(embedder)
+        return voice_refused("That voice came from a different model. Reload the page and record again.")
+      end
+
+      vector = Studio::VoiceMatch.enrol(params.dig(:voice, :embeddings), size: Studio::VoiceMatch.size(embedder))
+      if vector.nil?
+        return voice_refused("We couldn't use those recordings. Read all three phrases again.")
+      end
+
+      rescue_and_log(target: current_user) do
+        current_user.update!(voice_embedding: vector, voice_embedding_model: model,
+                             voice_embedding_updated_at: Time.current)
+        respond_to do |format|
+          format.json { render json: { url: profile_path }, status: :ok }
+          format.any  { redirect_to profile_path, notice: "Your voice is set up.", status: :see_other }
+        end
+      end
+    end
+
+    # DELETE /profile/voice — remove the stored voice entirely: the vector, its
+    # model and its date. Nothing of it is kept.
+    def delete_voice
+      return unsupported("voice profile") unless row_rendered?(:voice)
+
+      rescue_and_log(target: current_user) do
+        current_user.update!(voice_embedding: nil, voice_embedding_model: nil, voice_embedding_updated_at: nil)
+        redirect_to profile_path, notice: "Your voice was deleted.", status: :see_other
+      end
+    end
+
     private
 
+    def voice_refused(message, status = :unprocessable_entity)
+      respond_to do |format|
+        format.json { render json: { error: message }, status: status }
+        format.any  { redirect_to profile_path, alert: message, status: :see_other }
+      end
+    end
+
     # Tell the host, and NEVER let it break the subscription.
     #
     # The subscription is the durable fact; the reaction is not. turf-monster's

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_profile_controller.js

@@ -0,0 +1,20 @@
+// voice-profile: the voice row on /profile (studio/profiles/_voice_section), on
+// the engine's Stimulus application (studio/stimulus registers it lazily, the
+// first time a page renders the row). It sits on the row's wrapper:
+//
+//   <div data-studio-controller="voice-profile" data-voice-save-url="/profile/voice" ...>
+//
+// The recording, the meter, the embedding and the save are studio/voice_profile.
+import { Controller } from "@hotwired/stimulus"
+import { mountVoiceProfile } from "studio/voice_profile"
+
+export default class extends Controller {
+  connect() {
+    this.voice = mountVoiceProfile(this.element)
+  }
+
+  disconnect() {
+    if (this.voice) this.voice.destroy()
+    this.voice = 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 }
+  }
+}