yt2text 0.1.0

package/dist/cli.js

@@ -0,0 +1,384 @@
+#!/usr/bin/env node
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { Command, InvalidArgumentError } from "commander";
+import { createRuntimePaths } from "./cache.js";
+import { defaultConfigPath, expandHome, loadConfig, writeDefaultConfig } from "./config.js";
+import { defaultCookiesFromBrowser, detectCookieBrowsers, knownCookieBrowsers } from "./cookies.js";
+import { runDoctor } from "./doctor.js";
+import { downloadMedia, normalizeToWav, prepareLocalMedia } from "./media.js";
+import { installLogger } from "./logger.js";
+import { defaultAsrProvider, defaultSystemMode, isSupportedPlatform, platformName } from "./platform.js";
+import { assignSpeakers } from "./segments.js";
+import { transcribe } from "./asr.js";
+import { diarizeWithLocal } from "./local-asr.js";
+import { renderOutputStem, writeTranscript } from "./output.js";
+import { explainError, Yt2TextError } from "./errors.js";
+const defaultLanguage = process.env.YT2TEXT_LANGUAGE ?? "zh-CN";
+function defaultOutputDir() {
+    return process.env.YT2TEXT_OUTPUT_DIR ?? expandHome("~/Downloads");
+}
+function parseChoice(value, choices) {
+    if (choices.includes(value))
+        return value;
+    throw new InvalidArgumentError(`Expected one of: ${choices.join(", ")}`);
+}
+function parseIntegerOption(name, min) {
+    return (value) => {
+        const parsed = Number(value);
+        if (!Number.isInteger(parsed) || parsed < min)
+            throw new InvalidArgumentError(`${name} must be an integer >= ${min}`);
+        return parsed;
+    };
+}
+function parseNumberOption(name, min) {
+    return (value) => {
+        const parsed = Number(value);
+        if (!Number.isFinite(parsed) || parsed < min)
+            throw new InvalidArgumentError(`${name} must be a number >= ${min}`);
+        return parsed;
+    };
+}
+function commandValue(command, config, optionName, configName = optionName) {
+    const opts = command.opts();
+    const source = command.getOptionValueSource(optionName);
+    const configured = config[configName];
+    return source !== "cli" && configured !== undefined ? configured : opts[optionName];
+}
+async function collectOptions(command) {
+    const raw = command.opts();
+    const configPath = expandHome(String(raw.config ?? defaultConfigPath()));
+    const config = await loadConfig(configPath);
+    const language = String(commandValue(command, config, "language") ?? defaultLanguage);
+    const multilingual = Boolean(raw.multilingual) || language.toLowerCase() === "auto";
+    const cookies = commandValue(command, config, "cookies");
+    const requestedBrowser = commandValue(command, config, "cookiesFromBrowser");
+    const browserCookies = commandValue(command, config, "browserCookies") ?? true;
+    const parallelDownloads = command.getOptionValueSource("concurrentFragments") === "cli"
+        ? commandValue(command, config, "concurrentFragments")
+        : command.getOptionValueSource("parallelDownloads") === "cli"
+            ? commandValue(command, config, "parallelDownloads")
+            : config.concurrentFragments ?? config.parallelDownloads ?? commandValue(command, config, "concurrentFragments");
+    return {
+        configPath,
+        asr: multilingual ? "local" : commandValue(command, config, "asr"),
+        systemMode: commandValue(command, config, "systemMode"),
+        fallback: commandValue(command, config, "fallback"),
+        language: multilingual ? "auto" : language,
+        model: commandValue(command, config, "model"),
+        diarize: Boolean(commandValue(command, config, "diarize")),
+        format: commandValue(command, config, "format"),
+        outputDir: expandHome(String(commandValue(command, config, "output", "outputDir") ?? defaultOutputDir())),
+        cacheDir: commandValue(command, config, "cacheDir") ? expandHome(String(commandValue(command, config, "cacheDir"))) : undefined,
+        offline: Boolean(commandValue(command, config, "offline")),
+        keepAudio: Boolean(commandValue(command, config, "keepAudio")),
+        keepOriginalAudio: Boolean(commandValue(command, config, "keepOriginalAudio")),
+        chunkSeconds: Number(commandValue(command, config, "chunkSeconds")),
+        filenameTemplate: String(commandValue(command, config, "filenameTemplate") ?? "{title}"),
+        audioQuality: commandValue(command, config, "audioQuality"),
+        verbose: Boolean(commandValue(command, config, "verbose")),
+        cookies: cookies ? expandHome(cookies) : undefined,
+        cookiesFromBrowser: cookies ? undefined : requestedBrowser ?? (browserCookies === false ? undefined : defaultCookiesFromBrowser()),
+        browserCookies,
+        concurrentFragments: Number(parallelDownloads),
+        retries: Number(commandValue(command, config, "retries")),
+        fragmentRetries: Number(commandValue(command, config, "fragmentRetries")),
+        socketTimeout: Number(commandValue(command, config, "socketTimeout")),
+        downloadTimeoutSeconds: Number(commandValue(command, config, "downloadTimeout", "downloadTimeoutSeconds")),
+        convertTimeoutSeconds: Number(commandValue(command, config, "convertTimeout", "convertTimeoutSeconds")),
+        asrChunkTimeoutSeconds: Number(commandValue(command, config, "asrChunkTimeout", "asrChunkTimeoutSeconds")),
+        proxy: commandValue(command, config, "proxy"),
+        rateLimit: commandValue(command, config, "rateLimit"),
+        userAgent: commandValue(command, config, "userAgent"),
+        logFile: commandValue(command, config, "logFile") ? expandHome(String(commandValue(command, config, "logFile"))) : undefined,
+        updateYtDlp: Boolean(commandValue(command, config, "updateYtDlp")),
+    };
+}
+function addCommonOptions(command) {
+    return command
+        .option("--config <file>", "JSON config file", defaultConfigPath())
+        .option("--asr <provider>", "ASR provider: system or local", (value) => parseChoice(value, ["system", "local"]), defaultAsrProvider())
+        .option("--system-mode <mode>", "System ASR mode: online, offline, or auto", (value) => parseChoice(value, ["online", "offline", "auto"]), defaultSystemMode())
+        .option("--fallback <mode>", "Fallback when system ASR fails: local or fail", (value) => parseChoice(value, ["local", "fail"]), "fail")
+        .option("-l, --language <locale>", "Recognition locale, or auto for local multilingual ASR", defaultLanguage)
+        .option("--multilingual", "Use local ASR with automatic language detection", false)
+        .option("--model <model>", "Local ASR model", (value) => parseChoice(value, ["tiny", "base", "small", "medium"]), "small")
+        .option("--diarize", "Add anonymous speaker labels using local diarization", false)
+        .option("-f, --format <format>", "Output format", (value) => parseChoice(value, ["txt", "json", "srt"]), "txt")
+        .option("-o, --output <dir>", "Output directory", defaultOutputDir())
+        .option("--cache-dir <dir>", "Override cache directory")
+        .option("--offline", "Do not download missing tools or models", false)
+        .option("--keep-audio", "Keep normalized WAV next to the transcript", false)
+        .option("--keep-original-audio", "Keep the original downloaded audio next to the transcript", false)
+        .option("--filename-template <template>", "Output filename template, e.g. {date}-{title}", "{title}")
+        .option("--audio-quality <quality>", "Downloaded audio quality: best, balanced, or small", (value) => parseChoice(value, ["best", "balanced", "small"]), "best")
+        .option("--cookies <file>", "Pass a Netscape cookies file to yt-dlp")
+        .option("--cookies-from-browser <browser>", "Read cookies from a browser, e.g. auto, chrome, safari, firefox")
+        .option("--no-browser-cookies", "Do not automatically read browser cookies")
+        .option("--parallel-downloads <n>", "Alias for yt-dlp parallel fragment downloads", parseIntegerOption("parallel downloads", 1))
+        .option("--concurrent-fragments <n>", "yt-dlp fragment concurrency", parseIntegerOption("concurrent fragments", 1), 4)
+        .option("--retries <n>", "yt-dlp download retries", parseIntegerOption("retries", 0), 10)
+        .option("--fragment-retries <n>", "yt-dlp fragment retries", parseIntegerOption("fragment retries", 0), 10)
+        .option("--socket-timeout <seconds>", "yt-dlp socket timeout", parseNumberOption("socket timeout", 1), 20)
+        .option("--download-timeout <seconds>", "Fail yt-dlp if download exceeds this time; 0 disables", parseNumberOption("download timeout", 0), 1800)
+        .option("--convert-timeout <seconds>", "Fail ffmpeg conversion/splitting if it exceeds this time; 0 disables", parseNumberOption("convert timeout", 0), 600)
+        .option("--asr-chunk-timeout <seconds>", "Fail each system ASR chunk if it exceeds this time; 0 disables", parseNumberOption("ASR chunk timeout", 0), 180)
+        .option("--proxy <url>", "Proxy URL for yt-dlp")
+        .option("--rate-limit <rate>", "yt-dlp rate limit, e.g. 2M or 500K")
+        .option("--user-agent <ua>", "Custom yt-dlp user agent")
+        .option("--log-file <file>", "Append logs to a file")
+        .option("--update-ytdlp", "Force refresh cached yt-dlp before downloading", false)
+        .option("--chunk-seconds <seconds>", "System ASR chunk size", (value) => {
+        const parsed = Number(value);
+        if (!Number.isFinite(parsed) || parsed < 10)
+            throw new InvalidArgumentError("Expected a number >= 10");
+        return parsed;
+    }, 55)
+        .option("-v, --verbose", "Verbose logging", false);
+}
+function isUrl(value) {
+    return /^https?:\/\//i.test(value);
+}
+function progress(message) {
+    console.error(message);
+}
+async function runPipeline(input, inputKind, options) {
+    if (!isSupportedPlatform()) {
+        throw new Yt2TextError(`yt2text only supports macOS, Linux, and Windows. Current platform: ${platformName()} (${process.platform}).`, "UNSUPPORTED_PLATFORM");
+    }
+    if (options.verbose) {
+        console.error(`ASR: ${options.asr}; language: ${options.language}; system mode: ${options.systemMode}`);
+    }
+    const paths = await createRuntimePaths(options);
+    try {
+        progress(inputKind === "url" ? "[1/5] Downloading audio..." : "[1/5] Preparing local media...");
+        const media = inputKind === "url" ? await downloadMedia(input, paths, options) : await prepareLocalMedia(expandHome(input), paths);
+        progress(`[2/5] Converting audio: ${media.title}`);
+        const normalized = join(paths.workDir, "audio.16k.wav");
+        await normalizeToWav(media.mediaPath, normalized, options.convertTimeoutSeconds);
+        progress(`[3/5] Transcribing with ${options.asr} ASR (${options.language})...`);
+        const transcript = await transcribe(normalized, paths, options);
+        progress(`[4/5] Preparing transcript${options.diarize ? " and speaker labels" : ""}...`);
+        const segments = options.diarize
+            ? assignSpeakers(transcript.segments, await diarizeWithLocal(normalized, paths, options))
+            : transcript.segments;
+        const documentBase = {
+            source: input,
+            title: media.title,
+            engine: transcript.engine,
+            language: options.language,
+            segments,
+            createdAt: new Date().toISOString(),
+        };
+        const outputStem = renderOutputStem(documentBase, options.filenameTemplate);
+        const audioPath = options.keepAudio ? join(options.outputDir, `${outputStem}.wav`) : undefined;
+        if (audioPath) {
+            const { copyFile } = await import("node:fs/promises");
+            await copyFile(normalized, audioPath);
+        }
+        let originalAudioPath;
+        if (options.keepOriginalAudio) {
+            const { copyFile } = await import("node:fs/promises");
+            const { extname } = await import("node:path");
+            const extension = extname(media.mediaPath) || ".audio";
+            originalAudioPath = join(options.outputDir, `${outputStem}${extension}`);
+            await copyFile(media.mediaPath, originalAudioPath);
+        }
+        progress(`[5/5] Writing ${options.format} to ${options.outputDir}...`);
+        const outputPath = await writeTranscript({
+            ...documentBase,
+            audioPath,
+            originalAudioPath,
+        }, options.outputDir, options.format, options.filenameTemplate);
+        progress(`Done: ${outputPath}`);
+        console.log(outputPath);
+    }
+    finally {
+        await rm(paths.workDir, { recursive: true, force: true });
+    }
+}
+async function askRequired(rl, question) {
+    while (true) {
+        const value = (await rl.question(question)).trim();
+        if (value)
+            return value;
+    }
+}
+async function askDefault(rl, question, defaultValue) {
+    const value = (await rl.question(`${question} [${defaultValue}]: `)).trim();
+    return value || defaultValue;
+}
+async function askChoice(rl, question, choices, defaultIndex = 0) {
+    console.error(question);
+    choices.forEach((choice, index) => {
+        const marker = index === defaultIndex ? "*" : " ";
+        console.error(`  ${index + 1}. ${marker} ${choice.label}`);
+    });
+    while (true) {
+        const answer = (await rl.question(`Choose [${defaultIndex + 1}]: `)).trim();
+        if (!answer)
+            return choices[defaultIndex].value;
+        const index = Number(answer) - 1;
+        if (Number.isInteger(index) && choices[index])
+            return choices[index].value;
+    }
+}
+async function runInteractive() {
+    const rl = createInterface({ input, output });
+    try {
+        const config = await loadConfig();
+        console.error("yt2text interactive mode");
+        const source = expandHome(await askRequired(rl, "YouTube URL or local file path: "));
+        const inputKind = isUrl(source) ? "url" : "file";
+        const languageChoice = await askChoice(rl, "Recognition language", [
+            { label: "Chinese (zh-CN)", value: "zh-CN" },
+            { label: "English (en-US)", value: "en-US" },
+            { label: "Auto / multilingual (local ASR)", value: "auto" },
+            { label: "Custom locale", value: "custom" },
+        ]);
+        const languageDefault = config.language ?? defaultLanguage;
+        const language = languageChoice === "custom" ? await askDefault(rl, "Locale", languageDefault) : languageChoice;
+        const multilingual = language === "auto";
+        const outputDir = expandHome(await askDefault(rl, "Output directory", config.outputDir ?? defaultOutputDir()));
+        let cookies;
+        let cookiesFromBrowser;
+        let browserCookies = true;
+        if (inputKind === "url") {
+            const cookieMode = await askChoice(rl, "YouTube cookies", [
+                { label: "Auto-detect browser cookies", value: "auto" },
+                { label: "Choose a browser", value: "browser" },
+                { label: "Manual cookies file", value: "file" },
+                { label: "No cookies", value: "none" },
+            ]);
+            if (cookieMode === "auto") {
+                cookiesFromBrowser = "auto";
+            }
+            else if (cookieMode === "browser") {
+                const detected = await detectCookieBrowsers();
+                const detectedIds = new Set(detected.map((browser) => browser.id));
+                const browsers = knownCookieBrowsers().map((browser) => ({
+                    label: detectedIds.has(browser.id) ? `${browser.name} (${browser.id}, detected)` : `${browser.name} (${browser.id})`,
+                    value: browser.id,
+                }));
+                cookiesFromBrowser = await askChoice(rl, "Browser", browsers);
+            }
+            else if (cookieMode === "file") {
+                cookies = expandHome(await askRequired(rl, "Cookies file path: "));
+            }
+            else {
+                browserCookies = false;
+            }
+        }
+        const options = {
+            configPath: defaultConfigPath(),
+            asr: multilingual ? "local" : config.asr ?? defaultAsrProvider(),
+            systemMode: config.systemMode ?? defaultSystemMode(),
+            fallback: config.fallback ?? "fail",
+            language,
+            model: config.model ?? "small",
+            diarize: config.diarize ?? false,
+            format: config.format ?? "txt",
+            outputDir,
+            cacheDir: config.cacheDir ? expandHome(config.cacheDir) : undefined,
+            offline: config.offline ?? false,
+            keepAudio: config.keepAudio ?? false,
+            keepOriginalAudio: config.keepOriginalAudio ?? false,
+            chunkSeconds: config.chunkSeconds ?? 55,
+            filenameTemplate: config.filenameTemplate ?? "{title}",
+            audioQuality: config.audioQuality ?? "best",
+            verbose: config.verbose ?? false,
+            cookies,
+            cookiesFromBrowser,
+            browserCookies,
+            concurrentFragments: config.parallelDownloads ?? config.concurrentFragments ?? 4,
+            retries: config.retries ?? 10,
+            fragmentRetries: config.fragmentRetries ?? 10,
+            socketTimeout: config.socketTimeout ?? 20,
+            downloadTimeoutSeconds: config.downloadTimeoutSeconds ?? 1800,
+            convertTimeoutSeconds: config.convertTimeoutSeconds ?? 600,
+            asrChunkTimeoutSeconds: config.asrChunkTimeoutSeconds ?? 180,
+            proxy: config.proxy,
+            rateLimit: config.rateLimit,
+            userAgent: config.userAgent,
+            logFile: config.logFile ? expandHome(config.logFile) : undefined,
+            updateYtDlp: config.updateYtDlp ?? false,
+        };
+        await installLogger(options.logFile);
+        await runPipeline(source, inputKind, options);
+    }
+    finally {
+        rl.close();
+    }
+}
+const program = new Command();
+program
+    .name("yt2text")
+    .description("Download audio and save local transcripts.")
+    .version("0.1.0");
+const runCommand = addCommonOptions(program.command("run").argument("<url>", "YouTube or yt-dlp supported URL").description("Download and transcribe a URL"));
+runCommand.action(async (url) => {
+    const options = await collectOptions(runCommand);
+    await installLogger(options.logFile);
+    await runPipeline(url, "url", options);
+});
+const fileCommand = addCommonOptions(program.command("file").argument("<path>", "Local audio/video file"));
+fileCommand.action(async (filePath) => {
+    const options = await collectOptions(fileCommand);
+    await installLogger(options.logFile);
+    await runPipeline(expandHome(filePath), "file", options);
+});
+const doctorCommand = addCommonOptions(program.command("doctor").description("Check local dependencies and cache"));
+doctorCommand.option("--fix", "Download missing small dependencies where possible", false);
+doctorCommand.option("--show-config", "Print the effective options after config and CLI overrides", false);
+doctorCommand.action(async () => {
+    const options = await collectOptions(doctorCommand);
+    await installLogger(options.logFile);
+    const paths = await createRuntimePaths(options);
+    try {
+        const doctorOptions = doctorCommand.opts();
+        await runDoctor(paths, options, Boolean(doctorOptions.fix), Boolean(doctorOptions.showConfig));
+    }
+    finally {
+        await rm(paths.workDir, { recursive: true, force: true });
+    }
+});
+const configCommand = program
+    .command("config")
+    .argument("[path]", "Where to write config JSON", defaultConfigPath())
+    .option("--print", "Print the default config JSON instead of writing a file", false)
+    .description("Write a default JSON config file");
+configCommand.action(async (path) => {
+    if (configCommand.opts().print) {
+        const { defaultConfig } = await import("./config.js");
+        console.log(JSON.stringify(defaultConfig(), null, 2));
+        return;
+    }
+    const target = await writeDefaultConfig(path);
+    console.log(target);
+});
+function withDefaultCommand(argv) {
+    const knownCommands = new Set(["run", "file", "doctor", "config", "help"]);
+    const first = argv[0];
+    if (!first || first === "-h" || first === "--help" || first === "-V" || first === "--version")
+        return argv;
+    if (knownCommands.has(first))
+        return argv;
+    return ["run", ...argv];
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.length === 0) {
+        if (process.stdin.isTTY && process.stdout.isTTY) {
+            await runInteractive();
+            return;
+        }
+        program.help();
+    }
+    await program.parseAsync(["node", "yt2text", ...withDefaultCommand(argv)]);
+}
+main().catch((error) => {
+    console.error(explainError(error));
+    process.exitCode = 1;
+});

