@lumavox/react 0.9.0 → 0.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -58,6 +58,7 @@ redial.
58
58
  | `interrupted` | the device has the audio — a call, Siri, another app |
59
59
  | `send` `startAudio` `sendAudio` `endAudio` `cancel` `mute` `reconnect` `close` | the conversation's |
60
60
  | `startRecording` `stopRecording({ transcribeOnly, discard })` | through the `audio` adapter |
61
+ | `listen(options)` `stopListening()` `listening` `hearing` | hands-free: each utterance a turn, talking over the agent stopping it (`@lumavox/client`'s `listen`) |
61
62
  | `newSession()` | a new conversation with the same agent |
62
63
  | `conversation` | the `Conversation` itself |
63
64
 
@@ -20,8 +20,13 @@
20
20
  * - **A late answer is dropped quietly**: a session opened after unmount
21
21
  * is never connected, and a press released while the microphone was
22
22
  * still opening gives it back.
23
+ * - **Hands-free is `listen()`** (`@lumavox/client`'s): the recorder stays
24
+ * open and each utterance is a turn; talking over the agent stops it on
25
+ * the edge's `barge_in`, and its voice stays stopped for the rest of
26
+ * that reply. Push-to-talk waits while it listens, and it ends with the
27
+ * conversation.
23
28
  */
24
- import { type AgentAudio, type Client, type CloseInfo, type ConnectOptions, type Conversation, type ConversationHandlers, type ErrorFrame, type PlatformError, type SessionDetail, type Snapshot, type StartAudioOptions, type TranscriptOutcome, type TurnOptions, type TurnOutcome } from "@lumavox/client";
29
+ import { type AgentAudio, type Client, type CloseInfo, type ConnectOptions, type Conversation, type ConversationHandlers, type ErrorFrame, type ListenOptions, type PlatformError, type SessionDetail, type Snapshot, type StartAudioOptions, type TranscriptOutcome, type TurnOptions, type TurnOutcome } from "@lumavox/client";
25
30
  /** Whom to talk to; `null` for nobody yet — nothing is opened. */
26
31
  export type AgentTarget =
27
32
  /** An agent: the person's last conversation with it, by default — `resume: false` for a new one. */
@@ -92,6 +97,10 @@ export interface AgentControls extends Snapshot {
92
97
  recording: boolean;
93
98
  /** The device has the audio — a call, Siri, another app: playback is paused until it gives it back. */
94
99
  interrupted: boolean;
100
+ /** Hands-free is on: the recorder is open, waiting for the person. */
101
+ listening: boolean;
102
+ /** Hands-free hears the person: an utterance is being recorded. */
103
+ hearing: boolean;
95
104
  /** The conversation itself, once it is made. */
96
105
  conversation: Conversation | null;
97
106
  send(text: string, options?: TurnOptions): Promise<TurnOutcome>;
@@ -102,6 +111,15 @@ export interface AgentControls extends Snapshot {
102
111
  startRecording(options?: RecordingOptions): Promise<boolean>;
103
112
  /** Close the recorder and end the recording: as a turn, as words, or discarded. */
104
113
  stopRecording(options?: StopRecordingOptions): Promise<TurnOutcome | TranscriptOutcome | null>;
114
+ /**
115
+ * Hands-free: the recorder left open, each utterance a turn, talking over
116
+ * the agent stopping it. Answers whether it listens; where the agent
117
+ * would hear itself it does not, and `error` says why — push-to-talk
118
+ * still works there.
119
+ */
120
+ listen(options?: ListenOptions): Promise<boolean>;
121
+ /** Hands-free off: the recorder closed, a half-heard utterance thrown away. */
122
+ stopListening(): Promise<void>;
105
123
  cancel(): void;
106
124
  mute(): void;
107
125
  reconnect(): void;
package/dist/use-agent.js CHANGED
@@ -20,8 +20,13 @@
20
20
  * - **A late answer is dropped quietly**: a session opened after unmount
21
21
  * is never connected, and a press released while the microphone was
22
22
  * still opening gives it back.
23
+ * - **Hands-free is `listen()`** (`@lumavox/client`'s): the recorder stays
24
+ * open and each utterance is a turn; talking over the agent stops it on
25
+ * the edge's `barge_in`, and its voice stays stopped for the rest of
26
+ * that reply. Push-to-talk waits while it listens, and it ends with the
27
+ * conversation.
23
28
  */
24
- import { RECORDING_RATES, } from "@lumavox/client";
29
+ import { listen as listenOn, RECORDING_RATES, } from "@lumavox/client";
25
30
  import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
26
31
  import { useClient, useLive } from "./provider.js";
27
32
  import { asPlatformError } from "./read.js";
@@ -80,6 +85,8 @@ export function useAgent(target, options = {}) {
80
85
  const [speaking, setSpeaking] = useState(false);
81
86
  const [recording, setRecording] = useState(false);
82
87
  const [interrupted, setInterrupted] = useState(false);
88
+ const [listening, setListening] = useState(false);
89
+ const [hearing, setHearing] = useState(false);
83
90
  const [failed, setFailed] = useState(false);
84
91
  const current = useRef(null);
85
92
  const waiting = useRef([]);
@@ -87,6 +94,8 @@ export function useAgent(target, options = {}) {
87
94
  /** The reply's frames still arriving after a stop are not played. */
88
95
  const silenced = useRef(false);
89
96
  const capture = useRef(null);
97
+ /** Hands-free, once `listen` opened it; `starting` while it opens. */
98
+ const handsFree = useRef(null);
90
99
  const sessionId = target && "sessionId" in target ? target.sessionId : null;
91
100
  const agentId = target && "agentId" in target ? target.agentId : null;
92
101
  const resume = target && "agentId" in target ? target.resume : undefined;
@@ -201,6 +210,12 @@ export function useAgent(target, options = {}) {
201
210
  return () => {
202
211
  alive = false;
203
212
  opening.current = false;
213
+ const free = handsFree.current;
214
+ handsFree.current = null;
215
+ if (free && free !== "starting")
216
+ void free.stop();
217
+ setListening(false);
218
+ setHearing(false);
204
219
  const open = capture.current;
205
220
  if (open) {
206
221
  open.cancelled = open.over = true;
@@ -254,8 +269,9 @@ export function useAgent(target, options = {}) {
254
269
  async startRecording(record = {}) {
255
270
  const recorder = latest.current.audio;
256
271
  const c = current.current;
257
- if (!recorder || !c || capture.current)
272
+ if (!recorder || !c || capture.current || handsFree.current) {
258
273
  return false;
274
+ }
259
275
  if (!record.transcribeOnly)
260
276
  hush();
261
277
  const mine = {
@@ -340,6 +356,48 @@ export function useAgent(target, options = {}) {
340
356
  hush();
341
357
  return c.endAudio();
342
358
  },
359
+ async listen(listenOptions = {}) {
360
+ const audio = latest.current.audio;
361
+ const c = current.current ?? (await connected());
362
+ if (!audio || !c || capture.current || handsFree.current)
363
+ return false;
364
+ handsFree.current = "starting";
365
+ const outcome = await listenOn(c, audio, {
366
+ ...listenOptions,
367
+ onState(state) {
368
+ setHearing(state === "hearing");
369
+ if (state === "stopped")
370
+ setListening(false);
371
+ listenOptions.onState?.(state);
372
+ },
373
+ onBargeIn(frame) {
374
+ hush();
375
+ listenOptions.onBargeIn?.(frame);
376
+ },
377
+ });
378
+ // Stopped, unmounted or redialled while it opened: given back.
379
+ if (handsFree.current !== "starting" || current.current !== c) {
380
+ if (outcome.ok)
381
+ await outcome.listening.stop();
382
+ return false;
383
+ }
384
+ if (!outcome.ok) {
385
+ handsFree.current = null;
386
+ setError({ kind: "audio", message: outcome.reason, error: null });
387
+ return false;
388
+ }
389
+ handsFree.current = outcome.listening;
390
+ setListening(true);
391
+ return true;
392
+ },
393
+ async stopListening() {
394
+ const free = handsFree.current;
395
+ handsFree.current = null;
396
+ setListening(false);
397
+ setHearing(false);
398
+ if (free && free !== "starting")
399
+ await free.stop();
400
+ },
343
401
  cancel() {
344
402
  hush();
345
403
  current.current?.cancel();
@@ -387,6 +445,8 @@ export function useAgent(target, options = {}) {
387
445
  speaking,
388
446
  recording,
389
447
  interrupted,
448
+ listening,
449
+ hearing,
390
450
  conversation,
391
451
  ...controls,
392
452
  newSession,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lumavox/react",
3
- "version": "0.9.0",
3
+ "version": "0.10.1",
4
4
  "description": "React and React Native hooks for Lumavox agents: a conversation that keeps itself connected, sessions, memory and relations, over @lumavox/client.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -29,7 +29,7 @@
29
29
  "typecheck": "tsc --noEmit && tsc --noEmit -p test"
30
30
  },
31
31
  "dependencies": {
32
- "@lumavox/client": "0.9.0"
32
+ "@lumavox/client": "0.10.1"
33
33
  },
34
34
  "peerDependencies": {
35
35
  "react": ">=18"