recap/start9/0.4/instructions.md

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