feat(downloader): YouTube cookie auth for age-restricted videos

[Shironex]

Background

Users are reporting download and preview failures on age-restricted YouTube videos. The root cause was confirmed from a verbose yt-dlp -v run:

android_vr player response playability status: LOGIN_REQUIRED
web_embedded player response playability status: UNPLAYABLE
web_safari player response playability status: LOGIN_REQUIRED
ERROR: [youtube] <id>: Sign in to confirm your age.

yt-dlp already cycles through all its client impersonations (android_vr, web_embedded, web_safari) — every one is bounced by YouTube because the video requires a logged-in, age-verified session. This affects both the preview flow (downloader:get-stream-url) and the full download flow (downloader:download), and it's the dominant "works for some, fails for others" failure class in 2026.

As a quick fix we now classify the failure and surface a clear translated error ("This video is age-restricted…") in the UI. See the commit attached to this issue. The quick fix does not unlock the videos — it only tells the user why they failed. This issue tracks the real fix.

Proposed solution — browser cookie import

yt-dlp supports reading cookies directly from installed browsers via --cookies-from-browser BROWSER. If the user is already signed into YouTube in that browser and has confirmed their age once, yt-dlp pulls the session cookie automatically. No manual export, no cookies.txt wrangling. This is the standard pattern for desktop yt-dlp wrappers.

Supported browsers: firefox, chrome, edge, brave, safari (macOS only), chromium, opera, vivaldi.

Scope

• Add a "YouTube authentication" control to DownloadsSection.tsx (Settings → Downloads) with options:
  • None (default, current behavior)
  • Firefox / Chrome / Edge / Brave / Safari (macOS only)
  • Cookies file… → file picker for a cookies.txt (power-user fallback)
