Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
37.5 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-or-later

import {Logger} from '@app/features/platform/utils/AppLogger';
import {getElectronAPI} from '@app/features/ui/utils/NativeUtils';
import type {VoiceEngineV2AppSourceLifecycleBridge} from '@app/features/voice/engine/v2/VoiceEngineV2AppSourceLifecycleBridge';
import {getNativeAudioErrorDetail} from '@app/features/voice/utils/NativeAudioFailureUtils';
import {
	getEndedBridgeCaptures,
	getBridgeStats as getNativeAudioBridgeStats,
} from '@app/features/voice/utils/native_audio_capture_bridge/bridgeStats';
import {createGeneratorBridge} from '@app/features/voice/utils/native_audio_capture_bridge/createGeneratorBridge';
import {createScriptProcessorBridge} from '@app/features/voice/utils/native_audio_capture_bridge/createScriptProcessorBridge';
import {
	type ActiveNativeAudioBridge,
	type ArmedNativeAudioCapture,
	getArmedCaptureId,
	getAudioDataCtor,
	getGeneratorCtor,
	getNativeAudioApi,
	isNativeAudioDesktopPlatform,
	type NativeAudioBridgeHandle,
	nativeAudioRoutingRulesEqual,
	patchTrackStopForCleanup,
	replaceStreamAudioTrack,
	selectWindowsDesktopAudioStart,
	shouldMixSelfWindowAudioIntoSystemCapture,
	unsupportedPlatformAvailability,
	type WindowsDesktopAudioSelection,
	windowsEndpointsEqual,
} from '@app/features/voice/utils/native_audio_capture_bridge/shared';
import type {ScreenShareAudioCaptureDebugInfo} from '@app/features/voice/utils/ScreenShareAudioCaptureError';
import {
	acquireSelfWindowScreenShareAudioTrack,
	releaseSelfWindowScreenShareAudioTrack,
} from '@app/features/voice/utils/SelfWindowScreenShareAudio';
import {
	type MixedSelfWindowAudioTrack,
	mixTrackWithSelfWindowScreenShareAudio,
} from '@app/features/voice/utils/SelfWindowScreenShareAudioMix';
import type {
	ElectronAPI,
	NativeAudioApi,
	NativeAudioAvailability,
	NativeAudioPlaybackDevice,
	NativeAudioStartOptions,
	NativeAudioStartResult,
} from '@app/types/electron.d';

const logger = new Logger('NativeAudioCaptureBridge');

let patched = false;
let originalGetDisplayMedia: MediaDevices['getDisplayMedia'] | null = null;
let availabilityCache: Promise<NativeAudioAvailability> | null = null;
let resolvedAvailability: NativeAudioAvailability | null = null;
let armedCapture: ArmedNativeAudioCapture | null = null;
let lastArmFailure: ScreenShareAudioCaptureDebugInfo | null = null;
let activeBridge: ActiveNativeAudioBridge | null = null;
let supersededBridge: ActiveNativeAudioBridge | null = null;

interface NativeAudioStartedCaptureDiagnostic {
	captureId: string;
	startedAtMs: number;
	platform?: string;
	sourceMode?: 'system' | 'specific';
	targetPid?: number;
	linuxRule?: NativeAudioStartOptions['linuxRule'];
	macBackend?: NativeAudioStartOptions['macBackend'];
	macCaptureScope?: NativeAudioStartOptions['macCaptureScope'];
	winCaptureScope?: NativeAudioStartOptions['winCaptureScope'];
	winEndpoints?: Array<string>;
	includeSelfWindowAudio?: boolean;
}

interface NativeAudioLifecycleFaultDiagnostic {
	captureId: string;
	sourceId: string;
	message: string;
	atMs: number;
}

const MAX_RETAINED_LIFECYCLE_FAULTS = 8;

let lastStartedCapture: NativeAudioStartedCaptureDiagnostic | null = null;
let lastPlaybackDeviceListing: {atMs: number; devices: Array<NativeAudioPlaybackDevice>} | null = null;
let sourceLifecycleBridge: VoiceEngineV2AppSourceLifecycleBridge | null = null;
let lifecycleFaults: Array<NativeAudioLifecycleFaultDiagnostic> = [];
const lifecycleBoundCaptureIds = new Set<string>();

export {getNativeAudioBridgeStats};

export function setNativeAudioCaptureBridgeLifecycleBridge(bridge: VoiceEngineV2AppSourceLifecycleBridge | null): void {
	for (const captureId of lifecycleBoundCaptureIds) {
		sourceLifecycleBridge?.unbind(captureId);
	}
	lifecycleBoundCaptureIds.clear();
	sourceLifecycleBridge = bridge;
}

function bindNativeAudioCaptureLifecycle(captureId: string): void {
	const bridge = sourceLifecycleBridge;
	if (!bridge) return;
	if (typeof captureId !== 'string' || captureId.length === 0) return;
	if (lifecycleBoundCaptureIds.has(captureId)) return;
	const sourceId = `native-audio-tap:${captureId}`;
	const bound = bridge.bind({captureId, sourceId});
	if (bound) {
		lifecycleBoundCaptureIds.add(captureId);
	}
}

