Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
/**
* Platform detection + audio capability matrix.
*
* Used by the upload modal's system-audio path to (a) show platform-
* aware hints / warnings BEFORE the user clicks, (b) route capture
* failures to a contextual help modal, and (c) surface virtual audio
* devices (BlackHole, VB-Cable, Loopback, PulseAudio monitor sources)
* as alternative microphone inputs when the user has installed one.
*
* The capability matrix encodes what browsers / OS combinations can
* actually do — getDisplayMedia({audio:true}) is supported as an API
* everywhere modern, but the underlying OS gates whether system audio
* actually flows through. Only Chrome / Edge on Windows + Chrome OS
* deliver true OS-wide system audio. macOS and Linux Chrome can only
* capture audio when sharing a TAB (chrome.tabCapture-style behaviour
* exposed via getDisplayMedia). Firefox and Safari can't capture any
* audio through getDisplayMedia.
*/
const KNOWN_VIRTUAL_DEVICE_HINTS = [
// macOS
{ match: /blackhole/i, os: 'macOS', name: 'BlackHole' },
{ match: /loopback/i, os: 'macOS', name: 'Loopback' },
{ match: /soundflower/i, os: 'macOS', name: 'Soundflower' },
{ match: /background music/i, os: 'macOS', name: 'Background Music' },
{ match: /existential audio/i, os: 'macOS', name: 'BlackHole' },
// Windows
{ match: /vb[- ]?(audio|cable)/i, os: 'Windows', name: 'VB-Audio Cable' },
{ match: /voicemeeter/i, os: 'Windows', name: 'Voicemeeter' },
{ match: /stereo mix/i, os: 'Windows', name: 'Stereo Mix' },
{ match: /what u hear/i, os: 'Windows', name: 'What U Hear' },
// Linux
{ match: /monitor of /i, os: 'Linux', name: 'PulseAudio Monitor' },
{ match: /monitor source/i, os: 'Linux', name: 'PulseAudio Monitor' },
{ match: /pipewire.*monitor/i, os: 'Linux', name: 'PipeWire Monitor' },
{ match: /pulse.*monitor/i, os: 'Linux', name: 'PulseAudio Monitor' },
];
const EXTERNAL_INPUT_LABEL_HINT = /\b(?:usb|external|wireless|bluetooth|headset|receiver|webcam|camera|audio interface|audio codec)\b/i;
const INTERNAL_INPUT_LABEL_HINT = /\b(?:built[- ]?in|internal|phone|handset|microphone array|bottom mic|top mic|front mic|rear mic)\b/i;
const GENERIC_INPUT_LABEL = /^(?:default|communications|microphone(?:\s*\d+)?|earpiece|headset earpiece|speakerphone)$/i;
function findVirtualDeviceHint(label) {
if (!label) return null;
return KNOWN_VIRTUAL_DEVICE_HINTS.find(hint => hint.match.test(label)) || null;
}
export function isVirtualAudioDeviceLabel(label) {
return !!findVirtualDeviceHint(label);
}
export function normalizeAudioInputDevices(devices = []) {
return devices
.filter(device => device && (!device.kind || device.kind === 'audioinput'))
.map(device => ({
kind: 'audioinput',
deviceId: device.deviceId || '',
label: device.label || '',
groupId: device.groupId || '',
isVirtual: isVirtualAudioDeviceLabel(device.label || '')
}));
}
export function findExternalAudioInputCandidates(devices = [], activeDeviceId = '') {
const inputs = normalizeAudioInputDevices(devices);
const active = inputs.find(device => device.deviceId === activeDeviceId) || null;
return inputs.filter(device => {
if (!device.deviceId || !device.label || device.isVirtual) return false;
if (device.deviceId === activeDeviceId) return false;
if (device.deviceId === 'default' || device.deviceId === 'communications') return false;
if (GENERIC_INPUT_LABEL.test(device.label) || INTERNAL_INPUT_LABEL_HINT.test(device.label)) return false;
// Positive label-hint matches only. A bare "different groupId"
// fallback was tried here and over-triggered badly: the
// internal/generic exclusion regexes are English-only, so on
// non-English devices internal routes (earpiece, speakerphone)
// escape them and every phone would prompt about its own built-in
// inputs. Requiring an explicit external hint keeps the prompt
// conservative; users can always open the device panel manually.
return EXTERNAL_INPUT_LABEL_HINT.test(device.label);
});
}
export function getAudioInputCandidateSignature(devices = []) {
return devices
.map(device => device?.deviceId || '')
.filter(Boolean)
.sort()
.join('|');
}
/**
* Inspect the current user agent + platform string and return a small
* normalized descriptor used everywhere else in the audio capture flow.
* Cheap, sync, safe to call repeatedly.
*/
export function detectPlatform() {
if (typeof navigator === 'undefined') {
return { os: 'unknown', browser: 'unknown' };
}
const ua = navigator.userAgent || '';
const platform = (navigator.userAgentData?.platform || navigator.platform || '').toLowerCase();
let os = 'unknown';
if (/iphone|ipad|ipod/i.test(ua) || (/mac/.test(platform) && navigator.maxTouchPoints > 1)) {
os = 'iOS';
} else if (/mac/i.test(platform) || /mac os x/i.test(ua)) {
os = 'macOS';
} else if (/win/i.test(platform) || /windows/i.test(ua)) {
os = 'Windows';
} else if (/cros|chrome os/i.test(ua) || /cros/i.test(platform)) {
os = 'ChromeOS';
} else if (/android/i.test(ua)) {
os = 'Android';
} else if (/linux/i.test(platform) || /linux/i.test(ua)) {
os = 'Linux';
}
let browser = 'unknown';
// Order matters: Edge UA contains "Chrome", so check Edge first.
if (/edg(e|ios|a)?\//i.test(ua)) browser = 'Edge';
else if (/firefox|fxios/i.test(ua)) browser = 'Firefox';
else if (/chrome|crios/i.test(ua)) browser = 'Chrome';
else if (/safari/i.test(ua)) browser = 'Safari';
else if (/opera|opr\//i.test(ua)) browser = 'Opera';
return { os, browser };
}
export function shouldAutoOfferExternalAudioInput(platform = detectPlatform()) {
return platform?.os === 'Android' || platform?.os === 'iOS';
}
/**
* Returns a structured capability report describing what audio capture
* is realistically available on the current browser + OS — for use by
* the UI to show pre-emptive hints and to know whether to route a
* failed capture to the help modal.
*
* Flags:
* - supportsGetUserMedia: classic microphone capture
* - supportsGetDisplayMedia: the API exists at all
* - supportsTabAudio: getDisplayMedia({audio:true}) is expected to
* deliver audio when the user picks "Share tab"
* - supportsWindowAudio: ... when picking a window
* - supportsSystemAudio: ... full OS-wide audio (Windows / ChromeOS
* only via the "Share system audio" checkbox)
* - virtualDeviceHint: a string the help modal can show — name of the
* virtual audio routing tool that's idiomatic on this OS
*/
export function getAudioCapabilities() {
const p = detectPlatform();
const hasGUM = typeof navigator !== 'undefined'
&& navigator.mediaDevices
&& typeof navigator.mediaDevices.getUserMedia === 'function';
const hasGDM = typeof navigator !== 'undefined'
&& navigator.mediaDevices
&& typeof navigator.mediaDevices.getDisplayMedia === 'function';
let supportsTabAudio = false;
let supportsWindowAudio = false;
let supportsSystemAudio = false;
let virtualDeviceHint = null;
if (hasGDM) {
// Firefox: getDisplayMedia({audio:true}) returns a stream but no
// audio track on any platform. Effectively no audio capture.
if (p.browser === 'Firefox') {
// intentionally all false
}
// Safari: same story
else if (p.browser === 'Safari') {
// intentionally all false
}
// Chrome / Edge: matrix below
else if (p.browser === 'Chrome' || p.browser === 'Edge') {
supportsTabAudio = true;
if (p.os === 'Windows' || p.os === 'ChromeOS') {
supportsWindowAudio = true;
supportsSystemAudio = true;
}
// macOS / Linux: only tab audio works in practice.
}
}
if (p.os === 'macOS') virtualDeviceHint = 'BlackHole';
if (p.os === 'Windows') virtualDeviceHint = 'VB-Audio Cable';
if (p.os === 'Linux') virtualDeviceHint = 'PulseAudio monitor source';
return {
platform: p,
supportsGetUserMedia: hasGUM,
supportsGetDisplayMedia: hasGDM,
supportsTabAudio,
supportsWindowAudio,
supportsSystemAudio,
virtualDeviceHint,
};
}
/**
* Scan enumerateDevices() for installed virtual audio routing devices.
* Returns an array of { deviceId, label, virtualToolName, os } entries
* that the upload UI can surface as alternative microphone inputs (the
* user routes system audio through them and then captures via the
* regular microphone path).
*
* Returns [] when permission hasn't been granted yet (labels are blank
* pre-permission, so we can't pattern-match). The UI should retry this
* after the user grants mic permission once.
*/
export async function enumerateVirtualAudioDevices() {
if (typeof navigator === 'undefined'
|| !navigator.mediaDevices
|| typeof navigator.mediaDevices.enumerateDevices !== 'function') {
return [];
}
let devices;
try {
devices = await navigator.mediaDevices.enumerateDevices();
} catch (_) {
return [];
}
const inputs = normalizeAudioInputDevices(devices).filter(d => d.label);
const matches = [];
for (const d of inputs) {
const hint = findVirtualDeviceHint(d.label);
if (hint) {
matches.push({
deviceId: d.deviceId,
label: d.label,
virtualToolName: hint.name,
os: hint.os,
});
}
}
return matches;
}