academic-presentations

---
name: academic-presentations
description: >-
  Create academic presentation slide decks and optionally demo videos from
  research papers. Use when the user asks to "make slides", "create a deck",
  "make a presentation", "demo video", "paper slides", "conference talk slides",
  or wants to turn a paper into a visual presentation. Covers slide generation,
  narration scripts, TTS audio, and video assembly.
---

# Academic Presentations

Produce slide decks (and optionally narrated demo videos) from research papers. The human drives all outline and visual decisions — the agent executes.

## Pipeline

```
[1] Script Draft ──→ [2] Slide Generation ──→ [3] TTS Audio (optional) ──→ [4] Video Assembly (optional)
     Claude Code          nanobanana /edit     edge-tts / Kokoro / ElevenLabs       ffmpeg
```

Skip stages 3–4 for slide-only output. User can enter at any stage.

## Stage 1: Script / Outline

**Input**: paper + user-provided outline or slide plan
**Output**: `video-scripts.md` or `slide-outline.md` — per-slide content with talking points

The agent drafts scripts based on the user's outline. The user owns the structure — agent does not decide slide count, order, or what to emphasize.

## Stage 2: Slide Generation

> Full reference: [references/slide-generation.md](references/slide-generation.md)

**Tool**: nanobanana (Gemini CLI extension)

**Priority order** (edit-first):
1. **Has paper figure** → nanobanana `/edit` to wrap into slide frame
2. **Has existing slide** → `/edit` to adapt
3. **User-provided reference** (e.g., from NotebookLM or PPTX the user made) → `/edit` to refine
4. **Title slide from scratch** → generate with academic style prompt
5. **Content slide from scratch** → generate with deck-style preamble

**Key principle**: prefer `/edit` on existing HQ paper figures over generating from scratch.

**Deck style**: create `deck-style.md` once per deck, prepend to all generate-from-scratch prompts. For `/edit`, style is inherited from the base image.

Example `deck-style.md`:
```markdown
- Canvas: 1920x1080, white background
- Accent: #2563EB blue, text: #1e293b dark slate
- Clean sans-serif, flat design, no gradients/shadows
- Bottom bar: blue accent with white affiliation text
```

## Stage 3: TTS Audio (optional)

> Full reference: [references/tts-engines.md](references/tts-engines.md)
> Batch scripts: [scripts/batch_tts_edge.py](scripts/batch_tts_edge.py), [scripts/batch_tts_kokoro.py](scripts/batch_tts_kokoro.py)

**Output**: one audio file per narrated slide

### Engine Selection

| Engine | Quality | Cost | Latency | Best For |
|--------|---------|------|---------|----------|
| **edge-tts** (default) | Very good | Free, unlimited | ~6s/slide (cloud) | Quick generation, good male voices |
| **Kokoro** | Very good | Free, unlimited | ~1.5s/slide (local) | Offline use, fast batch, good female voices |
| **ElevenLabs** | Premium | 10k chars free/mo | ~3s/slide (cloud) | Highest quality, voice cloning |

**Default**: Use edge-tts unless user requests offline or premium quality.

### Quick Start (edge-tts)

```python
import edge_tts, asyncio

async def tts_slide(text, output, voice="en-US-AndrewNeural"):
    await edge_tts.Communicate(text, voice).save(output)

asyncio.run(tts_slide("Your slide text here", "slide_01.mp3"))
```

**Voices**: AndrewNeural (male, presenter), AriaNeural (female), GuyNeural (male, warm), JennyNeural (female, pro)

## Stage 4: Video Assembly (optional)

**Tool**: ffmpeg
**Input**: slide PNGs + audio files + optional demo recording

```bash
# Use symlink to avoid iCloud path spaces: ln -sfn "long path" /tmp/workdir

# Slide with audio:
ffmpeg -y -loop 1 -i slide.png -i audio.mp3 \
  -c:v libx264 -tune stillimage -pix_fmt yuv420p \
  -c:a aac -ar 44100 -ac 2 -shortest seg.mp4

# Silent slide (N seconds):
ffmpeg -y -loop 1 -i slide.png -f lavfi -i anullsrc=r=44100:cl=stereo \
  -c:v libx264 -tune stillimage -pix_fmt yuv420p \
  -c:a aac -ar 44100 -ac 2 -t N seg.mp4

# Concat (always re-encode, never -c copy):
printf "file 'seg1.mp4'\nfile 'seg2.mp4'\n..." > concat.txt
ffmpeg -y -f concat -safe 0 -i concat.txt \
  -c:v libx264 -pix_fmt yuv420p -c:a aac -ar 44100 -ac 2 final.mp4
```

All segments MUST share: 44100Hz sample rate, stereo, AAC codec.

## PPTX Conversion (if needed)

> Full reference: [references/pptx-conversion.md](references/pptx-conversion.md)

If starting from an existing PPTX, convert slides to PNG images first:
```bash
soffice --headless --convert-to pdf --outdir output/ presentation.pptx
pdftoppm -png -r 300 output/presentation.pdf output/slide
```

## NotebookLM — Human Reference Only

**The agent must NOT auto-invoke NotebookLM or use its outputs to drive slide/script decisions.** The human owns the outline, visual arrangement, and deck direction.

**When to recommend**: only when the user says they're unsure what to put on slides or need inspiration.

## Gotchas

- **iCloud paths with spaces break ffmpeg** — symlink to `/tmp/`
- **Audio format mismatch breaks concat** — always re-encode with `-ar 44100 -ac 2`
- **ElevenLabs free tier** — `mp3_22050_32` only, 10k chars/month
- **edge-tts needs internet** — falls back to Kokoro if offline
- **Kokoro WAV files are ~7x larger** — convert to MP3 with ffmpeg before video assembly
- **Kokoro first run downloads ~350MB model** — ensure pip is in the venv
- **`/edit` distorts figure** — be more explicit: "Keep the original figure exactly as-is, only add framing"
- **Style drift across slides** — use `/edit` from base slide or prepend shared `deck-style.md`

## Dependencies

| Tool | Stage | Install |
|------|-------|---------|
| Gemini CLI + nanobanana | 2 | `gemini extensions install https://github.com/gemini-cli-extensions/nanobanana` |
| LibreOffice + poppler | 2 (PPTX) | `brew install --cask libreoffice && brew install poppler` |
| edge-tts | 3 | `pip install edge-tts` |
| Kokoro | 3 (offline) | `pip install kokoro soundfile` |
| ElevenLabs | 3 (premium) | `pip install elevenlabs` + `ELEVENLABS_API_KEY` |
| ffmpeg | 4 | `brew install ffmpeg` |