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:

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:

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:

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

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:

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:

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:

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:

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.