function recordLifecycleFault(captureId: string, message: string): void {
	lifecycleFaults.push({captureId, sourceId: `native-audio-tap:${captureId}`, message, atMs: Date.now()});
	if (lifecycleFaults.length > MAX_RETAINED_LIFECYCLE_FAULTS) {
		lifecycleFaults = lifecycleFaults.slice(-MAX_RETAINED_LIFECYCLE_FAULTS);
	}
}

function unbindNativeAudioCaptureLifecycle(captureId: string, fault: string | null): void {
	if (!lifecycleBoundCaptureIds.has(captureId)) return;
	const bridge = sourceLifecycleBridge;
	if (fault) {
		recordLifecycleFault(captureId, fault);
	}
	if (bridge) {
		if (fault) {
			bridge.reportLifecycle({captureId, kind: 'error', message: fault});
		}
		bridge.unbind(captureId);
	}
	lifecycleBoundCaptureIds.delete(captureId);
}

function nativeAudioUnavailableReason(
	electronApi: ElectronAPI | null,
	nativeAudioApi: NativeAudioApi | undefined,
): string {
	if (!electronApi) {
		return 'electron-api-unavailable';
	}
	if (!nativeAudioApi) {
		return 'native-audio-api-unavailable';
	}
	return 'unsupported-platform';
}

function setLastArmFailure(debugInfo: ScreenShareAudioCaptureDebugInfo): void {
	lastArmFailure = debugInfo;
}

function clearLastArmFailure(): void {
	lastArmFailure = null;
}

export function getLastNativeAudioArmFailure(): ScreenShareAudioCaptureDebugInfo | null {
	return lastArmFailure ? {...lastArmFailure} : null;
}

function cloneLinuxRule(rule: NativeAudioStartOptions['linuxRule']): NativeAudioStartOptions['linuxRule'] {
	if (!rule) return undefined;
	const next: NativeAudioStartOptions['linuxRule'] = {
		...rule,
		include: rule.include?.map((entry) => ({...entry})),
		exclude: rule.exclude?.map((entry) => ({...entry})),
	};
	return next;
}

function summarizeArmedCapture(capture: ArmedNativeAudioCapture | null): Record<string, unknown> | null {
	if (!capture) return null;
	if (capture.kind === 'linux-routing') {
		return {
			kind: capture.kind,
			linuxRule: cloneLinuxRule(capture.linuxRule),
			includeSelfWindowAudio: capture.includeSelfWindowAudio,
		};
	}
	if (capture.kind === 'capture') {
		return {
			kind: capture.kind,
			captureId: capture.captureId,
			includeSelfWindowAudio: capture.includeSelfWindowAudio,
			winEndpoints: capture.winEndpoints ? [...capture.winEndpoints] : undefined,
		};
	}
	return {kind: capture.kind};
}

function rememberStartedCapture(capture: NativeAudioStartedCaptureDiagnostic): void {
	lastStartedCapture = {
		...capture,
		linuxRule: cloneLinuxRule(capture.linuxRule),
		winEndpoints: capture.winEndpoints ? [...capture.winEndpoints] : undefined,
	};
}

export async function refreshWindowsPlaybackDeviceListing(): Promise<Array<NativeAudioPlaybackDevice>> {
	const nativeAudioApi = getNativeAudioApi();
	if (getElectronAPI()?.platform !== 'win32' || typeof nativeAudioApi?.listPlaybackDevices !== 'function') {
		return [];
	}
	try {
		const devices = await nativeAudioApi.listPlaybackDevices();
		lastPlaybackDeviceListing = {atMs: Date.now(), devices};
		return devices;
	} catch (error) {
		logger.warn('Failed to list Windows playback devices', {error});
		return [];
	}
}

type CapturedDisplayAudioDiagnostic = {
	readyState: MediaStreamTrackState;
	label: string;
	deviceId: string | null;
	discarded: boolean;
};

let lastCapturedDisplayAudio: CapturedDisplayAudioDiagnostic | null = null;

export function rememberCapturedDisplayAudioTrack(track: MediaStreamTrack | undefined, discarded: boolean): void {
	if (!track) {
		lastCapturedDisplayAudio = null;
		return;
	}
	let deviceId: string | null = null;
	try {
		deviceId = track.getSettings().deviceId ?? null;
	} catch {
		deviceId = null;
	}
	lastCapturedDisplayAudio = {readyState: track.readyState, label: track.label, deviceId, discarded};
}

export function getNativeAudioCaptureDiagnosticState(): Record<string, unknown> {
	const started = lastStartedCapture
		? {
				...lastStartedCapture,
				linuxRule: cloneLinuxRule(lastStartedCapture.linuxRule),
			}
		: null;
	return {
		armedCapture: summarizeArmedCapture(armedCapture),
		activeBridge: activeBridge
			? {
					captureId: activeBridge.captureId,
					winEndpoints: activeBridge.winEndpoints ? [...activeBridge.winEndpoints] : undefined,
				}
			: null,
		supersededBridge: supersededBridge ? {captureId: supersededBridge.captureId} : null,
		lastStartedCapture: started,
		lastArmFailure: getLastNativeAudioArmFailure(),
		bridgeStats: getNativeAudioBridgeStats(),
		endedBridgeCaptures: getEndedBridgeCaptures(),
		lifecycleFaults: lifecycleFaults.map((fault) => ({...fault})),
		capturedDisplayAudio: lastCapturedDisplayAudio ? {...lastCapturedDisplayAudio} : null,
		lastPlaybackDeviceListing: lastPlaybackDeviceListing
			? {
					atMs: lastPlaybackDeviceListing.atMs,
					devices: lastPlaybackDeviceListing.devices.map((device) => ({
						...device,
						sessions: device.sessions.map((session) => ({...session})),
					})),
				}
			: null,
	};
}