package/dist/config.js

@@ -0,0 +1,185 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { Yt2TextError } from "./errors.js";
+import { defaultAsrProvider, defaultSystemMode } from "./platform.js";
+const knownConfigKeys = new Set([
+    "asr",
+    "systemMode",
+    "fallback",
+    "language",
+    "model",
+    "diarize",
+    "format",
+    "outputDir",
+    "cacheDir",
+    "offline",
+    "keepAudio",
+    "keepOriginalAudio",
+    "chunkSeconds",
+    "filenameTemplate",
+    "audioQuality",
+    "verbose",
+    "cookies",
+    "cookiesFromBrowser",
+    "browserCookies",
+    "parallelDownloads",
+    "concurrentFragments",
+    "retries",
+    "fragmentRetries",
+    "socketTimeout",
+    "downloadTimeoutSeconds",
+    "convertTimeoutSeconds",
+    "asrChunkTimeoutSeconds",
+    "proxy",
+    "rateLimit",
+    "userAgent",
+    "logFile",
+    "updateYtDlp",
+]);
+function optional(value) {
+    return value === undefined || value === null;
+}
+function configError(path, key, expected) {
+    return new Yt2TextError(`Invalid config ${path}: ${key} must be ${expected}`, "INVALID_CONFIG");
+}
+function enumValue(path, key, value, choices) {
+    if (optional(value))
+        return undefined;
+    if (typeof value === "string" && choices.includes(value))
+        return value;
+    throw configError(path, key, `one of ${choices.join(", ")}`);
+}
+function stringValue(path, key, value) {
+    if (optional(value))
+        return undefined;
+    if (typeof value === "string")
+        return value;
+    throw configError(path, key, "a string");
+}
+function booleanValue(path, key, value) {
+    if (optional(value))
+        return undefined;
+    if (typeof value === "boolean")
+        return value;
+    throw configError(path, key, "a boolean");
+}
+function numberValue(path, key, value, min) {
+    if (optional(value))
+        return undefined;
+    if (typeof value === "number" && Number.isFinite(value) && value >= min)
+        return value;
+    throw configError(path, key, `a number >= ${min}`);
+}
+function integerValue(path, key, value, min) {
+    if (optional(value))
+        return undefined;
+    if (typeof value === "number" && Number.isInteger(value) && value >= min)
+        return value;
+    throw configError(path, key, `an integer >= ${min}`);
+}
+function normalizeConfig(raw, path) {
+    for (const key of Object.keys(raw)) {
+        if (!knownConfigKeys.has(key)) {
+            throw new Yt2TextError(`Invalid config ${path}: unknown field "${key}"`, "INVALID_CONFIG");
+        }
+    }
+    return {
+        asr: enumValue(path, "asr", raw.asr, ["system", "local"]),
+        systemMode: enumValue(path, "systemMode", raw.systemMode, ["online", "offline", "auto"]),
+        fallback: enumValue(path, "fallback", raw.fallback, ["local", "fail"]),
+        language: stringValue(path, "language", raw.language),
+        model: enumValue(path, "model", raw.model, ["tiny", "base", "small", "medium"]),
+        diarize: booleanValue(path, "diarize", raw.diarize),
+        format: enumValue(path, "format", raw.format, ["txt", "json", "srt"]),
+        outputDir: stringValue(path, "outputDir", raw.outputDir),
+        cacheDir: stringValue(path, "cacheDir", raw.cacheDir),
+        offline: booleanValue(path, "offline", raw.offline),
+        keepAudio: booleanValue(path, "keepAudio", raw.keepAudio),
+        keepOriginalAudio: booleanValue(path, "keepOriginalAudio", raw.keepOriginalAudio),
+        chunkSeconds: numberValue(path, "chunkSeconds", raw.chunkSeconds, 10),
+        filenameTemplate: stringValue(path, "filenameTemplate", raw.filenameTemplate),
+        audioQuality: enumValue(path, "audioQuality", raw.audioQuality, ["best", "balanced", "small"]),
+        verbose: booleanValue(path, "verbose", raw.verbose),
+        cookies: stringValue(path, "cookies", raw.cookies),
+        cookiesFromBrowser: stringValue(path, "cookiesFromBrowser", raw.cookiesFromBrowser),
+        browserCookies: booleanValue(path, "browserCookies", raw.browserCookies),
+        parallelDownloads: integerValue(path, "parallelDownloads", raw.parallelDownloads, 1),
+        concurrentFragments: integerValue(path, "concurrentFragments", raw.concurrentFragments, 1),
+        retries: integerValue(path, "retries", raw.retries, 0),
+        fragmentRetries: integerValue(path, "fragmentRetries", raw.fragmentRetries, 0),
+        socketTimeout: numberValue(path, "socketTimeout", raw.socketTimeout, 1),
+        downloadTimeoutSeconds: numberValue(path, "downloadTimeoutSeconds", raw.downloadTimeoutSeconds, 0),
+        convertTimeoutSeconds: numberValue(path, "convertTimeoutSeconds", raw.convertTimeoutSeconds, 0),
+        asrChunkTimeoutSeconds: numberValue(path, "asrChunkTimeoutSeconds", raw.asrChunkTimeoutSeconds, 0),
+        proxy: stringValue(path, "proxy", raw.proxy),
+        rateLimit: stringValue(path, "rateLimit", raw.rateLimit),
+        userAgent: stringValue(path, "userAgent", raw.userAgent),
+        logFile: stringValue(path, "logFile", raw.logFile),
+        updateYtDlp: booleanValue(path, "updateYtDlp", raw.updateYtDlp),
+    };
+}
+export function defaultConfigPath() {
+    if (process.env.YT2TEXT_CONFIG)
+        return process.env.YT2TEXT_CONFIG;
+    if (process.platform === "win32") {
+        return join(process.env.APPDATA ?? join(homedir(), "AppData", "Roaming"), "yt2text", "config.json");
+    }
+    return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "yt2text", "config.json");
+}
+export function expandHome(path) {
+    return path === "~" || path.startsWith("~/") ? join(homedir(), path.slice(2)) : path;
+}
+export async function loadConfig(path = defaultConfigPath()) {
+    const target = expandHome(path);
+    try {
+        const body = await readFile(target, "utf8");
+        const parsed = JSON.parse(body);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Yt2TextError(`Invalid config ${target}: root must be a JSON object`, "INVALID_CONFIG");
+        }
+        return normalizeConfig(parsed, target);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return {};
+        if (error instanceof SyntaxError) {
+            throw new Yt2TextError(`Invalid config ${target}: ${error.message}`, "INVALID_CONFIG");
+        }
+        throw error;
+    }
+}
+export function defaultConfig() {
+    return {
+        asr: defaultAsrProvider(),
+        systemMode: defaultSystemMode(),
+        fallback: "fail",
+        language: "zh-CN",
+        outputDir: "~/Downloads",
+        format: "txt",
+        cookiesFromBrowser: process.platform === "darwin" ? "auto" : undefined,
+        browserCookies: true,
+        model: "small",
+        offline: false,
+        diarize: false,
+        chunkSeconds: 55,
+        filenameTemplate: "{title}",
+        audioQuality: "best",
+        keepAudio: false,
+        keepOriginalAudio: false,
+        parallelDownloads: 4,
+        concurrentFragments: 4,
+        retries: 10,
+        fragmentRetries: 10,
+        socketTimeout: 20,
+        downloadTimeoutSeconds: 1800,
+        convertTimeoutSeconds: 600,
+        asrChunkTimeoutSeconds: 180,
+    };
+}
+export async function writeDefaultConfig(path = defaultConfigPath()) {
+    const target = expandHome(path);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, `${JSON.stringify(defaultConfig(), null, 2)}\n`, "utf8");
+    return target;
+}