studio-engine 0.121.0 → 0.122.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 161d3e00f32dba8b6c36d769228b39815a79b85a702d76b80f89be4c4365b876
-  data.tar.gz: a56e3fe6902119b4e5ecba61c77347a95893c04c3d8a5543833246b0a674c38f
+  metadata.gz: cd0f77b33c7833a6cb5061bc17b11baad3db5ad3b2e6ad232b31cc363d124e49
+  data.tar.gz: 942b24a25b2dbdb8d7e1af5a918c323718fcb2438eced8b46dd1593f1563d9a0
 SHA512:
-  metadata.gz: 4c9506dfec92c4174d85f3d03002d63d222b42c1be0866184a6551faa075471aec3440265e7623378d804e0b7f4dd6eb9e7978ab50f8403ce4edabb8be186df2
-  data.tar.gz: 9ec9cfde7907b0c5dd09a0c19cda518da4fc6341c32003bdda71debdd0ff8de4a13c4091936223d646713c98d7e87c7201550ff725f8f8aecedaf6e53563e962
+  metadata.gz: 2d81f612a81ddb2d5e9ccdf6c85d4e4cea1bd47043ba5e0c9732202f55e39489b44059646e8f42848530525c2c4c8f23ecd299afeb322b43adb3dd3bb513ff1a
+  data.tar.gz: 3f6a3214f4a5a80cfc2c73453dd0429161f28879ba3bd41857160ab02c2f70bb633213d317c19d9026e786afb7d99c37ddc5e6e1da2793d8edf495fa976f216d

data/CHANGELOG.md

@@ -4,6 +4,49 @@ 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

data/app/controllers/studio/voice_takes_controller.rb

@@ -19,6 +19,10 @@ module Studio
   # 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
@@ -27,13 +31,22 @@ module Studio
     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]
-      audio = voice.respond_to?(:[]) ? voice[:audio] : nil
+      # 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
@@ -68,6 +81,41 @@ module Studio
 
     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
@@ -84,8 +132,13 @@ module Studio
       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)
-      ::ErrorLog.capture!(error) if defined?(::ErrorLog) && ::ErrorLog.respond_to?(:capture!)
+      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

data/app/javascript/studio/microphone_chip.js

