Components / Voice
@peerkit-dev/voice
Two-person voice calls with mute, devices, and a live timer.
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/sdkReact
npm install @peerkit-dev/voice @peerkit-dev/sdk react react-domLive 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
- Create one audio session and two invitations: publisher and viewer. Both can speak and hear.
- Pass each invitation URL, or a redeemed token and signaling URL, to
VoiceController,<peerkit-voice>, orPeerKitVoice. - 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.
presentationModeenlarges 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
disconnectOnEndis 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.
| Prop | Purpose |
|---|---|
invitationUrl | Redeem a hosted invitation when the call starts and this controller creates the session. |
signalingUrl and token | Join with credentials you already redeemed. |
session | Reuse an existing audio PeerKitSession. Left connected on end unless disconnectOnEnd is true. |
sessionController | Share a PeerSessionController. Voice does not create or dispose that owner. |
disconnectOnEnd | Disconnect when the local person ends the call. Default true for an owned session and false for a provided session. |
manageConnection | Disconnect a session this controller created when it is disposed. Default true for that session. |
autoStart | Call start() from sync(). Default false, so the microphone request stays on a click. |
localName and remoteName | Labels on the two people in the call. Defaults are You and Participant. |
controls | Hide mute, microphone, speaker, timer, or end. |
theme | light or dark. |
onStatusChange, onConnectionChange, onError, onCallStart, onCallEnd | Lifecycle 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.
| Browser | Call | Microphone select | Speaker select |
|---|---|---|---|
| Chrome and Edge | Yes | Yes | Yes |
| Firefox | Yes | Yes | No. Output follows the system device. |
| Safari on macOS | Yes | Yes | No. Output follows the system device. |
| Safari on iOS | Yes | Often a single microphone | No. The route follows the system output. |
If autoplay blocks remote audio, the call shows Enable sound after Start call.