function cleanupBridgeAsync(
	bridge: ActiveNativeAudioBridge,
	stopRemote: boolean,
	logContext: string,
	endDetail?: string,
): void {
	void bridge.cleanup(stopRemote, endDetail).catch((error) => {
		logger.warn(`Failed to clean up native audio bridge after ${logContext}`, {
			captureId: bridge.captureId,
			error,
		});
	});
}

function cleanupManagedBridgeById(
	captureId: string,
	stopRemote: boolean,
	logContext: string,
	endDetail?: string,
): boolean {
	if (activeBridge?.captureId === captureId) {
		const bridge = activeBridge;
		activeBridge = supersededBridge;
		supersededBridge = null;
		cleanupBridgeAsync(bridge, stopRemote, logContext, endDetail);
		return true;
	}
	if (supersededBridge?.captureId === captureId) {
		const bridge = supersededBridge;
		supersededBridge = null;
		cleanupBridgeAsync(bridge, stopRemote, logContext, endDetail);
		return true;
	}
	return false;
}

async function stopArmedCapture(capture: ArmedNativeAudioCapture, logContext: string): Promise<void> {
	if (capture.kind === 'self-window-web-audio') {
		releaseSelfWindowScreenShareAudioTrack();
		return;
	}
	if (capture.kind !== 'capture') return;
	await getNativeAudioApi()
		?.stop(capture.captureId)
		.catch((error) => {
			logger.warn(`Failed to stop native audio capture after ${logContext}`, {
				captureId: capture.captureId,
				error,
			});
		});
}

function attachNativeAudioCleanup(
	stream: MediaStream,
	captureId: string,
	handle: NativeAudioBridgeHandle,
): ActiveNativeAudioBridge['cleanup'] {
	const videoTracks = stream.getVideoTracks();
	const tracks = [...videoTracks, handle.track];
	const cleanupListeners: Array<() => void> = [];
	const restoreStops: Array<() => void> = [];
	let cleanedUp = false;
	bindNativeAudioCaptureLifecycle(captureId);
	const cleanup = async (stopRemote: boolean = true, endDetail?: string): Promise<void> => {
		if (cleanedUp) return;
		cleanedUp = true;
		for (const removeListener of cleanupListeners.splice(0)) {
			removeListener();
		}
		for (const restoreStop of restoreStops.splice(0)) {
			restoreStop();
		}
		if (activeBridge?.captureId === captureId) {
			activeBridge = null;
		}
		unbindNativeAudioCaptureLifecycle(captureId, null);
		await handle.cleanup(stopRemote, endDetail);
	};
	const requestCleanup = (fault: string | null, endDetail: string, logContext: string): void => {
		unbindNativeAudioCaptureLifecycle(captureId, fault);
		if (!cleanupManagedBridgeById(captureId, true, logContext, endDetail)) {
			cleanupBridgeAsync({captureId, cleanup}, true, logContext, endDetail);
		}
	};
	for (const track of tracks) {
		const trackKind = track === handle.track ? 'audio' : 'video';
		const onEnded = (): void =>
			requestCleanup(`native-audio-tap-${trackKind}-track-ended`, `${trackKind}-track-ended`, 'track ended');
		track.addEventListener('ended', onEnded);
		cleanupListeners.push(() => track.removeEventListener('ended', onEnded));
		restoreStops.push(patchTrackStopForCleanup(track, () => requestCleanup(null, 'caller-stopped', 'caller stop')));
	}
	return cleanup;
}

async function createNativeAudioBridge(captureId: string): Promise<NativeAudioBridgeHandle> {
	if (getGeneratorCtor() && getAudioDataCtor()) {
		return createGeneratorBridge(captureId, (id) => cleanupManagedBridgeById(id, false, 'remote end'));
	}
	logger.info('Falling back to ScriptProcessor native-audio bridge');
	return createScriptProcessorBridge(captureId, (id) => cleanupManagedBridgeById(id, false, 'remote end'));
}

async function createNativeAudioBridgeWithSelfWindowAudio(captureId: string): Promise<NativeAudioBridgeHandle> {
	const nativeHandle = await createNativeAudioBridge(captureId);
	let mixedTrack: MixedSelfWindowAudioTrack;
	try {
		mixedTrack = await mixTrackWithSelfWindowScreenShareAudio(nativeHandle.track, {
			sampleRate: 48000,
			unavailableMessage: 'Self-window app-audio tap unavailable for system audio mix',
		});
	} catch (error) {
		await nativeHandle.cleanup(true).catch((cleanupError) => {
			logger.warn('Failed to clean up native audio bridge after system audio mixer creation failed', {
				captureId,
				error: cleanupError,
			});
		});
		throw error;
	}
	let cleanedUp = false;
	const cleanup = async (stopRemote: boolean = true, endDetail?: string): Promise<void> => {
		if (cleanedUp) return;
		cleanedUp = true;
		await mixedTrack.cleanup();
		await nativeHandle.cleanup(stopRemote, endDetail);
	};
	return {
		track: mixedTrack.track,
		cleanup,
	};
}