@@ -193,7 +193,8 @@ export function mountMicrophoneChip(root, { win = window } = {}) {
       button.type = "button"
       button.className = "studio-mic-option"
       button.dataset.microphoneOption = choice.deviceId
-      button.setAttribute("aria-pressed", inUse ? "true" : "false")
+      // aria-current marks the one in use; aria-pressed would make each option
+      // a toggle, which picking is not.
       if (inUse) button.setAttribute("aria-current", "true")
       const mark = doc.createElement("span")
       mark.className = "studio-mic-check"
@@ -333,12 +334,15 @@ export function mountMicrophoneChip(root, { win = window } = {}) {
     if (chip && target.closest("[data-microphone-chip]") === chip) toggle()
   }
 
-  // Esc closes the list, but an Esc inside the help dialog is the dialog's: it
-  // shuts the dialog and leaves the list where it was.
+  // Esc closes the list and hands focus back to the chip, so a keyboard user
+  // is not left on an option that just vanished. An Esc inside the help dialog
+  // is the dialog's: it shuts the dialog and leaves the list where it was.
   function onKey(event) {
     if (event.key !== "Escape") return
     if (dialog && dialog.contains(event.target)) return
+    if (!panel || panel.hidden) return
     closePanel()
+    if (chip) chip.focus()
   }
 
   const onDeviceChange = () => refresh()

data/app/javascript/studio/voice_profile.js

@@ -58,6 +58,7 @@ export const MESSAGES = {
   silent: "I couldn't hear that one. Check your microphone and read it again.",
   failed: "That one didn't work. Tap Record and read it again.",
   denied: "Allow the microphone to set up your voice.",
+  busy: "Your microphone is busy in another app. Close it there, then try again.",
   unsupported: "This browser can't record here. Try Safari or Chrome.",
   network: "We couldn't reach the server. Tap Save again.",
   notSaved: "That didn't save. Tap Save again."
@@ -65,6 +66,15 @@ export const MESSAGES = {
 
 export class SilentTakeError extends Error {}
 
+// Why the microphone would not open: refused, held by another app
+// (NotReadableError; Chrome's older TrackStartError), or anything else.
+export function openFailure(error) {
+  const name = error && error.name
+  if (name === "NotAllowedError") return MESSAGES.denied
+  if (name === "NotReadableError" || name === "TrackStartError") return MESSAGES.busy
+  return MESSAGES.failed
+}
+
 // The words for a state, with {n} the phrase being read (1-based).
 export function copyFor(state, step) {
   const [button, status] = COPY[state] || ["Try again", ""]
@@ -304,7 +314,7 @@ export function mountVoiceProfile(root, win = window) {
     try {
       stream = await win.navigator.mediaDevices.getUserMedia({ audio: true })
     } catch (error) {
-      setState("ready", error && error.name === "NotAllowedError" ? MESSAGES.denied : MESSAGES.failed)
+      setState("ready", openFailure(error))
       return
     }
     if (destroyed || state !== "ready") { release(); return }

data/app/javascript/studio/voice_recorder.js

@@ -61,7 +61,8 @@ export const COPY = {
   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." },
+            missing: "I couldn't find a microphone. Plug one in and try again.",
+            busy: "Your microphone is busy in another app. Close it there, then 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." }
 }
@@ -78,6 +79,16 @@ export function formatElapsed(ms) {
   return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`
 }
 
+// The line for a microphone that would not open (NotAllowedError is "denied",
+// not this). NotReadableError is a microphone another app holds (Chrome's
+// older name, TrackStartError); everything else reads as no microphone found.
+export const BUSY_ERRORS = ["NotReadableError", "TrackStartError"]
+
+export function failedLine(error, copy = COPY) {
+  const busy = !!error && BUSY_ERRORS.includes(error.name)
+  return busy ? (copy.failed.busy || COPY.failed.busy) : copy.failed.missing
+}
+
 // The page's words over the defaults, one state at a time.
 export function mergeCopy(overrides) {
   const merged = {}
@@ -193,7 +204,7 @@ export function mountVoiceRecorder(root, { win = window, open = openMicrophone,
       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)
+      setState(denied ? "denied" : "failed", denied ? null : failedLine(error, copy))
       return
     }
     stream = opened.stream

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

@@ -27,7 +27,9 @@
           <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>
+        <%# The address is a drawn bar, not this app's host: the drawing is the
+            same on every app, and renders without a request. %>
+        <rect x="48" y="19" width="132" height="10" rx="5" class="mock-address"/>
         <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"/>

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

@@ -32,6 +32,9 @@
     border: 1px solid transparent; background: transparent; padding: .5rem .75rem; text-align: left; font-size: .875rem;
     color: var(--color-text, inherit); cursor: pointer; }
   .studio-mic-option:hover { background-color: rgb(var(--color-primary-500-rgb, 99 102 241) / .08); }
+  /* The same 3px ring as the chip on every control in the picker. */
+  .studio-mic-option:focus-visible, .studio-mic-help-link:focus-visible {
+    outline: 3px solid rgb(var(--color-primary-500-rgb, 99 102 241) / .5); outline-offset: 2px; }
   .studio-mic-option[aria-current="true"] { border-color: rgb(var(--color-primary-500-rgb, 99 102 241));
     background-color: rgb(var(--color-primary-500-rgb, 99 102 241) / .12); font-weight: 600; }
   .studio-mic-check { width: 1rem; flex-shrink: 0; font-weight: 700; color: rgb(var(--color-primary-500-rgb, 99 102 241)); }
@@ -64,6 +67,7 @@
   .studio-mic-mock .mock-ink { stroke: currentColor; }
   .studio-mic-mock .mock-knob { fill: currentColor; stroke: none; }
   .studio-mic-mock .mock-text { fill: currentColor; font-family: inherit; }
+  .studio-mic-mock .mock-address { fill: currentColor; fill-opacity: .3; }
   .studio-mic-mock .mock-on, .studio-mic-mock .mock-badge { fill: rgb(var(--color-primary-500-rgb, 99 102 241)); }
   .studio-mic-mock .mock-knob-on, .studio-mic-mock .mock-badge-text { fill: var(--color-surface, Canvas); }
 

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.121.0"
+  VERSION = "0.122.0"
 end

data/lib/studio/voice_transcription.rb

@@ -5,6 +5,7 @@ require "net/http"
 require "openssl"
 require "securerandom"
 require "stringio"
+require "timeout"
 require "uri"
 
 # Understand: one finished take (the recorder's blob and its mime type, plus the
@@ -38,17 +39,36 @@ require "uri"
 # logger and environment, so the unit suite runs it without an app.
 module Studio
   module VoiceTranscription
-    # A transcriber call that failed: the message carries the vendor's words.
+    # A transcriber call that failed.
     class Error < StandardError; end
 
-    # The vendor answered a non-2xx; the status rides along so a caller can tell
-    # an auth failure from a model that fell over.
+    # The vendor failed. The status rides along (0 when nothing answered) with a
+    # reason code, so a caller can tell an auth failure from a model that fell
+    # over. The message names only the model, the status and the reason, never
+    # the vendor's own words: it reaches ErrorLog, and a vendor's error text can
+    # echo what it was sent.
     class HttpError < Error
-      attr_reader :status
+      # Why, as a code: unauthorized (401/403), rate_limited (429),
+      # server_error (5xx), rejected (another non-2xx), timeout (the deadline
+      # ran out), unreachable (no answer: refused, reset, DNS, TLS).
+      REASONS = %w[unauthorized rate_limited server_error rejected timeout unreachable].freeze
 
-      def initialize(message, status:)
+      attr_reader :status, :reason
+
+      def initialize(message, status:, reason: nil)
         super(message)
         @status = status
+        @reason = reason || self.class.reason_for(status)
+      end
+
+      def self.reason_for(status)
+        case status.to_i
+        when 401, 403 then "unauthorized"
+        when 429 then "rate_limited"
+        when 500..599 then "server_error"
+        when 0 then "unreachable"
+        else "rejected"
+        end
       end
     end
 
@@ -64,7 +84,8 @@ module Studio
 
     NO_LIVE_CALLS_ENV = "VOICE_NO_LIVE_CALLS"
     TRANSCRIBER_ENV = "STUDIO_VOICE_TRANSCRIBER"
-    API_KEY_ENV = "OPENAI_API_KEY"
+    # Voice's own key. Deliberately NOT the app's shared OPENAI_API_KEY.
+    API_KEY_ENV = "STUDIO_VOICE_OPENAI_API_KEY"
 
     # What a page shows when the app has no transcriber key. Says what is wrong
     # without naming the variable to a visitor.
@@ -123,24 +144,38 @@ module Studio
     # The real speech-to-text: OpenAI's POST /v1/audio/transcriptions, one
     # multipart file. Ported from Voicebox's Transcription::OpenAI: the model is
     # told the language (left to guess, a model handed near-silence answers a
-    # stock word in any language), and a failure other than auth is retried once
-    # on the fallback model from the start of the audio.
+    # stock word in any language), and a model that fell over (a 5xx, or a 4xx
+    # other than auth and 429) is retried once on the fallback from the start of
+    # the audio.
+    #
+    # ONE DEADLINE for the whole take (Studio.voice_transcribe_deadline, 25 s):
+    # both attempts share it, every socket timeout is what is left of it, and a
+    # hard Timeout backs it, so a vendor that trickles bytes cannot hold a web
+    # thread past it. Nothing is retried after a timeout (the deadline is spent),
+    # a 429 (the account is throttled; a second model only spends more), an auth
+    # failure, or no answer at all; nor with under MIN_RETRY_SECONDS left.
     class OpenAI
       ENDPOINT = "https://api.openai.com/v1/audio/transcriptions"
+      # The cap on connecting, inside the deadline.
       OPEN_TIMEOUT = 10
-      READ_TIMEOUT = 120
-      AUTH_FAILURES = [401, 403].freeze
+      NO_RETRY = %w[unauthorized rate_limited timeout unreachable].freeze
+      MIN_RETRY_SECONDS = 2
 
-      attr_reader :model, :fallback_model, :language, :endpoint
+      # The hard backstop's exception; turned into HttpError(reason: "timeout").
+      class DeadlineExceeded < Timeout::Error; end
+
+      attr_reader :model, :fallback_model, :language, :endpoint, :deadline
 
       def initialize(api_key: VoiceTranscription.api_key, model: Studio.voice_transcribe_model,
                      fallback_model: Studio.voice_transcribe_fallback_model,
-                     language: Studio.voice_transcribe_language, endpoint: ENDPOINT)
+                     language: Studio.voice_transcribe_language, endpoint: ENDPOINT,
+                     deadline: Studio.voice_transcribe_deadline)
         @api_key = api_key
         @model = model.to_s
         @fallback_model = fallback_model.to_s.strip.empty? ? nil : fallback_model.to_s
         @language = language.to_s.strip.empty? ? nil : language.to_s
         @endpoint = endpoint
+        @deadline = deadline.to_f.positive? ? deadline.to_f : 25.0
       end
 
       def configured? = !@api_key.to_s.strip.empty?
@@ -149,13 +184,24 @@ module Studio
       def transcribe(io:, filename:, content_type:)
         raise NotConfigured, "#{API_KEY_ENV} is not set, so this app cannot transcribe voice" unless configured?
 
-        request_text(model, io, filename, content_type)
-      rescue HttpError => e
-        raise if fallback_model.nil? || fallback_model == model || AUTH_FAILURES.include?(e.status)
+        ends_at = now + deadline
+        begin
+          request_text(model, io, filename, content_type, ends_at)
+        rescue HttpError => e
+          raise unless retry?(e, ends_at)
 
-        VoiceTranscription.log_warn("#{model} transcription failed (#{e.message}); retrying on #{fallback_model}")
-        io.rewind
-        request_text(fallback_model, io, filename, content_type)
+          VoiceTranscription.log_warn("#{model} transcription failed (HTTP #{e.status}, #{e.reason}); " \
+                                      "retrying on #{fallback_model}")
+          io.rewind
+          request_text(fallback_model, io, filename, content_type, ends_at)
+        end
+      end
+
+      def retry?(error, ends_at)
+        return false if fallback_model.nil? || fallback_model == model
+        return false if NO_RETRY.include?(error.reason)
+
+        ends_at - now >= MIN_RETRY_SECONDS
       end
 
       # The multipart fields, apart from the socket so a test reads them.
@@ -184,36 +230,52 @@ module Studio
 
       private
 
-      def request_text(model_name, io, filename, content_type)
-        perform(model_name, io, filename, content_type).fetch("text", "").to_s.strip
+      def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      def request_text(model_name, io, filename, content_type, ends_at)
+        perform(model_name, io, filename, content_type, ends_at).fetch("text", "").to_s.strip
       end
 
       # The only place a socket opens, so the only place the trap sits.
-      def perform(model_name, io, filename, content_type)
+      # uri.hostname, not uri.host: an IPv6 literal's host keeps its brackets
+      # ("[::1]"), which neither the loopback check nor the connect reads.
+      def perform(model_name, io, filename, content_type, ends_at)
         uri = URI.parse(endpoint)
-        VoiceTranscription.guard_live_call!("OpenAI", host: uri.host)
+        VoiceTranscription.guard_live_call!("OpenAI", host: uri.hostname)
+
+        left = ends_at - now
+        raise HttpError.new("OpenAI #{model_name} was not tried: the take's deadline ran out", status: 0, reason: "timeout") if left <= 0
 
         request = build_request(model_name, io, filename, content_type)
-        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
-                                                       open_timeout: OPEN_TIMEOUT, read_timeout: READ_TIMEOUT) do |http|
-          http.request(request)
+        response = Timeout.timeout(left, DeadlineExceeded) do
+          Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https", open_timeout: [OPEN_TIMEOUT, left].min,
+                                                  read_timeout: left, write_timeout: left) do |http|
+            http.request(request)
+          end
         end
         interpret(response, model_name)
-      rescue Timeout::Error, SystemCallError, IOError, OpenSSL::SSL::SSLError, SocketError => e
-        raise HttpError.new("OpenAI #{model_name} could not be reached (#{e.class})", status: 0)
+      rescue Timeout::Error => e
+        raise HttpError.new("OpenAI #{model_name} did not answer within the take's #{deadline.round(1)} s deadline (#{e.class})",
+                            status: 0, reason: "timeout")
+      rescue SystemCallError, IOError, OpenSSL::SSL::SSLError, SocketError => e
+        raise HttpError.new("OpenAI #{model_name} could not be reached (#{e.class})", status: 0, reason: "unreachable")
       end
 
+      # A failure carries the status and its reason code, never the vendor's
+      # words (HttpError).
       def interpret(response, model_name)
+        status = response.code.to_i
+        unless response.is_a?(Net::HTTPSuccess)
+          reason = HttpError.reason_for(status)
+          raise HttpError.new("OpenAI #{model_name} answered HTTP #{status} (#{reason})", status: status, reason: reason)
+        end
+
         parsed = begin
           JSON.parse(response.body.to_s)
         rescue JSON::ParserError
           {}
         end
-        parsed = {} unless parsed.is_a?(Hash)
-        return parsed if response.is_a?(Net::HTTPSuccess)
-
-        detail = parsed.dig("error", "message") || response.body.to_s[0, 200]
-        raise HttpError.new("OpenAI #{model_name} answered HTTP #{response.code}: #{detail}", status: response.code.to_i)
+        parsed.is_a?(Hash) ? parsed : {}
       end
     end
 
@@ -269,7 +331,8 @@ module Studio
       klass.new
     end
 
-    # Studio.voice_openai_api_key, else OPENAI_API_KEY (Voicebox's name).
+    # Studio.voice_openai_api_key, else STUDIO_VOICE_OPENAI_API_KEY. Never the
+    # app's shared OPENAI_API_KEY: voice spends on its own key and budget.
     def api_key
       key = Studio.voice_openai_api_key.to_s.strip
       key.empty? ? ENV[API_KEY_ENV].to_s.strip : key
@@ -285,9 +348,12 @@ module Studio
       rails_env == "test"
     end
 
+    # This machine. host is URI#hostname, so IPv6 arrives unbracketed.
+    LOOPBACK_HOSTS = %w[127.0.0.1 localhost ::1].freeze
+
     def guard_live_call!(vendor, host:)
       return unless live_calls_blocked?
-      return if %w[127.0.0.1 localhost ::1].include?(host.to_s)
+      return if LOOPBACK_HOSTS.include?(host.to_s)
 
       raise LiveCallAttempted, "A live #{vendor} call was attempted with #{NO_LIVE_CALLS_ENV} armed. " \
                                "Tests drive the mock transcriber (Studio.voice_transcriber = \"mock\")."

data/lib/studio.rb

@@ -589,10 +589,25 @@ module Studio
   # VOICE_NO_LIVE_CALLS is armed in every test environment.
   mattr_accessor :voice_transcriber, default: nil
 
-  # The OpenAI key for the real transcriber. nil reads OPENAI_API_KEY. Missing,
-  # the endpoint answers 503 with a line the page can show; nothing crashes.
+  # The OpenAI key for the real transcriber, voice's OWN key. nil reads
+  # STUDIO_VOICE_OPENAI_API_KEY, and never the app's shared OPENAI_API_KEY (on
+  # the hub that is the image key, with its own budget). Missing, the endpoint
+  # answers 503 with a line the page can show; nothing crashes.
   mattr_accessor :voice_openai_api_key, default: nil
 
+  # One take's whole budget at the vendor, in seconds: the first model AND the
+  # fallback share it, so a take never holds a web thread longer than this
+  # (Studio::VoiceTranscription::OpenAI). A timeout or a vendor 429 is not
+  # retried.
+  mattr_accessor :voice_transcribe_deadline, default: 25
+
+  # POST /voice/takes per signed-in user: at most `to` takes in any `within`
+  # seconds (a fixed window), else a JSON 429 with retry_after. Every take is a
+  # paid vendor call. `store:` (optional) is the counter's cache; nil uses
+  # Rails.cache, or a per-process memory store when Rails.cache is a NullStore.
+  # false turns the limit off.
+  mattr_accessor :voice_takes_rate_limit, default: { to: 20, within: 600 }
+
   # The speech-to-text models (Voicebox's measured pair) and the language both
   # are told to hear. A blank fallback turns the one retry off.
   mattr_accessor :voice_transcribe_model, default: "gpt-4o-transcribe"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.121.0
+  version: 0.122.0
 platform: ruby
 authors:
 - Alex McRitchie