A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.
// 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();
}