async function startLinuxNativeAudioCapture(
	linuxRule: NonNullable<NativeAudioStartOptions['linuxRule']>,
): Promise<NativeAudioStartResult | null> {
	const electronApi = getElectronAPI();
	const nativeAudioApi = electronApi?.nativeAudio;
	if (electronApi?.platform !== 'linux' || !nativeAudioApi) {
		setLastArmFailure({
			platform: electronApi?.platform,
			reason: nativeAudioUnavailableReason(electronApi, nativeAudioApi),
		});
		logger.warn('Cannot start Linux native audio capture: native audio API unavailable', {
			hasElectronApi: Boolean(electronApi),
			hasNativeAudioApi: Boolean(nativeAudioApi),
			platform: electronApi?.platform,
		});
		return null;
	}
	if (!(await isNativeAudioAvailable())) {
		const availability = await nativeAudioApi.getAvailability().catch(() => null);
		setLastArmFailure({
			platform: electronApi.platform,
			backend: availability?.backend ?? null,
			reason: availability?.reason ?? 'unavailable',
			detail: availability?.detail ?? null,
		});
		logger.warn('Cannot start Linux native audio capture: native audio addon unavailable', {availability});
		return null;
	}
	try {
		const result = await nativeAudioApi.start({linuxRule});
		rememberStartedCapture({
			captureId: result.captureId,
			startedAtMs: Date.now(),
			platform: electronApi.platform,
			sourceMode: linuxRule.include && linuxRule.include.length > 0 ? 'specific' : 'system',
			linuxRule,
		});
		clearLastArmFailure();
		return result;
	} catch (error) {
		const detail = getNativeAudioErrorDetail(error);
		setLastArmFailure({
			platform: electronApi.platform,
			sourceMode: linuxRule.include && linuxRule.include.length > 0 ? 'specific' : 'system',
			reason: 'native-audio-start-failed',
			detail,
		});
		logger.warn('Cannot start Linux native audio capture: native audio start failed', {error});
		return null;
	}
}

function installPatchIfNeeded(): void {
	if (patched) return;
	if (!isNativeAudioDesktopPlatform()) return;
	if (typeof navigator === 'undefined' || !navigator.mediaDevices?.getDisplayMedia) return;
	originalGetDisplayMedia = navigator.mediaDevices.getDisplayMedia.bind(navigator.mediaDevices);
	navigator.mediaDevices.getDisplayMedia = async function patchedGetDisplayMedia(
		this: MediaDevices,
		constraints?: DisplayMediaStreamOptions,
	): Promise<MediaStream> {
		const pendingCapture = armedCapture;
		let stream: MediaStream;
		try {
			stream = await originalGetDisplayMedia!(constraints);
		} catch (error) {
			if (pendingCapture && armedCapture === pendingCapture) {
				armedCapture = null;
				await stopArmedCapture(pendingCapture, 'display capture failed');
			}
			throw error;
		}
		if (pendingCapture && armedCapture === pendingCapture) {
			armedCapture = null;
			if (pendingCapture.kind === 'self-window-web-audio') {
				const track = acquireSelfWindowScreenShareAudioTrack();
				if (track) {
					const cleanupListeners: Array<() => void> = [];
					const restoreStops: Array<() => void> = [];
					let cleanedUpSelf = false;
					const cleanupSelf = (): void => {
						if (cleanedUpSelf) return;
						cleanedUpSelf = true;
						for (const removeListener of cleanupListeners.splice(0)) {
							removeListener();
						}
						for (const restoreStop of restoreStops.splice(0)) {
							restoreStop();
						}
						releaseSelfWindowScreenShareAudioTrack(track);
					};
					try {
						await replaceStreamAudioTrack(stream, track);
						for (const otherTrack of [...stream.getVideoTracks(), track]) {
							const onEnded = (): void => cleanupSelf();
							otherTrack.addEventListener('ended', onEnded);
							cleanupListeners.push(() => otherTrack.removeEventListener('ended', onEnded));
							restoreStops.push(patchTrackStopForCleanup(otherTrack, cleanupSelf));
						}
					} catch (error) {
						logger.warn('Failed to attach self-window screen-share audio tap; degrading to video-only', {error});
						cleanupSelf();
					}
				} else {
					logger.warn('Self-window screen-share audio tap unavailable; degrading to video-only');
				}
				return stream;
			}
			let handle: NativeAudioBridgeHandle | null = null;
			let captureId = getArmedCaptureId(pendingCapture);
			try {
				if (!captureId && pendingCapture.kind === 'linux-routing') {
					const result = await startLinuxNativeAudioCapture(pendingCapture.linuxRule);
					if (!result) {
						return stream;
					}
					captureId = result.captureId;
				}
				if (!captureId) {
					return stream;
				}
				const previousBridge = activeBridge;
				handle =
					(pendingCapture.kind === 'capture' || pendingCapture.kind === 'linux-routing') &&
					pendingCapture.includeSelfWindowAudio
						? await createNativeAudioBridgeWithSelfWindowAudio(captureId)
						: await createNativeAudioBridge(captureId);
				await replaceStreamAudioTrack(stream, handle.track);
				const cleanup = attachNativeAudioCleanup(stream, captureId, handle);
				activeBridge =
					pendingCapture.kind === 'capture' && pendingCapture.winEndpoints
						? {captureId, cleanup, winEndpoints: [...pendingCapture.winEndpoints]}
						: {captureId, cleanup};
				if (previousBridge && previousBridge.captureId !== captureId) {
					supersededBridge = previousBridge;
				}
			} catch (error) {
				logger.warn('Failed to substitute native audio capture into display stream; degrading to video-only', {
					captureId,
					error,
				});
				if (handle) {
					await handle.cleanup(true).catch((cleanupError) => {
						logger.warn('Failed to clean up native audio bridge after substitution failure', {
							captureId,
							error: cleanupError,
						});
					});
				} else if (captureId) {
					await getNativeAudioApi()
						?.stop(captureId)
						.catch((stopError) => {
							logger.warn('Failed to stop native audio capture after substitution failure', {
								captureId,
								error: stopError,
							});
						});
				}
			}
		}
		return stream;
	};
	patched = true;
}

