ClientPreferences | SignalWire

ClientPreferences is the central knob panel for every tunable runtime default in the SDK — connection timeouts, ICE behavior, default media constraints, codec preferences, recovery thresholds, persisted device selections, and UX defaults like auto-mute-on-hidden. The single instance is owned by SignalWire and reached as client.preferences; applications never construct it directly.

Each preference is exposed as a paired getter/setter accessor — setting it applies immediately and affects subsequent operations (e.g. setting reconnectDelayMax changes the next reconnect attempt’s back-off). All time-based preferences take seconds, not milliseconds.

By default, preferences live only in memory for the current session. Calling enableSavePreferences with a Storage loads any persisted values on startup and writes back to storage on every subsequent change — survive page reload and tab restore without re-configuring on each session.

Constructors

Constructor

new ClientPreferences(): ClientPreferences

Accessors

autoMuteVideoOnHidden

Whether to auto-mute video when the tab becomes hidden.

checkConnectionOnVisible

Whether to check peer connection health when the page becomes visible.

connectionTimeout

WebSocket connection timeout in seconds.

defaultAudioConstraints

Default audio track constraints applied when no explicit constraints are provided.

defaultVideoConstraints

Default video track constraints applied when video is enabled without explicit constraints.

degradationBitrateThreshold

Bitrate in kbps below which video is automatically disabled.

degradationRecoveryThreshold

Bitrate in kbps above which video is automatically re-enabled.

deviceDebounceTime

Debounce time for device change events, in seconds.

devicePollingInterval

Polling interval for device enumeration, in seconds.

disableUdpIceServers

Whether to filter out UDP-based ICE servers.

enableAutoDegradation

Whether automatic video degradation on low bandwidth is enabled.

enableNetworkChangeDetection

Whether browser network change detection (online/offline) is enabled.

enableRelayFallback

Whether relay-only escalation is enabled as a last-resort recovery tier.

enableServerHangupInterception

Whether server-sent media-timeout hangups are intercepted for recovery.

iceCandidateTimeout

Timeout for individual ICE candidate gathering, in seconds.

iceDisconnectedGracePeriod

Grace period before treating ICE ‘disconnected’ as failure, in seconds.

iceGatheringTimeout

Timeout for the entire ICE gathering phase, in seconds.

iceRestartTimeout

Timeout for a single ICE restart attempt in seconds.

iceServers

Custom ICE servers for TURN/STUN configuration.

inputAudioConstraints

Default audio input track constraints.

inputVideoConstraints

Default video input track constraints.

keyframeBurstWindow

Keyframe burst window duration in milliseconds.

keyframeCooldown

Cooldown period in ms after keyframe burst limit is reached.

keyframeMaxBurst

Maximum keyframe requests in a burst window.

maxRecoveryAttempts

Maximum recovery attempts before giving up.

persistDeviceSelection

Whether device selections are persisted to storage.

preferredAudioCodecs

Preferred audio codecs in priority order.

preferredAudioInput

Preferred audio input device for new calls.

preferredAudioOutput

Preferred audio output device for new calls.

preferredVideoCodecs

Preferred video codecs in priority order.

preferredVideoInput

Preferred video input device for new calls.

receiveAudio

Whether to receive remote audio by default.

receiveVideo

Whether to receive remote video by default.

reconnectCallsTimeout

Timeout for reconnecting to previously attached calls, in seconds.

reconnectDelayMax

Maximum reconnection backoff delay in seconds.

reconnectDelayMin

Minimum reconnection backoff delay in seconds.

recoveryCooldown

Cooldown period between recovery attempts in seconds.

recoveryDebounceTime

Recovery signal debounce window in seconds.

refreshDevicesOnVisible

Whether to re-enumerate devices when the page becomes visible.

reinviteDebounceTime

Minimum time in ms between re-INVITE attempts.

reinviteMaxAttempts

Maximum re-INVITE attempts per call.

reinviteTimeout

Timeout in ms for a single re-INVITE attempt.

relayHost

Custom relay host URL. Empty string uses the default.

relayOnly

Whether to force TURN relay-only ICE candidates.

statsBaselineSamples

Number of baseline samples for stats monitoring.

statsHistorySize

Number of seconds of metrics history to retain.

statsJitterSpikeMultiplier

Multiplier for jitter spike detection relative to baseline.

statsNoPacketThreshold

Duration in ms with no inbound packets before a critical issue is emitted.

statsPacketLossThreshold

Packet loss fraction threshold (0-1) for issue detection.

statsPollingInterval

Stats polling interval in milliseconds.

statsRttSpikeMultiplier

Multiplier for RTT spike detection relative to baseline.

stereoAudio

Whether stereo Opus is enabled globally.

syncDevicesToActiveCalls

Whether device changes are auto-applied to active calls.

userVariables

Custom user variables attached to calls.

Methods

enableSavePreferences

Enables persistence of preferences to storage. Loads any previously saved preferences and syncs future changes.