speaker 
speaker is a Codex skill project for academic presentations. It reads a real .pptx, combines text extraction, PPTX structure inspection, slide rendering, OCR, and vision review, then generates grounded speaker notes and injects the clean script into PowerPoint's speaker notes pane.
Current skill package:
speaker-v8.skill
Internal skill name:ppt-speech-writer
What's New in v0.8
This release focuses on tighter, evidence-grounded output and realistic speech pacing.
- Pause-aware pacing model. Speech length is now budgeted with a deterministic model (English ~110 wpm, Chinese ~165 characters/min) that reserves time for slide transitions and
[PAUSE]marks. This fixes the previous problem where a "15-minute" script ran to ~1,800 words and overran to ~30 minutes; a 15-minute talk now targets roughly 1,300–1,400 words. Both Chinese and English notes are tuned per slide. - Per-slide word budget.
SKILL.mdnow computes and records a per-slide budget so each slide stays within the overall time target, and the timing table reports words/characters, budget, and pauses with a TOTAL row. - Glossary toggle. A new on/off switch (default on) can skip the "Key Parameters And Methods" glossary table end to end.
- Compact extraction (
read_slides.py --mode compact). Drops redundant raw OOXML dumps and non-visual geometry while keeping picture bounding boxes, producing much smaller intermediate JSON. - Region-scoped OCR (
visual_inventory.py --ocr-scope image-regions). OCR runs only on picture/media regions (text boxes, tables, and charts already come from XML), with an automatic full-slide fallback. Includes robustness fixes: byte-safe OCR decoding and symlink path resolution. - Compact vision-review packet (
vision_review.py --format compact). The shared review prompt and result schema are hoisted to the top level instead of being repeated per slide; Markdown is now optional. - Concise final delivery. The skill returns a summary plus file paths by default instead of pasting the full slide-by-slide script into chat. Reply
show notesto print the complete notes.
What It Solves
Many presentation-note tools only read text boxes. That misses charts, screenshots, SmartArt, axes, legends, tables, and text embedded in images. This skill is designed to keep speaker notes grounded in the actual slides:
- Build a visible-element inventory for every slide.
- Review visually complex content with a vision-capable agent or human reviewer.
- Tie each spoken sentence to visible slide evidence.
- Produce two versions: a display version for rehearsal and a clean version for PowerPoint notes.
Workflow
flowchart TD
A[Input .pptx] --> B[Structured Extraction]
B --> C[Render Slides to PNG]
C --> D[OCR and Visual Inventory]
D --> E[Vision Review]
E --> F[Deck Comprehension Brief]
F --> G[Narrative Arc]
G --> H[Slide-by-Slide Display Notes]
H --> I[Clean Notes JSON]
H --> J[Display Version DOCX or Markdown]
I --> K[Inject Notes into PPTX]
K --> L[Output PPTX with Speaker Notes]
Evidence Chain
graph LR
XML[PPTX XML] --> INV[Visible Element Inventory]
TEXT[Text Boxes] --> INV
TABLE[Tables] --> INV
CHART[Native Charts] --> INV
IMAGE[Rendered Slide Images] --> INV
OCR[OCR Text] --> INV
VISION[Vision Review] --> INV
INV --> NOTES[Grounded Speaker Notes]
Features
| Feature | Description |
|---|---|
| Text extraction | Extracts titles, body text, placeholders, and text boxes |
| Table extraction | Reads row and column text from PowerPoint tables |
| Chart extraction | Attempts to read native chart titles, categories, series, values, axes, and legends |
| OOXML fallback | Extracts additional slide XML text not exposed by python-pptx, including some SmartArt or grouped-shape text |
| Slide rendering | Renders slides to PNG so the final visual presentation can be inspected |
| OCR | Optionally reads text in screenshots, images, small labels, and other visual regions |
| Vision review | Produces a review packet for a vision-capable agent or human reviewer |
| Notes injection | Writes clean speaker notes into the PowerPoint notes pane |
| Display document | Generates a complete rehearsal document as .docx, with Markdown fallback when python-docx is unavailable |
Repository Layout
ppt-speech-writer/
├── SKILL.md
└── scripts/
├── read_slides.py
├── render_slides.py
├── visual_inventory.py
├── vision_review.py
├── write_display_docx.py
└── inject_notes.py
speaker-v8.skill
Claude Code compatibility:
.claude/skills/ppt-speech-writer -> ../../ppt-speech-writer
CLAUDE.md
Installation
Download or use the packaged skill:
speaker-v8.skill
Install it using your Codex client's skill import flow. Once installed, use it when you need speaker notes, presenter notes, a speech script, or narration for a real .pptx file.
For Claude Code, this repository includes a project skill at .claude/skills/ppt-speech-writer. Open Claude Code from the repository root and invoke:
/ppt-speech-writer
If Claude Code is already running, use /reload-skills after pulling updates.
Example Prompt
Use speaker / ppt-speech-writer to write a 15-minute academic presentation script
for this PowerPoint deck. Inject the clean script into speaker notes and also
generate a complete display-version rehearsal document.
The skill will:
- Read the full deck.
- Render every slide.
- Build a visual inventory.
- Run vision review for visually complex content.
- Produce a Deck Comprehension Brief.
- Confirm the narrative arc.
- Write display notes and clean notes.
- Generate the complete display document.
- Inject clean notes into the
.pptx. - Keep intermediate evidence files inside
work/.
Before writing notes, the skill must explicitly confirm the output language. It does not infer the note language from the language you use in chat.
Outputs
Most users only need the top-level deliverables:
| Top-level output | Purpose |
|---|---|
<deck-stem>-with-notes.pptx |
PowerPoint file with speaker notes injected |
<deck-stem>-display.docx |
Complete rehearsal script with slide labels, transitions, glossary, and timing table |
<deck-stem>-display.md |
Markdown fallback when python-docx is unavailable |
<deck-stem>-vision-review.md |
Markdown packet for human or vision-agent review |
Intermediate files are grouped under work/:
<deck-stem>-speaker-output/
├── <deck-stem>-with-notes.pptx
├── <deck-stem>-display.docx
├── <deck-stem>-display.md
├── <deck-stem>-vision-review.md
└── work/
├── slide_extract.json
├── visual_inventory.json
├── vision_review_packet.json
├── vision_review.json
├── display_document.json
├── notes.json
└── rendered_slides/
Script Reference
1. Structured extraction
python scripts/read_slides.py "/path/to/deck.pptx" \
--output "<deck-stem>-speaker-output/work/slide_extract.json"
Reads text boxes, tables, charts, picture objects, OOXML text, and existing notes.
2. Slide rendering
python scripts/render_slides.py "/path/to/deck.pptx" \
--output-dir "<deck-stem>-speaker-output/work/rendered_slides"
Renders slides to PNG. The script tries LibreOffice / soffice first and falls back to macOS Quick Look when available.
3. Visual inventory
python scripts/visual_inventory.py \
--extract "<deck-stem>-speaker-output/work/slide_extract.json" \
--rendered-dir "<deck-stem>-speaker-output/work/rendered_slides" \
--output "<deck-stem>-speaker-output/work/visual_inventory.json" \
--ocr auto
Combines structured extraction, rendered slide paths, and OCR text into a per-slide coverage inventory.
4. Vision review packet
python scripts/vision_review.py \
--inventory "<deck-stem>-speaker-output/work/visual_inventory.json" \
--output "<deck-stem>-speaker-output/work/vision_review_packet.json" \
--markdown "<deck-stem>-speaker-output/<deck-stem>-vision-review.md"
Prepares review prompts and evidence for a vision-capable agent or human reviewer.
5. Display document
python scripts/write_display_docx.py \
--input "<deck-stem>-speaker-output/work/display_document.json" \
--output "<deck-stem>-speaker-output/<deck-stem>-display.docx"
Writes the display-version rehearsal document. If python-docx is missing, it writes a Markdown fallback.
6. Speaker notes injection
python scripts/inject_notes.py \
--input "/path/to/deck.pptx" \
--output "<deck-stem>-speaker-output/<deck-stem>-with-notes.pptx" \
--notes "<deck-stem>-speaker-output/work/notes.json" \
--mode replace
Injects clean notes into the PowerPoint notes pane.
Display Version vs Clean Version
flowchart LR
A[One Grounded Source] --> B[Display Version]
A --> C[Clean Version]
B --> D[DOCX or Markdown for rehearsal]
C --> E[Injected into PPT notes pane]
| Version | Content | Use |
|---|---|---|
| Display version | Slide labels, separators, transitions, pauses, emphasis marks, glossary, timing table | Rehearsal and review |
| Clean version | Spoken text only | Injected into PowerPoint speaker notes |
Language And Style Rules
- The output language must be confirmed before drafting.
- The full deliverable must use one language consistently.
- Canonical technical terms may remain in English, but sentence