export async function getNativeAudioAvailabilityCached(): Promise<NativeAudioAvailability> {
	if (!isNativeAudioDesktopPlatform()) return unsupportedPlatformAvailability();
	if (!availabilityCache) {
		const nativeAudioApi = getNativeAudioApi();
		availabilityCache = nativeAudioApi
			? nativeAudioApi.getAvailability().catch((error): NativeAudioAvailability => {
					logger.warn('Failed to query native audio availability', {error});
					return {available: false, reason: 'load-failed'};
				})
			: Promise.resolve<NativeAudioAvailability>({available: false, reason: 'unsupported-platform'});
	}
	const availability = await availabilityCache;
	resolvedAvailability = availability;
	if (!availability.available) {
		availabilityCache = null;
	}
	return availability;
}

export function getNativeAudioAvailabilitySnapshot(): NativeAudioAvailability | null {
	if (resolvedAvailability == null) {
		void getNativeAudioAvailabilityCached().catch(() => undefined);
	}
	return resolvedAvailability;
}

function nativeAudioSupportsScope(availability: NativeAudioAvailability, scope: 'process' | 'system'): boolean {
	if (!availability.available) return false;
	return availability.capabilities?.[scope] ?? true;
}

function systemAudioExcludesFluxer(availability: NativeAudioAvailability): boolean {
	if (!availability.available) return false;
	return availability.capabilities?.systemExcludesSelf === true;
}

function rejectUnverifiedSystemSelfExclusion(
	platform: string,
	availability: NativeAudioAvailability,
	context: string,
): void {
	setLastArmFailure({
		platform,
		sourceMode: 'system',
		backend: availability.backend ?? null,
		reason: 'system-audio-self-exclusion-unverified',
		detail: availability.detail ?? null,
	});
	logger.warn(`${context}: self-audio exclusion is not verified`, {availability});
}

async function isNativeAudioAvailable(): Promise<boolean> {
	const availability = await getNativeAudioAvailabilityCached();
	return availability.available;
}

export async function armNativeAudioForNextCapture(sourceId: string): Promise<boolean> {
	const electronApi = getElectronAPI();
	const nativeAudioApi = electronApi?.nativeAudio;
	if (!electronApi || !nativeAudioApi || !isNativeAudioDesktopPlatform()) {
		setLastArmFailure({
			platform: electronApi?.platform,
			sourceId,
			reason: nativeAudioUnavailableReason(electronApi, nativeAudioApi),
		});
		logger.warn('Cannot arm per-window audio capture: not a supported desktop platform', {
			hasElectronApi: Boolean(electronApi),
			hasNativeAudioApi: Boolean(nativeAudioApi),
			platform: electronApi?.platform,
		});
		return false;
	}
	if (!sourceId.startsWith('window:')) {
		setLastArmFailure({platform: electronApi.platform, sourceId, reason: 'source-is-not-window'});
		logger.warn('Cannot arm per-window audio capture: source is not a window', {sourceId});
		return false;
	}
	const availability = await getNativeAudioAvailabilityCached();
	if (!nativeAudioSupportsScope(availability, 'process')) {
		setLastArmFailure({
			platform: electronApi.platform,
			sourceId,
			backend: availability?.backend ?? null,
			reason: availability?.reason ?? 'process-scope-unsupported',
			detail: availability?.detail ?? null,
		});
		logger.warn('Cannot arm per-window audio capture: native audio addon unavailable', {
			sourceId,
			availability,
		});
		return false;
	}
	const targetPid = await nativeAudioApi.resolveAudioRootPidForSource(sourceId);
	if (!targetPid) {
		setLastArmFailure({platform: electronApi.platform, sourceId, reason: 'target-pid-not-resolved'});
		logger.warn('Per-window audio target PID could not be resolved', {sourceId});
		return false;
	}
	if (armedCapture) {
		await stopArmedCapture(armedCapture, 'new per-window capture arm');
		armedCapture = null;
	}
	installPatchIfNeeded();
	if (!patched) {
		setLastArmFailure({
			platform: electronApi.platform,
			sourceId,
			reason: 'display-capture-unavailable',
		});
		logger.warn('Cannot arm per-window audio capture: display capture patch unavailable', {sourceId});
		return false;
	}
	let result: NativeAudioStartResult;
	try {
		result = await nativeAudioApi.start({
			targetPid,
			includeProcessTree:
				electronApi.platform === 'win32' || electronApi.platform === 'darwin' || electronApi.platform === 'linux',
		});
		rememberStartedCapture({
			captureId: result.captureId,
			startedAtMs: Date.now(),
			platform: electronApi.platform,
			sourceMode: 'specific',
			targetPid,
		});
	} catch (error) {
		const detail = getNativeAudioErrorDetail(error);
		setLastArmFailure({
			platform: electronApi.platform,
			sourceId,
			reason: 'native-audio-start-failed',
			detail,
		});
		logger.warn('Cannot arm per-window audio capture; attempting system fallback', {sourceId, targetPid, error});
		if (electronApi.platform === 'win32') {
			const fallback = await armNativeSystemAudioForNextCapture();
			if (fallback) return true;
		}
		return false;
	}
	clearLastArmFailure();
	armedCapture = {
		kind: 'capture',
		captureId: result.captureId,
	};
	return true;
}

