# YouTube Summarizer (StartOS)

## What This Package Does

YouTube Summarizer downloads audio from YouTube videos and podcast RSS feeds,
transcribes them using Google Gemini AI, and produces structured topic summaries
with timestamps. It supports channel subscriptions with automatic new episode
detection and an organized history with folders.

## Requirements

You need a **Google Gemini API key** to use this service. A free tier is
available:

1. Go to [aistudio.google.com/apikey](https://aistudio.google.com/apikey)
2. Sign in with your Google account
3. Click "Create API Key"
4. Copy the key

## First Launch

1. Open the service web UI from StartOS.
2. Click the **Settings** icon (gear) in the top-right.
3. Paste your Gemini API key and save.
4. You're ready to summarize! Paste a YouTube URL and click **Summarize**.

## YouTube Authentication (Recommended)

For reliable YouTube downloads, set up authentication using **one** of these
methods:

### Option A: OAuth2 (Recommended — lasts indefinitely)

1. In the web UI, go to **Settings > YouTube Authentication**.
2. Click **Start OAuth Setup**.
3. You'll see a device code and a URL.
4. On any device (phone, laptop), go to the URL and enter the code.
5. Sign in with your Google account when prompted.
6. The token is saved and will be used for all future downloads.

### Option B: Cookies File (expires every 3-5 days)

1. On your computer, export YouTube cookies from your browser using a
   cookies.txt browser extension.
2. In the web UI, go to **Settings > YouTube Authentication**.
3. Click **Upload cookies.txt** and select the file.
4. Click **Test Cookies** to verify they work.

Note: YouTube cookies expire quickly (3-5 days). You will need to re-export
and re-upload them regularly. OAuth2 is strongly recommended instead.

## Subscriptions

Add YouTube channels and podcast RSS feeds to automatically discover new
episodes:

1. Click **Subscriptions** in the sidebar.
2. Click **Add Subscription**.
3. Paste a YouTube channel URL or podcast RSS feed URL.
4. New episodes will appear in the **Queue** tab for your approval.
5. Click **Approve** to send items to the background processor, or
   **Approve All** to queue everything at once.

### Auto-Download

For subscriptions you always want processed, enable **Auto-Download**:

1. In the **Subscriptions** list, toggle **Auto-Download** on for a subscription.
2. New episodes from that subscription will be automatically approved and
   processed in the background — no manual approval needed.

### Background Processing Queue

Approved items are processed one at a time with a configurable delay between
each (default: 5 minutes) to avoid triggering YouTube's rate limits.

- **Rush Mode**: If you want the next item processed immediately (no delay),
  use the Rush button in the Queue panel.
- **Configure Delay**: Adjust the delay between items in Settings > Processing.
  Longer delays (5-10 minutes) are safer; shorter delays risk YouTube blocks.
- **Pause/Resume**: You can pause background processing entirely and resume
  when ready.

## Updating yt-dlp

YouTube frequently changes its download systems. If downloads start failing:

1. Go to **StartOS > YouTube Summarizer > Actions**.
2. Click **Update yt-dlp**.
3. Wait for the update to complete.
4. Try your download again.

The service also checks for yt-dlp updates automatically every 24 hours.

## Data & Backups

All your data (summaries, subscriptions, settings) is stored in the StartOS
service volume and included in StartOS backups. Your Gemini API key is stored
locally on this server and is never transmitted anywhere except to the Google
Gemini API for processing.

## Troubleshooting

**"No API key provided"** — Enter your Gemini API key in Settings.

**"Download failed"** — YouTube may be rate-limiting. Wait a few minutes and
try again. If persistent, run the "Update yt-dlp" action.

**"Sign in to confirm you're not a bot"** — Set up YouTube authentication
(OAuth2 or cookies) in Settings.

**Summaries seem truncated** — Very long videos (3+ hours) are automatically
split into chunks for transcription. If chunks are still truncated, try a
different Gemini model in Settings.