call-lifecycle

Pexip call lifecycle

Joining a Pexip meeting is not "call this function and you're in." There are 6 call stages, ~30 event handlers, a join-flow state machine with 7+ steps, and several invariants that webapp3 has fought through in production. This skill captures the shape that actually works.

The two state machines

Every Pexip call has two state machines that run in parallel:

CallStage              MeetingFlow (UI step)
─────────              ────────────────────
New                    Loading
  ↓                      ↓
EventStreamConnected   Idp / EnterPin / AreYouHost / EnterExtension
  ↓                      ↓
Connected              ReadyToJoin
  ↓                      ↓
Restarting (on ICE)    InMeeting
  ↓                      ↓
Ending                 PostMeeting
  ↓
Ended

CallStage is internal — driven by SDK events. MeetingFlow is what the user sees. They're decoupled: Loading may persist across New → EventStreamConnected while the server decides whether to ask for a PIN.

export enum CallStage {
    New = 0,
    EventStreamConnected = 1,
    Connected = 2,
    Restarting = 3,
    Ending = 4,
    Ended = 5,
}

export enum MeetingFlow {
    Loading,
    Idp,
    EnterPin,
    EnterHostPin,
    AreYouHost,
    EnterExtension,
    ReadyToJoin,
    InMeeting,
    Ended,
}

Quick start: minimal call setup

import {
    createInfinityClient,
    createInfinityClientSignals,
    createCallSignals,
} from '@pexip/infinity';

// 1. Create the signal hubs (see signals-pattern skill)
const infinityClientSignals = createInfinityClientSignals([], {
    batchScheduleTimeoutMS: 100,
    batchBufferSize: 50,
});
const callSignals = createCallSignals([]);

// 2. Create the client
const infinityClient = createInfinityClient(
    infinityClientSignals,
    callSignals,
);

// 3. Wire the events you care about (BEFORE calling .call())
infinityClientSignals.onPinRequired.add(({hasHostPin, hasGuestPin}) => {
    // Server demands a PIN — show the appropriate UI step
    setMeetingStep(
        hasHostPin && hasGuestPin ? MeetingFlow.EnterPin : MeetingFlow.AreYouHost
    );
});

infinityClientSignals.onConnected.add(() => {
    // Event stream is up. Sync initial mute state to the server NOW.
    void infinityClient.clientMute({mute: media.audioMuted ?? true});
    void infinityClient.muteVideo({muteVideo: media.videoMuted ?? true});
});

callSignals.onRemoteStream.add(stream => {
    // Wire to <video srcObject={stream} />
    setRemoteStream(stream);
    setMeetingStep(MeetingFlow.InMeeting);
});

infinityClientSignals.onPeerDisconnect.add(async () => {
    // ICE failed — call restartCall to recover without rejoining
    await infinityClient.restartCall({
        ...callConfigs,
        conferenceAlias,
        mediaStream: media.stream,
    });
});

// 4. Make the call
await infinityClient.call({
    conferenceAlias: 'meet.alice',
    callType: 'AudioSendRecvVideoSendRecvPresentationSendRecv',
    bandwidth: 1264,
    clientId: 'my-client-id',
    displayName: 'Alice',
    node: 'pexip.example.com',
    mediaStream: media.stream,
});