@lumavox/react-native 0.16.0 → 0.17.0

package/README.md

@@ -3,7 +3,7 @@
 Voice conversations with Lumavox agents in a React Native app, on iOS,
 Android and the web — **one install**: the client (`@lumavox/client`), the
 hooks (`@lumavox/react`), and the audio they lack, a player and a recorder
-for **push-to-talk**, on
+for **push-to-talk**, **half-duplex** and **hands-free**, on
 [`react-native-audio-api`](https://github.com/software-mansion/react-native-audio-api)
 on a phone and Web Audio in a browser.
 
@@ -54,10 +54,20 @@ function Talk({ agentId }: { agentId: string }) {
 - A call, Siri or another app pauses the reply and throws away a recording
   in progress — `interrupted`, `onAudioInterrupted`, `onAudioResumed`; so
   does leaving the screen: no background audio in this release.
-- Hands-free (`agent.listen()`) runs on the web, where the browser cancels
-  echo; on a phone it is refused until `react-native-audio-api` 1.0 does —
-  `listen({ assumeNoEcho: true })` with headphones on. Background audio
-  comes with 1.0 too.
+- **Half-duplex on every phone**: `agent.listen({ halfDuplex: true })` —
+  tap once and talk for the whole conversation; the microphone stays open,
+  but nothing is heard while the agent speaks, so it never hears itself
+  and needs no echo cancellation. It cannot be talked over: give a stop
+  button (`agent.cancel()`).
+- **Hands-free** (`agent.listen()`, talking over the agent to stop it):
+  on the web where the browser cancels echo, and on a phone **in early
+  access**, on one build of the audio library, exactly:
+  `npm install react-native-audio-api@1.0.0-nightly-6fd4c68-20261102`,
+  then build the app again. While it listens the phone's sound is a
+  call's — the echo taken out, the agent a little quieter — and Bluetooth
+  earbuds' microphone is used. On 0.13 it is refused (`audio.handsFree()`
+  says why): offer half-duplex, or `listen({ assumeNoEcho: true })` with
+  headphones on. Background audio comes with the library's 1.0.
 - **A clock for a lip-synced face or subtitles**, on a phone and the web:
   `audio.onScheduled(({ pcm, sample_rate, chunk, startsAt }) => …)` tells
   every frame as it is queued, before it plays; draw against

package/app.plugin.js

@@ -68,7 +68,10 @@ function audioApiOptions(options = {}) {
     androidFSStopWithTask: true,
     // The library's own defaults: FFmpeg decodes compressed files, which a
     // conversation's raw PCM never needs — `true` makes the app smaller.
+    // 1.0 turned the option round, FFmpeg off unless `enableFFmpeg`: each
+    // build reads its own and ignores the other's, so both say the same.
     disableFFmpeg: options.disableFFmpeg ?? false,
+    enableFFmpeg: !(options.disableFFmpeg ?? false),
     disableStaticExternalLibs: options.disableStaticExternalLibs ?? false,
   };
 }
@@ -90,7 +93,8 @@ function withLumavox(config, options, library) {
 }
 
 function loadLibrary() {
-  const plugin = require(`${LIBRARY}/app.plugin`);
+  // With its extension: 1.0's `exports` names `./app.plugin.js` alone.
+  const plugin = require(`${LIBRARY}/app.plugin.js`);
   return plugin.default ?? plugin;
 }
 

package/dist/audio.native.d.ts

