Shanty/Main
1
0
Fork 0
Code Issues 18 Pull Requests Actions Packages Projects Releases Wiki Activity

Streamline YouTube Music cookie management for better UX #40

New Issue
Closed
opened 2026-03-19 14:52:53 -04:00 by connor · 0 comments
connor commented 2026-03-19 14:52:53 -04:00
Owner
Copy Link

Currently, yt-dlp authentication requires users to manually export cookies from their browser to a Netscape-format cookies.txt file and configure the path in config.yaml. This is tedious, error-prone, and the cookies expire regularly — requiring users to repeat the
process.

Authenticated access is important: it raises the rate limit from ~500/hr to ~2000/hr and is required for some age-restricted or region-locked content.

Research needed

Investigate the best approach from these options:

Option A: Browser cookie extraction

  • Tools like yt-dlp --cookies-from-browser chrome can extract cookies directly from an installed browser
  • Could add a config option cookies_from_browser: chrome|firefox|edge that passes the flag to yt-dlp
  • Pros: Zero manual steps, always fresh cookies
  • Cons: Only works if the server has a browser with an active YouTube login (unlikely for Docker/headless deployments)

Option B: OAuth token flow

  • yt-dlp supports --username and --password for some extractors
  • YouTube has moved to OAuth — yt-dlp has experimental --username oauth2 support that opens a device auth flow
  • Could trigger this from the web UI: user clicks "Authenticate YouTube" → backend starts OAuth flow → shows device code → user approves on their phone
  • Pros: Clean UX, works headless
  • Cons: Experimental in yt-dlp, may break

Option C: Cookie paste in web UI

  • Add a textarea in Settings where users can paste their cookies.txt content directly
  • Backend saves it to the configured path
  • Could also accept cookies exported via browser extensions (EditThisCookie, Cookie-Editor export as Netscape format)
  • Pros: Works everywhere, simple implementation
  • Cons: Still requires manual browser extension step

Option D: Browser extension integration

  • Provide instructions for a cookie export extension
  • Add an API endpoint that accepts cookies via POST (from a bookmarklet or extension)
  • User visits YouTube Music, clicks bookmarklet, cookies are sent to Shanty
  • Pros: Relatively smooth UX
  • Cons: Requires initial setup, security considerations

Option E: Automatic refresh via ytmusicapi OAuth

  • ytmusicapi (the Python library we already use for search) has its own OAuth flow: ytmusicapi oauth
  • This generates a persistent oauth.json token that auto-refreshes
  • We could use ytmusicapi's auth for both search AND pass cookies to yt-dlp
  • Pros: One auth flow for both search and download, auto-refreshing
  • Cons: Need to investigate if ytmusicapi's auth token works with yt-dlp

Acceptance criteria

  • Research which option(s) are viable for headless/Docker deployments
  • Implement the chosen approach
  • Authentication status visible in the web UI (Settings page: "YouTube: Authenticated" / "Not authenticated")
  • Clear instructions or guided flow for users to set up auth
  • Rate limit automatically adjusts when authenticated
  • Cookies/tokens persist across container restarts (via volume mount)

Dependencies

  • yt-dlp OAuth support status
  • ytmusicapi OAuth capabilities
  • Current cookie handling in shanty-dl/src/ytdlp.rs and config download.cookies_path
Currently, yt-dlp authentication requires users to manually export cookies from their browser to a Netscape-format cookies.txt file and configure the path in config.yaml. This is tedious, error-prone, and the cookies expire regularly — requiring users to repeat the process. Authenticated access is important: it raises the rate limit from ~500/hr to ~2000/hr and is required for some age-restricted or region-locked content. Research needed Investigate the best approach from these options: Option A: Browser cookie extraction - Tools like yt-dlp --cookies-from-browser chrome can extract cookies directly from an installed browser - Could add a config option cookies_from_browser: chrome|firefox|edge that passes the flag to yt-dlp - Pros: Zero manual steps, always fresh cookies - Cons: Only works if the server has a browser with an active YouTube login (unlikely for Docker/headless deployments) Option B: OAuth token flow - yt-dlp supports --username and --password for some extractors - YouTube has moved to OAuth — yt-dlp has experimental --username oauth2 support that opens a device auth flow - Could trigger this from the web UI: user clicks "Authenticate YouTube" → backend starts OAuth flow → shows device code → user approves on their phone - Pros: Clean UX, works headless - Cons: Experimental in yt-dlp, may break Option C: Cookie paste in web UI - Add a textarea in Settings where users can paste their cookies.txt content directly - Backend saves it to the configured path - Could also accept cookies exported via browser extensions (EditThisCookie, Cookie-Editor export as Netscape format) - Pros: Works everywhere, simple implementation - Cons: Still requires manual browser extension step Option D: Browser extension integration - Provide instructions for a cookie export extension - Add an API endpoint that accepts cookies via POST (from a bookmarklet or extension) - User visits YouTube Music, clicks bookmarklet, cookies are sent to Shanty - Pros: Relatively smooth UX - Cons: Requires initial setup, security considerations Option E: Automatic refresh via ytmusicapi OAuth - ytmusicapi (the Python library we already use for search) has its own OAuth flow: ytmusicapi oauth - This generates a persistent oauth.json token that auto-refreshes - We could use ytmusicapi's auth for both search AND pass cookies to yt-dlp - Pros: One auth flow for both search and download, auto-refreshing - Cons: Need to investigate if ytmusicapi's auth token works with yt-dlp Acceptance criteria - Research which option(s) are viable for headless/Docker deployments - Implement the chosen approach - Authentication status visible in the web UI (Settings page: "YouTube: Authenticated" / "Not authenticated") - Clear instructions or guided flow for users to set up auth - Rate limit automatically adjusts when authenticated - Cookies/tokens persist across container restarts (via volume mount) Dependencies - yt-dlp OAuth support status - ytmusicapi OAuth capabilities - Current cookie handling in shanty-dl/src/ytdlp.rs and config download.cookies_path
connor added the MediumPriority label 2026-03-19 14:53:01 -04:00
connor started working 2026-03-20 11:37:37 -04:00
connor worked for 2 hours 1 minute 2026-03-20 13:39:21 -04:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
LowPriority
MediumPriority
HighPriority
MVP
No Label MediumPriority
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
connor
No Assignees
1 Participants
Notifications
Total Time Spent: 2 hours 1 minute
connor
2 hours 1 minute
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Shanty/Main#40
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?