documentation

2026-03-23 16:17:01 -04:00
parent c7110fbbe7
commit 53b3a644a1
12 changed files with 1518 additions and 157 deletions
@@ -0,0 +1,72 @@
+# 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. |