import { ChatMessage as ChatMessageModel, ClientInfo, ClientInfo_Capability, ClientInfo_SDK, DisconnectReason, Transcription as TranscriptionModel, } from '@livekit/protocol'; import type { NonSharedUint8Array } from '../type-polyfills/non-shared-typed-arrays'; import TypedPromise from '../utils/TypedPromise'; import { getBrowser } from '../utils/browserParser'; import type { BrowserDetails } from '../utils/browserParser'; import { type Throws } from '../utils/throws'; import { clientProtocol, protocolVersion, version } from '../version'; import { type ConnectionError, ConnectionErrorReason } from './errors'; import type { LocalParticipant } from './participant/LocalParticipant'; import type Participant from './participant/Participant'; import type RemoteParticipant from './participant/RemoteParticipant'; import CriticalTimers from './timers'; import type LocalAudioTrack from './track/LocalAudioTrack'; import type LocalTrack from './track/LocalTrack'; import type LocalTrackPublication from './track/LocalTrackPublication'; import type LocalVideoTrack from './track/LocalVideoTrack'; import type RemoteAudioTrack from './track/RemoteAudioTrack'; import type RemoteTrack from './track/RemoteTrack'; import type RemoteTrackPublication from './track/RemoteTrackPublication'; import type RemoteVideoTrack from './track/RemoteVideoTrack'; import { Track } from './track/Track'; import type { TrackPublication } from './track/TrackPublication'; import { type AudioCodec, type VideoCodec, audioCodecs, videoCodecs } from './track/options'; import { getNewAudioContext } from './track/utils'; import type { ChatMessage, LiveKitReactNativeInfo, TranscriptionSegment } from './types'; const separator = '|'; export const ddExtensionURI = 'https://aomediacodec.github.io/av1-rtp-spec/#dependency-descriptor-rtp-header-extension'; export function unpackStreamId(packed: string): string[] { const parts = packed.split(separator); if (parts.length > 1) { return [parts[0], packed.substr(parts[0].length + 1)]; } return [packed, '']; } export function sleep(duration: number): TypedPromise { return new TypedPromise((resolve) => CriticalTimers.setTimeout(resolve, duration)); } /** @internal */ export function supportsTransceiver() { return 'addTransceiver' in RTCPeerConnection.prototype; } /** @internal */ export function supportsAddTrack() { return 'addTrack' in RTCPeerConnection.prototype; } export function supportsAdaptiveStream() { return typeof ResizeObserver !== 'undefined' && typeof IntersectionObserver !== 'undefined'; } export function supportsDynacast() { return supportsTransceiver(); } export function supportsAV1(): boolean { if (!('getCapabilities' in RTCRtpSender)) { return false; } if (isSafari() || isFireFox()) { // Safari 17 on iPhone14 reports AV1 capability, but does not actually support it // Firefox does support AV1, but SVC publishing is not supported return false; } const capabilities = RTCRtpSender.getCapabilities('video'); let hasAV1 = false; if (capabilities) { for (const codec of capabilities.codecs) { if (codec.mimeType.toLowerCase() === 'video/av1') { hasAV1 = true; break; } } } return hasAV1; } export function supportsVP9(): boolean { if (!('getCapabilities' in RTCRtpSender)) { return false; } if (isFireFox()) { // technically speaking FireFox supports VP9, but SVC publishing is broken // https://bugzilla.mozilla.org/show_bug.cgi?id=1633876 return false; } if (isSafari()) { const browser = getBrowser(); if (browser?.version && compareVersions(browser.version, '16') < 0) { // Safari 16 and below does not support VP9 return false; } if ( browser?.os === 'iOS' && browser?.osVersion && compareVersions(browser.osVersion, '16') < 0 ) { // Safari 16 and below on iOS does not support VP9 we need the iOS check to account for other browsers running webkit under the hood return false; } } const capabilities = RTCRtpSender.getCapabilities('video'); let hasVP9 = false; if (capabilities) { for (const codec of capabilities.codecs) { if (codec.mimeType.toLowerCase() === 'video/vp9') { hasVP9 = true; break; } } } return hasVP9; } export function supportsH265(): boolean { if (!('getCapabilities' in RTCRtpSender)) { return false; } const capabilities = RTCRtpSender.getCapabilities('video'); let hasH265 = false; if (capabilities) { for (const codec of capabilities.codecs) { if (codec.mimeType.toLowerCase() === 'video/h265') { hasH265 = true; break; } } } return hasH265; } export function isSVCCodec(codec?: string): boolean { return codec === 'av1' || codec === 'vp9'; } /** * Opts `transceiver` into negotiating the AV1 dependency descriptor, reporting whether it will be. * * Chrome only offers the extension on transceivers that can send, so one we create to receive on * never negotiates it — and Chrome 152 stopped decoding AV1 that arrives without it: frames get * assembled, none ever decode, and the receiver asks for a keyframe forever. Asking through the * transceiver rather than munging the extension into the SDP leaves the browser owning the * extension id, which is what keeps that id consistent across the bundle and across * renegotiations. * * A no-op where the browser offers no such control, or does not know the extension at all. * @internal */ export function negotiateDependencyDescriptor(transceiver: RTCRtpTransceiver): boolean { const extensions = transceiver.getHeaderExtensionsToNegotiate?.(); if (!extensions || !transceiver.setHeaderExtensionsToNegotiate) { return false; } const dd = extensions.find((ext) => ext.uri === ddExtensionURI); if (!dd) { return false; } if (dd.direction !== 'stopped') { return true; } // sendrecv rather than recvonly, so that the extension is written as a plain `a=extmap` line — // the form the server already emits where it is the one offering — rather than one carrying a // `/recvonly` suffix that its parser may not expect dd.direction = 'sendrecv'; try { transceiver.setHeaderExtensionsToNegotiate(extensions); return true; } catch (e) { // a rejected direction throws. Negotiating without the extension is what happened before this // existed, so it is not worth failing the connection over return false; } } /** * VP9 and AV1 are published as SVC (a single RTP stream carrying every spatial layer) * by default. They can instead be published as real, rid based simulcast — one * independent stream per rid, each carrying a single spatial layer — when the caller * opts in with `simulcast: true` and a single spatial layer scalability mode (`L1Tx`). * * The SFU has to be told about this: without an explicit * `SimulcastCodec.videoLayerMode` it assumes `MULTIPLE_SPATIAL_LAYERS_PER_STREAM` for * any SVC capable codec. */ export function isSVCSimulcast( codec?: string, options?: { simulcast?: boolean; scalabilityMode?: string }, ): boolean { return isSVCCodec(codec) && !!options?.simulcast && !!options.scalabilityMode?.startsWith('L1T'); } /** * Whether the browser reads multiple encodings on an SVC capable codec as *legacy SVC* * rather than as real simulcast. * * Before Chrome M113, supplying more than one encoding for VP9/AV1 selected SVC mode; * only from M113 does libwebrtc treat such encodings as simulcast, and only when each * one carries its own scalabilityMode. Safari (and anything WebKit based, i. e. every * browser on iOS) still uses the old interpretation, as does React Native's libwebrtc. * Announced at https://groups.google.com/g/discuss-webrtc/c/-QQ3pxrl-fw * * Where this is true the rids would not exist on the wire, so VP9/AV1 must be published * as SVC no matter what the caller asked for. */ export function usesLegacySVCEncodings(): boolean { const browser = getBrowser(); return ( isSafariBased() || // Even tho RN runs M114, it does not produce SVC layers when a single encoding // is provided. So we'll use the legacy SVC specification for now. // TODO: when we upstream libwebrtc, this will need additional verification isReactNative() || (browser?.name === 'Chrome' && compareVersions(browser.version, '113') < 0) ); } /** * Last server version that doesn't support vp9/av1 simulcast. */ const svcSimulcastMinServerVersion = '1.13.6'; /** * Whether the connected server honours `SimulcastCodec.videoLayerMode`, i. e. whether * VP9/AV1 can be published as rid based simulcast. An unknown version is treated as * unsupported so the publish falls back to SVC. */ export function isSVCSimulcastSupportedByServer(serverVersion?: string): boolean { if (!serverVersion) { return false; } return compareVersions(serverVersion, svcSimulcastMinServerVersion) > 0; } /** * First server protocol that matches publisher m-sections by mid, not by position * (livekit/livekit#5122). A stopped transceiver lets the browser put a later one into its * m-section, so an older server can match that section to the wrong track. */ const stopTransceiverMinServerProtocol = 19; /** * Whether the connected server handles stopped publisher transceivers. An unknown protocol is * treated as unsupported, so the transceivers stay inactive as before. */ export function isStopTransceiverSupportedByServer(serverProtocol?: number): boolean { return (serverProtocol ?? 0) >= stopTransceiverMinServerProtocol; } export function supportsSetSinkId(elm?: HTMLMediaElement): boolean { if (!document || isSafariBased()) { return false; } if (!elm) { elm = document.createElement('audio'); } return 'setSinkId' in elm; } /** * Checks whether or not setting an audio output via {@link Room#setActiveDevice} * is supported for the current browser. */ export function supportsAudioOutputSelection(): boolean { // Note: this is method publicly exported under a user friendly name and currently only proxying `supportsSetSinkId` return supportsSetSinkId(); } /** * machina, the signalling state machine, calls `WeakRef` and `Object.hasOwn`. A build that bundles * machina rewrites those calls and sets this to `false` (`machina-browser-compat` in * rollup.config.js). The core entry leaves machina external, so there the browser must have both. */ const machinaNeedsNativeApis = true; export function isBrowserSupported() { if (typeof RTCPeerConnection === 'undefined') { return false; } if (machinaNeedsNativeApis && (typeof WeakRef === 'undefined' || !('hasOwn' in Object))) { return false; } return supportsTransceiver() || supportsAddTrack(); } export function isFireFox(): boolean { return getBrowser()?.name === 'Firefox'; } export function isChromiumBased(): boolean { const browser = getBrowser(); return !!browser && browser.name === 'Chrome' && browser.os !== 'iOS'; } export function isScriptTransformSupportedForWorker(): boolean { // Chrome occasionally throws an `InvalidState` error when using script transforms directly after introducing this API in 141. // Disabling it for Chrome based browsers until the API has stabilized. // @ts-ignore return ( typeof window !== 'undefined' && // @ts-ignore typeof window.RTCRtpScriptTransform !== 'undefined' && !isChromiumBased() ); } export function isSafari(): boolean { return getBrowser()?.name === 'Safari'; } export function isSafariBased(): boolean { const b = getBrowser(); return b?.name === 'Safari' || b?.os === 'iOS'; } /** * iPadOS has sent the desktop Macintosh user agent by default since iPadOS 13, so `getBrowser()` * reports `os: 'macOS'` there and every `os === 'iOS'` check misses it. macOS Safari implements no * touch events at all (`TouchEvent` undefined, `maxTouchPoints` 0) regardless of any touchscreen * attached, so touch capability separates the two. Measured on an iPad 6 / iPadOS 17 * (`maxTouchPoints` 5) against macOS Safari 26.4 (`maxTouchPoints` 0). * * Deliberately a separate helper rather than a fix in `browserParser`: iPadOS spoofs the Mac * version too, so reporting `os: 'iOS'` there would leave `osVersion` at `10.15.7` and silently * break {@link isSafari17Based} and {@link isSafariSvcApi}, which compare it. */ export function isIPadOS(): boolean { if (!isWeb()) { return false; } const b = getBrowser(); return b?.name === 'Safari' && b?.os === 'macOS' && navigator.maxTouchPoints > 1; } /** * iPhone, iPad and iOS-hosted browsers — everything running the Apple camera capture pipeline, * including iPads that present themselves as a Mac. */ export function isAppleMobile(): boolean { return getBrowser()?.os === 'iOS' || isIPadOS(); } export function isSafari17Based(): boolean { const b = getBrowser(); return ( (b?.name === 'Safari' && b.version.startsWith('17.')) || (b?.os === 'iOS' && !!b?.osVersion && compareVersions(b.osVersion, '17') >= 0) ); } export function isSafariSvcApi(browser?: BrowserDetails): boolean { if (!browser) { browser = getBrowser(); } // Safari 18.4 requires legacy svc api and scaleResolutionDown to be set return ( (browser?.name === 'Safari' && compareVersions(browser.version, '18.3') > 0) || (browser?.os === 'iOS' && !!browser?.osVersion && compareVersions(browser.osVersion, '18.3') > 0) ); } export function isMobile(): boolean { if (!isWeb()) return false; return ( // @ts-expect-error `userAgentData` is not yet part of typescript navigator.userAgentData?.mobile ?? /Tablet|iPad|Mobile|Android|BlackBerry/.test(navigator.userAgent) ); } export function isE2EESimulcastSupported() { const browser = getBrowser(); const supportedSafariVersion = '17.2'; // see https://bugs.webkit.org/show_bug.cgi?id=257803 if (browser) { if (browser.name !== 'Safari' && browser.os !== 'iOS') { return true; } else if ( browser.os === 'iOS' && browser.osVersion && compareVersions(browser.osVersion, supportedSafariVersion) >= 0 ) { return true; } else if ( browser.name === 'Safari' && compareVersions(browser.version, supportedSafariVersion) >= 0 ) { return true; } else { return false; } } } export function isWeb(): boolean { return typeof document !== 'undefined'; } export function isReactNative(): boolean { // navigator.product is deprecated on browsers, but will be set appropriately for react-native. return navigator.product == 'ReactNative'; } export function isCloud(serverUrl: URL) { return ( serverUrl.hostname.endsWith('.livekit.cloud') || serverUrl.hostname.endsWith('.livekit.run') ); } export function extractProjectFromUrl(serverUrl: URL): string | null { if (!isCloud(serverUrl)) { return null; } return serverUrl.hostname.split('.')[0]; } function getLKReactNativeInfo(): LiveKitReactNativeInfo | undefined { // global defined only for ReactNative. // @ts-ignore if (global && global.LiveKitReactNativeGlobal) { // @ts-ignore return global.LiveKitReactNativeGlobal as LiveKitReactNativeInfo; } return undefined; } export function getReactNativeOs(): string | undefined { if (!isReactNative()) { return undefined; } let info = getLKReactNativeInfo(); if (info) { return info.platform; } return undefined; } export function getDevicePixelRatio(): number { if (isWeb()) { return window.devicePixelRatio; } if (isReactNative()) { let info = getLKReactNativeInfo(); if (info) { return info.devicePixelRatio; } } return 1; } /** * @param v1 - The first version string to compare. * @param v2 - The second version string to compare. * @returns A number indicating the order of the versions: * - 1 if v1 is greater than v2 * - -1 if v1 is less than v2 * - 0 if v1 and v2 are equal */ export function compareVersions(v1: string, v2: string): number { const parts1 = v1.split('.'); const parts2 = v2.split('.'); const k = Math.min(parts1.length, parts2.length); for (let i = 0; i < k; ++i) { const p1 = parseInt(parts1[i], 10); const p2 = parseInt(parts2[i], 10); if (p1 > p2) return 1; if (p1 < p2) return -1; if (i === k - 1 && p1 === p2) return 0; } if (v1 === '' && v2 !== '') { return -1; } else if (v2 === '') { return 1; } return parts1.length == parts2.length ? 0 : parts1.length < parts2.length ? -1 : 1; } function roDispatchCallback(entries: ResizeObserverEntry[]) { for (const entry of entries) { (entry.target as ObservableMediaElement).handleResize(entry); } } function ioDispatchCallback(entries: IntersectionObserverEntry[]) { for (const entry of entries) { (entry.target as ObservableMediaElement).handleVisibilityChanged(entry); } } let resizeObserver: ResizeObserver | null = null; export const getResizeObserver = () => { if (!resizeObserver) resizeObserver = new ResizeObserver(roDispatchCallback); return resizeObserver; }; let intersectionObserver: IntersectionObserver | null = null; export const getIntersectionObserver = () => { if (!intersectionObserver) { intersectionObserver = new IntersectionObserver(ioDispatchCallback, { root: null, rootMargin: '0px', }); } return intersectionObserver; }; export interface ObservableMediaElement extends HTMLMediaElement { handleResize: (entry: ResizeObserverEntry) => void; handleVisibilityChanged: (entry: IntersectionObserverEntry) => void; } /** @hidden */ export type WrapperSdkInfo = { /** The `ClientInfo.SDK` enum name of the wrapping SDK, e.g. `'UNITY_WEB'` */ sdk: keyof typeof ClientInfo_SDK; /** The wrapping SDK's own version */ version: string; }; let wrapperSdkInfo: WrapperSdkInfo | undefined; /** * For LiveKit SDKs built on top of livekit-client (e.g. Unity WebGL). * Reports the wrapper as the client SDK to the server, and moves livekit-client's * own version to `ClientInfo.other_sdks`. Pass `undefined` to reset. * Meant for wrapper SDKs, not for apps. * @hidden */ export function setWrapperSdkInfo(info: WrapperSdkInfo | undefined) { wrapperSdkInfo = info; } export function getClientInfo(capabilities?: ClientInfo_Capability[]): ClientInfo { let sdk = isReactNative() ? ClientInfo_SDK.REACT_NATIVE : ClientInfo_SDK.JS; if (wrapperSdkInfo) { sdk = ClientInfo_SDK[wrapperSdkInfo.sdk]; } const info = new ClientInfo({ capabilities, sdk, protocol: protocolVersion, clientProtocol, version: wrapperSdkInfo?.version ?? version, otherSdks: wrapperSdkInfo ? `js:${version}` : undefined, }); if (isReactNative()) { info.os = getReactNativeOs() ?? ''; } return info; } let emptyVideoStreamTrack: MediaStreamTrack | undefined; export function getEmptyVideoStreamTrack() { if (!emptyVideoStreamTrack) { emptyVideoStreamTrack = createDummyVideoStreamTrack(); } return emptyVideoStreamTrack.clone(); } export function createDummyVideoStreamTrack( width: number = 16, height: number = 16, enabled: boolean = false, paintContent: boolean = false, ) { const canvas = document.createElement('canvas'); // the canvas size is set to 16 by default, because electron apps seem to fail with smaller values canvas.width = width; canvas.height = height; const ctx = canvas.getContext('2d'); ctx?.fillRect(0, 0, canvas.width, canvas.height); if (paintContent && ctx) { ctx.beginPath(); ctx.arc(width / 2, height / 2, 50, 0, Math.PI * 2, true); ctx.closePath(); ctx.fillStyle = 'grey'; ctx.fill(); } // @ts-ignore const dummyStream = canvas.captureStream(); const [dummyTrack] = dummyStream.getTracks(); if (!dummyTrack) { throw Error('Could not get empty media stream video track'); } dummyTrack.enabled = enabled; return dummyTrack; } let emptyAudioStreamTrack: MediaStreamTrack | undefined; let emptyAudioStreamContext: AudioContext | undefined; /** tracks handed out by `getEmptyAudioStreamTrack` that haven't been released yet */ const outstandingEmptyAudioStreamTracks = new Set(); /** * Returns a silent audio track, cloned off a shared `AudioContext` created on first use. Hand the * clone back to `releaseEmptyAudioStreamTrack` rather than stopping it, so the context can close. * A clone that is only stopped stays counted as outstanding, which holds the shared context open * for the lifetime of the page. */ export function getEmptyAudioStreamTrack() { if (!emptyAudioStreamTrack) { // implementation adapted from https://blog.mozilla.org/webrtc/warm-up-with-replacetrack/ const ctx = new AudioContext(); const oscillator = ctx.createOscillator(); const gain = ctx.createGain(); gain.gain.setValueAtTime(0, 0); const dst = ctx.createMediaStreamDestination(); oscillator.connect(gain); gain.connect(dst); oscillator.start(); [emptyAudioStreamTrack] = dst.stream.getAudioTracks(); if (!emptyAudioStreamTrack) { // don't hold on to a context we can't get a track out of ctx.close().catch(() => {}); throw Error('Could not get empty media stream audio track'); } emptyAudioStreamTrack.enabled = false; emptyAudioStreamContext = ctx; } const track = emptyAudioStreamTrack.clone(); outstandingEmptyAudioStreamTracks.add(track); return track; } /** * Stops a track obtained from `getEmptyAudioStreamTrack` and closes the shared `AudioContext` * backing it once every track it handed out has been released. Does nothing for a track this * module never handed out, or one that has been released already. */ export async function releaseEmptyAudioStreamTrack(track: MediaStreamTrack) { if (!outstandingEmptyAudioStreamTracks.delete(track)) { // the track wasn't obtained from `getEmptyAudioStreamTrack`, or has been released before return; } track.stop(); if (outstandingEmptyAudioStreamTracks.size > 0) { return; } const context = emptyAudioStreamContext; emptyAudioStreamTrack?.stop(); emptyAudioStreamTrack = undefined; emptyAudioStreamContext = undefined; await context?.close(); } /** An object that represents a serialized version of a `new Promise((resolve, reject) => {})` * constructor. Wait for a promise resolution with `await future.promise` and explicitly resolve or * reject the inner promise with `future.resolve(...)` or `future.reject(...)`. */ export class Future { promise: Promise>; resolve?: (arg: T) => void; reject?: (e: E) => void; onFinally?: () => void; get isResolved(): boolean { return this._isResolved; } private _isResolved: boolean = false; constructor( futureBase?: (resolve: (arg: T) => void, reject: (e: E) => void) => void, onFinally?: () => void, ) { this.onFinally = onFinally; this.promise = new Promise(async (resolve, reject) => { this.resolve = resolve; this.reject = reject; if (futureBase) { await futureBase(resolve, reject); } }).finally(() => { this._isResolved = true; this.onFinally?.(); }) as Promise>; } } export type AudioAnalyserOptions = { /** * If set to true, the analyser will use a cloned version of the underlying mediastreamtrack, which won't be impacted by muting the track. * Useful for local tracks when implementing things like "seems like you're muted, but trying to speak". * Defaults to false */ cloneTrack?: boolean; /** * see https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/fftSize */ fftSize?: number; /** * see https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/smoothingTimeConstant */ smoothingTimeConstant?: number; /** * see https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/minDecibels */ minDecibels?: number; /** * see https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/maxDecibels */ maxDecibels?: number; }; /** * Creates and returns an analyser web audio node that is attached to the provided track. * Additionally returns a convenience method `calculateVolume` to perform instant volume readings on that track. * Call the returned `cleanup` function to close the audioContext that has been created for the instance of this helper */ export function createAudioAnalyser( track: LocalAudioTrack | RemoteAudioTrack, options?: AudioAnalyserOptions, ) { const opts = { cloneTrack: false, fftSize: 2048, smoothingTimeConstant: 0.8, minDecibels: -100, maxDecibels: -80, ...options, }; const audioContext = getNewAudioContext(); if (!audioContext) { throw new Error('Audio Context not supported on this browser'); } const streamTrack = opts.cloneTrack ? track.mediaStreamTrack.clone() : track.mediaStreamTrack; const mediaStreamSource = audioContext.createMediaStreamSource(new MediaStream([streamTrack])); const analyser = audioContext.createAnalyser(); analyser.minDecibels = opts.minDecibels; analyser.maxDecibels = opts.maxDecibels; analyser.fftSize = opts.fftSize; analyser.smoothingTimeConstant = opts.smoothingTimeConstant; mediaStreamSource.connect(analyser); const dataArray = new Uint8Array(analyser.frequencyBinCount); /** * Calculates the current volume of the track in the range from 0 to 1 */ const calculateVolume = () => { analyser.getByteFrequencyData(dataArray); let sum = 0; for (const amplitude of dataArray) { sum += Math.pow(amplitude / 255, 2); } const volume = Math.sqrt(sum / dataArray.length); return volume; }; let isCleanedUp = false; const cleanup = async () => { if (isCleanedUp) { // closing an already closed context would reject, make repeated cleanups a no-op instead return; } isCleanedUp = true; mediaStreamSource.disconnect(); analyser.disconnect(); if (opts.cloneTrack) { streamTrack.stop(); } await audioContext.close(); }; return { calculateVolume, analyser, cleanup }; } export function isAudioCodec(maybeCodec: string): maybeCodec is AudioCodec { return audioCodecs.includes(maybeCodec as AudioCodec); } export function isVideoCodec(maybeCodec: string): maybeCodec is VideoCodec { return videoCodecs.includes(maybeCodec as VideoCodec); } export function unwrapConstraint(constraint: ConstrainDOMString): string; export function unwrapConstraint(constraint: ConstrainULong): number; export function unwrapConstraint(constraint: ConstrainDOMString | ConstrainULong): string | number { if (typeof constraint === 'string' || typeof constraint === 'number') { return constraint; } if (Array.isArray(constraint)) { return constraint[0]; } if (constraint.exact !== undefined) { if (Array.isArray(constraint.exact)) { return constraint.exact[0]; } return constraint.exact; } if (constraint.ideal !== undefined) { if (Array.isArray(constraint.ideal)) { return constraint.ideal[0]; } return constraint.ideal; } throw Error('could not unwrap constraint'); } /** * The getUserMedia rejections that no softer constraint can recover from, because the user or the * document refused capture outright. Retrying one of these would put a second prompt in front of * someone who already said no. The last two names are legacy spellings still reported by older * engines. Matched by `name` rather than with `instanceof`, because these are not reliably distinct * constructors across environments. happy-dom, which the tests run under, aliases them to `Event`. */ export function isPermissionDeniedError(e: unknown): boolean { return ( typeof e === 'object' && e !== null && 'name' in e && (e.name === 'NotAllowedError' || e.name === 'SecurityError' || e.name === 'PermissionDeniedError' || e.name === 'PermissionDismissedError') ); } const deviceAcquisitionFailures = new WeakSet(); /** Records that `e` is the rejection getUserMedia itself produced. */ export function markDeviceAcquisitionFailure(e: unknown) { if (typeof e === 'object' && e !== null) { deviceAcquisitionFailures.add(e); } } /** * Whether a track restart failed at getUserMedia rather than in the work that adopts the new track. * Recorded on the side rather than by wrapping, because callers of `restartTrack` match on the * rejection's own name. */ export function isDeviceAcquisitionFailure(e: unknown): boolean { return typeof e === 'object' && e !== null && deviceAcquisitionFailures.has(e); } export function toWebsocketUrl(url: string): string { if (url.startsWith('http')) { return url.replace(/^(http)/, 'ws'); } return url; } export function toHttpUrl(url: string): string { if (url.startsWith('ws')) { return url.replace(/^(ws)/, 'http'); } return url; } export function extractTranscriptionSegments( transcription: TranscriptionModel, firstReceivedTimesMap: Map, ): TranscriptionSegment[] { return transcription.segments.map(({ id, text, language, startTime, endTime, final }) => { const firstReceivedTime = firstReceivedTimesMap.get(id) ?? Date.now(); const lastReceivedTime = Date.now(); if (final) { firstReceivedTimesMap.delete(id); } else { firstReceivedTimesMap.set(id, firstReceivedTime); } return { id, text, startTime: Number.parseInt(startTime.toString()), endTime: Number.parseInt(endTime.toString()), final, language, firstReceivedTime, lastReceivedTime, }; }); } export function extractChatMessage(msg: ChatMessageModel): ChatMessage { const { id, timestamp, message, editTimestamp } = msg; return { id, timestamp: Number.parseInt(timestamp.toString()), editTimestamp: editTimestamp ? Number.parseInt(editTimestamp.toString()) : undefined, message, }; } export function getDisconnectReasonFromConnectionError(e: ConnectionError) { switch (e.reason) { case ConnectionErrorReason.LeaveRequest: return e.context as DisconnectReason; case ConnectionErrorReason.Cancelled: return DisconnectReason.CLIENT_INITIATED; case ConnectionErrorReason.NotAllowed: return DisconnectReason.USER_REJECTED; case ConnectionErrorReason.ServerUnreachable: return DisconnectReason.JOIN_FAILURE; default: return DisconnectReason.UNKNOWN_REASON; } } /** convert bigints to numbers preserving undefined values */ export function bigIntToNumber( value: T, ): T extends BigInt ? number : undefined { return (value !== undefined ? Number(value) : undefined) as T extends BigInt ? number : undefined; } /** convert numbers to bigints preserving undefined values */ export function numberToBigInt( value: T, ): T extends number ? bigint : undefined { return (value !== undefined ? BigInt(value) : undefined) as T extends number ? bigint : undefined; } export function isLocalTrack(track: Track | MediaStreamTrack | undefined): track is LocalTrack { return !!track && !(track instanceof MediaStreamTrack) && track.isLocal; } export function isAudioTrack( track: Track | undefined, ): track is LocalAudioTrack | RemoteAudioTrack { return !!track && track.kind == Track.Kind.Audio; } export function isVideoTrack( track: Track | undefined, ): track is LocalVideoTrack | RemoteVideoTrack { return !!track && track.kind == Track.Kind.Video; } export function isLocalVideoTrack( track: Track | MediaStreamTrack | undefined, ): track is LocalVideoTrack { return isLocalTrack(track) && isVideoTrack(track); } export function isLocalAudioTrack( track: Track | MediaStreamTrack | undefined, ): track is LocalAudioTrack { return isLocalTrack(track) && isAudioTrack(track); } export function isRemoteTrack(track: Track | undefined): track is RemoteTrack { return !!track && !track.isLocal; } export function isRemotePub(pub: TrackPublication | undefined): pub is RemoteTrackPublication { return !!pub && !pub.isLocal; } export function isLocalPub(pub: TrackPublication | undefined): pub is LocalTrackPublication { return !!pub && !pub.isLocal; } export function isRemoteVideoTrack(track: Track | undefined): track is RemoteVideoTrack { return isRemoteTrack(track) && isVideoTrack(track); } export function isLocalParticipant(p: Participant): p is LocalParticipant { return p.isLocal; } export function isRemoteParticipant(p: Participant): p is RemoteParticipant { return !p.isLocal; } export function splitUtf8(s: string, n: number): NonSharedUint8Array[] { if (n < 4) { throw new Error('n must be at least 4 due to utf8 encoding rules'); } // adapted from https://stackoverflow.com/a/6043797 const result: NonSharedUint8Array[] = []; let encoded = new TextEncoder().encode(s); while (encoded.length > n) { let k = n; while (k > 0) { const byte = encoded[k]; if (byte !== undefined && (byte & 0xc0) !== 0x80) { break; } k--; } result.push(encoded.slice(0, k)); encoded = encoded.slice(k); } if (encoded.length > 0) { result.push(encoded); } return result; } /** Wraps a byte array in a `ReadableStream` that yields it as a single chunk and then closes. */ export function readableFromBytes(bytes: NonSharedUint8Array): ReadableStream { return new ReadableStream({ start(controller) { controller.enqueue(bytes); controller.close(); }, }); } /** * Re-chunks a byte stream into pieces of exactly `chunkSize` bytes (the final piece may be * smaller), coalescing or splitting the source's pieces as needed. Memory use is bounded to roughly * `chunkSize` plus one source read, so it never buffers the whole stream — used to pack * `CompressionStream`/`file.stream()` output into MTU-sized data-stream chunks. */ export async function* readBytesInChunks( source: ReadableStream, chunkSize: number, ): AsyncGenerator { const reader = source.getReader(); let buffer = new Uint8Array(0); try { while (true) { const { done, value } = await reader.read(); if (done) { break; } if (value.byteLength === 0) { continue; } const merged = new Uint8Array(buffer.byteLength + value.byteLength); merged.set(buffer); merged.set(value, buffer.byteLength); buffer = merged; while (buffer.byteLength >= chunkSize) { yield buffer.slice(0, chunkSize); buffer = buffer.slice(chunkSize); } } if (buffer.byteLength > 0) { yield buffer; } } finally { reader.releaseLock(); } } /** Encodes a byte array as a base64 string (suitable for embedding binary data in a string field). */ export function encodeBase64(bytes: Uint8Array): string { let binary = ''; for (let i = 0; i < bytes.byteLength; i++) { binary += String.fromCharCode(bytes[i]!); } return btoa(binary); } /** Decodes a base64 string (as produced by {@link encodeBase64}) back into a byte array. */ export function decodeBase64(base64: string): Uint8Array { const binary = atob(base64); const bytes = new Uint8Array(binary.length); for (let i = 0; i < binary.length; i++) { bytes[i] = binary.charCodeAt(i); } return bytes; } export function extractMaxAgeFromRequestHeaders(headers: Headers): number | undefined { const cacheControl = headers.get('Cache-Control'); if (cacheControl) { const maxAge = cacheControl.match(/(?:^|[,\s])max-age=(\d+)/)?.[1]; if (maxAge) { return parseInt(maxAge, 10); } } return undefined; } export function isCompressionStreamSupported() { return typeof CompressionStream !== 'undefined'; } let deflateRawCompressionSupported: boolean | null = null; /** * Whether this runtime can compress AND decompress the `deflate-raw` format, which is a stricter * requirement than {@link isCompressionStreamSupported}: Chromium 80-102 included * `CompressionStream` supporting only `gzip` / `deflate`, and `deflate-raw` was added in Chromium * 103 (Firefox 113, Safari 16.4). */ export function isDeflateRawCompressionSupported(): boolean { if (typeof deflateRawCompressionSupported !== 'boolean') { deflateRawCompressionSupported = probeDeflateRawCompressionSupport(); } return deflateRawCompressionSupported; } function probeDeflateRawCompressionSupport(): boolean { if (typeof CompressionStream === 'undefined' || typeof DecompressionStream === 'undefined') { return false; } try { // There is no api to query format support, and constructing with an unsupported format throws // synchronously, so constructing one of each is the probe. Both are checked because the // deflate-raw capability advertised to peers is as much about decompressing what they send us // as it is about compressing what we send them. new CompressionStream('deflate-raw'); new DecompressionStream('deflate-raw'); return true; } catch { return false; } } /** * Clears the memoized {@link isDeflateRawCompressionSupported} probe result. A runtime doesn't * gain or lose compression formats while it is running, so this only exists for tests that swap * the global `CompressionStream` / `DecompressionStream`. * * @internal */ export function resetDeflateRawCompressionSupportCache() { deflateRawCompressionSupported = null; } export function isPublisherOfferWithJoinSupported() { // we have connectivity issue about publisher offer with join on firefox #1919 return isCompressionStreamSupported() && !isFireFox(); } export function extractTrackSid( mediaTrack: MediaStreamTrack, stream: MediaStream, ): Track.SID | undefined { const [, streamId] = unpackStreamId(stream.id); if (streamId?.startsWith('TR')) { return streamId; } if (mediaTrack.id.startsWith('TR')) { return mediaTrack.id; } }