Add StartOS 0.4.0 packaging

2026-04-09 15:03:31 -05:00
commit 68ec875ee7
2057 changed files with 490924 additions and 0 deletions
@@ -0,0 +1,114 @@
+# 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.