export async function armNativeSystemAudioForNextCapture(
	windowsAudio: WindowsDesktopAudioSelection = {all: true, devices: []},
): Promise<boolean> {
	const electronApi = getElectronAPI();
	const nativeAudioApi = electronApi?.nativeAudio;
	const supported = electronApi?.platform === 'darwin' || electronApi?.platform === 'win32';
	if (!electronApi || !supported || !nativeAudioApi) {
		setLastArmFailure({
			platform: electronApi?.platform,
			sourceMode: 'system',
			reason: nativeAudioUnavailableReason(electronApi, nativeAudioApi),
		});
		logger.warn('Cannot arm native system audio capture: native audio API unavailable', {
			hasElectronApi: Boolean(electronApi),
			hasNativeAudioApi: Boolean(nativeAudioApi),
			platform: electronApi?.platform,
		});
		return false;
	}
	const availability = await getNativeAudioAvailabilityCached();
	if (!nativeAudioSupportsScope(availability, 'system')) {
		setLastArmFailure({
			platform: electronApi.platform,
			sourceMode: 'system',
			backend: availability?.backend ?? null,
			reason: availability?.reason ?? 'unavailable',
			detail: availability?.detail ?? null,
		});
		logger.warn('Cannot arm native system audio capture: native audio addon unavailable', {availability});
		return false;
	}
	if (!systemAudioExcludesFluxer(availability)) {
		rejectUnverifiedSystemSelfExclusion(electronApi.platform, availability, 'Cannot arm native system audio capture');
		return false;
	}
	const includeSelfWindowAudio = shouldMixSelfWindowAudioIntoSystemCapture(availability);
	const windowsStart = selectWindowsDesktopAudioStart(windowsAudio, availability);
	if (armedCapture) {
		await stopArmedCapture(armedCapture, 'new system capture arm');
		armedCapture = null;
	}
	installPatchIfNeeded();
	if (!patched) {
		setLastArmFailure({
			platform: electronApi.platform,
			sourceMode: 'system',
			reason: 'display-capture-unavailable',
		});
		logger.warn('Cannot arm native system audio capture: display capture patch unavailable');
		return false;
	}
	let result: NativeAudioStartResult;
	try {
		result = await nativeAudioApi.start({
			includeProcessTree: electronApi.platform !== 'win32',
			...(electronApi.platform === 'darwin'
				? {
						macBackend: 'sck' as const,
						macCaptureScope: 'system' as const,
					}
				: windowsStart),
		});
		rememberStartedCapture({
			captureId: result.captureId,
			startedAtMs: Date.now(),
			platform: electronApi.platform,
			sourceMode: 'system',
			...(electronApi.platform === 'darwin'
				? {
						macBackend: 'sck' as const,
						macCaptureScope: 'system' as const,
					}
				: windowsStart),
			includeSelfWindowAudio,
		});
	} catch (error) {
		const detail = getNativeAudioErrorDetail(error);
		setLastArmFailure({
			platform: electronApi.platform,
			sourceMode: 'system',
			reason: 'native-audio-start-failed',
			detail,
		});
		logger.warn('Cannot arm native system audio capture: native audio start failed', {error});
		return false;
	}
	clearLastArmFailure();
	armedCapture = {
		kind: 'capture',
		captureId: result.captureId,
		includeSelfWindowAudio,
		...(windowsStart.winEndpoints ? {winEndpoints: windowsStart.winEndpoints} : {}),
	};
	if (windowsStart.winEndpoints) {
		void refreshWindowsPlaybackDeviceListing();
	}
	return true;
}

