Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.
JavaScript aianthropiccross-platformgeminigroqlinuxmacosnvidiaopen-sourceopenaiparakeetspeech-to-texttranscribewhisperwindows
const https = require("https");
const http = require("http");
const dns = require("dns");
const { isIP } = require("net");
// Namespaced (not destructured) so tests can monkeypatch childProcess.spawn.
const childProcess = require("child_process");
const crypto = require("crypto");
const fs = require("fs");
const os = require("os");
const path = require("path");
const debugLogger = require("./debugLogger");
const { getSafeTempDir } = require("./safeTempDir");
const { getFFmpegPath } = require("./ffmpegUtils");
const YOUTUBE_HOSTS = new Set([
"youtube.com",
"www.youtube.com",
"m.youtube.com",
"music.youtube.com",
"youtu.be",
]);
const STALL_TIMEOUT_MS = 30_000;
const CONNECT_TIMEOUT_MS = 30_000;
const MAX_DOWNLOAD_BYTES = 500 * 1024 * 1024;
const MAX_REDIRECTS = 3;
// Reject absurdly long videos before downloading.
const MAX_DURATION_SECONDS = 6 * 60 * 60;
const USER_AGENT = "OpenWhispr/1.0";
// Writable yt-dlp cache, seeded from the read-only bundle so the binary can
// self-update (the bundled copy is read-only / inside the signed bundle).
// OPENWHISPR_YTDLP_CACHE_DIR overrides the location (relocate it, or isolate it in tests).
const YT_DLP_CACHE_DIR =
process.env.OPENWHISPR_YTDLP_CACHE_DIR ||
path.join(os.homedir(), ".cache", "openwhispr", "yt-dlp");
const YT_DLP_UPDATE_THROTTLE_MS = 24 * 60 * 60 * 1000;
// Bound the self-update so a stalled GitHub request can never hang a download
// or wedge the single-flight flag. Overridable via options.timeoutMs for tests.
const UPDATE_TIMEOUT_MS = 120_000;
// Absolute ceilings on yt-dlp runs so a wedged process can never hang a queue item.
const YT_DLP_METADATA_TIMEOUT_MS = 2 * 60 * 1000;
const YT_DLP_EXTRACTION_TIMEOUT_MS = 30 * 60 * 1000;
let ytDlpUpdateInFlight = false;
let ytDlpBusyCount = 0;
// Decode the IPv4 embedded in the trailing 32 bits of a NAT64 (64:ff9b::/96) address.
// Handles "::" compression; returns dotted IPv4 or null.
function nat64EmbeddedV4(lowerAddr) {
const parts = lowerAddr.split("::");
const head = parts[0].split(":").filter(Boolean);
const tail = parts.length > 1 ? parts[1].split(":").filter(Boolean) : [];
let groups;
if (parts.length > 1) {
const missing = 8 - head.length - tail.length;
if (missing < 0) return null;
groups = [...head, ...Array(missing).fill("0"), ...tail];
} else {
groups = head;
}
if (groups.length !== 8) return null;
const g6 = parseInt(groups[6], 16);
const g7 = parseInt(groups[7], 16);
if (Number.isNaN(g6) || Number.isNaN(g7)) return null;
return `${(g6 >> 8) & 0xff}.${g6 & 0xff}.${(g7 >> 8) & 0xff}.${g7 & 0xff}`;
}
function isPrivateIp(ip) {
if (ip === "::1" || ip === "::") return true;
if (isIP(ip) === 4) {
const parts = ip.split(".").map(Number);
if (parts[0] === 0) return true;
if (parts[0] === 127) return true;
if (parts[0] === 10) return true;
if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) return true;
if (parts[0] === 192 && parts[1] === 168) return true;
if (parts[0] === 169 && parts[1] === 254) return true;
if (parts[0] === 100 && parts[1] >= 64 && parts[1] <= 127) return true;
if (parts[0] >= 224) return true;
return false;
}
if (isIP(ip) === 6) {
const lower = ip.toLowerCase();
// NAT64 well-known prefix embeds an IPv4 in the trailing 32 bits.
// Match zero-padded first hextet too ("0064:ff9b" == "64:ff9b").
if (isNat64Prefix(lower)) {
const dottedTail = lower.match(/(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
if (dottedTail) return isPrivateIp(dottedTail[1]);
const embedded = nat64EmbeddedV4(lower);
if (embedded) return isPrivateIp(embedded);
return false;
}
if (lower.startsWith("fc") || lower.startsWith("fd")) return true;
// Link-local is fe80::/10 (fe80–febf), not just the literal fe80 hextet.
if (/^fe[89ab]/.test(lower)) return true;
if (lower.startsWith("ff")) return true;
const v4mapped = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
if (v4mapped) return isPrivateIp(v4mapped[1]);
const v4compat = lower.match(/^::(\d+\.\d+\.\d+\.\d+)$/);
if (v4compat) return isPrivateIp(v4compat[1]);
const v4mappedHex = lower.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
if (v4mappedHex) {
const hi = parseInt(v4mappedHex[1], 16);
const lo = parseInt(v4mappedHex[2], 16);
const dotted = `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
return isPrivateIp(dotted);
}
// Fully-expanded / zero-padded v4-mapped form "<all-zero groups>:ffff:HHHH:HHHH"
// (e.g. "0:0:0:0:0:ffff:7f00:1"). The leading [0:]+ ensures only zeros precede ffff.
const v4mappedExpanded = lower.match(/^[0:]+:ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
if (v4mappedExpanded) {
const hi = parseInt(v4mappedExpanded[1], 16);
const lo = parseInt(v4mappedExpanded[2], 16);
const dotted = `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
return isPrivateIp(dotted);
}
// Same expanded form but with a dotted IPv4 tail (e.g. "0:0:0:0:0:ffff:127.0.0.1").
const v4mappedExpandedDotted = lower.match(/^[0:]+:ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
if (v4mappedExpandedDotted) {
return isPrivateIp(v4mappedExpandedDotted[1]);
}
return false;
}
return false;
}
// True when the first two hextets are the NAT64 well-known prefix 64:ff9b,
// tolerating zero-padding ("0064:ff9b").
function isNat64Prefix(lower) {
const head = lower.split("::")[0].split(":");
if (head.length < 2) return false;
const h0 = head[0].replace(/^0+/, "") || "0";
const h1 = head[1].replace(/^0+/, "") || "0";
return h0 === "64" && h1 === "ff9b";
}
// Unified accept gate for HEAD and GET so the two stages can never disagree.
function isAcceptableAudioContentType(contentType) {
const ct = (contentType || "").toLowerCase();
return ct.startsWith("audio/") || ct.startsWith("video/");
}
// autoSelectFamily/Happy Eyeballs (default on Node 18+) calls lookup with
// { all: true }, so dns.lookup yields an ARRAY of { address, family }. Reject if
// ANY resolved entry is private; forward the original value unchanged on success.
function ssrfSafeLookup(hostname, options, callback) {
dns.lookup(hostname, options, (err, address, family) => {
if (err) return callback(err);
const entries = Array.isArray(address) ? address : [{ address, family }];
for (const e of entries) {
if (isPrivateIp(e.address)) {
return callback(
Object.assign(
new Error("Direct downloads from private/internal addresses are not allowed"),
{ code: "SSRF_BLOCKED" }
)
);
}
}
callback(null, address, family);
});
}
function firstHeaderValue(headers, name) {
const raw = headers[name];
return Array.isArray(raw) ? raw[0] : raw;
}
function detectUrlType(urlString) {
if (!urlString || typeof urlString !== "string") {
const err = new Error("Invalid URL");
err.code = "INVALID_URL";
throw err;
}
let parsed;
try {
parsed = new URL(urlString);
} catch {
const err = new Error(`Invalid URL: ${urlString}`);
err.code = "INVALID_URL";
throw err;
}
if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
const err = new Error(`Unsupported protocol: ${parsed.protocol}`);
err.code = "INVALID_URL";
throw err;
}
const host = parsed.hostname.toLowerCase();
if (YOUTUBE_HOSTS.has(host)) {
return "youtube";
}
return "direct";
}
function extractYouTubeVideoId(urlString) {
let parsed;
try {
parsed = new URL(urlString);
} catch {
return null;
}
const host = parsed.hostname.toLowerCase();
if (host === "youtu.be") {
const id = parsed.pathname.slice(1).split("/")[0];
if (id && /^[A-Za-z0-9_-]{11}$/.test(id)) return id;
return null;
}
if (YOUTUBE_HOSTS.has(host)) {
const watchId = parsed.searchParams.get("v");
if (watchId && /^[A-Za-z0-9_-]{11}$/.test(watchId)) return watchId;
const pathMatch = parsed.pathname.match(/^\/(shorts|embed|live)\/([a-zA-Z0-9_-]{11})/);
if (pathMatch) return pathMatch[2];
}
return null;
}
function isPlaylistUrl(urlString) {
try {
const parsed = new URL(urlString);
const host = parsed.hostname.toLowerCase();
if (!YOUTUBE_HOSTS.has(host)) return false;
return parsed.pathname === "/playlist" && parsed.searchParams.has("list");
} catch {
return false;
}
}
function createStallChecker(onStall) {
let lastDataTime = Date.now();
const interval = setInterval(() => {
if (Date.now() - lastDataTime > STALL_TIMEOUT_MS) {
clearInterval(interval);
onStall();
}
}, 5_000);
return {
touch() {
lastDataTime = Date.now();
},
clear() {
clearInterval(interval);
},
};
}
function ytDlpBinaryName() {
return `yt-dlp-${process.platform}-${process.arch}${process.platform === "win32" ? ".exe" : ""}`;
}
// Resolve the bundled yt-dlp sidecar binary. Mirrors whisper.js resolution.
function resolveYtDlpPath() {
const name = ytDlpBinaryName();
const candidates = [];
if (process.resourcesPath) {
candidates.push(path.join(process.resourcesPath, "bin", name));
}
candidates.push(path.join(__dirname, "..", "..", "resources", "bin", name));
return candidates.find((p) => fs.existsSync(p)) || null;
}
// Path to the writable (self-updating) yt-dlp copy. Same basename as the bundle.
function getCacheYtDlpPath() {
return path.join(YT_DLP_CACHE_DIR, ytDlpBinaryName());
}
function sha256File(p) {
return crypto.createHash("sha256").update(fs.readFileSync(p)).digest("hex");
}
// Trust anchors: the signed app bundle (seed) and yt-dlp's SUMS-verified self-update.
function recordCacheChecksum() {
try {
const cachePath = getCacheYtDlpPath();
fs.writeFileSync(`${cachePath}.sha256`, sha256File(cachePath));
verifiedCacheStat = null;
} catch (e) {
debugLogger.warn("Failed to record yt-dlp cache checksum", { error: e.message });
}
}
// The cache dir is user-writable; verify before executing. Mismatch discards the
// copy so the next download re-seeds from the signed bundle. Hashing the ~40 MB
// binary blocks the main process, so remember the last verified (mtime, size) —
// an attacker who could forge those could also rewrite the sibling .sha256, so
// the memo adds no new trust.
let verifiedCacheStat = null;
function cacheChecksumValid(cachePath) {
try {
const st = fs.statSync(cachePath);
if (
verifiedCacheStat &&
verifiedCacheStat.path === cachePath &&
verifiedCacheStat.mtimeMs === st.mtimeMs &&
verifiedCacheStat.size === st.size
) {
return true;
}
const expected = fs.readFileSync(`${cachePath}.sha256`, "utf8").trim();
if (expected && expected === sha256File(cachePath)) {
verifiedCacheStat = { path: cachePath, mtimeMs: st.mtimeMs, size: st.size };
return true;
}
} catch {}
verifiedCacheStat = null;
try {
fs.unlinkSync(cachePath);
} catch {}
try {
fs.unlinkSync(`${cachePath}.sha256`);
} catch {}
debugLogger.warn("yt-dlp cache failed checksum verification; discarded", { cachePath });
return false;
}
// Best-effort: copy the bundled binary into the writable cache on first use.
// Never throws — callers fall back to the bundled copy.
function seedYtDlpFromBundle() {
let tempPath;
try {
const cachePath = getCacheYtDlpPath();
if (fs.existsSync(cachePath)) return;
const bundled = resolveYtDlpPath();
if (!bundled) return;
fs.mkdirSync(YT_DLP_CACHE_DIR, { recursive: true, mode: 0o700 });
try {
fs.chmodSync(YT_DLP_CACHE_DIR, 0o700);
} catch {}
// Atomic seed: copy to a temp path, chmod, then rename so a crash mid-copy
// can never leave a truncated cache binary that would fail to spawn.
tempPath = `${cachePath}.tmp-${process.pid}`;
fs.copyFileSync(bundled, tempPath);
fs.chmodSync(tempPath, 0o755);
fs.renameSync(tempPath, cachePath);
recordCacheChecksum();
} catch (e) {
if (tempPath) {
try {
fs.unlinkSync(tempPath);
} catch {}
}
debugLogger.warn("Failed to seed yt-dlp from bundle", { error: e.message });
}
}
function isExecutableFile(p) {
if (process.platform === "win32") return fs.existsSync(p);
try {
fs.accessSync(p, fs.constants.X_OK);
return true;
} catch {
return false;
}
}
// Checksum-verified cache copy, else bundled binary, else null. During an update
// swap, prefer the bundle so we never spawn a half-replaced file.
function resolveYtDlpBinary() {
if (ytDlpUpdateInFlight) {
const bundled = resolveYtDlpPath();
if (bundled) return bundled;
}
const cachePath = getCacheYtDlpPath();
if (fs.existsSync(cachePath) && isExecutableFile(cachePath) && cacheChecksumValid(cachePath)) {
return cachePath;
}
return resolveYtDlpPath();
}
// Wrap runYtDlp so maybeUpdateYtDlp can skip while a download holds the binary.
async function runYtDlpTracked(binaryPath, args, abortSignal, timeoutMs, onOutput) {
ytDlpBusyCount += 1;
try {
return await runYtDlp(binaryPath, args, abortSignal, timeoutMs, onOutput);
} finally {
ytDlpBusyCount -= 1;
}
}
// Throttled, single-flight, best-effort background self-update of the CACHE copy
// only (never the bundled binary). Never throws/rejects to the caller.
function maybeUpdateYtDlp({ force, abortSignal, timeoutMs } = {}) {
return new Promise((resolve) => {
const stampPath = path.join(YT_DLP_CACHE_DIR, ".last-update");
const touchStamp = () => {
try {
fs.mkdirSync(YT_DLP_CACHE_DIR, { recursive: true, mode: 0o700 });
fs.writeFileSync(stampPath, String(Date.now()));
} catch {}
};
try {
if (ytDlpUpdateInFlight) return resolve();
if (ytDlpBusyCount > 0) return resolve();
if (!force) {
try {
const st = fs.statSync(stampPath);
if (Date.now() - st.mtimeMs < YT_DLP_UPDATE_THROTTLE_MS) return resolve();
} catch {}
}
seedYtDlpFromBundle();
const cacheBinary = getCacheYtDlpPath();
if (!fs.existsSync(cacheBinary)) return resolve();
// Never execute (or later bless) a tampered copy: verify first; a failed
// check discards the copy, so reseed from the signed bundle and re-verify.
if (!cacheChecksumValid(cacheBinary)) {
seedYtDlpFromBundle();
if (!fs.existsSync(cacheBinary) || !cacheChecksumValid(cacheBinary)) return resolve();
}
ytDlpUpdateInFlight = true;
let child;
try {
// Nightly: upstream calls stable "prone to external breakage"; the updater
// self-verifies against the release's SHA2-256SUMS.
child = childProcess.spawn(cacheBinary, ["--update-to", "nightly"], { windowsHide: true });
} catch (e) {
ytDlpUpdateInFlight = false;
debugLogger.warn("yt-dlp self-update failed to start", { error: e.message });
touchStamp();
return resolve();
}
// Drain stdio so the child never blocks on a full pipe buffer.
if (child.stdout) child.stdout.on("data", () => {});
if (child.stderr) child.stderr.on("data", () => {});
// Bounded kill timer so a stalled -U network request can never hang.
const limit = typeof timeoutMs === "number" ? timeoutMs : UPDATE_TIMEOUT_MS;
let killTimer = null;
let onAbort = null;
let done = false;
// Always clears the timer/listener, resets the in-flight flag, stamps the
// throttle, and resolves — never rejects (best-effort contract).
const finish = (errMessage) => {
if (done) return;
done = true;
if (killTimer) clearTimeout(killTimer);
if (onAbort && abortSignal) abortSignal.removeEventListener("abort", onAbort);
ytDlpUpdateInFlight = false;
if (errMessage) debugLogger.warn("yt-dlp self-update error", { error: errMessage });
touchStamp();
resolve();
};
killTimer = setTimeout(() => {
try {
child.kill("SIGKILL");
} catch {}
finish("yt-dlp -U timed out");
}, limit);
if (abortSignal) {
if (abortSignal.aborted) {
try {
child.kill("SIGKILL");
} catch {}
return finish(null);
}
onAbort = () => {
try {
child.kill("SIGKILL");
} catch {}
finish(null);
};
abortSignal.addEventListener("abort", onAbort, { once: true });
}
child.on("error", (err) => finish(err.message));
child.on("close", (code) => {
// Only a successful update may move the trust anchor; a failed or killed
// run leaves the previously verified binary (and checksum) in place.
if (code === 0) recordCacheChecksum();
finish(null);
});
} catch (e) {
ytDlpUpdateInFlight = false;
debugLogger.warn("yt-dlp self-update unexpected error", { error: e.message });
resolve();
}
});
}
// Resolve the OS/corporate proxy for a target URL via Electron. Returns a proxy
// URL string (e.g. "http://host:port") or null for DIRECT / when unavailable.
async function resolveProxyForUrl(targetUrl) {
let session;
try {
({ session } = require("electron"));
} catch {
return null;
}
if (
!session ||
!session.defaultSession ||
typeof session.defaultSession.resolveProxy !== "function"
) {
return null;
}
let result;
try {
result = await session.defaultSession.resolveProxy(targetUrl);
} catch (e) {
debugLogger.warn("resolveProxy failed; falling back to direct", { error: e.message });
return null;
}
return parseProxyResult(result);
}
function parseProxyResult(result) {
if (!result || typeof result !== "string") return null;
const first = result.split(";")[0].trim();
if (!first || first.toUpperCase() === "DIRECT") return null;
const [scheme, hostPort] = first.split(/\s+/);
if (!hostPort) return null;
const s = scheme.toUpperCase();
let proto;
if (s === "PROXY") proto = "http";
else if (s === "HTTPS") proto = "https";
else if (s === "SOCKS" || s === "SOCKS5") proto = "socks5";
else if (s === "SOCKS4") proto = "socks4";
else return null;
return `${proto}://${hostPort}`;
}
function deriveTitleAndExt(urlPath) {
const extMatch = urlPath.match(/\.([a-zA-Z0-9]{2,5})$/);
const ext = extMatch ? extMatch[1] : "audio";
const fileName = path.basename(urlPath, `.${ext}`) || "audio";
let title;
try {
title = decodeURIComponent(fileName).replace(/[_-]+/g, " ");
} catch {
title = fileName.replace(/[_-]+/g, " ");
}
return { title, ext };
}
// Reject hostnames that resolve (or already are) a private/internal address.
// Defense-in-depth pre-flight for the proxy path.
function assertPublicHost(hostname) {
return new Promise((resolve, reject) => {
const raw = hostname.replace(/^\[|\]$/g, "");
if (isIP(raw)) {
if (isPrivateIp(raw)) {
return reject(
Object.assign(
new Error("Direct downloads from private/internal addresses are not allowed"),
{ code: "SSRF_BLOCKED" }
)
);
}
return resolve();
}
dns.lookup(raw, { all: true }, (err, addresses) => {
if (err) {
return reject(
Object.assign(new Error(`DNS lookup failed: ${err.message}`), { code: "DOWNLOAD_FAILED" })
);
}
for (const a of addresses) {
if (isPrivateIp(a.address)) {
return reject(
Object.assign(
new Error("Direct downloads from private/internal addresses are not allowed"),
{ code: "SSRF_BLOCKED" }
)
);
}
}
resolve();
});
});
}
// yt-dlp needs an external JS runtime for YouTube player challenges. Reuse the
// app's Electron binary in Node mode; the env var is inherited by yt-dlp's child.
function jsRuntimeSpawnConfig() {
return {
args: ["--js-runtimes", `node:${process.execPath}`],
env: { ...process.env, ELECTRON_RUN_AS_NODE: "1" },
};
}
// Kill yt-dlp AND its subprocesses (ffmpeg postprocessor, node JS-runtime):
// the detached process group on Unix, taskkill /T on Windows — a plain kill on
// the parent orphans them mid-download.
function killYtDlpTree(child, signal) {
if (process.platform === "win32" && child.pid) {
try {
childProcess.spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
windowsHide: true,
});
return;
} catch {}
}
if (child.pid) {
try {
process.kill(-child.pid, signal);
return;
} catch {}
}
try {
child.kill(signal);
} catch {}
}
// Spawn the yt-dlp sidecar, capture stdout/stderr, honor abort and a hard timeout.
function runYtDlp(binaryPath, args, abortSignal, timeoutMs, onOutput) {
return new Promise((resolve, reject) => {
if (abortSignal?.aborted) {
reject(Object.assign(new Error("Download cancelled"), { code: "DOWNLOAD_CANCELLED" }));
return;
}
const runtime = jsRuntimeSpawnConfig();
let child;
try {
child = childProcess.spawn(binaryPath, [...runtime.args, ...args], {
windowsHide: true,
env: runtime.env,
detached: process.platform !== "win32",
});
} catch (e) {
reject(
Object.assign(new Error(e.message || "Failed to start yt-dlp"), { code: "DOWNLOAD_FAILED" })
);
return;
}
let stdout = "";
let stderr = "";
let aborted = false;
let timedOut = false;
const onAbort = () => {
aborted = true;
killYtDlpTree(child, "SIGTERM");
};
if (abortSignal) abortSignal.addEventListener("abort", onAbort, { once: true });
const killTimer = timeoutMs
? setTimeout(() => {
timedOut = true;
killYtDlpTree(child, "SIGKILL");
}, timeoutMs)
: null;
child.stdout.on("data", (d) => {
const text = d.toString();
stdout += text;
onOutput?.(text);
});
child.stderr.on("data", (d) => {
stderr += d.toString();
});
const cleanup = () => {
if (killTimer) clearTimeout(killTimer);
if (abortSignal) abortSignal.removeEventListener("abort", onAbort);
};
child.on("error", (err) => {
cleanup();
reject(
Object.assign(new Error(err.message || "yt-dlp failed to run"), { code: "DOWNLOAD_FAILED" })
);
});
child.on("close", (code) => {
cleanup();
if (aborted || abortSignal?.aborted) {
reject(Object.assign(new Error("Download cancelled"), { code: "DOWNLOAD_CANCELLED" }));
return;
}
if (timedOut) {
reject(Object.assign(new Error("yt-dlp timed out"), { code: "DOWNLOAD_FAILED", stderr }));
return;
}
if (code !== 0) {
reject(
Object.assign(new Error(stderr.trim() || `yt-dlp exited with code ${code}`), {
code: "DOWNLOAD_FAILED",
stderr,
})
);
return;
}
resolve({ stdout, stderr });
});
});
}
// Heuristic: yt-dlp stderr/message that smells like a stale extractor (YouTube
// changed its player and a newer yt-dlp is needed). Drives the self-heal retry.
function looksLikeStaleExtractor(message) {
return /unable to extract|nsig|signature|player|sig extraction|failed to extract|update yt-dlp|confirm.*latest version|please report/i.test(
message || ""
);
}
// YouTube refusing this network/IP (bot checks, 403s, login walls) — transient,
// hits even fully-updated clients.
function looksLikeYouTubeBlock(message) {
return /sign in to confirm|not a bot|login_required|http error 403|403 forbidden|sabr/i.test(
message || ""
);
}
// Single self-heal retry: on stale-extractor failures, force-update and retry once.
async function runYtDlpWithSelfHeal(binary, args, abortSignal, timeoutMs, onBeforeRetry, onOutput) {
try {
return await runYtDlpTracked(binary, args, abortSignal, timeoutMs, onOutput);
} catch (e) {
if (e.code === "DOWNLOAD_CANCELLED") throw e;
const text = `${e.message || ""} ${e.stderr || ""}`;
if (!looksLikeStaleExtractor(text)) throw e;
onBeforeRetry?.();
await maybeUpdateYtDlp({ force: true, abortSignal });
return runYtDlpTracked(resolveYtDlpBinary() || binary, args, abortSignal, timeoutMs, onOutput);
}
}
// Startup sweep for orphans left by crashes or windows closed mid-download;
// live downloads are protected by the age cutoff.
function sweepStaleTempArtifacts(maxAgeMs = 24 * 60 * 60 * 1000) {
try {
const tempDir = getSafeTempDir();
const cutoff = Date.now() - maxAgeMs;
for (const f of fs.readdirSync(tempDir)) {
if (!f.startsWith("ow-url-") && !f.startsWith("ow-diarize-")) continue;
const p = path.join(tempDir, f);
try {
if (fs.statSync(p).mtimeMs < cutoff) fs.unlinkSync(p);
} catch {}
}
} catch {}
}
// Remove any temp artifacts produced for a given base path. Best-effort.
function cleanupTempArtifacts(tempBase) {
try {
const tempDir = getSafeTempDir();
const prefix = path.basename(tempBase);
for (const f of fs.readdirSync(tempDir).filter((f) => f.startsWith(prefix))) {
try {
fs.unlinkSync(path.join(tempDir, f));
} catch {}
}
} catch {}
}
const YT_DLP_AUDIO_EXTENSIONS = new Set([
"m4a",
"mp3",
"opus",
"webm",
"ogg",
"wav",
"aac",
"flac",
]);
// Select the finished audio file yt-dlp left for `prefix`, delete every other
// prefix-matched file (transient scratch files included), return its absolute path.
function selectYtDlpOutput(tempDir, prefix) {
const all = fs.readdirSync(tempDir).filter((f) => f.startsWith(prefix));
let best = null;
for (const name of all) {
// Match on the lowercased suffix after the prefix so the video id can never
// trip an artifact pattern; yt-dlp writes these scratch suffixes lowercase.
const rest = name.slice(prefix.length).toLowerCase();
const isTransient =
/-frag\d+/.test(rest) ||
/\.(part|ytdl|aria2|meta)$/.test(rest) ||
rest.endsWith(".temp") ||
rest.includes(".temp.") ||
rest.includes(".orig.");
if (isTransient) continue;
let mtimeMs;
try {
mtimeMs = fs.statSync(path.join(tempDir, name)).mtimeMs;
} catch {
continue; // vanished between readdir and stat
}
const knownAudio = YT_DLP_AUDIO_EXTENSIONS.has(path.extname(name).slice(1).toLowerCase());
const tier = knownAudio ? (/\.f\d+\./.test(rest) ? 1 : 0) : 2;
if (!best || tier < best.tier || (tier === best.tier && mtimeMs > best.mtimeMs)) {
best = { name, tier, mtimeMs };
}
}
if (!best) {
const err = new Error("Download produced no output");
err.code = "DOWNLOAD_FAILED";
throw err;
}
for (const f of all) {
if (f === best.name) continue;
try {
fs.unlinkSync(path.join(tempDir, f));
} catch {}
}
return path.join(tempDir, best.name);
}
async function downloadYouTube(url, onProgress, abortSignal) {
seedYtDlpFromBundle();
const binary = resolveYtDlpBinary();
if (!binary) {
const err = new Error("yt-dlp binary not found in resources/bin");
err.code = "DOWNLOAD_FAILED";
throw err;
}
// yt-dlp's -x post-processor needs ffmpeg, which is not on PATH in packaged builds.
const ffmpegPath = getFFmpegPath();
if (!ffmpegPath) {
const err = new Error("FFmpeg not found — required for YouTube audio extraction");
err.code = "DOWNLOAD_FAILED";
throw err;
}
const ffmpegDir = path.dirname(ffmpegPath);
const parsedUrl = new URL(url);
if (parsedUrl.protocol !== "https:") {
parsedUrl.protocol = "https:";
url = parsedUrl.href;
}
onProgress?.({ stage: "resolving", percent: 0 });
if (isPlaylistUrl(url)) {
const err = new Error("Playlists are not supported. Paste a single video URL.");
err.code = "PLAYLIST_URL";
throw err;
}
const videoId = extractYouTubeVideoId(url);
if (!videoId) {
const err = new Error("Could not extract video ID from URL");
err.code = "INVALID_URL";
throw err;
}
const sanitizedUrl = `https://www.youtube.com/watch?v=${videoId}`;
// Route yt-dlp through the OS proxy when one is configured.
const proxyUrl = await resolveProxyForUrl("https://www.youtube.com/");
const proxyArgs = proxyUrl ? ["--proxy", proxyUrl] : [];
let info;
try {
// Stale-extractor failures usually surface here, so this step self-heals too.
const { stdout } = await runYtDlpWithSelfHeal(
binary,
[...proxyArgs, "--dump-single-json", "--no-warnings", sanitizedUrl],
abortSignal,
YT_DLP_METADATA_TIMEOUT_MS
);
info = JSON.parse(stdout);
} catch (e) {
if (e.code === "DOWNLOAD_CANCELLED" || abortSignal?.aborted) {
const err = new Error("Download cancelled");
err.code = "DOWNLOAD_CANCELLED";
throw err;
}
const text = `${e.message || ""} ${e.stderr || ""}`;
if (looksLikeYouTubeBlock(text)) {
const err = new Error(
"YouTube is temporarily blocking downloads from your network. Try again later."
);
err.code = "YOUTUBE_BLOCKED";
throw err;
}
// A network stall is not "video unavailable" — keep it retryable.
if (/timed out/i.test(e.message || "")) {
const err = new Error("yt-dlp timed out");
err.code = "DOWNLOAD_FAILED";
throw err;
}
const err = new Error(e.message || "Video unavailable");
err.code = "VIDEO_UNAVAILABLE";
throw err;
}
if (info.is_live) {
const err = new Error("Live streams are not supported");
err.code = "VIDEO_UNAVAILABLE";
throw err;
}
const title = info.title || `youtube-${videoId}`;
const durationSeconds = info.duration || null;
if (durationSeconds && durationSeconds > MAX_DURATION_SECONDS) {
const err = new Error("Video is too long to download. Maximum length is 6 hours.");
err.code = "FILE_TOO_LARGE";
throw err;
}
onProgress?.({ stage: "downloading", percent: 0, title });
if (abortSignal?.aborted) {
const err = new Error("Download cancelled");
err.code = "DOWNLOAD_CANCELLED";
throw err;
}
const tempBase = path.join(getSafeTempDir(), `ow-url-${Date.now()}-${videoId}`);
const extractionArgs = [
...proxyArgs,
"-x",
"--audio-format",
"best",
"--max-filesize",
"500M",
"--ffmpeg-location",
ffmpegDir,
"-o",
`${tempBase}.%(ext)s`,
// Line-buffered progress ("[download] 42.3% of ...") instead of \r rewrites.
"--newline",
"--no-warnings",
sanitizedUrl,
];
// Cap at 99: after the download hits 100%, ffmpeg still has to extract audio.
let lastPercent = 0;
const onExtractionOutput = (text) => {
const matches = text.match(/\[download\]\s+(\d{1,3}(?:\.\d+)?)%/g);
if (!matches) return;
const percent = Math.min(
99,
Math.round(parseFloat(matches[matches.length - 1].match(/([\d.]+)%/)[1]))
);
if (percent > lastPercent) {
lastPercent = percent;
onProgress?.({ stage: "downloading", percent, title });
}
};
try {
// The metadata step may have self-healed the cache copy; pick up the fresh binary.
const { stdout: extractionOut } = await runYtDlpWithSelfHeal(
resolveYtDlpBinary() || binary,
extractionArgs,
abortSignal,
YT_DLP_EXTRACTION_TIMEOUT_MS,
() => cleanupTempArtifacts(tempBase),
onExtractionOutput
);
// --max-filesize makes yt-dlp skip the file and exit 0 with no output.
if (/larger than max-filesize/i.test(extractionOut)) {
const err = new Error("File too large. Maximum download size is 500 MB.");
err.code = "FILE_TOO_LARGE";
throw err;
}
const tempPath = selectYtDlpOutput(getSafeTempDir(), path.basename(tempBase));
const sizeBytes = fs.statSync(tempPath).size;
// --max-filesize doesn't enforce for unknown-size streams; re-check after the fact.
if (sizeBytes > MAX_DOWNLOAD_BYTES) {
try {
fs.unlinkSync(tempPath);
} catch {}
const err = new Error("File too large. Maximum download size is 500 MB.");
err.code = "FILE_TOO_LARGE";
throw err;
}
// Throttled background self-update for next time (never awaited).
maybeUpdateYtDlp();
onProgress?.({ stage: "ready", percent: 100, title });
return { tempPath, title, durationSeconds, sizeBytes };
} catch (e) {
cleanupTempArtifacts(tempBase);
if (e.code === "DOWNLOAD_CANCELLED" || e.code === "PLAYLIST_URL") throw e;
const text = `${e.message || ""} ${e.stderr || ""}`;
if (looksLikeYouTubeBlock(text)) {
const err = new Error(
"YouTube is temporarily blocking downloads from your network. Try again later."
);
err.code = "YOUTUBE_BLOCKED";
throw err;
}
const err = new Error(e.stderr || e.message || "Download failed");
err.code = e.code || "DOWNLOAD_FAILED";
throw err;
}
}
function httpRequest(parsed, options) {
const mod = parsed.protocol === "https:" ? https : http;
return new Promise((resolve, reject) => {
// UA-less requests get bot-walled by common CDN fronts. `signal` lets a
// cancel land during the connect phase, not just once data is streaming.
const req = mod.request(
parsed,
{ timeout: CONNECT_TIMEOUT_MS, headers: { "User-Agent": USER_AGENT }, ...options },
resolve
);
req.on("error", (err) => {
if (options.signal?.aborted) {
reject(Object.assign(new Error("Download cancelled"), { code: "DOWNLOAD_CANCELLED" }));
} else {
reject(err);
}
});
req.on("timeout", () => {
req.destroy();
reject(new Error("Connection timed out"));
});
req.end();
});
}
// Stream a readable HTTP response to disk under the shared caps (size, stall,
// abort, progress). Used by both the direct and proxy paths. `abort` tears down
// the underlying transport. Resolves to byte size; cleans up temp file on failure.
function streamToFile(
response,
tempPath,
{ contentLength, title, onProgress, abortSignal, abort }
) {
return new Promise((resolve, reject) => {
// An already-dispatched abort event never re-fires for a late listener.
if (abortSignal?.aborted) {
try {
abort();
} catch {}
reject(Object.assign(new Error("Download cancelled"), { code: "DOWNLOAD_CANCELLED" }));
return;
}
const fileStream = fs.createWriteStream(tempPath);
let downloaded = 0;
let settled = false;
const stall = createStallChecker(() => {
if (settled) return;
try {
abort();
} catch {}
bail(Object.assign(new Error("Download stalled"), { code: "DOWNLOAD_FAILED" }));
});
// destroy() returns before the stream's async open finishes, so unlinking
// right away can race a pending open into recreating the file. Wait for 'close'.
const cleanupFile = () =>
new Promise((done) => {
const unlink = () =>
fs.unlink(tempPath, (e) => {
try {
if (e && e.code !== "ENOENT") {
debugLogger.warn("Failed to remove partial download", {
tempPath,
error: e.message,
});
}
} finally {
done();
}
});
if (fileStream.closed) {
unlink();
return;
}
fileStream.once("close", unlink);
fileStream.destroy();
});
const bail = (err) => {
if (settled) return;
settled = true;
stall.clear();
if (abortSignal) abortSignal.removeEventListener("abort", onAbort);
cleanupFile().then(() => reject(err));
};
// React to cancel even while stalled (no data events arriving).
const onAbort = () => {
try {
abort();
} catch {}
bail(Object.assign(new Error("Download cancelled"), { code: "DOWNLOAD_CANCELLED" }));
};
if (abortSignal) abortSignal.addEventListener("abort", onAbort, { once: true });
response.on("data", (chunk) => {
if (settled) return;
stall.touch();
downloaded += chunk.length;
if (downloaded > MAX_DOWNLOAD_BYTES) {
try {
abort();
} catch {}
bail(
Object.assign(new Error("File too large. Maximum download size is 500 MB."), {
code: "FILE_TOO_LARGE",
})
);
return;
}
if (contentLength) {
const percent = Math.min(99, Math.round((downloaded / contentLength) * 100));
onProgress?.({ stage: "downloading", percent, title });
}
});
response.on("error", (e) => {
bail(Object.assign(new Error(e.message || "Download failed"), { code: "DOWNLOAD_FAILED" }));
});
response.pipe(fileStream);
fileStream.on("error", (e) => {
bail(Object.assign(new Error(e.message || "Write failed"), { code: "DOWNLOAD_FAILED" }));
});
fileStream.on("finish", () => {
if (settled) return;
settled = true;
stall.clear();
if (abortSignal) abortSignal.removeEventListener("abort", onAbort);
try {
const sizeBytes = fs.statSync(tempPath).size;
resolve(sizeBytes);
} catch {
cleanupFile().then(() =>
reject(
Object.assign(new Error("Download produced no output"), { code: "DOWNLOAD_FAILED" })
)
);
}
});
});
}
// Test seam: electron's net is unavailable under node --test.
let electronNetOverride = null;
function getElectronNet() {
return electronNetOverride || require("electron").net;
}
// Internal sentinel: the redirect handler aborts the request and asks the caller
// to restart the download at the redirect URL (followRedirect must be invoked
// synchronously inside the redirect event, but our host validation is async).
const REDIRECT_RESTART = "REDIRECT_RESTART";
// Proxy path: route through Electron net.request (which honors the OS proxy
// automatically). For defense-in-depth we still pre-flight the target hostname and
// re-validate each redirect hop against private IPs. With a proxy the corporate
// egress policy is the primary SSRF control; net.request does not accept a
// per-request lookup, leaving a narrow DNS-rebinding TOCTOU residual.
async function downloadViaProxy(url, onProgress, abortSignal, redirectCount = 0) {
const net = getElectronNet();
await assertPublicHost(new URL(url).hostname);
const settledResponse = await new Promise((resolve, reject) => {
if (abortSignal?.aborted) {
reject(Object.assign(new Error("Download cancelled"), { code: "DOWNLOAD_CANCELLED" }));
return;
}
let redirects = redirectCount;
let request;
try {
request = net.request({ url, method: "GET", redirect: "manual" });
request.setHeader("User-Agent", USER_AGENT);
} catch (e) {
reject(Object.assign(new Error(e.message || "Download failed"), { code: "DOWNLOAD_FAILED" }));
return;
}
// ClientRequest.abort() emits 'abort'/'close' but never 'error', so an abort
// that lands after request.end() must settle the promise itself or it hangs.
const onAbort = () => {
try {
request.abort();
} catch {}
detach();
reject(Object.assign(new Error("Download cancelled"), { code: "DOWNLOAD_CANCELLED" }));
};
if (abortSignal) abortSignal.addEventListener("abort", onAbort, { once: true });
// Chromium's net stack has no response-header timeout; without this a proxy
// that accepts the connection but never answers wedges the queue forever
// (the direct path gets the same bound from httpRequest's socket timeout).
const connectTimer = setTimeout(() => {
try {
request.abort();
} catch {}
detach();
reject(Object.assign(new Error("Connection timed out"), { code: "DOWNLOAD_FAILED" }));
}, CONNECT_TIMEOUT_MS);
const detach = () => {
clearTimeout(connectTimer);
if (abortSignal) abortSignal.removeEventListener("abort", onAbort);
};
request.on("redirect", (statusCode, method, redirectUrl) => {
redirects += 1;
if (redirects > MAX_REDIRECTS) {
try {
request.abort();
} catch {}
detach();
reject(Object.assign(new Error("Too many redirects"), { code: "DOWNLOAD_FAILED" }));
return;
}
let next;
try {
next = new URL(redirectUrl);
} catch {
try {
request.abort();
} catch {}
detach();
reject(Object.assign(new Error("Invalid redirect URL"), { code: "INVALID_URL" }));
return;
}
if (next.protocol !== "https:") {
try {
request.abort();
} catch {}
detach();
reject(
Object.assign(new Error("Only HTTPS URLs are supported for direct downloads"), {
code: "INVALID_URL",
})
);
return;
}
// Abort and restart at the redirect URL; the recursive call re-runs assertPublicHost.
try {
request.abort();
} catch {}
detach();
reject(
Object.assign(new Error("Redirected"), {
code: REDIRECT_RESTART,
url: next.href,
redirects,
})
);
});
request.on("response", (response) => {
detach();
const statusCode = response.statusCode;
if (statusCode !== 200) {
response.resume();
try {
request.abort();
} catch {}
reject(Object.assign(new Error(`HTTP ${statusCode}`), { code: "DOWNLOAD_FAILED" }));
return;
}
const contentType = (firstHeaderValue(response.headers, "content-type") || "").toLowerCase();
if (!isAcceptableAudioContentType(contentType)) {
response.resume();
try {
request.abort();
} catch {}
reject(
Object.assign(
new Error(`URL does not point to an audio file (content-type: ${contentType})`),
{ code: "CONTENT_TYPE_INVALID" }
)
);
return;
}
const clHeader = firstHeaderValue(response.headers, "content-length");
const contentLength = clHeader ? Number(clHeader) : null;
if (contentLength && contentLength > MAX_DOWNLOAD_BYTES) {
response.resume();
try {
request.abort();
} catch {}
reject(
Object.assign(new Error("File too large. Maximum download size is 500 MB."), {
code: "FILE_TOO_LARGE",
})
);
return;
}
resolve({ response, contentLength, request });
});
request.on("error", (err) => {
detach();
if (abortSignal?.aborted) {
reject(Object.assign(new Error("Download cancelled"), { code: "DOWNLOAD_CANCELLED" }));
} else {
reject(
Object.assign(new Error(err.message || "Download failed"), { code: "DOWNLOAD_FAILED" })
);
}
});
request.end();
}).catch((err) => {
if (err && err.code === REDIRECT_RESTART) return err;
throw err;
});
if (settledResponse && settledResponse.code === REDIRECT_RESTART) {
return downloadViaProxy(
settledResponse.url,
onProgress,
abortSignal,
settledResponse.redirects
);
}
const { response, contentLength, request } = settledResponse;
const { title, ext } = deriveTitleAndExt(new URL(url).pathname);
const tempPath = path.join(getSafeTempDir(), `ow-url-${Date.now()}.${ext}`);
onProgress?.({ stage: "downloading", percent: 0, title });
const sizeBytes = await streamToFile(response, tempPath, {
contentLength,
title,
onProgress,
abortSignal,
abort: () => {
try {
request.abort();
} catch {}
},
});
onProgress?.({ stage: "ready", percent: 100, title });
return { tempPath, title, durationSeconds: null, sizeBytes };
}
async function downloadDirect(url, onProgress, abortSignal, redirectCount = 0) {
onProgress?.({ stage: "resolving", percent: 0 });
const parsed = new URL(url);
if (parsed.protocol !== "https:") {
const err = new Error("Only HTTPS URLs are supported for direct downloads");
err.code = "INVALID_URL";
throw err;
}
const rawHost = parsed.hostname.replace(/^\[|\]$/g, "");
if (isIP(rawHost) && isPrivateIp(rawHost)) {
const err = new Error("Direct downloads from private/internal addresses are not allowed");
err.code = "SSRF_BLOCKED";
throw err;
}
// When the OS has a proxy configured, raw node-https would bypass it. Route through
// Electron net.request instead; keep the airtight node-https + ssrfSafeLookup path
// as the default for the common no-proxy case.
const proxyUrl = await resolveProxyForUrl(url);
if (proxyUrl) {
return downloadViaProxy(url, onProgress, abortSignal, redirectCount);
}
// Servers may refuse HEAD (GET-only presigned URLs, 405s): non-2xx or transport
// failures fall through to the GET, which is fully re-validated anyway.
let headParsed = parsed;
let headRedirects = 0;
let headResponse = null;
try {
while (true) {
headResponse = await httpRequest(headParsed, {
method: "HEAD",
lookup: ssrfSafeLookup,
signal: abortSignal,
});
headResponse.resume();
if (
headResponse.statusCode >= 300 &&
headResponse.statusCode < 400 &&
headResponse.headers.location
) {
// Cumulative redirect bound across alternating GET+HEAD hops.
if (redirectCount + ++headRedirects > MAX_REDIRECTS) {
const err = new Error("Too many redirects");
err.code = "DOWNLOAD_FAILED";
throw err;
}
const nextUrl = new URL(headResponse.headers.location, headParsed.href);
if (nextUrl.protocol !== "https:") {
const err = new Error("Only HTTPS URLs are supported for direct downloads");
err.code = "INVALID_URL";
throw err;
}
const nextRawHost = nextUrl.hostname.replace(/^\[|\]$/g, "");
if (isIP(nextRawHost) && isPrivateIp(nextRawHost)) {
const err = new Error("Direct downloads from private/internal addresses are not allowed");
err.code = "SSRF_BLOCKED";
throw err;
}
headParsed = nextUrl;
continue;
}
break;
}
} catch (e) {
if (
e.code === "SSRF_BLOCKED" ||
e.code === "INVALID_URL" ||
e.code === "DOWNLOAD_FAILED" ||
e.code === "DOWNLOAD_CANCELLED"
) {
throw e;
}
headResponse = null;
}
let contentLength = null;
if (headResponse && headResponse.statusCode >= 200 && headResponse.statusCode < 300) {
const contentType = (headResponse.headers["content-type"] || "").toLowerCase();
if (!isAcceptableAudioContentType(contentType)) {
const err = new Error(`URL does not point to an audio file (content-type: ${contentType})`);
err.code = "CONTENT_TYPE_INVALID";
throw err;
}
contentLength = headResponse.headers["content-length"]
? Number(headResponse.headers["content-length"])
: null;
if (contentLength && contentLength > MAX_DOWNLOAD_BYTES) {
const err = new Error("File too large. Maximum download size is 500 MB.");
err.code = "FILE_TOO_LARGE";
throw err;
}
}
const { title, ext } = deriveTitleAndExt(headParsed.pathname);
const tempPath = path.join(getSafeTempDir(), `ow-url-${Date.now()}.${ext}`);
onProgress?.({ stage: "downloading", percent: 0, title });
const response = await httpRequest(headParsed, {
method: "GET",
lookup: ssrfSafeLookup,
signal: abortSignal,
});
if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
response.destroy();
if (redirectCount + headRedirects >= MAX_REDIRECTS) {
const err = new Error("Too many redirects");
err.code = "DOWNLOAD_FAILED";
throw err;
}
const redirectUrl = new URL(response.headers.location, headParsed.href).href;
return downloadDirect(redirectUrl, onProgress, abortSignal, redirectCount + headRedirects + 1);
}
if (response.statusCode !== 200) {
response.destroy();
const err = new Error(`HTTP ${response.statusCode}`);
err.code = "DOWNLOAD_FAILED";
throw err;
}
const getContentType = (response.headers["content-type"] || "").toLowerCase();
if (!isAcceptableAudioContentType(getContentType)) {
response.destroy();
const err = new Error(`URL does not point to an audio file (content-type: ${getContentType})`);
err.code = "CONTENT_TYPE_INVALID";
throw err;
}
if (contentLength == null && response.headers["content-length"]) {
contentLength = Number(response.headers["content-length"]);
if (contentLength > MAX_DOWNLOAD_BYTES) {
response.destroy();
const err = new Error("File too large. Maximum download size is 500 MB.");
err.code = "FILE_TOO_LARGE";
throw err;
}
}
const sizeBytes = await streamToFile(response, tempPath, {
contentLength,
title,
onProgress,
abortSignal,
abort: () => {
try {
response.destroy();
} catch {}
},
});
onProgress?.({ stage: "ready", percent: 100, title });
return { tempPath, title, durationSeconds: null, sizeBytes };
}
async function download(url, onProgress, abortSignal) {
const type = detectUrlType(url);
debugLogger.log("URL audio download starting", { url, type });
if (type === "youtube") {
return downloadYouTube(url, onProgress, abortSignal);
}
return downloadDirect(url, onProgress, abortSignal);
}
module.exports = {
detectUrlType,
extractYouTubeVideoId,
isPlaylistUrl,
download,
sweepStaleTempArtifacts,
isPrivateIp,
isAcceptableAudioContentType,
ssrfSafeLookup,
maybeUpdateYtDlp,
downloadViaProxy,
// Test-only seam: lets the regression test confirm the single-flight flag is cleared.
_isYtDlpUpdateInFlight: () => ytDlpUpdateInFlight,
// Test-only seam: injects a fake electron net for downloadViaProxy tests.
_setElectronNetForTests: (net) => {
electronNetOverride = net;
},
// Test-only seam: exposes yt-dlp output selection to the regression tests.
_selectYtDlpOutput: selectYtDlpOutput,
// Test-only seams: cache checksum verification and block-detection heuristics.
_resolveYtDlpBinary: resolveYtDlpBinary,
_recordCacheChecksum: recordCacheChecksum,
_looksLikeYouTubeBlock: looksLikeYouTubeBlock,
};