Report the real getUserMedia failure, not always 'access denied' (#156)

The recorder caught every getUserMedia rejection and showed 'Microphone
access was denied', so a busy device (NotReadableError, e.g. another app
or the companion holding the mic) or a missing one (NotFoundError) read
as a permission problem the user could not fix. Classify by DOMException
name and give an actionable message per case.

Author: pratikbodkhe

scripts/verify-audio-capture.test.mjs

@@ -29,6 +29,7 @@ const {
   audioStoragePath,
   formatRecordingDuration,
   uploadMeetingAudio,
+  micErrorMessage,
 } = await import(pathToFileURL(bundled).href);
 
 function read(rel) {
@@ -330,3 +331,28 @@ test("seed user has full access so gated capture is reachable in E2E", () => {
   const seed = read("supabase/seed.sql");
   assert.ok(seed.includes("has_full_access"), "seed must set has_full_access for the test user");
 });
+
+test("micErrorMessage distinguishes denial from busy, missing, and unknown", () => {
+  const denied = micErrorMessage(Object.assign(new Error("x"), { name: "NotAllowedError" }));
+  assert.match(denied, /denied/i, "NotAllowedError must read as a permission denial");
+
+  const busy = micErrorMessage(Object.assign(new Error("x"), { name: "NotReadableError" }));
+  assert.match(busy, /in use by another app/i, "NotReadableError must say the device is busy");
+  assert.doesNotMatch(busy, /denied/i, "a busy device must not be reported as denied");
+
+  const missing = micErrorMessage(Object.assign(new Error("x"), { name: "NotFoundError" }));
+  assert.match(missing, /no microphone/i, "NotFoundError must say no microphone was found");
+
+  const unknown = micErrorMessage(new Error("boom"));
+  assert.match(unknown, /could not start the microphone/i, "unknown errors get a generic retry message");
+  assert.doesNotMatch(unknown, /denied/i, "an unknown failure must not be reported as denied");
+});
+
+test("recorder hook uses micErrorMessage, not a hardcoded denial string", () => {
+  const hook = read("src/lib/hooks/use-meeting-recorder.ts");
+  assert.ok(hook.includes("micErrorMessage(err)"), "hook must classify the getUserMedia error");
+  assert.ok(
+    !hook.includes('"Microphone access was denied."'),
+    "hook must not hardcode the denial message for every failure"
+  );
+});

src/lib/audio/index.ts

@@ -94,6 +94,28 @@ export function formatRecordingDuration(totalSeconds: number): string {
     : `${pad(minutes)}:${pad(seconds)}`;
 }
 
+/**
+ * Turn a getUserMedia failure into a specific, actionable message. The DOMException
+ * `name` distinguishes a real permission denial from a device that is missing or held
+ * by another app, so we never tell a user "access denied" when they already granted it.
+ */
+export function micErrorMessage(err: unknown): string {
+  const name = err instanceof Error ? err.name : "";
+  switch (name) {
+    case "NotAllowedError":
+    case "SecurityError":
+      return "Microphone access was denied. Allow it for this site in your browser, then press Record again.";
+    case "NotReadableError":
+    case "AbortError":
+      return "Your microphone is in use by another app. Close it (Zoom, the Minutia companion, another tab), then press Record again.";
+    case "NotFoundError":
+    case "OverconstrainedError":
+      return "No microphone was found. Connect one, then press Record again.";
+    default:
+      return "Could not start the microphone. Check your browser's microphone settings and try again.";
+  }
+}
+
 export interface UploadMeetingAudioParams {
   meetingId: string;
   blob: Blob;

src/lib/hooks/use-meeting-recorder.ts

@@ -7,6 +7,7 @@ import {
   audioContentType,
   isRecordingSupported,
   MEETING_AUDIO_BUCKET,
+  micErrorMessage,
   pickAudioMimeType,
 } from "@/lib/audio";
 import {
@@ -134,8 +135,8 @@ export function useMeetingRecorder(meetingId: string): MeetingRecorder {
     let stream: MediaStream;
     try {
       stream = await navigator.mediaDevices.getUserMedia({ audio: true });
-    } catch {
-      setError("Microphone access was denied.");
+    } catch (err) {
+      setError(micErrorMessage(err));
       setState("idle");
       return;
     }