export async function armNativeAudioForLinuxRouting(
	linuxRule: NonNullable<NativeAudioStartOptions['linuxRule']>,
	options: {includeSelfWindowAudio?: boolean} = {},
): Promise<boolean> {
	const electronApi = getElectronAPI();
	const nativeAudioApi = electronApi?.nativeAudio;
	if (electronApi?.platform !== 'linux' || !nativeAudioApi) {
		setLastArmFailure({
			platform: electronApi?.platform,
			reason: nativeAudioUnavailableReason(electronApi, nativeAudioApi),
		});
		logger.warn('Cannot arm Linux native audio capture: native audio API unavailable', {
			hasElectronApi: Boolean(electronApi),
			hasNativeAudioApi: Boolean(nativeAudioApi),
			platform: electronApi?.platform,
		});
		return false;
	}
	if (!(await isNativeAudioAvailable())) {
		const availability = await nativeAudioApi.getAvailability().catch(() => null);
		setLastArmFailure({
			platform: electronApi.platform,
			backend: availability?.backend ?? null,
			reason: availability?.reason ?? 'unavailable',
			detail: availability?.detail ?? null,
		});
		logger.warn('Cannot arm Linux native audio capture: native audio addon unavailable', {availability});
		return false;
	}
	if (armedCapture) {
		await stopArmedCapture(armedCapture, 'new Linux routing capture arm');
		armedCapture = null;
	}
	installPatchIfNeeded();
	if (!patched) {
		setLastArmFailure({
			platform: electronApi.platform,
			sourceMode: linuxRule.include && linuxRule.include.length > 0 ? 'specific' : 'system',
			reason: 'display-capture-unavailable',
		});
		logger.warn('Cannot arm Linux native audio capture: display capture patch unavailable');
		return false;
	}
	armedCapture = {
		kind: 'linux-routing',
		linuxRule,
		includeSelfWindowAudio: options.includeSelfWindowAudio,
	};
	return true;
}

export async function captureNativeAudioTrackForWindowPid(targetPid: number): Promise<MediaStreamTrack | null> {
	const electronApi = getElectronAPI();
	const nativeAudioApi = electronApi?.nativeAudio;
	const supported =
		electronApi?.platform === 'darwin' || electronApi?.platform === 'win32' || electronApi?.platform === 'linux';
	if (!electronApi || !supported || !nativeAudioApi) {
		setLastArmFailure({
			platform: electronApi?.platform,
			sourceMode: 'specific',
			reason: nativeAudioUnavailableReason(electronApi, nativeAudioApi),
		});
		logger.warn('Cannot capture native window audio track: native audio API unavailable', {
			hasElectronApi: Boolean(electronApi),
			hasNativeAudioApi: Boolean(nativeAudioApi),
			platform: electronApi?.platform,
			targetPid,
		});
		return null;
	}
	if (!Number.isInteger(targetPid) || targetPid <= 0) {
		setLastArmFailure({
			platform: electronApi.platform,
			sourceMode: 'specific',
			reason: 'target-pid-not-resolved',
		});
		logger.warn('Cannot capture native window audio track: invalid target PID', {targetPid});
		return null;
	}
	const availability = await getNativeAudioAvailabilityCached();
	if (!nativeAudioSupportsScope(availability, 'process')) {
		setLastArmFailure({
			platform: electronApi.platform,
			sourceMode: 'specific',
			backend: availability?.backend ?? null,
			reason: availability?.reason ?? 'unavailable',
			detail: availability?.detail ?? null,
		});
		logger.warn('Cannot capture native window audio track: native audio addon unavailable for process scope', {
			availability,
			targetPid,
		});
		return null;
	}
	let result: NativeAudioStartResult;
	try {
		result = await nativeAudioApi.start({
			targetPid,
			includeProcessTree: true,
		});
		rememberStartedCapture({
			captureId: result.captureId,
			startedAtMs: Date.now(),
			platform: electronApi.platform,
			sourceMode: 'specific',
			targetPid,
		});
	} catch (error) {
		const detail = getNativeAudioErrorDetail(error);
		const refusedSelf = /Refusing to capture native audio from (?:own|Fluxer) process/.test(detail);
		setLastArmFailure({
			platform: electronApi.platform,
			sourceMode: 'specific',
			reason: refusedSelf ? 'native-audio-refused-self' : 'native-audio-start-failed',
			detail,
		});
		if (refusedSelf) {
			logger.info('Native window audio capture refused for Fluxer-owned process', {targetPid, detail});
		} else {
			logger.warn('Cannot capture native window audio track: native audio start failed', {error, targetPid});
		}
		return null;
	}
	clearLastArmFailure();
	let handle: NativeAudioBridgeHandle | null = null;
	try {
		const previousBridge = activeBridge;
		handle = await createNativeAudioBridge(result.captureId);
		const cleanup = attachNativeAudioCleanup(new MediaStream([handle.track]), result.captureId, handle);
		activeBridge = {captureId: result.captureId, cleanup};
		if (previousBridge && previousBridge.captureId !== result.captureId) {
			supersededBridge = previousBridge;
		}
		return handle.track;
	} catch (error) {
		logger.warn('Failed to create native window audio media track', {
			captureId: result.captureId,
			error,
			targetPid,
		});
		if (handle) {
			await handle.cleanup(true).catch((cleanupError) => {
				logger.warn('Failed to clean up native window audio bridge after track creation failure', {
					captureId: result.captureId,
					error: cleanupError,
				});
			});
		} else {
			await nativeAudioApi.stop(result.captureId).catch((stopError) => {
				logger.warn('Failed to stop native window audio capture after track creation failure', {
					captureId: result.captureId,
					error: stopError,
				});
			});
		}
		setLastArmFailure({
			platform: electronApi.platform,
			sourceMode: 'specific',
			reason: 'native-audio-substitution-failed',
			detail: error instanceof Error ? error.message : String(error),
		});
		return null;
	}
}

export type NativeAudioReconfigureResult = 'unchanged' | 'updated' | 'unsupported';

