studio-engine 0.120.0 → 0.122.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 602092c1d8ddd3ce61cb6f192162ea1cae13af1313769742fa88d5f954327232
-  data.tar.gz: 6a2ca70d13097ebfe23e52c7b14d551b430f92ef07da51bed9c1b80f1baa522c
+  metadata.gz: cd0f77b33c7833a6cb5061bc17b11baad3db5ad3b2e6ad232b31cc363d124e49
+  data.tar.gz: 942b24a25b2dbdb8d7e1af5a918c323718fcb2438eced8b46dd1593f1563d9a0
 SHA512:
-  metadata.gz: 5e8a55b6e21888c67df80712062478ae4b635a4a95d2e062771ab00570f5cd9ba417601e05ab39f14791be16619c3780799d965d2c02491952386001dd6b6f18
-  data.tar.gz: 7abef1323bfc65d590af8c5cef094d7136471e6f0356703b6a1fd73c1bb3137d76b70051b500f6ddab24c4d092d3812f3ae82e766123dbf728c15b28dbd410a4
+  metadata.gz: 2d81f612a81ddb2d5e9ccdf6c85d4e4cea1bd47043ba5e0c9732202f55e39489b44059646e8f42848530525c2c4c8f23ecd299afeb322b43adb3dd3bb513ff1a
+  data.tar.gz: 3f6a3214f4a5a80cfc2c73453dd0429161f28879ba3bd41857160ab02c2f70bb633213d317c19d9026e786afb7d99c37ddc5e6e1da2793d8edf495fa976f216d

data/CHANGELOG.md

@@ -4,6 +4,90 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.122.0 — 2026-11-01
+
+### Added
+
+- **`POST /voice/takes` is rate-limited per user.** `Studio.voice_takes_rate_limit`
+  (default `{ to: 20, within: 600 }`, a fixed window per user id; `store:`
+  optional; `false` turns it off). Over it: a JSON `429`
+  `{error, reason: "rate_limited", retry_after}` with `Retry-After`, before the
+  take is read or transcribed. On a `NullStore` cache it counts in a per-process
+  memory store rather than going inert.
+- **One deadline per take at the vendor.** `Studio.voice_transcribe_deadline`
+  (25 s) covers both models together; every socket timeout is what is left of
+  it, and a hard timeout backs it (the old 10 s + 120 s per attempt could hold a
+  Puma thread about 260 s).
+- `Studio::VoiceTranscription::HttpError#reason` (`unauthorized`,
+  `rate_limited`, `server_error`, `rejected`, `timeout`, `unreachable`).
+- The recorder's `failed.busy` line: a microphone another app holds
+  (`NotReadableError`) reads "Your microphone is busy in another app. Close it
+  there, then try again.", not "I couldn't find a microphone".
+
+### Changed
+
+- **Voice reads its own key.** `Studio.voice_openai_api_key`, else
+  `STUDIO_VOICE_OPENAI_API_KEY`; the app's shared `OPENAI_API_KEY` is no longer
+  read. An app that turned voice on with `OPENAI_API_KEY` alone sets
+  `STUDIO_VOICE_OPENAI_API_KEY` (until then a take answers the 503
+  `not_configured`).
+- The `whisper-1` fallback no longer runs after a timeout, a vendor 429, or no
+  answer at all, nor with under 2 s of the deadline left.
+- `HttpError` messages, and so `ErrorLog` rows, carry the model, the status and
+  a reason code, never the vendor's error text. The row's `target` is the user
+  who sent the take.
+- Microphone picker: Esc in the open list returns focus to the chip; options
+  drop `aria-pressed` (the one in use keeps `aria-current`); options and the
+  help link wear the chip's 3px focus ring; the help's address-bar drawing shows
+  a drawn bar instead of printing `request.host`.
+
+### Fixed
+
+- A `voice` param that is a string or a list answers `422`, not `500`.
+- The no-live-calls trap reads `URI#hostname`, so an IPv6 loopback endpoint
+  (`http://[::1]:…`) counts as this machine.
+
+## 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,146 @@
+# 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.
+  #
+  # RATE-LIMITED per user (Studio.voice_takes_rate_limit, 20 takes in 10
+  # minutes): over it, a JSON 429 {error, reason: "rate_limited", retry_after}
+  # and a Retry-After header, before anything is read or transcribed.
+  #
+  # 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
+    before_action :limit_takes
+
+    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."
+    TOO_MANY = "That's a lot of recordings in a short time. Wait a moment, then try again."
+
+    # The counter's fallback when the app's Rails.cache counts nothing (a
+    # NullStore, as many apps run in development): per process, so a limit
+    # still holds.
+    FALLBACK_STORE = ActiveSupport::Cache::MemoryStore.new(size: 4.megabytes)
+
+    def create
+      voice = params[:voice]
+      # A string (voice=abc) or an array is no take: refuse it, never index it.
+      voice = nil unless voice.is_a?(ActionController::Parameters)
+      audio = voice ? 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
+
+    # The per-user limit, a fixed window: the window's number is in the key, so
+    # its end (retry_after) is known exactly. Rails' own rate_limit macro fixes
+    # to:/within: when the class loads and counts nothing on a NullStore; this
+    # reads the config per request and never goes inert. It instruments the same
+    # rate_limit.action_controller event.
+    def limit_takes
+      limit = Studio.voice_takes_rate_limit
+      return unless limit && current_user
+
+      limit = limit.to_h.transform_keys(&:to_sym)
+
+      to = limit[:to].to_i
+      within = limit[:within].to_i
+      return unless to.positive? && within.positive?
+
+      epoch = Time.now.to_i
+      window = epoch / within
+      key = "rate-limit:#{controller_path}:#{current_user.id}:#{window}"
+      count = rate_limit_store(limit).increment(key, 1, expires_in: within)
+      return if count.nil? || count <= to
+
+      retry_after = within - (epoch % within)
+      ActiveSupport::Notifications.instrument("rate_limit.action_controller",
+                                              request: request, count: count, to: to, within: within,
+                                              by: current_user.id, name: nil, scope: controller_path, cache_key: key) do
+        response.headers["Retry-After"] = retry_after.to_s
+        refuse(TOO_MANY, :too_many_requests, reason: "rate_limited", retry_after: retry_after)
+      end
+    end
+
+    def rate_limit_store(limit)
+      store = limit[:store] || (Rails.cache if defined?(Rails.cache))
+      store.nil? || store.is_a?(ActiveSupport::Cache::NullStore) ? FALLBACK_STORE : store
+    end
+
+    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
+
+    # An ErrorLog row on the user who sent the take. The error's message is the
+    # engine's own words (model, status, reason code), never the vendor's.
+    def capture(error)
+      return unless defined?(::ErrorLog) && ::ErrorLog.respond_to?(:capture!)
+
+      log = ::ErrorLog.capture!(error)
+      log.update(target: current_user) if log.respond_to?(:target=) && current_user
+    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 }
+  }
+}