• Persist to electron-store under downloads.youtubeAuth: { kind: 'none' | 'browser' | 'file'; browser?: string; cookiesPath?: string }.
• New IPC handlers downloader:get-youtube-auth / downloader:set-youtube-auth.
• Build a shared helper getYouTubeAuthArgs(): string[] in apps/desktop/src/main/ipc/downloader.ts that reads the setting and returns the appropriate yt-dlp flags ([], ['--cookies-from-browser', 'firefox'], or ['--cookies', '<path>']).
• Splice it into all three yt-dlp invocation sites:
  • downloader:search (so search doesn't hide age-gated results)
  • downloader:get-stream-url (fixes preview)
  • downloader:download (fixes download)
• Update classifyYtDlpFailure age-restriction message to point the user at Settings when auth is not configured, and to a different "cookies may be stale / browser locked" message when it is configured.
• Add i18n strings (EN + PL) for all new Settings labels, dropdown options, error hints, and help text. Use namespace settings for labels and toast for error messages, consistent with the rest of the app.
• Tests:
  • Unit tests for getYouTubeAuthArgs() covering all three kind values
  • IPC handler tests asserting the args are spliced in based on store state
  • A test for the "cookies configured but still failing" error branch

Caveats to surface in the UI

• Chromium-family browsers (Chrome, Edge, Brave, Opera, Vivaldi) on Windows encrypt cookies with DPAPI and hold an exclusive lock on the cookies SQLite DB. yt-dlp can read them, but the browser must be closed at the time of the call. UI should warn the user: "Close Chrome before downloading, or use Firefox to avoid this."
• Firefox has no such lock — if it's installed, recommend it as the default.
• On macOS, Safari works out of the box but requires Full Disk Access permission.
• On Linux, only Firefox and Chromium are commonly supported — detection should gate the options list by platform.

UX details

• Default to None — do not touch user cookies without consent.
• On first save with a non-None option, run a silent validation call (yt-dlp --cookies-from-browser X --simulate --skip-download https://www.youtube.com/) to confirm yt-dlp can actually read the cookies, and show an inline success/error indicator.
• On failure during download, if auth is configured and yt-dlp still returns a LOGIN_REQUIRED or age-restricted error, prompt: "YouTube cookies appear to be stale or the browser is running. Close {browser} and retry, or refresh your YouTube sign-in."
• Consider adding a small inline "Fix this" deep-link from the age-restriction toast straight to the new Settings row.

Out of scope (for this issue)

• PO Token provider plugin support — yt-dlp debug output shows PO Token Providers: none. Some SABR-only videos need a PO token even with cookies. Adding a PO-token provider requires bundling a plugin or integrating yt-dlp-ejs. File as a separate issue once we see it bite users in the wild.
• Cross-platform cookie sync / shared profile — some users run multiple browsers; picking one is fine for v1.
• Auto-detect installed browsers — v1 can just list a static set and let the user pick.

Related quick-fix (already landed)

The diagnostic and error-classification groundwork is already in place, so this issue only needs to add the cookie flags and the Settings UI on top:

• classifyYtDlpFailure() + stable error codes (yt_dlp_age_restricted, yt_dlp_video_unavailable, yt_dlp_no_audio_format) in apps/desktop/src/main/ipc/downloader.ts
• translateYtDlpError() helper in apps/web/src/lib/ytdlpErrors.ts
• EN + PL translations in apps/web/src/locales/{en,pl}/toast.json
• Shared-logger fix so logger.error(..., err) actually serializes Error.message/stack instead of {}
• Stderr capture on yt-dlp failure in get-stream-url (previously discarded)
• Unit tests for classifyYtDlpFailure including the age-restriction detection path

References

• yt-dlp — --cookies-from-browser docs
• yt-dlp — Exporting YouTube cookies

[Shironex]

Tip

✅ Feature Feasibility: Confirmed (95% ██████████)

Property	Value
Type	Feature Request
Complexity	🟡 Medium
Confidence	95%
Effort Estimate	3–5 days for a single developer. Phase 1 (backend) is ~1.5 days, Phase 2 (frontend) is ~1 day, Phase 3 (i18n) is ~0.5 days, Phase 4 (tests) is ~1 day. The bulk of the work is wiring the new IPC handlers, the Settings UI dropdown, and ensuring the auth args are correctly spliced into all three invocation sites with proper test coverage.

Suggested Approach

Phase 1: Backend (electron main process)

1. Define the auth schema in apps/desktop/src/main/store.ts — add 'downloads.youtubeAuth': { kind: 'none' | 'browser' | 'file'; browser?: string; cookiesPath?: string } to StoreSchema. Default is { kind: 'none' }.

2. Create getYouTubeAuthArgs() helper in apps/desktop/src/main/ipc/downloader.ts:

   • Read store.get('downloads.youtubeAuth')
   • Return [] for kind: 'none'
   • Return ['--cookies-from-browser', browser] for kind: 'browser'
   • Return ['--cookies', cookiesPath] for kind: 'file'

3. Splice auth args into all three yt-dlp invocation sites:

   • downloader:search — prepend ...getYouTubeAuthArgs() to the args array passed to spawnYtDlp()
   • downloader:get-stream-url — same approach with spawnYtDlp()
   • downloader:download — splice into the local args array before spawn(getYtDlpPath(), args)

4. Add Zod schemas in apps/desktop/src/main/ipc/schemas/downloader.ts:

   • downloaderGetYoutubeAuthArgs = z.tuple([])
   • downloaderSetYoutubeAuthArgs = z.tuple([z.object({ kind: z.enum(['none', 'browser', 'file']), browser: z.string().optional(), cookiesPath: z.string().optional() })])

5. Register IPC handlers downloader:get-youtube-auth and downloader:set-youtube-auth in registerDownloaderHandlers(). On set, optionally run a silent validation (spawnYtDlp(['--cookies-from-browser', X, '--simulate', '--skip-download', 'https://www.youtube.com/'])) and return success/error.

6. Update classifyYtDlpFailure() to return a new error code (e.g., yt_dlp_age_restricted_auth_configured) when age-restriction is detected and store.get('downloads.youtubeAuth').kind !== 'none'. This enables the renderer to show a different, more helpful message.

7. Wire preload bridge in apps/desktop/src/main/preload.ts — add the two new channels to the allowlist and expose getYoutubeAuth() / setYoutubeAuth() on window.electronAPI.downloader.

Phase 2: Frontend (web/renderer)

8. Extend useDownloadsSettings.ts — add state for youtubeAuth, youtubeAuthValidating, youtubeAuthValid, and handlers handleSetYoutubeAuth() / handleValidateYoutubeAuth().

9. Add YouTube Authentication UI to DownloadsSection.tsx — place a new section after the download location panel:

   • Label: "YouTube authentication" with help text explaining the purpose
   • Dropdown: None, Firefox, Chrome, Edge, Brave, Safari (conditionally on macOS), Cookies file…
   • Selecting "Cookies file…" opens a file picker for cookies.txt
   • Inline success/error indicator after validation
   • Warning text for Chromium browsers ("Close Chrome before downloading")

10. Update translateYtDlpError() in apps/web/src/lib/ytdlpErrors.ts to handle the new yt_dlp_age_restricted_auth_configured code and map it to a "cookies stale / browser locked" message.

Phase 3: i18n + cleanup

11. Add EN + PL translations for:

    • settings.json → dl.youtubeAuth, dl.youtubeAuthDesc, dl.authNone, dl.authFirefox, dl.authChrome, etc., dl.authCookiesFile, dl.authBrowserWarning, dl.authValidating, dl.authValid, dl.authInvalid
    • toast.json → yt_dlp_age_restricted_auth_configured (stale/locked message), update yt_dlp_age_restricted to reference Settings

12. Update cleanup in cleanupDownloaderHandlers() to remove the two new handlers.

Phase 4: Tests

13. Unit tests for getYouTubeAuthArgs() — mock store.get to return each kind variant and assert the correct flag arrays.

14. IPC handler tests — assert that downloader:search, downloader:get-stream-url, and downloader:download handlers include auth args when the store has a non-none config.

15. Error branch test — verify that classifyYtDlpFailure() returns the auth_configured variant when the store indicates auth is set up.

Prerequisites

• Quick-fix error classification already landed (classifyYtDlpFailure, YT_DLP_ERROR_CODES, translateYtDlpError — all confirmed present)
• yt-dlp binary must be installed via the existing tool management flow (already handled by the app)
• electron-store dependency already in use for settings persistence

Potential Conflicts

• The downloader:download handler uses raw spawn() while search and get-stream-url use the spawnYtDlp() utility — auth args need to be injected in two different code paths, which could drift if not centralized
• The classifyYtDlpFailure() function currently takes only output: string — adding awareness of the auth config means either reading the store inside it (adding a side-effect to a pure function) or passing the config as a parameter (breaking existing call sites and tests)
• The preload allowlist in preload.ts is a string literal array — adding new channels must be done carefully to avoid TypeScript errors or missing the type definition
• Chromium cookie lock on Windows may cause confusing UX — yt-dlp will fail silently or with a vague error if the browser is open, which may not map cleanly to the existing error classification patterns

Affected Files (13)

File	Reason
apps/desktop/src/main/ipc/downloader.ts	Core implementation: add getYouTubeAuthArgs() helper, splice auth args into all 3 yt-dlp invocation sites (search, get-stream-url, download), add get/set-youtube-auth IPC handlers, update classifyYtDlpFailure to emit context-aware error codes
apps/desktop/src/main/store.ts	Add 'downloads.youtubeAuth' key to StoreSchema with type { kind: 'none' | 'browser' | 'file'; browser?: string; cookiesPath?: string }
apps/desktop/src/main/ipc/schemas/downloader.ts	Add Zod schemas for downloader:get-youtube-auth and downloader:set-youtube-auth IPC handlers
apps/desktop/src/main/utils/ytdlp-spawn.ts	Consider injecting auth args centrally in spawnYtDlp() or have callers pass them in — this utility is used by search and get-stream-url
apps/desktop/src/main/preload.ts	Expose getYoutubeAuth/setYoutubeAuth methods on window.electronAPI.downloader, add to allowed IPC channels list
apps/web/src/components/settings/downloads/DownloadsSection.tsx	Add YouTube Authentication control UI section (dropdown for None/browser/file, file picker, validation indicator, warning text)
apps/web/src/components/settings/downloads/useDownloadsSettings.ts	Add state/handlers for YouTube auth setting: youtubeAuth, handleSetYoutubeAuth, validation state
apps/web/src/lib/ytdlpErrors.ts	Update translateYtDlpError() to support context-aware age-restriction messages (auth configured vs not configured)
apps/web/src/locales/en/toast.json	Add new error strings for auth-configured-but-stale scenario, update age-restriction message to reference Settings
apps/web/src/locales/pl/toast.json	Add Polish translations for new auth error strings
apps/web/src/locales/en/settings.json	Add new i18n strings under dl.* namespace for YouTube auth labels, dropdown options, help text, warnings
apps/web/src/locales/pl/settings.json	Add Polish translations for all new settings labels
apps/desktop/src/main/ipc/downloader.test.ts	Add unit tests for getYouTubeAuthArgs() (all 3 kind values), IPC handler tests for auth args splicing, and stale-cookies error branch test

Code Evidence (13 files)

apps/desktop/src/main/ipc/downloader.ts — Core implementation: add getYouTubeAuthArgs() helper, splice auth args into all 3 yt-dlp invocation sites (search, get-stream-url, download), add get/set-youtube-auth IPC handlers, update classifyYtDlpFailure to emit context-aware error codes

  handle(
    'downloader:search',
    async (_event, query: string) => {
      logger.info(`[downloader] Searching: ${query}`);
      const { stdout, code } = await spawnYtDlp([
        '--flat-playlist',
        '--dump-json',
        '--no-warnings',
        `ytsearch10:${query}`,
      ]);

      if (code !== 0) {
        throw new Error('yt-dlp search failed');
      }

apps/desktop/src/main/store.ts — Add 'downloads.youtubeAuth' key to StoreSchema with type { kind: 'none' | 'browser' | 'file'; browser?: string; cookiesPath?: string }

export interface StoreSchema {
  // Renderer-owned blob; read by discord-rpc.ts for `discordRpc` flag.
  settings: Record<string, unknown>;

  // Main-only (downloader.ts).
  'downloads.location': string;
  'downloads.toolStatusCache': ToolStatusCache;
}

apps/desktop/src/main/ipc/schemas/downloader.ts — Add Zod schemas for downloader:get-youtube-auth and downloader:set-youtube-auth IPC handlers

export const downloaderCheckArgs = z.tuple([]);
export const downloaderGetDownloadLocationArgs = z.tuple([]);
export const downloaderSetDownloadLocationArgs = z.tuple([
  z.union([z.string(), z.null()]),
]);
export const downloaderSearchArgs = z.tuple([nonEmpty]);

apps/desktop/src/main/utils/ytdlp-spawn.ts — Consider injecting auth args centrally in spawnYtDlp() or have callers pass them in — this utility is used by search and get-stream-url

export function spawnYtDlp(
  args: string[]
): Promise<{ stdout: string; stderr: string; code: number }> {
  return new Promise((resolve, reject) => {
    const proc = spawn(getYtDlpPath(), args, { env: { ...process.env } });

apps/desktop/src/main/preload.ts — Expose getYoutubeAuth/setYoutubeAuth methods on window.electronAPI.downloader, add to allowed IPC channels list

  downloader: {
    getStreamUrl: (url: string) => Promise<string>;
    suggest: (query: string) => Promise<string[]>;
    search: (query: string) => Promise<Array<{...}>>;
    download: (url: string) => Promise<string>;

apps/web/src/components/settings/downloads/DownloadsSection.tsx — Add YouTube Authentication control UI section (dropdown for None/browser/file, file picker, validation indicator, warning text)

export function DownloadsSection() {
  const { t } = useTranslation('settings');
  const s = useDownloadsSettings();
  // ... existing tool status rows, download location panel
}

apps/web/src/components/settings/downloads/useDownloadsSettings.ts — Add state/handlers for YouTube auth setting: youtubeAuth, handleSetYoutubeAuth, validation state

export function useDownloadsSettings() {
  const [ytdlpInstalled, setYtdlpInstalled] = useState<boolean | null>(null);
  // ... existing state
  return { /* existing + new youtube auth fields */ };
}

apps/web/src/lib/ytdlpErrors.ts — Update translateYtDlpError() to support context-aware age-restriction messages (auth configured vs not configured)

export function translateYtDlpError(raw: string): string {
  if (YT_DLP_ERROR_KEYS.has(raw)) {
    return i18n.t(raw, { ns: 'toast' });
  }
  return raw;
}

apps/web/src/locales/en/toast.json — Add new error strings for auth-configured-but-stale scenario, update age-restriction message to reference Settings

"yt_dlp_age_restricted": "This video is age-restricted. YouTube requires sign-in cookies to play or download it (not yet supported)."

apps/web/src/locales/pl/toast.json — Add Polish translations for new auth error strings

"yt_dlp_age_restricted": "Ten film ma ograniczenie wiekowe. YouTube wymaga plików cookie zalogowanego użytkownika do jego odtworzenia lub pobrania (funkcja jeszcze nieobsługiwana)."

apps/web/src/locales/en/settings.json — Add new i18n strings under dl.* namespace for YouTube auth labels, dropdown options, help text, warnings

"dl": {
    "title": "Downloads",
    "subtitle": "yt-dlp integration for searching and downloading music",
    // ... add youtubeAuth*, browserWarning*, etc.
  }

apps/web/src/locales/pl/settings.json — Add Polish translations for all new settings labels

"dl": { ... }

apps/desktop/src/main/ipc/downloader.test.ts — Add unit tests for getYouTubeAuthArgs() (all 3 kind values), IPC handler tests for auth args splicing, and stale-cookies error branch test

describe('classifyYtDlpFailure', () => {
  it('detects age-restricted videos from yt-dlp error output', () => {
    // ... existing tests, add new context-aware ones
  });
});

Reasoning

Evidence: The quick-fix groundwork is already landed. The classifyYtDlpFailure() function in apps/desktop/src/main/ipc/downloader.ts (lines 237–258) already detects age-restriction failures via sign in to confirm your age, login_required, and age-restricted patterns. The error codes (YT_DLP_ERROR_CODES.AGE_RESTRICTED) are already wired through to translateYtDlpError() in apps/web/src/lib/ytdlpErrors.ts, and EN+PL translation strings exist in both toast.json files — the EN string explicitly says "(not yet supported)".

Evidence: Three yt-dlp invocation sites are confirmed and locatable. The issue correctly identifies three sites:

1. downloader:search at line 395 in downloader.ts — uses spawnYtDlp() from apps/desktop/src/main/utils/ytdlp-spawn.ts
2. downloader:get-stream-url at line 578 — also uses spawnYtDlp()
3. downloader:download at line 493 — uses raw spawn(getYtDlpPath(), args) directly

All three build an args array that currently has no cookie/auth flags. The spawnYtDlp() utility in ytdlp-spawn.ts accepts args: string[] and forwards them to spawn(), making injection of auth flags straightforward.

Evidence: electron-store infrastructure supports the proposed persistence pattern. The StoreSchema in apps/desktop/src/main/store.ts already has main-only keys like downloads.location and downloads.toolStatusCache. Adding downloads.youtubeAuth follows the exact same pattern — a main-only key that downloader.ts reads directly without going through the renderer store allowlist. The IPC store gate in apps/desktop/src/main/ipc/schemas/store.ts has a documented pattern for adding both renderer-accessible and main-only keys.

Evidence: The Settings UI has a clean extension point. DownloadsSection.tsx is well-structured with sub-components (ToolStatusRow, DownloadLocationPanel, etc.) and a useDownloadsSettings hook that cleanly separates state/logic from presentation. A new "YouTube Authentication" section can slot in between the download location panel and the tool version blocks.

Evidence: The IPC handler registration pattern is well-established. The handle() / handleWithFallback() wrappers in with-ipc-handler.ts, schema validation via Zod in schemas/downloader.ts, and the preload bridge in preload.ts (type-safe window.electronAPI.downloader.*) provide a clear template for adding downloader:get-youtube-auth and downloader:set-youtube-auth handlers.

Evidence: The error-message upgrade path is clear. The current yt_dlp_age_restricted toast message says "not yet supported". The issue proposes context-aware messages: when auth is not configured, point to Settings; when it is configured but fails, suggest "cookies stale / browser locked". This requires classifyYtDlpFailure() to accept the current auth config as context, or the renderer-side translateYtDlpError() to check the store state before selecting the translation key.

Evidence: The download handler uses raw spawn() not spawnYtDlp(). The downloader:download handler (line 493) spawns yt-dlp directly via spawn(getYtDlpPath(), args) rather than the spawnYtDlp() utility. Auth args will need to be spliced into the local args array there. This is not a blocker, just a detail for implementation.

---

via GitChorus