# 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:

```yaml
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. |