Components / Voice

@peerkit-dev/voice


Two-person voice calls with mute, devices, and a live timer.

  • JavaScript
  • Web Components
  • React

Use VoiceController from @peerkit-dev/voice-core, the <peerkit-voice> element, or PeerKitVoice. Audio rides on a PeerKit audio session. The microphone stays off until Start call, and the call never requests the camera.

JavaScript and Web Components

npm install @peerkit-dev/voice-core @peerkit-dev/sdk

React

npm install @peerkit-dev/voice @peerkit-dev/sdk react react-dom

Try the callDocumentation

Live demo

PeerKitVoice

Starting a real audio session…

Preparing the call…

Installation

Install @peerkit-dev/voice-core for vanilla JavaScript or the <peerkit-voice> element. Install @peerkit-dev/voice when the page is React. The React package depends on Voice Core and re-exports VoiceController. Published versions are Voice Core 0.1.0 and React Voice 0.1.1.

JavaScript and Web Components

npm install @peerkit-dev/voice-core @peerkit-dev/sdk

React

npm install @peerkit-dev/voice @peerkit-dev/sdk react react-dom

Create the session on your server with media: "audio". Give each person an invitation. Audio sessions are two people. Both can speak and hear. The call asks for the microphone only, and it never requests the camera.

Vanilla JavaScript

VoiceController holds call status, mute, devices, levels, and errors. subscribe and getSnapshot are how a page reads that state. Call sync() after constructing the controller. attachAudio plays the other person into an <audio> element. dispose() drops listeners and, when this controller created the session, disconnects it.

Call start() from a click or another user interaction. start() calls play() on the audio element before any await, which keeps that activation for the microphone permission prompt and for remote playback. Calling start() from the constructor, from page load, or through autoStart can lose the gesture, and the browser can block the microphone prompt or the other person's audio. autoStart defaults to false.

import { VoiceController } from "@peerkit-dev/voice-core";

const audio = document.querySelector("audio");
const call = new VoiceController(() => ({
  invitationUrl: "https://peerkit.dev/s#inv_…",
  localName: "Alex",
  remoteName: "Jordan",
  onCallEnd: (reason) => console.log(reason),
  onError: (error) => console.error(error.code, error.message),
}));
call.attachAudio(audio);
call.subscribe(() => {
  const snapshot = call.getSnapshot();
  console.log(snapshot.statusLabel, snapshot.durationLabel);
});
call.sync();
document.querySelector("#start")?.addEventListener("click", () => {
  void call.start();
});
document.querySelector("#end")?.addEventListener("click", () => {
  call.end();
});

HTML

Import @peerkit-dev/voice-core/element to register <peerkit-voice>. Importing @peerkit-dev/voice-core alone does not register the element. The same element is available from dist/element.global.js, which also assigns PeerkitVoice.VoiceController on window. The element renders in light DOM, adds the class pk-voice, and owns the audio element used for remote playback.

The Start call button calls start() from that click, which is what keeps microphone permission and audio playback unlocked. Set labels.you and labels.participant for the two names. Set sessionController before the element connects.

<script type="module">
  import "@peerkit-dev/voice-core/element";
</script>
<peerkit-voice id="call"></peerkit-voice>
<script type="module">
  const call = document.querySelector("peerkit-voice");
  call.invitationUrl = "https://peerkit.dev/s#inv_…";
  call.labels = { you: "Alex", participant: "Jordan" };
  call.addEventListener("peerkit-call-end", (event) => {
    console.log(event.detail);
  });
</script>

React

PeerKitVoice uses the same controller. Its Start call button calls start() from the click. Leave autoStart off so the microphone request stays on that interaction.

import { PeerKitVoice } from "@peerkit-dev/voice";

export function Call({ invitationUrl }: { invitationUrl: string }) {
  return (
    <PeerKitVoice
      invitationUrl={invitationUrl}
      localName="Alex"
      remoteName="Jordan"
      onCallEnd={(reason) => console.log(reason)}
      onError={(error) => console.error(error.code, error.message)}
    />
  );
}

Two-person call

  1. Create one audio session and two invitations: publisher and viewer. Both can speak and hear.
  2. Pass each invitation URL, or a redeemed token and signaling URL, to VoiceController, <peerkit-voice>, or PeerKitVoice.
  3. Each person chooses Start call and allows the microphone. The timer starts when the other person is in the session.

Custom interface

usePeerKitVoice exposes start, mute, device selection, duration, levels, and end without the default layout. Keep an audio element bound to audioRef. Call startCall() from the button click. PeerKitVoiceControls renders the standard buttons for that hook result.

import { usePeerKitVoice } from "@peerkit-dev/voice";

