crowdplaysdk 0.4.0 → 0.4.2

package/Examples/App.tsx

@@ -91,7 +91,7 @@ export default function App(): React.JSX.Element {
 
   return (
     <SafeAreaView style={styles.screen}>
-      {/* The session is NOT being recorded when this is non-null — always show it. */}
+      {/* The session is NOT being recorded when this is non-null; always show it. */}
       {recordingError ? (
         <View style={styles.banner}>
           <Text style={styles.bannerText}>NOT RECORDING: {recordingError}</Text>
@@ -121,7 +121,7 @@ export default function App(): React.JSX.Element {
         />
       </View>
 
-      {/* Audio output menu (D-079): standard in every build — shows the
+      {/* Audio output menu (D-079): standard in every build; shows the
           device by name and lets the user flip to Speaker and back. */}
       <View style={styles.controls}>
         <Text>{route?.currentOutputName ?? 'audio output'}</Text>

package/LICENSE.md

@@ -0,0 +1,14 @@
+# CrowdPlay SDK License
+
+Copyright © 2026 Symbia Co. All rights reserved.
+
+The CrowdPlay SDK is distributed as a compiled binary for integration into
+applications that deliver recorded sessions to CrowdPlay. You may download,
+link, and ship the binary as part of such an application. You may not
+reverse engineer, decompile, redistribute the binary standalone, or use it
+to deliver data anywhere other than CrowdPlay. No source license is granted.
+
+This package depends on open-source software fetched from its own
+repositories under its own licenses: LiveKit Swift SDK and WebRTC
+(Apache License 2.0), swift-atomics (Apache License 2.0 with Runtime
+Library Exception). Their license terms apply to those components.

package/README.md

@@ -1,150 +1,232 @@
 # crowdplaysdk
 
-CrowdPlay's lossless conversation capture for **React Native (iOS)**. Your app
-hosts a live video call; every participant's audio (**48 kHz / 24-bit
-unprocessed WAV**) and video (**1080p30 HEVC**) is recorded **locally, at
-full quality**, clock-aligned across participants, and delivered to CrowdPlay
-automatically — uploads retry, resume, and survive crashes.
+CrowdPlaySDK adds live calls and high-quality conversation capture to React
+Native iOS apps. It is the same compiled engine as the native CrowdPlaySDK
+Swift package, driven from JavaScript with control calls and state events.
+No media ever crosses the JS bridge, so recording quality is identical to a
+fully native app.
 
-**No media ever crosses the JS bridge.** The engine is the same compiled
-native core (CrowdPlaySDK) our reference app runs; React Native drives it with
-control calls and receives state events. Recording quality is identical to
-a fully native app.
+## What the SDK handles
 
-## Non-technical? Paste this to your AI agent
+* Joining and leaving calls
+* Microphone and camera access
+* Participant audio and video
+* Mute, camera, and audio-output controls
+* User consent before capture begins
+* Per-participant data capture and synchronization
+* Uploads, retries, and recovery
+* Session lifecycle and common interruptions
 
+Once a user consents and joins a call, capture and delivery happen
+automatically.
+
+## What you build
+
+You build the actual product and user experience:
+
+* Your app's screens, navigation, and design
+* What users do in your app
+* When and why a call happens
+* The UI around the call
+* Your own accounts, profiles, content, or other product features
+
+For example, if you're building a tutoring app, **you build the tutoring
+experience**. CrowdPlaySDK provides the call and capture infrastructure
+underneath it.
+
+Your integration is essentially:
+
+**Your app → consent → join call → CrowdPlay handles the rest**
+
+## Three kinds of calls
+
+You pick one when you create your app on the dashboard, and you can change
+it later:
+
+* **Video + audio.** Face-to-face calls between people. Both are recorded.
+* **Audio-only.** Voice calls between people, no camera anywhere in the app.
+* **Voice AI.** Your users talk with a live AI voice instead of another
+  person. Audio only, no camera.
+
+## Getting started
+
+Sign in at **https://dashboard.crowdplay.ai**, create your app, and press
+**Copy agent prompt**. The prompt is pre-filled with your key and tailored
+to the tool you build with, so paste it into your coding agent and it will
+build the app. Your dashboard then tracks setup and shows your recordings.
+
+**Building in Swift?** Use the CrowdPlaySDK Swift package instead:
+https://github.com/symbiateam/crowdplaysdk
+
+## Setup (iOS)
+
+Requirements: iOS 17+, React Native 0.71 or newer, a real device to test
+(the Simulator has no camera or mic), and an **app key** from CrowdPlay.
+iOS only for now; calls to the module on other platforms throw with a
+clear message.
+
+**1. Install the package and wire the engine.**
+
+```bash
+npm install crowdplaysdk
+cd ios && pod install
+gem install xcodeproj --user-install              # one time
+ruby node_modules/crowdplaysdk/ios/wire.rb <YourProjectName>
+```
+
+`wire.rb` is idempotent. It adds the compiled CrowdPlaySDK Swift package,
+copies the three bridge files into your app target, and points the Swift
+bridging header at the React headers. There is no CocoaPod of our own, so
+your Podfile stays untouched.
+
+**2. Declare permissions in Info.plist.**
+
+```
+NSMicrophoneUsageDescription = "Records your microphone during sessions."
+NSCameraUsageDescription     = "Records your camera during sessions."
+UIBackgroundModes            = [audio]
 ```
-I'm building this app: <YOUR APP IDEA — e.g., a tutoring app where
-students and tutors meet over video>
-
-Build it as a React Native iOS app. For the video-call feature, use the
-crowdplaysdk package.
-
-What the app is about — read carefully:
-- The app's name, screens, and flows are about MY IDEA above. The SDK
-  records calls in the background for CrowdPlay; recording is NOT the
-  app's purpose and must not be presented as it. It appears in the UI in
-  the SDK's consent screen before joining a call,
-  a small REC indicator during the call, join/leave, and a small
-  audio-output menu.
-- Keep the SDK integration minimal: consent → join/leave → call screen.
-  The call screen MUST include a small audio-output menu showing the
-  current output device by name (from the 'audioRoute' event) with a
-  switch between the device and Speaker (CrowdPlay.setAudioOutput). Do
-  NOT build upload screens, diagnostics screens, or SDK settings.
-  Uploads happen automatically in the background.
-
-- npm install crowdplaysdk
-- In ios/: pod install, then run
-    gem install xcodeproj --user-install   # one-time
-    ruby node_modules/crowdplaysdk/ios/wire.rb <MyProjectName>
-  (adds the compiled CrowdPlay engine + bridge to the Xcode project)
-- Info.plist: NSMicrophoneUsageDescription, NSCameraUsageDescription,
-  UIBackgroundModes = [audio]
-- My CrowdPlay app key: <APP KEY from the CrowdPlay dashboard>
-- Follow node_modules/crowdplaysdk/llms.txt exactly: configure at
-  startup, the CrowdPlayConsentScreen before joining (join() throws
-  without a ConsentGrant), CrowdPlayVideoView tiles from the participants
-  event, and surface the warning events on the call screen.
-- Never add, pin or import LiveKit/WebRTC yourself, and never write your
-  own AVAudioSession/AVCaptureSession code — the engine owns the mic and
-  camera.
-- When done, run CrowdPlay.doctor() as a development check (not an app
-  screen) and fix anything actionable.
-- Your FINAL message must walk me through testing on my real iPhone,
-  step by step (the Simulator has no camera or mic, so nothing is proven
-  until then): plugging it in, signing/Developer Mode, running from
-  Xcode, allowing permissions, doing a ~1-minute test call, and checking
-  my session at https://dashboard.crowdplay.ai. Do not just say the
-  implementation is complete.
+
+**3. Let uploads finish while the app is suspended** (recommended). In your
+AppDelegate:
+
+```objc
+// AppDelegate.mm, with #import "<YourProjectName>-Swift.h" at the top
+- (void)application:(UIApplication *)application
+    handleEventsForBackgroundURLSession:(NSString *)identifier
+    completionHandler:(void (^)(void))completionHandler {
+  [CrowdPlayRNBackground handleWithCompletionHandler:completionHandler];
+}
 ```
 
-## Manual setup (iOS)
-
-1. `npm install crowdplaysdk`
-2. `cd ios && pod install`
-   (one-time: `gem install xcodeproj --user-install` — the wiring script needs it)
-3. `ruby node_modules/crowdplaysdk/ios/wire.rb <YourProjectName>` —
-   idempotent; adds the CrowdPlaySDK Swift package (the compiled engine), copies
-   the three bridge files into your app target, and points the Swift
-   bridging header at the React headers. (No CocoaPod of our own: the
-   engine ships as a binary Swift package, which keeps your Podfile
-   untouched.)
-4. Info.plist: `NSMicrophoneUsageDescription`, `NSCameraUsageDescription`,
-   `UIBackgroundModes = [audio]`.
-5. Recommended, for uploads that finish while your app is suspended — in
-   your AppDelegate:
-
-   ```objc
-   // AppDelegate.mm — add #import "<YourProjectName>-Swift.h" at the top
-   - (void)application:(UIApplication *)application
-       handleEventsForBackgroundURLSession:(NSString *)identifier
-       completionHandler:(void (^)(void))completionHandler {
-     [CrowdPlayRNBackground handleWithCompletionHandler:completionHandler];
-   }
-   ```
-
-   (Swift AppDelegates call `CrowdPlaySDK.handleBackgroundURLSessionEvents(completionHandler:)`.)
+Swift AppDelegates call `CrowdPlaySDK.handleBackgroundURLSessionEvents(completionHandler:)`.
 
 ## Usage
 
 ```tsx
 import CrowdPlay, { CrowdPlayConsentScreen, CrowdPlayVideoView } from 'crowdplaysdk';
 
-CrowdPlay.configure({ serverUrl: 'https://…', appKey: 'liva_pk_…' });
-// Voice-only app? add audioOnly: true — the camera is never touched
-// (no camera permission, no video captured or uploaded).
+CrowdPlay.configure({
+  serverUrl: 'https://dashboard.crowdplay.ai',
+  appKey: 'liva_pk_…',
+  // audioOnly: true,     // audio-only or Voice AI app: no camera at all
+  // otherAudio: 'mix',   // keep Apple Music / Spotify playing (0.4.0+)
+});
 
-// 1. Consent (REQUIRED — join() throws without it):
+// 1. Consent (required; join() throws without it):
 <CrowdPlayConsentScreen onConsent={(grant) => setConsent(grant)} />
 
-// 2. Join — recording starts automatically:
+// 2. Join. Recording starts automatically:
 await CrowdPlay.join({ displayName, roomCode, consent });
 
 // 3. Render the call:
-<CrowdPlayVideoView participant="local" style={…} />           // self view
+<CrowdPlayVideoView participant="local" style={…} />            // self view
 {participants.map(p => <CrowdPlayVideoView participant={p.identity} … />)}
 
 // 4. Controls:
-await CrowdPlay.setMicMuted(true);      // mutes the call AND records silence
+await CrowdPlay.setMicMuted(true);       // mutes the call and records silence
 await CrowdPlay.setCameraEnabled(false); // black frames, timeline continuous
 await CrowdPlay.leave();                 // stops recording; uploads continue
+```
+
+State arrives as events:
 
-// State: subscribe to events
-CrowdPlay.addListener('phase', …)         // idle/connecting/connected/failed
+```tsx
+CrowdPlay.addListener('phase', …)         // idle / connecting / connected / failed
 CrowdPlay.addListener('participants', …)  // who to render tiles for
 CrowdPlay.addListener('uploads', …)       // per-session progress
-CrowdPlay.addListener('warning', …)       // micSilent / clipping / crossTalk — SHOW THESE
-CrowdPlay.addListener('recording', …)     // error ⇒ NOT capturing; offer retryRecording()
-CrowdPlay.addListener('audioRoute', …)    // current output device — drive the output menu
+CrowdPlay.addListener('warning', …)       // micSilent / clipping / crossTalk: show these
+CrowdPlay.addListener('recording', …)     // error means NOT capturing; offer retryRecording()
+CrowdPlay.addListener('audioRoute', …)    // current output device, for the output menu
 CrowdPlay.setAudioOutput('speaker')       // or 'automatic' (the connected device)
-CrowdPlay.snapshot()                      // poll 1 Hz for REC timer + input level
-CrowdPlay.doctor()                        // integration self-check
+CrowdPlay.snapshot()                      // poll at 1 Hz for the REC timer and input level
+```
+
+That's the whole integration. Capture, sync, upload, retry and crash
+recovery are invisible. The complete example lives in this package's
+`Examples` folder: one file, consent → join → tiles → warnings → uploads.
+
+## Voice AI
+
+If you picked **Voice AI**, a live AI voice joins the call as an ordinary
+participant, greets your user, and holds a real spoken conversation. Users
+can interrupt it and it responds with natural timing. Both sides are
+recorded and transcribed like any other call.
+
+**Your app writes no AI code.** No model API calls, no API keys, no speech
+recognition, no text-to-speech. You choose the AI's voice and personality
+on the dashboard and can change them any time; everything else runs on
+CrowdPlay's servers.
+
+The only thing your app draws is what the AI looks like on screen. It has
+no camera, so never give it a video tile. The SDK ships an animated orb
+that breathes when idle, ripples with your user's voice, and pulses when
+the AI speaks:
+
+```tsx
+<CrowdPlayVoiceView />
+```
+
+Restyle it with props, wrap your own artwork in `<VoiceReactive>`, or drive
+any visual from the `useVoiceActivity()` hook. Show live subtitles with
+`useLatestCaption()`, and identify the AI participant by name `agent`.
+
+You can also override the voice, personality and context for a single call,
+which is how you give the AI memory of a particular user:
+
+```tsx
+await CrowdPlay.join({
+  displayName, roomCode, consent,
+  agent: { voice: 'Aoede', context: 'Their name is Sam. Last time you discussed Kyoto.' },
+});
+```
+
+See `llms.txt` in this package for the full menu of visuals and options.
+
+## Verifying your integration
+
+```tsx
+const checks = await CrowdPlay.doctor();
+```
+
+Doctor verifies configuration, Info.plist strings, permissions, free disk,
+backend reachability and your app key. Every failing check names its own
+fix. Then record a one-minute session on a real device and confirm the
+upload finishes.
+
+## Accessing your recordings
+
+Your app key is also your data-access credential: plain HTTPS, no AWS
+account, no SDK required.
+
+```bash
+BASE=https://dashboard.crowdplay.ai
+
+curl -H "x-liva-key: $APP_KEY" $BASE/sessions
+curl -H "x-liva-key: $APP_KEY" $BASE/sessions/<sessionId>/files
 ```
 
-The complete example lives in this repo's `Examples` (one file, ~170
-lines): consent → join → tiles → warnings → uploads.
-
-## Accessing recordings
-
-Your app key doubles as your data credential — see the CrowdPlay dashboard
-(browse + download per session) or the REST endpoints (`GET /sessions`,
-`GET /sessions/<id>/files`) documented in the CrowdPlaySDK README.
-
-## Requirements & limits
-
-- iOS 17+, React Native ≥ 0.71. **iOS only for now** — no Android engine
-  yet, calls to the module on other platforms throw with a clear message.
-- Real device required to record (the Simulator has no camera/mic).
-- The npm version can run ahead of the compiled engine version wire.rb
-  pins — bridge and doc fixes ship without a new engine binary. wire.rb
-  always pins the engine release this bridge was tested against.
-- Keep the screen awake during sessions; force-quitting the app pauses
-  uploads until next launch (they resume automatically).
-- **Slow join + glitchy first seconds = bad radio, not a bug.** Congested
-  2.4 GHz WiFi plus Bluetooth headphones (they share the antenna) slows the
-  call connect and can chop the first seconds of audio while the Bluetooth
-  link settles; capture self-heals and the rest of the session is
-  unaffected. Prefer a good network and wired headphones, and evaluate
-  quality with the app launched from the home screen — Metro/debugger
-  overhead can reproduce the same symptoms.
+`deliverable/` holds what you actually use: one clean audio file per
+person, aligned so they play together with no offset, plus a mixed version
+and a quality report. You can only reach sessions recorded with your key.
+
+## Things to know
+
+- **Don't force-quit the app** after a session: iOS pauses background
+  transfers until next launch. They resume automatically and nothing is
+  lost.
+- Sessions are roughly 2 GB per participant-hour, dominated by video. The
+  SDK refuses to join below 8 GB free disk.
+- Participants should wear **wired or closed-back headphones**. A
+  loudspeaker pipes the far end into the local mic and contaminates the
+  track; the SDK surfaces this live through the `warning` event.
+- **Slow join or glitchy first seconds is bad radio, not a bug.** Congested
+  2.4 GHz WiFi and Bluetooth headphones share an antenna. Capture
+  self-heals and the rest of the session is fine. Metro and the debugger
+  cause the same symptoms, so launch from the home screen when judging
+  quality.
+- The npm version can run ahead of the engine version `wire.rb` pins;
+  bridge and doc fixes ship without a new engine binary.
+
+`llms.txt` carries the full reference, including every event and warning
+and the voice-AI options. It is written for coding agents.

package/ios/CrowdPlayRNModule.swift

@@ -113,19 +113,19 @@ final class CrowdPlayRNCore {
         let snapshot = engine.recordingSnapshot()
         updateWarning("audioStalled",
                       active: snapshot?.audioStalled == true,
-                      message: "Audio capture stalled — the engine is being restarted. "
+                      message: "Audio capture stalled; the engine is being restarted. "
                         + "If this persists, leave and rejoin.")
         updateWarning("micSilent",
                       active: snapshot?.inputSilent == true && !engine.isMicMuted,
-                      message: "No sound is reaching the microphone — check the headset "
+                      message: "No sound is reaching the microphone; check the headset "
                         + "plug or switch to the phone microphone.")
         updateWarning("clipping",
                       active: (snapshot?.fullScaleSamples ?? 0) > 100,
-                      message: "The microphone is clipping — audio is distorting. Move "
+                      message: "The microphone is clipping; audio is distorting. Move "
                         + "the mic away or lower the input.")
         updateWarning("crossTalk",
                       active: engine.crossTalkRisk,
-                      message: "Playing through the loudspeaker — the other person's "
+                      message: "Playing through the loudspeaker; the other person's "
                         + "voice is being recorded into this microphone. Use headphones.")
         updateWarning("micPolicy",
                       active: engine.micPolicyViolation != nil,
@@ -136,7 +136,7 @@ final class CrowdPlayRNCore {
 
     private var voiceTimer: Timer?
 
-    /// Fast (0.15 s) voice-activity stream for the animated voice UI —
+    /// Fast (0.15 s) voice-activity stream for the animated voice UI , 
     /// runs only while some JS component is subscribed, so the bridge
     /// stays quiet for apps that never render it.
     func startVoiceActivity() {
@@ -205,7 +205,7 @@ final class CrowdPlayRNCore {
 ///     [CrowdPlayRNBackground handleWithCompletionHandler:completionHandler];
 ///
 /// iOS eventually stops delivering background upload events to apps that
-/// skip this — uploads still finish, just less promptly.
+/// skip this; uploads still finish, just less promptly.
 @objc(CrowdPlayRNBackground)
 public final class CrowdPlayRNBackground: NSObject {
     @objc public static func handle(completionHandler: @escaping () -> Void) {
@@ -258,6 +258,12 @@ public final class CrowdPlayRNModule: RCTEventEmitter {
             if let duringCall = config["uploadDuringCall"] as? Bool {
                 configuration.uploadDuringCall = duringCall
             }
+            // D-093: other apps' audio during the call. Unknown strings keep
+            // the default (.interrupt) rather than failing configure.
+            if let policy = config["otherAudio"] as? String,
+               let parsed = CrowdPlayConfiguration.OtherAudioPolicy(rawValue: policy) {
+                configuration.otherAudio = parsed
+            }
             if let quality = config["callQuality"] as? [String: Any] {
                 var callQuality = CallQuality()
                 if let v = quality["videoWidth"] as? Int { callQuality.videoWidth = v }

package/ios/CrowdPlayRNVideoView.swift

@@ -5,7 +5,7 @@ import React
 import UIKit
 
 /// Native video tile hosted in the RN layout. Resolves the requested
-/// participant's track from the shared engine on a short poll — idempotent
+/// participant's track from the shared engine on a short poll; idempotent
 /// and reconnect-proof, and the video itself never touches JavaScript.
 final class CrowdPlayRNVideoView: UIView {
     private let videoView = VideoView()

package/ios/CrowdPlayReactNative.m

@@ -1,6 +1,6 @@
 // Objective-C registration for the CrowdPlay RN bridge. Add this file AND the
 // two Swift files to your app target (they compile alongside your app, with
-// CrowdPlaySDK coming from the Swift package — see the package README).
+// CrowdPlaySDK coming from the Swift package; see the package README).
 #import <React/RCTBridgeModule.h>
 #import <React/RCTEventEmitter.h>
 #import <React/RCTViewManager.h>

package/ios/wire.rb

@@ -3,7 +3,7 @@
 #
 #   ruby node_modules/crowdplaysdk/ios/wire.rb <YourProjectName>
 #
-# What it does (idempotent — safe to re-run):
+# What it does (idempotent; safe to re-run):
 #   1. adds the CrowdPlaySDK Swift package (compiled engine) to the project
 #   2. copies the three bridge files into your app group + target
 #   3. creates/points the Swift bridging header at the React headers
@@ -30,7 +30,7 @@ BRIDGE_FILES = ['CrowdPlayRNModule.swift', 'CrowdPlayRNVideoView.swift', 'CrowdP
 
 project_name = ARGV[0] or abort 'usage: ruby wire.rb <YourProjectName>'
 project_path = "#{project_name}.xcodeproj"
-abort "#{project_path} not found — run from your app's ios/ directory" unless File.exist?(project_path)
+abort "#{project_path} not found; run from your app's ios/ directory" unless File.exist?(project_path)
 
 package_dir = File.expand_path(File.dirname(__FILE__))
 project = Xcodeproj::Project.open(project_path)
@@ -68,7 +68,7 @@ end
 target.build_configurations.each do |config|
   config.build_settings['SWIFT_VERSION'] ||= '5.0'
   # CrowdPlaySDK requires iOS 17; RN templates default far lower. Only the APP
-  # target is raised — pods keep their own targets, which is fine.
+  # target is raised; pods keep their own targets, which is fine.
   current = config.build_settings['IPHONEOS_DEPLOYMENT_TARGET']
   if current.nil? || current.to_f < 17.0
     config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '17.0'
@@ -86,7 +86,7 @@ target.build_configurations.each do |config|
   end
   # The setting must point at wherever the file ACTUALLY went. When the
   # project has no group named after itself (newer RN templates), the
-  # fallback above places files at the project root — hardcoding
+  # fallback above places files at the project root; hardcoding
   # "<Project>/<header>" there produced a missing-input build failure
   # (field-reported on the RN 0.87 template). Derive it instead:
   # SRCROOT is the .xcodeproj's directory.

package/lib/ConsentScreen.js

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

package/lib/VideoView.d.ts

@@ -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/lib/VideoView.js

@@ -2,7 +2,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/lib/VoiceView.d.ts

@@ -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.
  */
 import React from 'react';
@@ -27,7 +27,7 @@ export interface VoiceCaption {
 /** The latest live transcript line (speech bubbles, subtitles). Captions
  * are broadcast by the voice agent as it speaks; null until the first one. */
 export declare function useLatestCaption(): VoiceCaption | null;
-/** 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 declare function VoiceReactive({ children, glowColor, }: {

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. */
@@ -88,10 +96,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 +135,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;
@@ -175,7 +183,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.
      */

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.
      */

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
@@ -177,34 +177,34 @@ 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.
 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 +215,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 +228,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 +248,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 +275,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 +295,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.0",
+  "version": "0.4.2",
   "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",
@@ -10,7 +10,8 @@
     "ios",
     "README.md",
     "llms.txt",
-    "Examples"
+    "Examples",
+    "LICENSE.md"
   ],
   "scripts": {
     "build": "tsc",

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({

package/src/index.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.
  */
 
@@ -45,7 +45,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;
@@ -54,14 +54,22 @@ 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. */
@@ -100,10 +108,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;
 }
 
@@ -141,7 +149,7 @@ export interface CrowdPlayEvents {
   /** Connection lifecycle. `error` is set when phase === 'failed'. */
   phase: { phase: Phase; 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 };
   /** Upload progress for every session with outstanding or recent work. */
   uploads: { sessions: UploadProgress[]; onWifi: boolean };
@@ -189,8 +197,8 @@ function native(): NativeCrowdPlay {
       "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. " +
-        (Platform.OS !== 'ios' ? `(platform '${Platform.OS}' is not supported yet — iOS only.)` : '')
+        "to your app target; see the package README. " +
+        (Platform.OS !== 'ios' ? `(platform '${Platform.OS}' is not supported yet; iOS only.)` : '')
     );
   }
   return module;
@@ -240,7 +248,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.
    */