GEMINI.md - Project Instructions for Gemini AI

# GEMINI.md - Project Instructions for Gemini AI

> **This file provides persistent context to Gemini CLI about the yt-gemini-summarizer project.**

---

## 🎯 Project Overview

**yt-gemini-summarizer** is a premium YouTube transcript fetcher and AI summarizer designed to work seamlessly with Gemini CLI in VS Code. It allows users to:

1. Fetch transcripts from any YouTube video
2. Generate stunning, well-structured summaries using Gemini AI
3. Use the custom `/ytsum` slash command for instant summaries

---

## 📁 Project Structure

```
yt-gemini-summarizer/
├── package.json           # Node.js dependencies and scripts
├── ytsum.js               # Main CLI entry point (run with node)
├── src/
│   ├── getTranscript.js   # YouTube transcript fetching logic
│   ├── formatTranscript.js # Transcript formatting utilities
│   └── summaryPrompt.js   # AI prompt templates for summaries
├── .gemini/
│   └── commands/
│       └── ytsum.toml     # Custom /ytsum slash command definition
├── output/                # Generated summaries and transcripts
├── transcripts/           # Raw saved transcripts
├── README.md              # User documentation
├── GEMINI.md              # This file - Gemini AI instructions
├── .gitignore
└── .env.example
```

---

## 🚀 How to Use /ytsum Command

When a user types `/ytsum <url>`, you should:

### Step 1: Check if transcript exists
Look for the transcript file in:
- `output/transcript-{VIDEO_ID}.txt`
- `transcripts/transcript-{VIDEO_ID}.txt`

### Step 2: If transcript doesn't exist
Run the CLI tool to fetch it:
```bash
node ytsum.js <url>
```

### Step 3: Read the transcript
Read the full contents of the transcript file.

### Step 4: Generate the summary
Create a premium summary following the exact format below.

---

## 📝 Summary Format Specification

When creating a YouTube summary, ALWAYS use this structure:

```markdown
# 📺 YouTube Video Summary

> **[One-liner that captures the video's entire value proposition]**

**🔗 Video:** [Watch on YouTube](URL)

---

## 🎯 TL;DR
[2-3 sentences that perfectly summarize the video]

---

## 📋 Key Takeaways
1. **Point** — Explanation
2. **Point** — Explanation
3. **Point** — Explanation
4. **Point** — Explanation
5. **Point** — Explanation

---

## 🕐 Video Chapters
| Time | Chapter | Description |
|------|---------|-------------|
| [0:00](url&t=0) | 🎬 Intro | ... |

---

## 💬 Notable Quotes
> "Quote" — *[Timestamp]*

---

## ✅ Action Items
- [ ] Action 1
- [ ] Action 2

---

## 💻 Code & Technical Details
```language
code here
```

---

## 🔗 Resources Mentioned
- Resource with description

---

## 📝 Quick Reference Card
| Concept | Explanation |
|---------|------------|

---

*Summary generated by yt-gemini-summarizer*
```

---

## 📏 Formatting Rules

### Timestamps
- Always format as `[MM:SS]` or `[HH:MM:SS]` for longer videos
- Make timestamps clickable: `[5:30](https://youtube.com/watch?v=ID&t=330)`
- Include timestamps at natural topic transitions

