Visual representation of the call state machine and valid transitions.

┌─────────────────────────────────────────────────────────────────────┐
│                        Call State Machine                            │
└─────────────────────────────────────────────────────────────────────┘

                           ┌──────────┐
                           │   idle   │
                           └─────┬────┘
                                 │ initiateCall()
                                 ▼
                          ┌─────────────┐
                          │ initiating  │─────► ending ─► ended ─► idle
                          └──────┬──────┘         (cancel)
                                 │
                    ┌────────────┼────────────┐
                    │                         │
                    ▼                         ▼
             ┌─────────────┐          ┌─────────────┐
             │   ringing   │          │ connecting  │ (group call)
             └──────┬──────┘          └──────┬──────┘
                    │                        │
                    │ answered()             │
                    ▼                        │
             ┌─────────────┐                │
             │ connecting  │◄───────────────┘
             └──────┬──────┘
                    │ connected()
                    ▼
             ┌─────────────┐
        ┌───►│  connected  │◄───┐
        │    └──────┬──────┘    │
        │           │            │
        │    ┌──────┼──────┐    │
        │    │      │      │    │
        │    ▼      ▼      ▼    │
        │  ┌────┐ ┌────┐ ┌────┐│
        └──│held│ │tran│ │reco││
           └────┘ │sfer│ │nnec││
                  └────┘ │ting││
                         └────┘│
                                │
                                ▼
                          ┌─────────┐
                          │  ending │
                          └────┬────┘
                               │
                               ▼
                          ┌────────┐
                          │ ended  │
                          └────┬───┘
                               │
                               ▼
                          ┌────────┐
                          │  idle  │
                          └────────┘

Description: No active call Can Transition To: initiating Typical Duration: N/A (waiting state) Actions: None

Description: Creating call, getting media, initializing connection Can Transition To: ringing, connecting, ending, ended Typical Duration: 1-2 seconds Actions:

• Request microphone/camera permissions
• Get local media stream
• Create RTCPeerConnection
• Generate call ID

Description: Calling recipient, waiting for answer Can Transition To: connecting, ending, ended Typical Duration: Up to 30 seconds (timeout) Actions:

• Send call invitation
• Play ring back tone
• Wait for acceptance

Description: WebRTC negotiation in progress (offer/answer exchange) Can Transition To: connected, ending, ended Typical Duration: 2-5 seconds Actions:

• Exchange SDP offers/answers
• Gather ICE candidates
• Establish peer connection

Description: Call is active, media flowing Can Transition To: held, transferring, reconnecting, ending, ended Typical Duration: Varies (minutes to hours) Actions:

• Stream audio/video
• Monitor quality
• Handle media controls (mute, video toggle)

Description: Call on hold, media paused Can Transition To: connected, transferring, ending, ended Typical Duration: Varies Actions:

• Mute audio
• Pause video
• Show "on hold" status

Description: Call being transferred to another user Can Transition To: connected, ending, ended Typical Duration: 2-5 seconds Actions:

• Coordinate with transfer target
• Hand off media streams
• Notify participants

Description: Network issue, attempting to reconnect Can Transition To: connected, ending, ended Typical Duration: Up to 10 seconds Actions:

• Monitor ICE connection state
• Attempt to reestablish connection
• Show reconnecting UI

Description: Hanging up, cleaning up resources Can Transition To: ended Typical Duration: <1 second Actions:

• Close peer connection
• Stop media streams
• Send end call signal

Description: Call has ended, showing summary Can Transition To: idle Typical Duration: Brief (UI shows call ended) Actions:

• Display call duration
• Save call history
• Release resources

These transitions are not allowed:

• idle → connected (must go through initiating)
• ringing → held (can't hold unanswered call)
• ended → connected (can't revive ended call)
• Any state → ringing (except from initiating)

The state machine tracks three types of duration:

Time spent in the current state (since last transition).

const stateDuration = machine.getCurrentStateDuration() // milliseconds

Total time from idle → initiating until now.

const totalDuration = machine.getTotalDuration() // milliseconds

Total time spent in "connected" state (excludes held, reconnecting).

const connectedDuration = machine.getConnectedDuration() // milliseconds

idle
  → initiating (getting media)
  → ringing (calling recipient)
  → connecting (WebRTC negotiation)
  → connected (talking)
  → ending (hanging up)
  → ended (call summary)
  → idle (ready for next call)

Total Time: ~2 minutes Connected Time: ~1 minute 50 seconds

idle
  → initiating
  → ringing
  → connecting
  → connected (talking)
  → held (on hold for 30s)
  → connected (resumed)
  → ending
  → ended
  → idle

Total Time: ~3 minutes Connected Time: ~2 minutes 30 seconds (excludes held time)

idle
  → initiating
  → ringing
  → connecting
  → connected (talking)
  → reconnecting (network issue for 5s)
  → connected (reconnected)
  → ending
  → ended
  → idle

Total Time: ~2 minutes Connected Time: ~1 minute 55 seconds

idle
  → initiating (getting media)
  → ringing (calling recipient)
  → ending (user cancelled)
  → ended
  → idle

Total Time: ~10 seconds Connected Time: 0 seconds

idle
  → initiating
  → ringing
  → ended (recipient declined)
  → idle

Total Time: ~5 seconds Connected Time: 0 seconds

idle
  → initiating
  → ringing
  → connecting (WebRTC negotiation)
  → ending (connection failed)
  → ended
  → idle

Total Time: ~15 seconds Connected Time: 0 seconds

idle
  → initiating
  → connecting (direct connection)
  → connected (all participants join)
  → ending
  → ended
  → idle

Total Time: ~5 minutes Connected Time: ~4 minutes 55 seconds

The state machine emits events for each transition:

{
  from: 'ringing',
  to: 'connected',
  timestamp: Date,
  reason?: 'answered',
  metadata?: {
    answeredBy: 'user-123',
    delay: 5000
  }
}

// Listen to all transitions
machine.on('transition', (event) => {
  console.log(`${event.from} -> ${event.to}`)
})

// Listen to specific state entry
machine.on('enter:connected', (event) => {
  console.log('Call connected!')
  startQualityMonitoring()
})

// Listen to specific state exit
machine.on('exit:connected', (event) => {
  console.log('Call no longer connected')
  stopQualityMonitoring()
})

// Listen to invalid transitions
machine.on('invalid-transition', ({ from, to }) => {
  console.warn(`Cannot transition from ${from} to ${to}`)
})

The state machine maintains a history of all transitions:

const history = machine.getHistory()

// Example history:
[
  { from: 'idle', to: 'initiating', timestamp: Date, reason: 'user-initiated' },
  { from: 'initiating', to: 'ringing', timestamp: Date },
  { from: 'ringing', to: 'connecting', timestamp: Date, reason: 'answered' },
  { from: 'connecting', to: 'connected', timestamp: Date },
  { from: 'connected', to: 'ending', timestamp: Date, reason: 'user-hangup' },
  { from: 'ending', to: 'ended', timestamp: Date },
]

This history is useful for:

• Debugging state issues
• Analyzing call flows
• Calculating durations
• Audit trails

if (machine.canTransitionTo('connected')) {
  machine.transition('connected')
} else {
  console.error('Invalid transition to connected')
}

machine.transition('ending', 'user-hangup')
machine.transition('ended', 'network-error', { error: err })

machine.on('invalid-transition', ({ from, to }) => {
  showError(`Cannot ${to} call while ${from}`)
})

// Show live duration
setInterval(() => {
  if (machine.isState('connected')) {
    const duration = machine.getConnectedDuration()
    updateCallTimer(duration)
  }
}, 1000)

machine.on('enter:ended', () => {
  const connectedDuration = machine.getConnectedDuration()
  const totalDuration = machine.getTotalDuration()

  // Save to history
  saveCallHistory({
    connectedDuration,
    totalDuration,
    history: machine.getHistory(),
  })

  // Reset for next call
  setTimeout(() => {
    machine.transition('idle')
    machine.reset()
  }, 2000)
})

const machine = createCallStateMachine({
  onTransition: (event) => {
    console.log('[State]', event.from, '->', event.to, event.reason)
  },
  onInvalidTransition: (from, to) => {
    console.error('[State] Invalid:', from, '->', to)
  },
})

console.log('Current State:', machine.getState())
console.log('Display Name:', machine.getStateDisplayName())
console.log('Is Active?', machine.isActive())
console.log('Valid Next States:', getValidTransitions(machine.getState()))

const history = machine.getHistory()
console.log('Call Flow:')
history.forEach((event, i) => {
  console.log(`${i + 1}. ${event.from} -> ${event.to} (${event.reason || 'no reason'})`)
})

• Call Management Guide
• Call System Implementation
• WebRTC Guide

Version: 0.4.0 Last Updated: January 30, 2026