crowdplaysdk 0.4.1 → 0.5.0

package/lib/VoiceView.js

@@ -1,14 +1,14 @@
 "use strict";
 /**
  * The standard voice-AI visual (founders, 2026-08-22): a breathing orb in
- * the style of realtime assistants — calm while idle, a cool ring while the
+ * the style of realtime assistants: calm while idle, a cool ring while the
  * user talks, an energetic pulse while the AI speaks. The React Native
  * counterpart of the native SDK's CrowdPlayVoiceView, driven by the same
  * engine signal over a fast bridge event that runs only while mounted.
  *
  * Two levels of customization:
- * 1. Props on <CrowdPlayVoiceView> — colors and size of the built-in orb.
- * 2. useVoiceActivity() — the phase + smoothed energy underneath, for apps
+ * 1. Props on <CrowdPlayVoiceView>: colors and size of the built-in orb.
+ * 2. useVoiceActivity(): the phase + smoothed energy underneath, for apps
  *    that want to draw something entirely their own.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
@@ -81,7 +81,7 @@ function useVoiceActivity() {
                 phase = 'idle';
                 target = 0;
             }
-            // Fast attack, slow release — speech onsets snap, tails breathe out.
+            // Fast attack, slow release: speech onsets snap, tails breathe out.
             const rate = target > energyRef.current ? 0.55 : 0.12;
             energyRef.current += (target - energyRef.current) * rate;
             setActivity({ phase, energy: energyRef.current });
@@ -108,7 +108,7 @@ function useLatestCaption() {
     }, []);
     return caption;
 }
-/** Make ANY child view breathe, pulse, and glow with the conversation —
+/** Make ANY child view breathe, pulse, and glow with the conversation;
  * the one-line path from the app's own art (mascot, logo, character) to a
  * living AI presence. */
 function VoiceReactive({ children, glowColor = '#598CFF', }) {

package/lib/index.d.ts

@@ -1,11 +1,11 @@
 /**
- * crowdplaysdk — CrowdPlay's lossless capture SDK for React Native (iOS).
+ * crowdplaysdk: CrowdPlay's lossless capture SDK for React Native (iOS).
  *
  * The recording engine is 100% native (CrowdPlaySDK): studio-grade audio
  * (48 kHz / 24-bit, unprocessed) + 1080p30 video captured locally during a
  * live call, clock-synced across participants, uploaded to CrowdPlay with
- * retries and crash recovery. **No media ever crosses the JS bridge** —
- * only control calls and state events — so recording quality is identical
+ * retries and crash recovery. **No media ever crosses the JS bridge**,
+ * only control calls and state events, so recording quality is identical
  * to a fully native app.
  *
  *     import CrowdPlay, { CrowdPlayConsentScreen, CrowdPlayVideoView } from 'crowdplaysdk';
@@ -17,7 +17,7 @@
  *     await CrowdPlay.leave(); // recording stops; uploads continue automatically
  *
  * Consent is enforced twice: join() throws here without a grant, and the
- * native layer requires the consent record structurally — there is no code
+ * native layer requires the consent record structurally; there is no code
  * path that records without it.
  */
 /** Live-call (Path A) quality. The RECORDING is always 1080p30 + 24-bit WAV
@@ -37,7 +37,7 @@ export interface CrowdPlayConfig {
     serverUrl: string;
     /** From the CrowdPlay dashboard. Also your data-access credential. */
     appKey: string;
-    /** AUDIO-ONLY app: the camera is never touched — no camera permission,
+    /** AUDIO-ONLY app: the camera is never touched: no camera permission,
      * no video captured or uploaded, voice-only calls. The audio path is
      * identical to an A/V app. Requires engine 0.3.0+. Default false. */
     audioOnly?: boolean;
@@ -46,13 +46,21 @@ export interface CrowdPlayConfig {
     videoUploadsOnCellular?: boolean;
     /** Upload segments while the call records, so the post-call wait is
      * roughly the final segment + manifests. Mid-call transfers run one at
-     * a time and pause automatically when call quality drops — the call
+     * a time and pause automatically when call quality drops; the call
      * always wins the uplink. Default true. */
     uploadDuringCall?: boolean;
+    /** What happens to OTHER apps' audio (Apple Music, Spotify, podcasts)
+     * while a call is live. 'interrupt' (default) pauses them at join, the
+     * classic call behaviour. 'mix' keeps them playing alongside the call
+     * and the recording, for shared-listening and DJ apps; 'mixDucked' also
+     * lowers them for the whole call. Music stays on the device and never
+     * rides the call; listeners must wear headphones or it lands in the
+     * recording. Requires engine 0.4.0+. */
+    otherAudio?: 'interrupt' | 'mix' | 'mixDucked';
     callQuality?: CallQuality;
 }
-/** Proof the participant agreed. Produce it with CrowdPlayConsentScreen, or —
- * if you render your own consent UI — call CrowdPlay.consentText() to show the
+/** Proof the participant agreed. Produce it with CrowdPlayConsentScreen, or,
+ * if you render your own consent UI, call CrowdPlay.consentText() to show the
  * REQUIRED wording and construct the grant at the moment of agreement. */
 export interface ConsentGrant {
     /** Date.now() at the moment the participant agreed. */
@@ -66,6 +74,17 @@ export interface ConsentGrant {
  * apply to the whole room. The app can never change the provider, the
  * model, or the API key from here.
  */
+/** A tool the app offers the voice AI for one session (D-103). Requires
+ * the app's dashboard config to use the GPT-Live provider with an AI brain
+ * (delegation) enabled; ignored otherwise. */
+export interface AgentTool {
+    /** Letters, digits, underscore, dash; max 64 chars. */
+    name: string;
+    /** What the tool does and when to use it, for the model. */
+    description: string;
+    /** JSON-schema object describing the arguments. Omit for none. */
+    parameters?: Record<string, unknown>;
+}
 export interface AgentOptions {
     /** A voice of the app's configured provider. Gemini: Charon, Aoede,
      * Fenrir, Kore, Puck. OpenAI: marin, cedar, alloy, ash, ballad, coral,
@@ -79,6 +98,9 @@ export interface AgentOptions {
      * keep a few sentences per user in your own storage and pass them
      * here. Max 4000 chars. */
     context?: string;
+    /** Tools the AI may call this session (D-103). Handle calls with
+     * CrowdPlay.onAgentToolCall(). Max 16. */
+    tools?: AgentTool[];
 }
 export type Phase = 'idle' | 'connecting' | 'connected' | 'failed';
 export interface RecordingSnapshot {
@@ -88,10 +110,10 @@ export interface RecordingSnapshot {
     droppedSamples: number;
     /** Live input level. Speech sits around −25…−45 dBFS. */
     inputLevelDbfs: number;
-    /** True after 10 s of silence while unmuted — a dead/disconnected mic.
+    /** True after 10 s of silence while unmuted: a dead/disconnected mic.
      * Surface this loudly; it is fixable mid-call. */
     inputSilent: boolean;
-    /** Samples at digital full scale — a too-hot mic, irreversibly clipped. */
+    /** Samples at digital full scale: a too-hot mic, irreversibly clipped. */
     fullScaleSamples: number;
 }
 export interface UploadKindProgress {
@@ -127,7 +149,7 @@ export interface CrowdPlayEvents {
         error?: string;
     };
     /** Recording state. `error` non-null means the session is NOT being
-     * captured — show it prominently and offer retryRecording(). */
+     * captured; show it prominently and offer retryRecording(). */
     recording: {
         isRecording: boolean;
         error?: string;
@@ -159,6 +181,13 @@ export interface CrowdPlayEvents {
         detectedOutputs: string[];
         headphonesConnected: boolean;
     };
+    /** The voice AI asked the app to run a tool (D-103). Prefer
+     * CrowdPlay.onAgentToolCall(), which answers for you. */
+    agentToolCall: {
+        callId: string;
+        name: string;
+        argumentsJSON: string;
+    };
 }
 export type CrowdPlayEventName = keyof CrowdPlayEvents;
 declare const CrowdPlay: {
@@ -175,7 +204,7 @@ declare const CrowdPlay: {
      * Join a room. Recording starts automatically on join and stops on
      * leave(). Rejects if the connection fails.
      *
-     * `consent` is REQUIRED — produce it with <CrowdPlayConsentScreen> or from
+     * `consent` is REQUIRED; produce it with <CrowdPlayConsentScreen> or from
      * your own UI at the moment of agreement. There is no way to record
      * without it, here or natively.
      */
@@ -208,6 +237,19 @@ declare const CrowdPlay: {
     /** Integration self-check: configuration, permissions, disk, backend
      * reachability, app-key auth. Every failing check names its fix. */
     doctor(): Promise<DoctorCheck[]>;
+    /** Handle the voice AI's tool calls (D-103). The handler gets the tool
+     * name and its arguments (parsed JSON object) and returns the result as
+     * an object or JSON string; return null to decline on this device
+     * (another participant's device may answer; first answer wins). Ordinary
+     * app code, no AI here. The AI waits about 12 seconds per call. Returns
+     * a subscription; call .remove(). */
+    onAgentToolCall(handler: (name: string, args: Record<string, unknown>) => Promise<Record<string, unknown> | string | null> | Record<string, unknown> | string | null): {
+        remove(): void;
+    };
+    /** Tell the AI what just happened in the app, mid-session ("Night ended.
+     * Sam was eliminated."). Keep it to a sentence or two; long pushes are
+     * truncated. GPT-Live provider only; other providers ignore it. */
+    updateAgentContext(text: string): void;
     /** Subscribe to state events. Returns a subscription; call .remove(). */
     addListener<E extends CrowdPlayEventName>(event: E, listener: (payload: CrowdPlayEvents[E]) => void): {
         remove(): void;

package/lib/index.js

@@ -1,12 +1,12 @@
 "use strict";
 /**
- * crowdplaysdk — CrowdPlay's lossless capture SDK for React Native (iOS).
+ * crowdplaysdk: CrowdPlay's lossless capture SDK for React Native (iOS).
  *
  * The recording engine is 100% native (CrowdPlaySDK): studio-grade audio
  * (48 kHz / 24-bit, unprocessed) + 1080p30 video captured locally during a
  * live call, clock-synced across participants, uploaded to CrowdPlay with
- * retries and crash recovery. **No media ever crosses the JS bridge** —
- * only control calls and state events — so recording quality is identical
+ * retries and crash recovery. **No media ever crosses the JS bridge**,
+ * only control calls and state events, so recording quality is identical
  * to a fully native app.
  *
  *     import CrowdPlay, { CrowdPlayConsentScreen, CrowdPlayVideoView } from 'crowdplaysdk';
@@ -18,7 +18,7 @@
  *     await CrowdPlay.leave(); // recording stops; uploads continue automatically
  *
  * Consent is enforced twice: join() throws here without a grant, and the
- * native layer requires the consent record structurally — there is no code
+ * native layer requires the consent record structurally; there is no code
  * path that records without it.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -30,8 +30,8 @@ function native() {
         throw new Error("crowdplaysdk: native module not found. iOS setup: add the CrowdPlaySDK " +
             "Swift package (https://github.com/symbiateam/crowdplaysdk) to your Xcode " +
             "project and add the two bridge files from node_modules/crowdplaysdk/ios " +
-            "to your app target — see the package README. " +
-            (react_native_1.Platform.OS !== 'ios' ? `(platform '${react_native_1.Platform.OS}' is not supported yet — iOS only.)` : ''));
+            "to your app target; see the package README. " +
+            (react_native_1.Platform.OS !== 'ios' ? `(platform '${react_native_1.Platform.OS}' is not supported yet; iOS only.)` : ''));
     }
     return module;
 }
@@ -73,7 +73,7 @@ const CrowdPlay = {
      * Join a room. Recording starts automatically on join and stops on
      * leave(). Rejects if the connection fails.
      *
-     * `consent` is REQUIRED — produce it with <CrowdPlayConsentScreen> or from
+     * `consent` is REQUIRED; produce it with <CrowdPlayConsentScreen> or from
      * your own UI at the moment of agreement. There is no way to record
      * without it, here or natively.
      */
@@ -102,6 +102,11 @@ const CrowdPlay = {
             put('voice', agent.voice, 60);
             put('systemPrompt', agent.systemPrompt, 8192);
             put('context', agent.context, 4000);
+            // Tools cross the bridge as one JSON string; the native layer and the
+            // server both re-validate (D-103).
+            if (Array.isArray(agent.tools) && agent.tools.length) {
+                put('toolsJSON', JSON.stringify(agent.tools.slice(0, 16)), 8192);
+            }
         }
         return native().join(displayName.trim(), roomCode, consent.grantedAtMs, agentFields);
     },
@@ -144,6 +149,37 @@ const CrowdPlay = {
     doctor() {
         return native().doctor();
     },
+    /** Handle the voice AI's tool calls (D-103). The handler gets the tool
+     * name and its arguments (parsed JSON object) and returns the result as
+     * an object or JSON string; return null to decline on this device
+     * (another participant's device may answer; first answer wins). Ordinary
+     * app code, no AI here. The AI waits about 12 seconds per call. Returns
+     * a subscription; call .remove(). */
+    onAgentToolCall(handler) {
+        const subscription = events().addListener('crowdplay:agentToolCall', (payload) => {
+            void (async () => {
+                let args = {};
+                try {
+                    args = JSON.parse(payload.argumentsJSON);
+                }
+                catch { /* {} */ }
+                const result = await handler(payload.name, args);
+                if (result === null || result === undefined)
+                    return;
+                const output = typeof result === 'string' ? result : JSON.stringify(result);
+                native().respondToAgentToolCall(payload.callId, output);
+            })();
+        });
+        return { remove: () => subscription.remove() };
+    },
+    /** Tell the AI what just happened in the app, mid-session ("Night ended.
+     * Sam was eliminated."). Keep it to a sentence or two; long pushes are
+     * truncated. GPT-Live provider only; other providers ignore it. */
+    updateAgentContext(text) {
+        if (typeof text === 'string' && text.trim()) {
+            native().updateAgentContext(text.trim());
+        }
+    },
     /** Subscribe to state events. Returns a subscription; call .remove(). */
     addListener(event, listener) {
         const subscription = events().addListener(`crowdplay:${event}`, listener);

package/llms.txt

@@ -29,7 +29,7 @@ Consequences:
 - Recording starts automatically on join() and stops on leave(). Do not
   build a separate record button.
 
-## The HOST APP is the product — not recording
+## The HOST APP is the product, not recording
 
 The builder came to you with an app idea (a tutoring app, a language-
 exchange app, a remote interview tool…). Build THAT app. The SDK records
@@ -37,11 +37,11 @@ its video calls invisibly; recording is infrastructure, not identity:
 - The app's NAME, description, and screens are about the builder's idea.
   Never name or describe the app around recording.
 - Recording surfaces in the UI in exactly four places: the consent
-  screen before joining (required — never minimized away), a small REC
+  screen before joining (required, never minimized away), a small REC
   indicator during the call, join/leave, and a small audio-output menu
   (REQUIRED standard control: show the current output device by name from
   the 'audioRoute' event, with a switch between the device and Speaker
-  via CrowdPlay.setAudioOutput — Bluetooth users expect it).
+  via CrowdPlay.setAudioOutput; Bluetooth users expect it).
 - Do NOT build upload-progress screens, diagnostics screens, SDK settings
   pages, or recording libraries/playback. Uploads run automatically in
   the background; doctor() is a development-time check, not a screen.
@@ -56,7 +56,7 @@ its video calls invisibly; recording is infrastructure, not identity:
    add audio-session-touching RN packages like react-native-incall-manager)
    in an app using this SDK. The engine owns the microphone and camera.
 3. NEVER skip or fake consent. CrowdPlay.join() THROWS without a ConsentGrant,
-   and the user must actually SEE the consent wording first — use
+   and the user must actually SEE the consent wording first; use
    <CrowdPlayConsentScreen/>, or show CrowdPlay.consentText() verbatim in your own
    UI and construct { grantedAtMs: Date.now() } at the moment of
    agreement. Fabricating a grant creates false legal evidence.
@@ -79,7 +79,7 @@ its video calls invisibly; recording is infrastructure, not identity:
 4.  Info.plist: NSMicrophoneUsageDescription, NSCameraUsageDescription,
     UIBackgroundModes = [audio]. A missing usage string makes iOS kill
     the app at first mic/camera access (uncatchable).
-5.  AppDelegate (recommended — lets uploads finish while suspended):
+5.  AppDelegate (recommended; lets uploads finish while suspended):
       // AppDelegate.mm, with #import "<YourProjectName>-Swift.h"
       - (void)application:(UIApplication *)application
           handleEventsForBackgroundURLSession:(NSString *)identifier
@@ -112,18 +112,18 @@ its video calls invisibly; recording is infrastructure, not identity:
     already went out during the call). Show at most one quiet
     "finishing up…" line while an 'uploads' session is incomplete; do
     NOT build a dedicated upload screen.
-10. Verify: const checks = await CrowdPlay.doctor(); — every failing check's
+10. Verify: const checks = await CrowdPlay.doctor(); every failing check's
     detail names its own fix. NOTE: on a fresh install the "permissions"
-    check reports "not requested yet — NORMAL"; iOS prompts at first join.
-    That is not an integration bug — only a DENIED state needs action.
+    check reports "not requested yet (NORMAL)"; iOS prompts at first join.
+    That is not an integration bug; only a DENIED state needs action.
 11. Hand off (REQUIRED final message): the Simulator has no camera or
     mic, so nothing is proven until the app runs on a real iPhone. Do
-    not end with "the implementation is complete" — your FINAL message
+    not end with "the implementation is complete"; your FINAL message
     must walk the builder through: plugging in the iPhone (Trust +
     Developer Mode), picking a signing Team in Xcode and pressing Run on
     the device (via the .xcworkspace), allowing mic/camera permissions,
     a ~1-minute test call, and checking the session at
-    https://dashboard.crowdplay.ai — that is the end-to-end proof.
+    https://dashboard.crowdplay.ai; that is the end-to-end proof.
 
 ## API reference (exact TypeScript surface)
 
@@ -155,12 +155,12 @@ useVoiceActivity() -> { phase: 'connecting'|'idle'|'listening'|'speaking', energ
 
 The voice AI (apps with the Voice AI switch enabled on the dashboard):
 
-How it works — all server-side, nothing to wire up. When any user joins a
+How it works (all server-side, nothing to wire up). When any user joins a
 call, CrowdPlay's servers put a live AI participant into the room within
 ~3 seconds. It joins with name "agent" (identity "agent-<8hex>"), greets
 the user, and holds a real spoken conversation (speech-to-speech: it
 hears the user directly, answers in natural voice, can be interrupted).
-The app writes ZERO AI code — no model API calls, no AI keys, no chat
+The app writes ZERO AI code: no model API calls, no AI keys, no chat
 backend, no STT/TTS. Provider, model and API key are set by the BUILDER on
 the CrowdPlay dashboard, and so are the DEFAULT persona and voice.
 Per-join overrides (0.4.0+): the app MAY pass `agent` to join() to change
@@ -169,42 +169,67 @@ the voice and the persona and give a short context text for one session:
     agent: { voice: 'Aoede', context: "The user's name is Sam. Last time you practised past tense." } });
 voice must be one of the configured provider's voices (Gemini: Charon,
 Aoede, Fenrir, Kore, Puck; OpenAI: marin, cedar, alloy, ash, ballad,
-coral, echo, sage, shimmer, verse; Grok: Ara, Rex, Sal, Eve, Leo), unknown
+coral, echo, sage, shimmer, verse; Grok: Ara, Rex, Sal, Eve, Leo;
+OpenAI GPT-Live: quartz, ripple, vesper, willow, stone, gleam, meridian,
+bossa, tempo, beacon, delta, cinder), unknown
 falls back to the dashboard voice. Caps: systemPrompt 8192 chars, context
 4000. The options of the join that CREATES the AI apply to the whole room;
 fixed for the session (leave and join again to change); provider, model
 and key cannot be changed from the app. MEMORY is built with `context`:
 keep a few sentences per user in the app's own storage and pass them at
 every join.
+Agent tools + live context (0.5.0+, D-103; needs the app's dashboard
+config on the OpenAI GPT-Live provider with an AI brain enabled —
+ignored otherwise, never an error). Tools let the AI SEE app state and
+ACT in the app: pass them at join, handle calls with ordinary JS.
+  await CrowdPlay.join({ displayName, roomCode, consent: grant,
+    agent: { tools: [
+      { name: 'get_game_state',
+        description: 'The current players, roles you know, and votes.' },
+      { name: 'cast_vote', description: 'Vote to eliminate one player.',
+        parameters: { type: 'object',
+          properties: { player: { type: 'string' } }, required: ['player'] } },
+    ] } });
+  const sub = CrowdPlay.onAgentToolCall(async (name, args) => {
+    if (name === 'get_game_state') return game.state();
+    if (name === 'cast_vote') return game.castVote(args.player);
+    return null; // decline on this device; first device to answer wins
+  });
+Return an object (or JSON string), or null to decline. The AI waits
+about 12 seconds per call, then carries on gracefully. Max 16 tools;
+names letters/digits/underscore/dash up to 64 chars. To push events to
+the AI as they happen (it has no other way to know):
+CrowdPlay.updateAgentContext('Night ended. Sam was eliminated.') — a
+sentence or two, long pushes are truncated.
 Conversations are recorded and transcribed by the platform automatically.
-RECOMMENDED: voice-AI apps should be AUDIO-ONLY (audioOnly: true — no
+RECOMMENDED: voice-AI apps should be AUDIO-ONLY (audioOnly: true; no
 camera permission, no video anywhere); a camera adds nothing to talking
 with an AI. Keep video only when the app ALSO has calls between people.
 
-The AI conversation screen — the approved standard layout: the animated
+The AI conversation screen, the approved standard layout: the animated
 visual front and center, large (it IS the screen); NO self camera
 preview and NO video tiles on this screen, ever; around it only the AI's
 name/persona, a small REC indicator, a leave button, and the small
 audio-output menu. One calm screen, one living visual, nothing competing
 with it.
 
-What the app builds — the AI's on-screen presence. The AI publishes
+What the app builds: the AI's on-screen presence. The AI publishes
 AUDIO ONLY: never a camera tile, an empty box, or a static image; never
 count it as a generic user. Detect it in the participants event by name
 "agent" (or identity prefix "agent-").
 - The visual is a MENU, zero-effort to fully custom (0.3.4+ for 2-5):
-  1. Orb (default): <CrowdPlayVoiceView /> — breathes idle, rings with
+  1. Orb (default): <CrowdPlayVoiceView />, breathes idle, rings with
      the user's voice, pulses with the AI's. Props: agentColor,
      listeningColor, idleColor, size.
-  2. Bars: <CrowdPlayVoiceView variant='bars' /> — equalizer look, good
+  2. Bars: <CrowdPlayVoiceView variant='bars' />, equalizer look, good
      under other content (scoreboards, question cards, quizzes).
   3. Halo around the app's own art: pass a mascot portrait / logo /
-     character as children of <CrowdPlayVoiceView> — animated ring +
+     character as children of <CrowdPlayVoiceView>, animated ring +
      glow around whatever you provide.
-  4. Make ANY view alive: wrap it in <VoiceReactive> — breathing, pulse
+  4. Make ANY view alive: wrap it in <VoiceReactive>, breathing, pulse
      and speech glow on the app's own art in one line.
   5. Fully custom (best for characters): drive ANY visual from the
-     useVoiceActivity() hook — { phase: 'connecting'|'idle'|'listening'|
+     useVoiceActivity() hook, returning { phase: 'connecting'|'idle'|'listening'|
      'speaking', energy: 0…1 smoothed loudness }. Example, an illustrated
      tutor that reacts to the conversation:
 
@@ -215,10 +240,10 @@ count it as a generic user. Detect it in the participants event by name
           pose={phase === 'listening' ? 'leanIn' : 'idleBlink'} />;
       }
 
-  Any art pipeline works (Animated, Lottie, Rive, sprite frames) — bind
+  Any art pipeline works (Animated, Lottie, Rive, sprite frames): bind
   mouth/pose/glow to phase + energy.
 - Live captions (0.3.4+): each line the AI and the user say is streamed
-  as it is spoken — the useLatestCaption() hook returns { role, text }.
+  as it is spoken; the useLatestCaption() hook returns { role, text }.
   For speech bubbles, subtitles, language-learning corrections. Optional
   UI; the full timestamped transcript is always delivered with the
   session regardless.
@@ -228,8 +253,14 @@ count it as a generic user. Detect it in the participants event by name
 Types:
   CrowdPlayConfig { serverUrl; appKey; audioOnly?=false;
                videoUploadsOnCellular?=false;
-               uploadDuringCall?=true; callQuality? }
-               // audioOnly (0.3.0+): the camera is never touched — no
+               uploadDuringCall?=true;
+               otherAudio?='interrupt'|'mix'|'mixDucked'; callQuality? }
+               // otherAudio (0.4.0+): 'interrupt' pauses other apps'
+               // audio at join (classic call); 'mix' keeps Apple Music /
+               // Spotify playing through the call and the recording, for
+               // shared-listening apps; 'mixDucked' also lowers it. Music
+               // never rides the call; listeners must wear headphones.
+               // audioOnly (0.3.0+): the camera is never touched; no
                // camera permission, no video captured or uploaded,
                // voice-only calls. Skip NSCameraUsageDescription, skip
                // CrowdPlayVideoView and every camera control.
@@ -242,8 +273,8 @@ Types:
   ConsentGrant { grantedAtMs: number }
   RecordingSnapshot { seconds; segmentsClosed; droppedSamples;
                       inputLevelDbfs;   // speech ≈ −25…−45 dBFS
-                      inputSilent;      // dead mic — surface loudly
-                      fullScaleSamples } // clipping — mic too hot
+                      inputSilent;      // dead mic: surface loudly
+                      fullScaleSamples } // clipping: mic too hot
   UploadProgress { sessionId; fraction; isComplete; failed;
                    audio: UploadKindProgress; video: UploadKindProgress }
   DoctorCheck { id; passed; detail }
@@ -269,7 +300,7 @@ Events (CrowdPlay.addListener):
                  // this mic (wear headphones); micPolicy = unexpected
                  // input device.
 
-## Accessing recordings (no AWS, no SDK — plain HTTPS)
+## Accessing recordings (no AWS, no SDK, plain HTTPS)
 
 The app key doubles as the data credential:
   GET https://dashboard.crowdplay.ai/sessions            (x-liva-key header)
@@ -289,21 +320,21 @@ Humans use https://dashboard.crowdplay.ai directly (sign in, download).
   pauses uploads until next launch (nothing lost).
 - Participants should wear wired or closed-back headphones (crossTalk
   warns live when they don't).
-- SIMULATOR detection (engine 0.3.0+): on any Simulator — including CLOUD
-  previews — doctor()'s "platform" check fails and join() rejects with a
+- SIMULATOR detection (engine 0.3.0+): on any Simulator, including CLOUD
+  previews, doctor()'s "platform" check fails and join() rejects with a
   clear message instead of a cryptic audio-engine error. Expected, not a
   bug: no microphone exists there. A doctor() run also flips the "health
   check" step on the builder's dashboard checklist automatically.
 - Slow join or glitchy first seconds of a recording = poor radio
   environment (congested 2.4 GHz WiFi + Bluetooth share the antenna) or
-  Metro/debugger overhead — NOT an integration bug. Capture self-heals.
+  Metro/debugger overhead; NOT an integration bug. Capture self-heals.
   Advise: better network, wired headphones, evaluate from a home-screen
   launch (release build).
 - Build error mentioning LiveKit/WebRTC duplicate symbols: the app added
-  its own LiveKit dependency — remove it (rule 1).
+  its own LiveKit dependency; remove it (rule 1).
 - "Swift bridging" or "<Project>-Swift.h not found" errors: rerun
   ios/wire.rb, then a clean build (the header is generated at build time).
-- 401/"unauthorized": wrong app key — sign in at
+- 401/"unauthorized": wrong app key; sign in at
   https://dashboard.crowdplay.ai, reveal the key, and copy it again.
 - Uploads crawling on an otherwise-fine network: check for a VPN, iCloud
   Private Relay, or Low Data Mode on the phone (a VPN can cut throughput

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crowdplaysdk",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "CrowdPlay lossless conversation capture for React Native (iOS). Studio-grade per-participant recording during live video calls, delivered to CrowdPlay automatically.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/ConsentScreen.tsx

@@ -33,7 +33,7 @@ export function CrowdPlayConsentScreen({ onConsent, style }: CrowdPlayConsentScr
         if (!cancelled) setText(wording);
       })
       .catch(() => {
-        if (!cancelled) setText('Consent text unavailable — check that CrowdPlay.configure() ran and the native module is installed.');
+        if (!cancelled) setText('Consent text unavailable. Check that CrowdPlay.configure() ran and the native module is installed.');
       });
     return () => {
       cancelled = true;

package/src/VideoView.tsx

@@ -1,7 +1,7 @@
 /**
  * Native video tile. Renders the LOCAL camera preview or a REMOTE
  * participant's live video (identified by the `identity` from the
- * `participants` event). The video never touches JavaScript — this is a
+ * `participants` event). The video never touches JavaScript; this is a
  * native LiveKit view hosted in your RN layout.
  *
  *     <CrowdPlayVideoView participant="local" style={{ width: 120, height: 160 }} />

package/src/VoiceView.tsx

@@ -1,13 +1,13 @@
 /**
  * The standard voice-AI visual (founders, 2026-08-22): a breathing orb in
- * the style of realtime assistants — calm while idle, a cool ring while the
+ * the style of realtime assistants: calm while idle, a cool ring while the
  * user talks, an energetic pulse while the AI speaks. The React Native
  * counterpart of the native SDK's CrowdPlayVoiceView, driven by the same
  * engine signal over a fast bridge event that runs only while mounted.
  *
  * Two levels of customization:
- * 1. Props on <CrowdPlayVoiceView> — colors and size of the built-in orb.
- * 2. useVoiceActivity() — the phase + smoothed energy underneath, for apps
+ * 1. Props on <CrowdPlayVoiceView>: colors and size of the built-in orb.
+ * 2. useVoiceActivity(): the phase + smoothed energy underneath, for apps
  *    that want to draw something entirely their own.
  */
 
@@ -58,7 +58,7 @@ export function useVoiceActivity(): VoiceActivity {
         phase = 'idle';
         target = 0;
       }
-      // Fast attack, slow release — speech onsets snap, tails breathe out.
+      // Fast attack, slow release: speech onsets snap, tails breathe out.
       const rate = target > energyRef.current ? 0.55 : 0.12;
       energyRef.current += (target - energyRef.current) * rate;
       setActivity({ phase, energy: energyRef.current });
@@ -92,7 +92,7 @@ export function useLatestCaption(): VoiceCaption | null {
   return caption;
 }
 
-/** Make ANY child view breathe, pulse, and glow with the conversation —
+/** Make ANY child view breathe, pulse, and glow with the conversation;
  * the one-line path from the app's own art (mascot, logo, character) to a
  * living AI presence. */
 export function VoiceReactive({