### Code Blocks
- Use proper language identifiers: ```javascript, ```python, ```bash
- Include full, runnable code when possible
- Add comments explaining complex parts

### Quotes
- Use exact words from the transcript when possible
- Always include the timestamp
- Bold or emphasize key phrases

### Key Points
- Be specific, not vague
- Include numbers and details
- Make them actionable when possible

### Tables
- Use tables for comparisons, timelines, and reference cards
- Keep column headers concise
- Align content appropriately

---

## 🎨 Style Guidelines

### Tone
- Professional but accessible
- Engaging and helpful
- Concise but comprehensive

### Visual Elements
- Use emojis sparingly for section headers
- Create visual hierarchy with headers
- Use horizontal rules to separate sections

### Quality Standards
- Every summary should be **immediately useful**
- Include **specific details**, not generalizations
- Make key information **scannable**
- Provide **actionable insights**

---

## 🔧 Common Commands

### Fetch transcript only
```bash
node ytsum.js https://youtu.be/VIDEO_ID
```

### Fetch with summary prompt
```bash
node ytsum.js --summary https://youtu.be/VIDEO_ID
```

### Generate voice-over audio
```bash
node ytsum.js --voice https://youtu.be/VIDEO_ID
```

### Voice-over with custom settings
```bash
node ytsum.js --voice --voice-model fast --voice-speed 1.2 https://youtu.be/VIDEO_ID
```

### Using slash command
```
/ytsum https://youtu.be/VIDEO_ID
```

### Read existing transcript
```
Read the transcript at output/transcript-VIDEO_ID.txt and summarize it
```

---

## 🎤 Voice-Over Feature (Coqui TTS)

The project includes voice-over generation using Coqui TTS:

### Available Voice Models
| Model | Description |
|-------|-------------|
| `default` | Clear female voice (LJSpeech) |
| `male` | Natural male voice |
| `fast` | Fast synthesis, good quality |
| `multilingual` | Multi-language support |
| `expressive` | Multi-speaker expressive |

### Setup
```bash
./setup-coqui.sh
# or: pip install TTS
```

### Output Files
- `output/voiceover-{VIDEO_ID}.wav` — Generated audio file

---

## 📌 Important Notes for Gemini

1. **Always prefer local transcript files** over fetching new ones if they exist
2. **Save summaries** to `output/summary-{VIDEO_ID}.md`
3. **Handle errors gracefully** - if transcript fetch fails, explain why and suggest alternatives
4. **Extract VIDEO_ID** from various URL formats:
   - `https://www.youtube.com/watch?v=VIDEO_ID`
   - `https://youtu.be/VIDEO_ID`
   - `https://youtube.com/embed/VIDEO_ID`
   - `https://youtube.com/shorts/VIDEO_ID`
   - Just `VIDEO_ID` (11 characters)

5. **Video ID is always 11 characters** containing: `a-z`, `A-Z`, `0-9`, `-`, `_`

---

## 🎯 Summary Quality Checklist

Before finalizing any summary, ensure:

- [ ] TL;DR captures the essence in 2-3 sentences
- [ ] At least 5 key takeaways are listed
- [ ] Chapters have proper timestamps
- [ ] Notable quotes are real (from transcript)
- [ ] Action items are specific and achievable
- [ ] Code examples are properly formatted
- [ ] Resources are accurately listed
- [ ] Quick reference provides real value
- [ ] All timestamps are clickable links
- [ ] Formatting is consistent throughout

---

## 🛠 Troubleshooting

### "No transcript found"
- Video may not have captions
- Try different language: `node ytsum.js --lang es <url>`
- Some videos disable captions

### "Private video"
- Cannot access private videos
- Video must be public or unlisted

### "Age restricted"
- Age-restricted videos need authentication
- Not supported in this tool

### "Network error"
- Check internet connection
- Try again in a few moments

---

## 📚 Examples

### Example 1: Tech Tutorial
```
/ytsum https://youtu.be/dQw4w9WgXcQ
```

### Example 2: Just Video ID
```
/ytsum dQw4w9WgXcQ
```

### Example 3: Full URL
```
/ytsum https://www.youtube.com/watch?v=dQw4w9WgXcQ&list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf
```

---

## 🏆 Best Practices

1. **Read the entire transcript** before summarizing
2. **Identify the main argument** or purpose of the video
3. **Note timestamps** of important moments while reading
4. **Extract verbatim quotes** rather than paraphrasing
5. **Create logical chapters** based on topic changes
6. **Highlight actionable content** prominently
7. **Format code properly** with language hints
8. **Make it scannable** — someone should get value in 30 seconds

---

*This project is designed to make YouTube content accessible and summarizable through Gemini AI. Always aim for the highest quality summaries that save users time while delivering maximum value.*