Connor Johnstone
59 lines
3.1 KiB
Markdown
59 lines
3.1 KiB
Markdown
# 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.
|
|
|
|
## 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. |
|