@@ -1,6 +1,7 @@
 /**
- * A phone's player and recorder, on `react-native-audio-api` 0.13.6: what
- * Metro picks for `./audio` on iOS and Android (`index.ts`). With
+ * A phone's player and recorder, on `react-native-audio-api` — 0.13.6, or
+ * the one 1.0 nightly hands-free runs on (`session.ts`, `PINNED_NIGHTLY`):
+ * what Metro picks for `./audio` on iOS and Android (`index.ts`). With
  * `session.ts`, the only file that touches the library.
  *
  * - **The reply plays through one `AudioBufferQueueSourceNode`**, started
@@ -25,7 +26,8 @@
  * - **What is heard is the clock less the app's `outputLatencyMs`**:
  *   0.13.6 says nothing of the device's latency — its source nodes'
  *   `getLatency()` is their time-stretcher's — so the app, which can know
- *   its earbuds are on, says it.
+ *   its earbuds are on, says it. Unset on the nightly, the context's own
+ *   (`outputLatency` and `baseLatency`, 1.0's).
  * - **The microphone records at 16 kHz**, mono, 100 ms a buffer — less to
  *   send than 24 kHz, and a rate the socket takes. `onAudioReady` hands the
  *   samples over JSI as floats, at the rate the device chose, which need
@@ -36,22 +38,60 @@
  *   thrown away (the hook discards the recording on the socket). The audio
  *   comes back on its own when the system says it may, else on `resume()`
  *   or the next press.
- * - **No hands-free**: 0.13.6 cancels no echo, so a microphone left open
- *   hears the agent (D12, D16). `handsFree` refuses until 1.0; with
- *   headphones on, the app passes `assumeNoEcho`.
+ * - **Half-duplex on any build** (`listen`'s `halfDuplex`): the recorder
+ *   started once for the whole conversation, which suits the library —
+ *   on iOS, 0.13.6's recorder shares the player's one engine, and each
+ *   start stops and starts it and each stop rebuilds it, a gap in the
+ *   voice; the loudspeaker holds (`defaultToSpeaker`), and Android's
+ *   recorder and player are two streams that open side by side.
+ * - **Hands-free on the pinned nightly alone** (D17, D18; `handsFree`):
+ *   0.13.6 cancels no echo, so a microphone left open hears the agent
+ *   (D12, D16) — refused there, `assumeNoEcho` with headphones on. On the
+ *   nightly a capture that asks for echo cancellation (`listen` does, on
+ *   `handsFree`'s yes) is iOS's voice processing in `videoChat`, and
+ *   Android's voice-communication input with the reply on the call's path
+ *   (`androidOutputProfile`), in its communication mode
+ *   (`session.configure`): its canceller hears only that path. The reply
+ *   moves to it — a new context — once nothing is playing, never mid-word,
+ *   and back once the capture ends. **A recorder that will not start that
+ *   way fails the capture**, and `listen` answers why: the app offers
+ *   half-duplex (D16, D19). Whether an Android phone's canceller works is
+ *   not asked: the platform says it only to native code (left-overs #177).
+ * - **`duck`**: the reply goes through a gain, lowered while it may be
+ *   talked over — barge-in's first step.
  */
 import { type AgentAudio, type AudioDevice, type ScheduledAudio } from "@lumavox/client";
 import type { AudioOptions, CreateAudio, DeviceAudio, Output } from "./device-audio.js";
 /** Hz the microphone records at unless a rate the socket takes is asked. */
 export declare const RECORD_RATE = 16000;