export function CallButtons({ invitationUrl }: { invitationUrl: string }) {
  const call = usePeerKitVoice({ invitationUrl });
  return (
    <div>
      <audio ref={call.audioRef} autoPlay />
      <p>{call.statusLabel}</p>
      <button type="button" onClick={() => void call.startCall()}>Start call</button>
      <button type="button" onClick={() => void call.toggleMute()}>
        {call.muted ? "Unmute" : "Mute"}
      </button>
      <button type="button" onClick={() => call.endCall()}>End call</button>
    </div>
  );
}

Shared session

Pass a PeerKitSession another part of the page already owns. end() and dispose() leave that session connected. disconnectOnEnd defaults to true when this controller created the session, and to false when a session is provided. With the default, end() on a provided session mutes the microphone and playback. Set disconnectOnEnd to true when End call should disconnect that provided session. manageConnection controls whether dispose() disconnects a session this controller created. It defaults to true for that owned session.

import { PeerKitSession } from "@peerkit-dev/sdk";
import { VoiceController } from "@peerkit-dev/voice-core";

const session = new PeerKitSession({
  signalingUrl: "wss://signal.example",
  token: "participant-token",
  media: "audio",
});

const call = new VoiceController(() => ({ session }));
call.attachAudio(document.querySelector("audio"));
call.sync();
document.querySelector("#start")?.addEventListener("click", () => {
  void call.start();
});
document.querySelector("#end")?.addEventListener("click", () => {
  call.end();
});

For one owner shared with Chat or Share, construct a PeerSessionController and pass it as sessionController. Voice calls sync() on that owner. It does not create the session, and it does not call dispose() on the owner. Call sessions.sync() first. start() needs that owner's session to exist already, then the click opens the microphone. Pass sessionController on its own for that participant. With sessionController set, Voice never creates a session. sessions.dispose() disconnects a session that owner created. The page disconnects a provided PeerKitSession when that page is finished with it.

Import PeerSessionController from @peerkit-dev/chat-core/session when the page should not load the voice element. @peerkit-dev/voice-core re-exports it.

import { PeerSessionController, VoiceController } from "@peerkit-dev/voice-core";

const sessions = new PeerSessionController(() => ({
  signalingUrl: "wss://signal.example",
  token: "participant-token",
  media: "audio",
}));
sessions.sync();

const call = new VoiceController(() => ({ sessionController: sessions }));
call.attachAudio(document.querySelector("audio"));
call.sync();
document.querySelector("#start")?.addEventListener("click", () => {
  void call.start();
});

Features

  • Ready, connecting, waiting, connected, reconnecting, ended, and error states.
  • Microphone permission, mute, and input selection through the SDK audio session.
  • Speaker selection where the browser implements setSinkId.
  • Call duration, connection status, and local plus remote audio activity.
  • presentationMode enlarges the avatars, timer, and speaking animation for a camera-facing layout. It uses the same call.
  • End call disconnects a session this controller created and stops its microphone tracks. A provided session stays connected and muted unless disconnectOnEnd is set.
  • Names, theme, visible controls, and connection and error callbacks are configurable.

Props

React props, VoiceController options, and <peerkit-voice> properties use these names. className and style are React. The element reads names from labels.you and labels.participant.

PropPurpose
invitationUrlRedeem a hosted invitation when the call starts and this controller creates the session.
signalingUrl and tokenJoin with credentials you already redeemed.
sessionReuse an existing audio PeerKitSession. Left connected on end unless disconnectOnEnd is true.
sessionControllerShare a PeerSessionController. Voice does not create or dispose that owner.
disconnectOnEndDisconnect when the local person ends the call. Default true for an owned session and false for a provided session.
manageConnectionDisconnect a session this controller created when it is disposed. Default true for that session.
autoStartCall start() from sync(). Default false, so the microphone request stays on a click.
localName and remoteNameLabels on the two people in the call. Defaults are You and Participant.
controlsHide mute, microphone, speaker, timer, or end.
themelight or dark.
onStatusChange, onConnectionChange, onError, onCallStart, onCallEndLifecycle callbacks. The call stays independent of Share, Chat, and Record.

Theme

Styles stay under .pk-voice. Override --peerkit-voice-* variables. Fonts inherit from the page.

.my-call {
  --peerkit-voice-accent: #0d9488;
  --peerkit-voice-button-bg: #0d9488;
  --peerkit-voice-button-ink: #ffffff;
  --peerkit-voice-bg: #f8fafc;
}

Browser compatibility

Calls need a secure context and microphone permission. Camera permission is never requested. Start the call from a user interaction so the browser can show the microphone prompt and start remote playback.

BrowserCallMicrophone selectSpeaker select
Chrome and EdgeYesYesYes
FirefoxYesYesNo. Output follows the system device.
Safari on macOSYesYesNo. Output follows the system device.
Safari on iOSYesOften a single microphoneNo. The route follows the system output.

If autoplay blocks remote audio, the call shows Enable sound after Start call.