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,198 @@
+# YouTube Transcript Summarizer — Mac Setup Guide
+
+This is a step-by-step guide to get the app running on your Mac. No prior experience with servers or Terminal needed.
+
+---
+
+## What you're setting up
+
+This app has two parts:
+
+1. **A small server** that runs locally on your Mac (not on the internet — only you can access it). It downloads YouTube audio and talks to Google's Gemini AI.
+2. **A webpage** you open in your browser that connects to that local server.
+
+Nothing is uploaded anywhere. Everything runs on your machine.
+
+---
+
+## Where to save the project
+
+The `youtube-summarizer` folder you downloaded from Cowork can live anywhere, but the conventional place for projects like this on a Mac is:
+
+```
+~/Projects/youtube-summarizer
+```
+
+`~` means your home folder (e.g., `/Users/grant`). If you don't have a `Projects` folder yet, you'll create one below.
+
+**To move the files there:**
+
+1. Open **Finder**
+2. Go to your home folder (press `Cmd + Shift + H`)
+3. Create a new folder called `Projects` if you don't have one (right-click → New Folder)
+4. Drag the `youtube-summarizer` folder from your Cowork downloads into `Projects`
+
+You should end up with this structure:
+
+```
+~/Projects/youtube-summarizer/
+├── public/
+│   └── index.html          ← the app you open in your browser
+├── server/
+│   ├── index.js             ← the backend server code
+│   └── package.json         ← lists the server's dependencies
+├── setup.sh                 ← automatic setup script
+└── GET-STARTED.md           ← this file
+```
+
+---
+
+## Step 1: Install Node.js (if you don't have it)
+
+Node.js is what runs the server. Check if you already have it:
+
+1. Open **Terminal** (press `Cmd + Space`, type "Terminal", hit Enter)
+2. Type this and press Enter:
+
+```bash
+node --version
+```
+
+- If you see a version number like `v20.11.0` → you're good, skip to Step 2
+- If you see "command not found" → install it:
+  1. Go to **https://nodejs.org**
+  2. Download the **LTS** version (the green button)
+  3. Open the downloaded `.pkg` file and follow the installer
+  4. Close and reopen Terminal, then try `node --version` again
+
+---
+
+## Step 2: Run the setup script
+
+This installs yt-dlp (the YouTube audio downloader) and the server's dependencies. In Terminal:
+
+```bash
+cd ~/Projects/youtube-summarizer
+bash setup.sh
+```
+
+You should see checkmarks for Node.js, yt-dlp, and the server dependencies. If yt-dlp isn't found and can't auto-install, run:
+
+```bash
+brew install yt-dlp
+```
+
+(If you don't have Homebrew either, install it first from **https://brew.sh** — it's a one-line Terminal command shown on their homepage.)
+
+---
+
+## Step 3: Start the server
+
+```bash
+cd ~/Projects/youtube-summarizer/server
+npm start
+```
+
+You should see:
+
+```
+  YouTube Summarizer API running on http://localhost:3001
+  ✓  yt-dlp 2025.x.x (up to date)
+```
+
+**Leave this Terminal window open.** The server runs as long as this window is open. To stop it later, press `Ctrl + C`.
+
+---
+
+## Step 4: Open the app
+
+Open the webpage in your browser. The easiest way — open a **new** Terminal tab (`Cmd + T`) and run:
+
+```bash
+open ~/Projects/youtube-summarizer/public/index.html
+```
+
+Or just double-click `index.html` in Finder. It opens like any webpage.
+
+---
+
+## Step 5: Add your Gemini API key
+
+1. In the app, click **"Gemini API Settings"** to expand it
+2. Paste your Gemini API key into the API Key field
+3. Pick a model (the default `gemini-2.0-flash` is fast and cheap)
+
+**Don't have a key yet?** Get one free:
+1. Go to **https://aistudio.google.com/apikey**
+2. Sign in with your Google account
+3. Click "Create API Key"
+4. Copy the key and paste it in the app
+
+Your key is saved in your browser's localStorage so you don't have to re-enter it each time.
+
+---
+
+## Step 6: Summarize a video
+
+1. Paste a YouTube URL
+2. Click **Summarize**
+3. Watch the 3-step pipeline: Download audio → Transcribe → Analyze topics
+4. Click any topic section to expand the full transcript with clickable timestamps
+
+---
+
+## Day-to-day usage
+
+Each time you want to use the app:
+
+1. Open Terminal
+2. Run:
+```bash
+cd ~/Projects/youtube-summarizer/server && npm start
+```
+3. Open `index.html` in your browser (bookmark it for easy access)
+4. When done, press `Ctrl + C` in Terminal to stop the server
+
+That's it. Two commands.
+
+---
+
+## Troubleshooting
+
+**"Cannot connect to backend at localhost:3001"**
+→ The server isn't running. Go back to Step 3.
+
+**"yt-dlp not installed"**
+→ Run `brew install yt-dlp` in Terminal, then restart the server.
+
+**Download fails or hangs**
+→ yt-dlp might be outdated. The app will try to auto-update it, but you can also manually run:
+```bash
+yt-dlp -U
+```
+
+**"Gemini API error: 403" or "401"**
+→ Your API key is invalid or expired. Get a new one from https://aistudio.google.com/apikey
+
+**Long videos take a while**
+→ Normal. A 1-hour video takes ~30 seconds to download audio, then 30-60 seconds for Gemini to transcribe, then another 10-20 seconds for topic analysis. The app shows live progress.
+
+---
+
+## Optional: Make it even easier to start
+
+You can create a shortcut so you just double-click to launch everything. In Terminal:
+
+```bash
+cat > ~/Projects/youtube-summarizer/start.command << 'EOF'
+#!/bin/bash
+cd "$(dirname "$0")/server"
+echo "Starting YouTube Summarizer..."
+echo "Press Ctrl+C to stop."
+echo ""
+npm start
+EOF
+chmod +x ~/Projects/youtube-summarizer/start.command
+```
+
+Now you have a `start.command` file in the project folder. Double-click it to launch the server — it opens Terminal automatically. Then just open `index.html` in your browser.