@signalcore/ui 0.1.0 → 1.0.0-beta.0

package/src/useCall.ts

@@ -0,0 +1,292 @@
+import {
+  createAudioAnalyser,
+  createLocalAudioTrack,
+  DisconnectReason,
+  Room,
+  RoomEvent,
+  Track,
+  type AudioAnalyserOptions,
+  type LocalAudioTrack,
+  type LocalTrack,
+  type Participant,
+  type RemoteAudioTrack,
+} from "livekit-client";
+import { useEffect, useReducer, useRef, useState, type RefObject } from "react";
+
+import {
+  activityOf,
+  CALL_START,
+  callReducer,
+  endedBy,
+  loudness,
+  callProblemOf,
+  refusalOf,
+  type CallProblem,
+  type CallState,
+} from "./call";
+
+/** Where a call is joined: LiveKit's address, and a token for the call's room. */
+export interface CallJoin {
+  url: string;
+  token: string;
+}
+
+/** How loud each side of the call is right now, from 0 to 1, read when asked (every frame). */
+export interface CallMeter {
+  agent: () => number;
+  person: () => number;
+}
+
+/** A call, live: where it stands, how loud it is, and what the person can do on it. */
+export interface Call {
+  state: CallState;
+  meter: CallMeter;
+  /** Turns the microphone off or on; the other way from now when not said. */
+  mute: (muted?: boolean) => void;
+  /** Ends the call, for both sides. */
+  hangUp: () => void;
+  /** Lets the agent's voice play where the browser held it until the person pressed something. */
+  hear: () => void;
+}
+
+/** How long a room may wait for its agent before the call is given up as unanswered. */
+const ANSWER_WITHIN = 20_000;
+/** How long the agent may be gone from the room before the call counts as dropped (its own end
+ * closes the room for everyone, which says why, within this). */
+const GONE_FOR = 1_500;
+/** What LiveKit's agents say they are doing, on their participant. */
+const AGENT_STATE = "lk.agent.state";
+/** A voice, cleaned as a phone call's is. */
+const CAPTURE = { echoCancellation: true, noiseSuppression: true, autoGainControl: true };
+/** Speech, measured: a wide window of loudness, smoothed a little by the analyser itself. */
+const MEASURE: AudioAnalyserOptions = {
+  fftSize: 512,
+  smoothingTimeConstant: 0.5,
+  minDecibels: -90,
+  maxDecibels: -25,
+};
+const SILENT = (): number => 0;
+
+/**
+ * A voice call through LiveKit, for as long as the component is mounted: the microphone first
+ * (a person who can't be heard has no call, and no call is made for them), then `connect` for
+ * where to join (the API's refusal says why there is no call), the room, and the microphone
+ * published into it. The agent's voice plays as it comes (its `<audio>` goes into `sink`), and
+ * the call is on once the agent joins; its state is what the agent says it is doing. It ends when
+ * the person hangs up, when the room closes (the agent's goodbye, or its longest time: the API
+ * says which), when the line goes, or when no agent comes. Unmounting hangs up. `connect` is read
+ * once, when the call starts.
+ */
+export function useCall(
+  connect: () => Promise<CallJoin>,
+  { sink }: { sink: RefObject<HTMLElement | null> },
+): Call {
+  const [state, dispatch] = useReducer(callReducer, CALL_START);
+  const given = useRef(connect);
+  useEffect(() => {
+    given.current = connect;
+  });
+  // What the person's buttons reach into: the room and the microphone, once they exist.
+  const line = useRef<{ room: Room | null; mic: LocalAudioTrack | null; hangUp: () => void }>({
+    room: null,
+    mic: null,
+    hangUp: () => undefined,
+  });
+  // The meters read whatever track each side has now; silence until it has one.
+  const readers = useRef<CallMeter>({ agent: SILENT, person: SILENT });
+  const [meter] = useState<CallMeter>(() => ({
+    agent: () => readers.current.agent(),
+    person: () => readers.current.person(),
+  }));
+
+  useEffect(() => {
+    const room = new Room({ disconnectOnPageLeave: true });
+    let mic: LocalAudioTrack | null = null;
+    let gone = false;
+    let hungUp = false;
+    // In the room with the microphone published: from here the room's own end is the call's.
+    let joined = false;
+    let answeredAt: number | null = null;
+    let unanswered: ReturnType<typeof setTimeout> | undefined;
+    let away: ReturnType<typeof setTimeout> | undefined;
+    const releases: (() => void)[] = [];
+    const stopped = () => gone || hungUp;
+
+    /**
+     * Lets go of everything the call holds: the timers, the voices playing and the meters, the
+     * microphone, the room.
+     */
+    const release = () => {
+      clearTimeout(unanswered);
+      clearTimeout(away);
+      for (const each of releases.splice(0)) each();
+      readers.current = { agent: SILENT, person: SILENT };
+      mic?.stop();
+      void room.disconnect();
+    };
+
+    const fail = (problem: CallProblem) => {
+      if (gone) return;
+      dispatch({ type: "failed", problem });
+      release();
+    };
+
+    /** A meter over a track, and its release with the call. */
+    const measure = (track: LocalAudioTrack | RemoteAudioTrack): (() => number) => {
+      const analyser = createAudioAnalyser(track, MEASURE);
+      releases.push(() => {
+        void analyser.cleanup();
+      });
+      return () => loudness(analyser.calculateVolume());
+    };
+
+    const answer = (agent: Participant) => {
+      clearTimeout(unanswered);
+      clearTimeout(away);
+      if (answeredAt === null) {
+        answeredAt = Date.now();
+        dispatch({ type: "answered", at: answeredAt });
+      }
+      dispatch({ type: "agent", activity: activityOf(agent.attributes[AGENT_STATE]) });
+    };
+
+    room
+      .on(RoomEvent.ParticipantConnected, (participant) => {
+        if (participant.isAgent) answer(participant);
+      })
+      .on(RoomEvent.ParticipantAttributesChanged, (_, participant) => {
+        if (!participant.isAgent) return;
+        dispatch({ type: "agent", activity: activityOf(participant.attributes[AGENT_STATE]) });
+      })
+      .on(RoomEvent.ActiveSpeakersChanged, (speakers) => {
+        dispatch({ type: "speaking", speaking: speakers.some((each) => each.isAgent) });
+      })
+      .on(RoomEvent.TrackSubscribed, (track, _, participant) => {
+        if (track.kind !== Track.Kind.Audio) return;
+        const voice = track.attach();
+        sink.current?.append(voice);
+        // A room left from here says nothing of its tracks: the call lets go of each itself.
+        releases.push(() => {
+          track.detach(voice);
+          voice.remove();
+        });
+        if (participant.isAgent) readers.current.agent = measure(track as RemoteAudioTrack);
+      })
+      .on(RoomEvent.TrackUnsubscribed, (track) => {
+        for (const element of track.detach()) element.remove();
+      })
+      .on(RoomEvent.AudioPlaybackStatusChanged, () => {
+        dispatch({ type: "silenced", silenced: !room.canPlaybackAudio });
+      })
+      .on(RoomEvent.Reconnecting, () => {
+        dispatch({ type: "reconnecting", reconnecting: true });
+      })
+      .on(RoomEvent.Reconnected, () => {
+        dispatch({ type: "reconnecting", reconnecting: false });
+      })
+      .on(RoomEvent.ParticipantDisconnected, (participant) => {
+        // The agent left without closing the room: its side fell. A goodbye or the longest time
+        // closes the room, whose disconnect comes first and says so.
+        if (!participant.isAgent) return;
+        away = setTimeout(() => {
+          if (gone) return;
+          dispatch({ type: "ended", by: "dropped", at: Date.now() });
+          release();
+        }, GONE_FOR);
+      })
+      .on(RoomEvent.Disconnected, (reason) => {
+        // Before the call was joined, its start says what went wrong.
+        if (gone || !joined) return;
+        const name = reason === undefined ? undefined : DisconnectReason[reason];
+        dispatch({ type: "ended", by: endedBy(name, hungUp), at: Date.now() });
+        release();
+      });
+
+    const start = async () => {
+      if (typeof navigator === "undefined" || !navigator.mediaDevices?.getUserMedia) {
+        fail("unsupported");
+        return;
+      }
+      try {
+        mic = await createLocalAudioTrack(CAPTURE);
+      } catch (error) {
+        fail(callProblemOf(error));
+        return;
+      }
+      if (stopped()) return release();
+      line.current.mic = mic;
+      let where: CallJoin;
+      try {
+        where = await given.current();
+      } catch (error) {
+        if (stopped()) return release();
+        fail(refusalOf(error));
+        return;
+      }
+      if (stopped()) return release();
+      try {
+        await room.connect(where.url, where.token);
+        if (stopped()) return release();
+        // LiveKit's own types disagree under `exactOptionalPropertyTypes`: the track is one.
+        await room.localParticipant.publishTrack(mic as LocalTrack, {
+          source: Track.Source.Microphone,
+        });
+      } catch {
+        if (stopped()) return release();
+        fail("failed");
+        return;
+      }
+      if (stopped()) return release();
+      joined = true;
+      readers.current.person = measure(mic);
+      dispatch({ type: "ringing" });
+      dispatch({ type: "silenced", silenced: !room.canPlaybackAudio });
+      const agent = [...room.remoteParticipants.values()].find((each) => each.isAgent);
+      if (agent) answer(agent);
+      else unanswered = setTimeout(() => fail("unanswered"), ANSWER_WITHIN);
+    };
+
+    line.current = {
+      room,
+      mic: null,
+      hangUp: () => {
+        if (gone || hungUp) return;
+        hungUp = true;
+        dispatch({ type: "ended", by: "person", at: Date.now() });
+        release();
+      },
+    };
+    void start();
+
+    return () => {
+      gone = true;
+      release();
+      room.removeAllListeners();
+      line.current = { room: null, mic: null, hangUp: () => undefined };
+    };
+    // One call per mount: `connect` is read from `given` when it is needed.
+  }, [sink]);
+
+  return {
+    state,
+    meter,
+    mute: (muted) => {
+      const { mic } = line.current;
+      if (mic === null || state.stage === "over") return;
+      const next = muted ?? !state.muted;
+      void (next ? mic.mute() : mic.unmute()).then(() => {
+        dispatch({ type: "muted", muted: next });
+      });
+    },
+    hangUp: () => {
+      line.current.hangUp();
+    },
+    hear: () => {
+      const { room } = line.current;
+      if (room === null) return;
+      void room.startAudio().then(() => {
+        dispatch({ type: "silenced", silenced: !room.canPlaybackAudio });
+      });
+    },
+  };
+}