export async function reconfigureLinuxNativeAudioRouting(
	linuxRule: NonNullable<NativeAudioStartOptions['linuxRule']>,
	options: {includeSelfWindowAudio?: boolean} = {},
): Promise<NativeAudioReconfigureResult> {
	const bridge = activeBridge;
	if (!bridge) return 'unsupported';
	if (bridge.linuxRule === undefined) return 'unsupported';
	if (Boolean(bridge.includeSelfWindowAudio) !== (options.includeSelfWindowAudio === true)) return 'unsupported';
	if (nativeAudioRoutingRulesEqual(bridge.linuxRule, linuxRule)) return 'unchanged';
	const nativeAudioApi = getNativeAudioApi();
	if (typeof nativeAudioApi?.setRule !== 'function') return 'unsupported';
	let applied = false;
	try {
		applied = await nativeAudioApi.setRule(bridge.captureId, linuxRule);
	} catch (error) {
		logger.warn('Failed to reconfigure Linux native audio routing in place', {
			captureId: bridge.captureId,
			error,
		});
		return 'unsupported';
	}
	if (!applied) return 'unsupported';
	if (activeBridge !== bridge) return 'unsupported';
	activeBridge = {...bridge, linuxRule};
	return 'updated';
}

export async function reconfigureWindowsDesktopAudioEndpoints(
	endpoints: Array<string>,
): Promise<NativeAudioReconfigureResult> {
	const bridge = activeBridge;
	if (!bridge?.winEndpoints) return 'unsupported';
	if (windowsEndpointsEqual(bridge.winEndpoints, endpoints)) return 'unchanged';
	const nativeAudioApi = getNativeAudioApi();
	if (typeof nativeAudioApi?.setWinEndpoints !== 'function') return 'unsupported';
	let applied = false;
	try {
		applied = await nativeAudioApi.setWinEndpoints(bridge.captureId, endpoints);
	} catch (error) {
		logger.warn('Failed to change Windows desktop audio devices in place', {
			captureId: bridge.captureId,
			error,
		});
		return 'unsupported';
	}
	if (!applied) return 'unsupported';
	if (activeBridge !== bridge) return 'unsupported';
	activeBridge = {...bridge, winEndpoints: [...endpoints]};
	return 'updated';
}

export function getActiveWindowsDesktopAudioEndpoints(): Array<string> | null {
	return activeBridge?.winEndpoints ? [...activeBridge.winEndpoints] : null;
}

export async function captureNativeAudioTrackForLinuxRouting(
	linuxRule: NonNullable<NativeAudioStartOptions['linuxRule']>,
	options: {includeSelfWindowAudio?: boolean} = {},
): Promise<MediaStreamTrack | null> {
	const result = await startLinuxNativeAudioCapture(linuxRule);
	if (!result) return null;
	let handle: NativeAudioBridgeHandle | null = null;
	try {
		const previousBridge = activeBridge;
		handle = options.includeSelfWindowAudio
			? await createNativeAudioBridgeWithSelfWindowAudio(result.captureId)
			: await createNativeAudioBridge(result.captureId);
		const cleanup = attachNativeAudioCleanup(new MediaStream([handle.track]), result.captureId, handle);
		activeBridge = {
			captureId: result.captureId,
			cleanup,
			linuxRule,
			includeSelfWindowAudio: options.includeSelfWindowAudio === true,
		};
		if (previousBridge && previousBridge.captureId !== result.captureId) {
			supersededBridge = previousBridge;
		}
		return handle.track;
	} catch (error) {
		logger.warn('Failed to create Linux native audio media track', {
			captureId: result.captureId,
			error,
		});
		if (handle) {
			await handle.cleanup(true).catch((cleanupError) => {
				logger.warn('Failed to clean up Linux native audio bridge after track creation failure', {
					captureId: result.captureId,
					error: cleanupError,
				});
			});
		} else {
			await getNativeAudioApi()
				?.stop(result.captureId)
				.catch((stopError) => {
					logger.warn('Failed to stop Linux native audio capture after track creation failure', {
						captureId: result.captureId,
						error: stopError,
					});
				});
		}
		setLastArmFailure({
			platform: 'linux',
			sourceMode: linuxRule.include && linuxRule.include.length > 0 ? 'specific' : 'system',
			reason: 'native-audio-substitution-failed',
			detail: error instanceof Error ? error.message : String(error),
		});
		return null;
	}
}

export function disarmPendingNativeAudio(): void {
	const nativeAudioApi = getNativeAudioApi();
	if (!nativeAudioApi || !armedCapture) {
		armedCapture = null;
		return;
	}
	const capture = armedCapture;
	armedCapture = null;
	void stopArmedCapture(capture, 'pending capture cancellation');
}

export function commitNativeAudioBridgeReplacement(): void {
	const bridge = supersededBridge;
	if (!bridge) return;
	supersededBridge = null;
	cleanupBridgeAsync(bridge, true, 'bridge replacement commit');
}

export function disarmNativeAudio(): void {
	const bridge = activeBridge;
	if (bridge) {
		activeBridge = null;
		cleanupBridgeAsync(bridge, true, 'explicit disarm');
	}
	const previousBridge = supersededBridge;
	if (previousBridge) {
		supersededBridge = null;
		cleanupBridgeAsync(previousBridge, true, 'explicit disarm');
	}
	disarmPendingNativeAudio();
	releaseSelfWindowScreenShareAudioTrack();
}