-/** Why `handsFree` refuses on a phone. */
-export declare const PHONE_ECHO = "Hands-free needs echo cancellation, which comes with react-native-audio-api 1.0. Use push-to-talk, or assumeNoEcho with headphones on.";
+/** Why `handsFree` refuses on 0.13. */
+export declare const PHONE_ECHO = "Hands-free needs echo cancellation, which comes with react-native-audio-api 1.0. Use half-duplex or push-to-talk, or assumeNoEcho with headphones on.";
+/** Why it refuses on a 1.0 build that is not the one it was tested on. */
+export declare const untestedBuild: (version: string) => string;
 export declare class PhoneAudio implements DeviceAudio {
     interrupted: boolean;
     /** On a phone the system chooses the speaker. */
     readonly canChooseOutput = false;
     private context;
     private queue;
+    /** Between the queue and the speaker: the reply lowered while it may be talked over. */
+    private gain;
+    private volume;
+    /** The context's output on Android: the call's path while hands-free cancels echo. */
+    private profile;
+    /** A capture is cancelling echo: the session is hands-free's. */
+    private cancelling;
+    private unroute;
+    private output;
+    private disposed;
+    /** The call's route last asked on Android (`session.route`). */
+    private routed;
+    /**
+     * Until when an interruption is the session made again — Android's focus
+     * given up and taken back, told a moment later on its own thread — and
+     * not another app's.
+     */
+    private settling;
     /** The ids of the buffers enqueued and not yet played. */
     private readonly playing;
     /** Where the last buffer enqueued ends, on the context's clock. */
@@ -67,6 +107,7 @@ export declare class PhoneAudio implements DeviceAudio {
     private readonly unwatch;
     /** Seconds. */
     private readonly leadIn;
+    /** The app's, or `null`: the context's own where it says one. */
     private readonly latency;
     constructor(options?: AudioOptions);
     prime(): Promise<void>;
@@ -84,20 +125,43 @@ export declare class PhoneAudio implements DeviceAudio {
     setInput(): void;
     setProcessing(): void;
     setOutputDevice(): Promise<boolean>;
-    /** At 16 kHz, or at the rate asked when the socket takes it. */
+    /**
+     * At 16 kHz, or at the rate asked when the socket takes it; cancelling
+     * echo when hands-free asks and the library can.
+     */
     startCapture(onPcm: (pcm: ArrayBuffer) => void, options?: {
         rate?: number;
+        echoCancellation?: boolean;
     }): Promise<{
         rate: number;
     }>;
+    /** The recorder, open: its echo cancelled when `cancel`. */
+    private record;
     stopCapture(): Promise<void>;
     resume(): Promise<void>;
     setOutput(output: Output): void;
+    /** Hands-free's first step on sound over the reply: lowered, until the words say who it was. */
+    duck(on: boolean): void;
     handsFree(): ReturnType<DeviceAudio["handsFree"]>;
     onInterruption(fn: (interrupted: boolean) => void): () => void;
     dispose(): void;
     /** Behind what is queued; the playhead moves to its end. */
     private enqueue;
+    /**
+     * The session hands-free's, Android's reply on the call's path and the
+     * call's route: before the recorder starts, so the canceller hears the
+     * first reply too.
+     */
+    private enterHandsFree;
+    /** Back to push-to-talk's session; the reply leaves the call's path once it has played out. */
+    private leaveHandsFree;
+    /**
+     * The session for hands-free or not — disposed, the mode given back and
+     * nothing taken again for a screen gone — its focus's comings and goings
+     * no interruption.
+     */
+    private reconfigure;
+    private reroute;
     /** The queue for a reply at `rate`: this one, or a new context's. */
     private player;
     /**

package/dist/audio.native.js

@@ -1,6 +1,7 @@
 /**
- * A phone's player and recorder, on `react-native-audio-api` 0.13.6: what
- * Metro picks for `./audio` on iOS and Android (`index.ts`). With
+ * A phone's player and recorder, on `react-native-audio-api` — 0.13.6, or
+ * the one 1.0 nightly hands-free runs on (`session.ts`, `PINNED_NIGHTLY`):
+ * what Metro picks for `./audio` on iOS and Android (`index.ts`). With
  * `session.ts`, the only file that touches the library.
  *
  * - **The reply plays through one `AudioBufferQueueSourceNode`**, started
@@ -25,7 +26,8 @@
  * - **What is heard is the clock less the app's `outputLatencyMs`**:
  *   0.13.6 says nothing of the device's latency — its source nodes'
  *   `getLatency()` is their time-stretcher's — so the app, which can know
- *   its earbuds are on, says it.
+ *   its earbuds are on, says it. Unset on the nightly, the context's own
+ *   (`outputLatency` and `baseLatency`, 1.0's).
  * - **The microphone records at 16 kHz**, mono, 100 ms a buffer — less to
  *   send than 24 kHz, and a rate the socket takes. `onAudioReady` hands the
  *   samples over JSI as floats, at the rate the device chose, which need
@@ -36,17 +38,41 @@
  *   thrown away (the hook discards the recording on the socket). The audio
  *   comes back on its own when the system says it may, else on `resume()`
  *   or the next press.
- * - **No hands-free**: 0.13.6 cancels no echo, so a microphone left open
- *   hears the agent (D12, D16). `handsFree` refuses until 1.0; with
- *   headphones on, the app passes `assumeNoEcho`.
+ * - **Half-duplex on any build** (`listen`'s `halfDuplex`): the recorder
+ *   started once for the whole conversation, which suits the library —
+ *   on iOS, 0.13.6's recorder shares the player's one engine, and each
+ *   start stops and starts it and each stop rebuilds it, a gap in the
+ *   voice; the loudspeaker holds (`defaultToSpeaker`), and Android's
+ *   recorder and player are two streams that open side by side.
+ * - **Hands-free on the pinned nightly alone** (D17, D18; `handsFree`):
+ *   0.13.6 cancels no echo, so a microphone left open hears the agent
+ *   (D12, D16) — refused there, `assumeNoEcho` with headphones on. On the
+ *   nightly a capture that asks for echo cancellation (`listen` does, on
+ *   `handsFree`'s yes) is iOS's voice processing in `videoChat`, and
+ *   Android's voice-communication input with the reply on the call's path
+ *   (`androidOutputProfile`), in its communication mode
+ *   (`session.configure`): its canceller hears only that path. The reply
+ *   moves to it — a new context — once nothing is playing, never mid-word,
+ *   and back once the capture ends. **A recorder that will not start that
+ *   way fails the capture**, and `listen` answers why: the app offers
+ *   half-duplex (D16, D19). Whether an Android phone's canceller works is
+ *   not asked: the platform says it only to native code (left-overs #177).
+ * - **`duck`**: the reply goes through a gain, lowered while it may be
+ *   talked over — barge-in's first step.
  */
 import { DEFAULT_SAMPLE_RATE, floatToPcm16, pcm16ToFloat, RECORDING_RATES, resample, } from "@lumavox/client";
 import { AudioContext, AudioRecorder, } from "react-native-audio-api";
 import * as session from "./session.js";
 /** Hz the microphone records at unless a rate the socket takes is asked. */
 export const RECORD_RATE = 16000;
-/** Why `handsFree` refuses on a phone. */
-export const PHONE_ECHO = "Hands-free needs echo cancellation, which comes with react-native-audio-api 1.0. Use push-to-talk, or assumeNoEcho with headphones on.";
+/** Why `handsFree` refuses on 0.13. */
+export const PHONE_ECHO = "Hands-free needs echo cancellation, which comes with react-native-audio-api 1.0. Use half-duplex or push-to-talk, or assumeNoEcho with headphones on.";
+/** Why it refuses on a 1.0 build that is not the one it was tested on. */
+export const untestedBuild = (version) => `Hands-free runs on react-native-audio-api ${session.PINNED_NIGHTLY}, the build it was tested on; this app has ${version}. Use half-duplex or push-to-talk.`;
+/** After the session is made again, how long a focus change is still its own: Android tells it on another thread, a moment later. */
+const SETTLE_MS = 500;
+/** The reply's loudness while the person may be talking over it (`duck`): about -10 dB, as the web's. */
+const DUCKED = 0.3;
 /** Seconds of microphone per buffer delivered: the recorder's own latency. */
 const RECORD_SECONDS = 0.1;
 export class PhoneAudio {
@@ -56,6 +82,23 @@ export class PhoneAudio {
         this.canChooseOutput = false;
         this.context = null;
         this.queue = null;
+        /** Between the queue and the speaker: the reply lowered while it may be talked over. */
+        this.gain = null;
+        this.volume = 1;
+        /** The context's output on Android: the call's path while hands-free cancels echo. */
+        this.profile = "media";
+        /** A capture is cancelling echo: the session is hands-free's. */
+        this.cancelling = false;
+        this.unroute = null;
+        this.disposed = false;
+        /** The call's route last asked on Android (`session.route`). */
+        this.routed = null;
+        /**
+         * Until when an interruption is the session made again — Android's focus
+         * given up and taken back, told a moment later on its own thread — and
+         * not another app's.
+         */
+        this.settling = 0;
         /** The ids of the buffers enqueued and not yet played. */
         this.playing = new Set();
         /** Where the last buffer enqueued ends, on the context's clock. */
@@ -69,9 +112,17 @@ export class PhoneAudio {
         this.captured = new Set();
         this.interruptions = new Set();
         this.leadIn = (options.leadInMs ?? 0) / 1000;
-        this.latency = (options.outputLatencyMs ?? 0) / 1000;
-        session.configure(options.output ?? "speaker");
+        this.latency =
+            options.outputLatencyMs === undefined
+                ? null
+                : options.outputLatencyMs / 1000;
+        this.output = options.output ?? "speaker";
+        session.configure(this.output).catch(() => {
+            // swallowed: the library's defaults stand until `prime()` or a press sets the session again.
+        });
         this.unwatch = session.watch(({ began, shouldResume }) => {
+            if (Date.now() < this.settling)
+                return;
             if (began)
                 this.interrupt();
             else if (shouldResume && this.interrupted) {
@@ -138,7 +189,10 @@ export class PhoneAudio {
         return this.context?.currentTime ?? 0;
     }
     heardTime() {
-        return Math.max(0, this.now() - this.latency);
+        const context = this.context;
+        const latency = this.latency ??
+            (context?.outputLatency ?? 0) + (context?.baseLatency ?? 0);
+        return Math.max(0, this.now() - latency);
     }
     onScheduled(fn) {
         return add(this.scheduled, fn);
@@ -161,7 +215,10 @@ export class PhoneAudio {
     async setOutputDevice() {
         return false;
     }
-    /** At 16 kHz, or at the rate asked when the socket takes it. */
+    /**
+     * At 16 kHz, or at the rate asked when the socket takes it; cancelling
+     * echo when hands-free asks and the library can.
+     */
     async startCapture(onPcm, options) {
         // A press is the person going on: the audio is taken back first.
         if (this.interrupted)
@@ -176,7 +233,22 @@ export class PhoneAudio {
         const rate = asked && RECORDING_RATES.includes(asked)
             ? asked
             : RECORD_RATE;
-        const recorder = new AudioRecorder();
+        const cancel = options?.echoCancellation === true && session.cancelsEcho();
+        try {
+            if (cancel)
+                await this.enterHandsFree();
+            return await this.record(onPcm, rate, cancel);
+        }
+        catch (failure) {
+            await this.leaveHandsFree();
+            throw failure;
+        }
+    }
+    /** The recorder, open: its echo cancelled when `cancel`. */
+    async record(onPcm, rate, cancel) {
+        const recorder = new AudioRecorder(cancel
+            ? { iosVoiceProcessing: true, androidInputPreset: "voiceCommunication" }
+            : undefined);
         const mine = { recorder, open: true };
         const ready = recorder.onAudioReady({
             sampleRate: rate,
@@ -211,8 +283,10 @@ export class PhoneAudio {
     async stopCapture() {
         const mine = this.capture;
         this.capture = null;
-        if (!mine)
+        if (!mine) {
+            await this.leaveHandsFree();
             return;
+        }
         try {
             // What the recorder hands over until it has stopped is the end of
             // the last word: delivered before this settles.
@@ -221,6 +295,8 @@ export class PhoneAudio {
         finally {
             mine.open = false;
             mine.recorder.clearOnAudioReady();
+            // Once the recorder has let go: Android's session is made again.
+            await this.leaveHandsFree();
         }
     }
     async resume() {
@@ -232,43 +308,126 @@ export class PhoneAudio {
         this.tell(this.interruptions, false);
     }
     setOutput(output) {
-        session.configure(output);
+        this.output = output;
+        session.configure(output, this.cancelling).catch(() => {
+            // swallowed: the session stays as it was — the route the system chose.
+        });
+        if (this.cancelling)
+            this.reroute();
+    }
+    /** Hands-free's first step on sound over the reply: lowered, until the words say who it was. */
+    duck(on) {
+        this.volume = on ? DUCKED : 1;
+        if (this.gain)
+            this.gain.gain.value = this.volume;
     }
     async handsFree() {
-        return { ok: false, reason: PHONE_ECHO };
+        if (session.cancelsEcho())
+            return { ok: true };
+        const version = session.libraryVersion();
+        return {
+            ok: false,
+            reason: version.startsWith("0.") ? PHONE_ECHO : untestedBuild(version),
+        };
     }
     onInterruption(fn) {
         return add(this.interruptions, fn);
     }
     dispose() {
+        this.disposed = true;
         this.stop();
+        // Hands-free's session undone with the recorder.
         void this.stopCapture();
         this.unwatch();
         void this.context?.close();
         this.context = null;
         this.queue = null;
+        this.gain = null;
     }
     /** Behind what is queued; the playhead moves to its end. */
     enqueue(buffer) {
         this.playing.add(this.queue.enqueueBuffer(buffer));
         this.playhead += buffer.duration;
     }
+    /**
+     * The session hands-free's, Android's reply on the call's path and the
+     * call's route: before the recorder starts, so the canceller hears the
+     * first reply too.
+     */
+    async enterHandsFree() {
+        this.cancelling = true;
+        this.routed = null;
+        await this.reconfigure(true);
+        this.unroute ?? (this.unroute = session.watchRoutes(() => this.reroute()));
+        this.reroute();
+        if (this.context && this.playing.size === 0) {
+            this.player(this.context.sampleRate);
+        }
+    }
+    /** Back to push-to-talk's session; the reply leaves the call's path once it has played out. */
+    async leaveHandsFree() {
+        if (!this.cancelling)
+            return;
+        this.cancelling = false;
+        this.unroute?.();
+        this.unroute = null;
+        await this.reconfigure(false);
+    }
+    /**
+     * The session for hands-free or not — disposed, the mode given back and
+     * nothing taken again for a screen gone — its focus's comings and goings
+     * no interruption.
+     */
+    async reconfigure(handsFree) {
+        this.settling = Number.POSITIVE_INFINITY;
+        try {
+            await session.configure(this.output, handsFree, !this.disposed);
+        }
+        finally {
+            this.settling = Date.now() + SETTLE_MS;
+        }
+    }
+    reroute() {
+        session
+            .route(this.output, this.routed)
+            .then((device) => {
+            this.routed = device;
+        })
+            .catch(() => {
+            // swallowed: the system's route stands — the loudspeaker, or the earpiece in a call.
+        });
+    }
     /** The queue for a reply at `rate`: this one, or a new context's. */
     player(rate) {
-        if (this.queue && this.context?.sampleRate === rate)
+        const profile = this.cancelling && session.android() ? "voiceCommunication" : "media";
+        if (this.queue &&
+            this.context?.sampleRate === rate &&
+            // Onto the call's path or off it, never mid-reply.
+            (this.profile === profile || this.playing.size > 0)) {
             return this.queue;
+        }
         this.stop();
         void this.context?.close();
-        const context = new AudioContext({ sampleRate: rate });
+        const context = new AudioContext(profile === "media"
+            ? { sampleRate: rate }
+            : { sampleRate: rate, androidOutputProfile: profile });
+        this.profile = profile;
         const queue = context.createBufferQueueSource();
-        queue.connect(context.destination);
-        queue.onBufferEnded = ({ bufferId }) => {
+        const gain = context.createGain();
+        gain.gain.value = this.volume;
+        queue.connect(gain);
+        gain.connect(context.destination);
+        const ended = ({ bufferId }) => {
             if (this.queue !== queue)
                 return;
             if (this.playing.delete(bufferId) && this.playing.size === 0) {
                 this.tell(this.drained);
             }
         };
+        // 0.13's name, and 1.0's: each takes the other's as a plain property,
+        // set for nothing — and with the wrong one alone no reply ever ends.
+        queue.onBufferEnded = ended;
+        queue.onbufferended = ended;
         // Never `start()`: 0.13.6's wrapper defaults `offset` to -1 and then
         // throws on its own default (`offset must be a finite non-negative
         // number: -1`), which crashed the first reply on Android's emulator.
@@ -279,6 +438,7 @@ export class PhoneAudio {
             this.quiet(context);
         this.context = context;
         this.queue = queue;
+        this.gain = gain;
         return queue;
     }
     /**

package/dist/device-audio.d.ts

@@ -26,9 +26,9 @@ export interface AudioOptions {
     leadInMs?: number;
     /**
      * Milliseconds from the phone's player to the ear, which `heardTime()`
-     * takes off the clock: `react-native-audio-api` 0.13 cannot say it, so
-     * `0` unless set — Bluetooth earbuds add about 150 to 250. A browser says
-     * its own.
+     * takes off the clock — and half-duplex waits out: `react-native-audio-api`
+     * 0.13 cannot say it, so `0` unless set — Bluetooth earbuds add about 150
+     * to 250. A browser says its own.
      */
     outputLatencyMs?: number;
     /** The microphone, by its `inputs()` id, in a browser; a phone's system chooses. */
@@ -57,7 +57,9 @@ export interface DeviceAudio extends AgentAudio, PlaybackClock, DeviceChoices {
     /**
      * Whether hands-free may run (`useAgent`'s `listen`): on the web where
      * the browser cancels echo; on a phone not until `react-native-audio-api`
-     * 1.0 does — with headphones on, an app passes `assumeNoEcho`.
+     * 1.0 does — with headphones on, an app passes `assumeNoEcho`. Half-duplex
+     * (`listen({ halfDuplex: true })`) needs no echo cancelled, and runs
+     * everywhere.
      */
     handsFree(): Promise<{
         ok: true;
@@ -65,6 +67,8 @@ export interface DeviceAudio extends AgentAudio, PlaybackClock, DeviceChoices {
         ok: false;
         reason: string;
     }>;
+    /** Hands-free's first step: the reply quieter while it may be talked over, or as before. */
+    duck(on: boolean): void;
 }
 /** `createAudio`'s signature, which each platform's file implements. */
 export type CreateAudio = (options?: AudioOptions) => DeviceAudio;

package/dist/session.d.ts

@@ -1,6 +1,44 @@
+import { type CommunicationDevice } from "react-native-audio-api";
 import type { Output } from "./device-audio.js";
-/** The audio session's category, mode and options for `output`. */
-export declare function configure(output: Output): void;
+/**
+ * **The one `react-native-audio-api` build hands-free runs on before 1.0**
+ * (D17, D18): 1.0 is the first with echo cancellation — iOS's voice
+ * processing, Android's voice-communication audio — and is not released
+ * (no date, 2026-11-02), so one nightly, read in its source and tested,
+ * never "the latest": nightlies change under an app, and its iOS voice
+ * processing was weeks old. This one is commit 6fd4c68, built unchanged on
+ * 2026-10-31, 11-01 and 11-02 — the build npm's `audio-api-nightly` tag
+ * named on 2026-11-02. **Moved only for a fix we need, after a test on a
+ * real iPhone and Android; 1.0 replaces it.** Every other build, 0.13
+ * included, refuses hands-free and runs push-to-talk and half-duplex.
+ * `package.json`'s peer range names it too (`test/package.test.ts`).
+ */
+export declare const PINNED_NIGHTLY = "1.0.0-nightly-6fd4c68-20261102";
+/** The library's version, as installed. */
+export declare const libraryVersion: () => string;
+/** Whether this is the build hands-free runs on: echo can be cancelled. */
+export declare const cancelsEcho: () => boolean;
+/** Android, where the reply must be on the call's path for its echo to be cancelled. */
+export declare const android: () => boolean;
+/**
+ * The audio session's category, mode and options for `output`, for
+ * hands-free or not. Settles at once but for Android's session on 1.0,
+ * which takes a mode only as it is made active, so is made again.
+ */
+export declare function configure(output: Output, handsFree?: boolean, 
+/** `false` when the adapter is gone: the mode given back, the session left inactive. */
+active?: boolean): Promise<void>;
+/**
+ * Hands-free on Android: the call's voice to Bluetooth earbuds when they
+ * are connected — and their microphone with it (D8) — else to `output`.
+ * Asked again when a device comes or goes, never twice the same: the
+ * library's own Bluetooth link sets the device too, and its change is told
+ * as a route's. `asked`, the last asked; answers what is now. Nothing on
+ * iOS, whose route follows `allowBluetoothHFP` by itself, nor on 0.13.
+ */
+export declare function route(output: Output, asked: CommunicationDevice | null): Promise<CommunicationDevice | null>;
+/** Every change of the devices — earbuds connected, taken out — until the answer is called. */
+export declare function watchRoutes(fn: () => void): () => void;
 /** Make the session active: before the first sound, and after an interruption. */
 export declare function activate(): Promise<void>;
 /** Whether the app may record: asked only when not granted yet. */

package/dist/session.js

@@ -1,24 +1,33 @@
 /**
  * The phone's audio session: how the app's audio sits beside the system's
  * — the speaker, the earbuds, calls and other apps. With `audio.native.ts`
- * the only file that touches `react-native-audio-api`, so its 1.0, which
- * renames the session's API (`setSystemOptions`), changes these two and the
- * peer range, and nothing an app sees.
+ * the only file that touches `react-native-audio-api`, and **the one that
+ * knows which of the library it has**: 0.13, or the one 1.0 nightly
+ * hands-free runs on (`PINNED_NIGHTLY`), whose session API is renamed
+ * (`setSystemOptions`) — told apart by what the library has, at run time,
+ * so one build of this package runs on both.
  *
  * - **Play and record at once, from the loudspeaker** (`playAndRecord`,
  *   `defaultToSpeaker`): without it iOS plays a recording app's audio from
  *   the earpiece. Headphones and Bluetooth take over when connected; the
  *   earpiece is the app's choice (`Output`). Android keeps the loudspeaker
- *   until 1.0: 0.13.6 sets no communication mode, and so chooses no
- *   earpiece.
+ *   but in hands-free: the library sets no communication mode otherwise,
+ *   and so chooses no earpiece.
  * - **The earbuds' microphone on iPhones** (`allowBluetoothHFP`): their
  *   hands-free profile, at call quality, for the whole conversation — not
- *   switched per press, since every switch moves the route and 0.13.6's
- *   engine can die on a Bluetooth route change (its #1209, for R3). Android
- *   records from the phone until 1.0, whose `setInputDevice` works.
- * - **`default` mode, not `voiceChat`**: on 0.13.6 `voiceChat` cancels no
- *   echo — push-to-talk needs none, as the reply stops while the person
- *   speaks — and plays at the call volume, quieter on the loudspeaker.
+ *   switched per press, since every switch moves the route and the
+ *   library's engine can die on a Bluetooth route change (its #1209).
+ * - **`default` mode, not `voiceChat`**, for push-to-talk and half-duplex:
+ *   neither needs echo cancelled — the reply stops while the person speaks,
+ *   or nothing is heard while it plays — and `voiceChat` plays at the call
+ *   volume, quieter on the loudspeaker.
+ * - **Hands-free, on the pinned nightly** (`handsFree`): iOS's
+ *   `videoChat` — set before the recorder's voice processing, which would
+ *   otherwise move the session to `voiceChat` and the earpiece — and
+ *   Android's communication mode, its voice to the loudspeaker (or the
+ *   earpiece asked), to Bluetooth earbuds when they are connected: the
+ *   canceller hears only audio on the call's path, and the earbuds'
+ *   microphone comes with it (D8).
  * - **Interruptions are watched** (`observeAudioInterruptions`): a call,
  *   Siri or another app on iOS, a loss of audio focus on Android — which
  *   watching *asks for*, so other apps' audio stops while a conversation is
@@ -26,17 +35,104 @@
  *   audio in this release (the plugin turns the library's off), so the
  *   conversation pauses with the screen and goes on when it is back.
  */
-import { AppState } from "react-native";
+import { AppState, Platform } from "react-native";
 import { AudioManager } from "react-native-audio-api";
-/** The audio session's category, mode and options for `output`. */
-export function configure(output) {
-    AudioManager.setAudioSessionOptions({
-        iosCategory: "playAndRecord",
-        iosMode: "default",
-        iosOptions: output === "speaker"
-            ? ["defaultToSpeaker", "allowBluetoothHFP"]
-            : ["allowBluetoothHFP"],
+import library from "react-native-audio-api/package.json";
+/**
+ * **The one `react-native-audio-api` build hands-free runs on before 1.0**
+ * (D17, D18): 1.0 is the first with echo cancellation — iOS's voice
+ * processing, Android's voice-communication audio — and is not released
+ * (no date, 2026-11-02), so one nightly, read in its source and tested,
+ * never "the latest": nightlies change under an app, and its iOS voice
+ * processing was weeks old. This one is commit 6fd4c68, built unchanged on
+ * 2026-10-31, 11-01 and 11-02 — the build npm's `audio-api-nightly` tag
+ * named on 2026-11-02. **Moved only for a fix we need, after a test on a
+ * real iPhone and Android; 1.0 replaces it.** Every other build, 0.13
+ * included, refuses hands-free and runs push-to-talk and half-duplex.
+ * `package.json`'s peer range names it too (`test/package.test.ts`).
+ */
+export const PINNED_NIGHTLY = "1.0.0-nightly-6fd4c68-20261102";
+/** The library's version, as installed. */
+export const libraryVersion = () => library.version;
+/** 1.0's session API: `setSystemOptions` for 0.13's `setAudioSessionOptions`. */
+const isOne = () => typeof AudioManager.setSystemOptions === "function";
+/** Whether this is the build hands-free runs on: echo can be cancelled. */
+export const cancelsEcho = () => isOne() && library.version === PINNED_NIGHTLY;
+/** Android, where the reply must be on the call's path for its echo to be cancelled. */
+export const android = () => Platform.OS === "android";
+/**
+ * The audio session's category, mode and options for `output`, for
+ * hands-free or not. Settles at once but for Android's session on 1.0,
+ * which takes a mode only as it is made active, so is made again.
+ */
+export async function configure(output, handsFree = false, 
+/** `false` when the adapter is gone: the mode given back, the session left inactive. */
+active = true) {
+    const options = output === "speaker"
+        ? ["defaultToSpeaker", "allowBluetoothHFP"]
+        : ["allowBluetoothHFP"];
+    // Voice processing takes a mode that is no call's to `voiceChat` itself,
+    // and the library then sets its own again on every activation: a chat
+    // mode set first — `videoChat`, the loudspeaker's, or `voiceChat`, the
+    // earpiece's. Never without it: the call volume.
+    const mode = !handsFree
+        ? "default"
+        : output === "speaker"
+            ? "videoChat"
+            : "voiceChat";
+    if (!isOne()) {
+        AudioManager.setAudioSessionOptions?.({
+            iosCategory: "playAndRecord",
+            iosMode: mode,
+            iosOptions: options,
+        });
+        return;
+    }
+    // Both groups every time: one left out is set to its defaults.
+    AudioManager.setSystemOptions?.({
+        ios: { category: "playAndRecord", mode, options },
+        android: handsFree
+            ? { mode: "inCommunication", communicationDevice: output }
+            : {},
     });
+    if (android() && communicating !== handsFree) {
+        // Its communication mode is set, and the mode before it given back,
+        // only as the session is made active and inactive — which gives up the
+        // audio focus and takes it again: told as an interruption, which the
+        // adapter takes for none (`audio.native.ts`, `settling`).
+        communicating = handsFree;
+        await AudioManager.setAudioSessionActivity(false);
+        if (active)
+            await AudioManager.setAudioSessionActivity(true);
+    }
+}
+/** Android's communication mode is on: hands-free's session was made. */
+let communicating = false;
+/**
+ * Hands-free on Android: the call's voice to Bluetooth earbuds when they
+ * are connected — and their microphone with it (D8) — else to `output`.
+ * Asked again when a device comes or goes, never twice the same: the
+ * library's own Bluetooth link sets the device too, and its change is told
+ * as a route's. `asked`, the last asked; answers what is now. Nothing on
+ * iOS, whose route follows `allowBluetoothHFP` by itself, nor on 0.13.
+ */
+export async function route(output, asked) {
+    if (!android() || !isOne() || !AudioManager.getDevicesInfo)
+        return asked;
+    const { availableOutputs } = await AudioManager.getDevicesInfo();
+    // Earbuds with a microphone, as the library names Android's device
+    // types: a speaker on Bluetooth alone (A2DP) has none, and with
+    // `systemDefault` the call would go to the earpiece.
+    const earbuds = availableOutputs.some((device) => /^Bluetooth (SCO|LE Headset)$/.test(device.category));
+    const device = earbuds ? "systemDefault" : output;
+    if (device !== asked)
+        await AudioManager.setCommunicationDevice?.(device);
+    return device;
+}
+/** Every change of the devices — earbuds connected, taken out — until the answer is called. */
+export function watchRoutes(fn) {
+    const subscription = AudioManager.addSystemEventListener("routeChange", () => fn());
+    return () => subscription.remove();
 }
 /** Make the session active: before the first sound, and after an interruption. */
 export function activate() {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lumavox/react-native",
-  "version": "0.16.0",
-  "description": "Voice conversations with Lumavox agents in a React Native app, on iOS, Android and the web: the client, the React hooks, and push-to-talk audio on react-native-audio-api.",
+  "version": "0.17.0",
+  "description": "Voice conversations with Lumavox agents in a React Native app, on iOS, Android and the web: the client, the React hooks, and push-to-talk, half-duplex and hands-free audio on react-native-audio-api.",
   "license": "MIT",
   "files": [
     "dist",
@@ -30,13 +30,13 @@
     "typecheck": "tsc --noEmit && tsc --noEmit -p test"
   },
   "dependencies": {
-    "@lumavox/client": "0.16.0",
-    "@lumavox/react": "0.16.0"
+    "@lumavox/client": "0.17.0",
+    "@lumavox/react": "0.17.0"
   },
   "peerDependencies": {
     "react": ">=18",
     "react-native": ">=0.76",
-    "react-native-audio-api": ">=0.13.6 <0.14"
+    "react-native-audio-api": ">=0.13.6 <0.14 || 1.0.0-nightly-6fd4c68-20261102"
   },
   "peerDependenciesMeta": {
     "react-native": {