recap/GET-STARTED.md

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