Main/docs/features/youtube-auth.md

YouTube Authentication

Shanty downloads music from YouTube via yt-dlp. By default, it makes requests as a guest, which limits you to roughly 250 downloads per hour. Authenticating with a Google account increases this to roughly 1800 downloads per hour and grants access to age-restricted content.

Should you set this up?

If you are downloading just a few albums at a time, guest mode is fine. If you are adding several artists at once or building a large library, authentication will save you a lot of waiting.

Warning: Use a throwaway account

There is a small but real risk that Google may flag your account for unusual activity. Automated downloading is against YouTube's terms of service. To protect yourself:

• Create a new Google account specifically for this purpose.
• Do not use your main Google account.
• Do not use an account tied to important services (Gmail, Google Drive, etc.).

How to set up

1. Open the Shanty web UI and go to Settings.
2. Scroll to the YouTube Authentication section.
3. Click Authenticate.
4. A noVNC browser window opens, showing Firefox inside the Shanty container.
5. Navigate to YouTube and log in with your throwaway Google account.
6. Once you are logged in, go back to the Shanty settings page and click Done.

Shanty extracts the YouTube cookies from Firefox and saves them. From this point forward, all downloads use your authenticated session.

Docker port requirement

The noVNC interface runs on port 6080 by default. Your docker-compose.yml must expose this port:

ports:
  - "8085:8085"
  - "6080:6080"  # Required for YouTube login

If you are running Shanty on a remote server, you need to access noVNC from your browser at http://your-server-ip:6080. Make sure firewalls allow this port during the login process. You can close the port afterward if you want -- it is only needed during initial login and manual re-authentication.

The noVNC port is configurable via download.vnc_port in the config file.

How auto-refresh works

YouTube cookies expire roughly every 2 weeks. Shanty automatically refreshes them using headless Firefox (no visible browser window needed):

• After you complete the login process, auto-refresh is enabled automatically.
• Every 6 hours (configurable via download.cookie_refresh_hours), Shanty launches Firefox in headless mode, loads YouTube using the saved profile, and exports fresh cookies.
• If a refresh fails, Shanty logs a warning and tries again at the next interval.

You can check the current cookie status in Settings under YouTube Authentication. It shows whether cookies are present, how old they are, and whether auto-refresh is enabled.

Manual refresh

If cookies have expired and auto-refresh is not working, you can:

1. Click Refresh in the YouTube Authentication settings to trigger an immediate headless refresh.
2. If that fails, click Authenticate to log in again through noVNC.

Clearing cookies

To remove all YouTube authentication data, click Clear in the YouTube Authentication settings. This deletes the cookies file and the Firefox profile, and disables auto-refresh.

Configuration options

Option	Default	Description
download.cookies_path	(auto)	Path to the cookies file. Managed automatically.
download.cookie_refresh_enabled	false	Auto-enabled after login.
download.cookie_refresh_hours	6	Hours between refresh attempts.
download.rate_limit	250	Requests/hour without cookies.
download.rate_limit_auth	1800	Requests/hour with cookies.
download.vnc_port	6080	Port for the noVNC login interface.