Skip to content
Back to search

speaker

Speaker is a Codex skill project for academic presentations: read real.pptx, combine text extraction, PPTX structure parsing, page-by-page rendering, OCR, and visual review to generate page-by-page speaker notes, and write a clean version of the lecture into the PowerPoint comment area.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ai272--speaker/badge.svg)](/listings/ai272--speaker)

HTML

<a href="/listings/ai272--speaker"><img src="/api/listings/ai272--speaker/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 309 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # speaker [![Available on CodeGuilds](https://img.shields.io/badge/Available_on-CodeGuilds-6366f1?logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyTDIgN2wxMCA1IDEwLTV6TTIgMTdsMTAgNSAxMC01TTIgMTJsMTAgNSAxMC01Ii8+PC9zdmc+)](https://codeguilds.dev/packages/speaker)
  2. ![speaker cover](assets/speaker-cover.png)
  3. [中文说明](README.zh.md)
  4. `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.
  5. > Current skill package: `speaker-v8.skill`
  6. > Internal skill name: `ppt-speech-writer`
  7. ## What's New in v0.8
  8. This release focuses on tighter, evidence-grounded output and realistic speech pacing.
  9. - **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.
  10. - **Per-slide word budget.** `SKILL.md` now 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.
  11. - **Glossary toggle.** A new on/off switch (default on) can skip the "Key Parameters And Methods" glossary table end to end.
  12. - **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.
  13. - **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.
  14. - **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.
  15. - **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 notes` to print the complete notes.
  16. ## What It Solves
  17. 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:
  18. - Build a visible-element inventory for every slide.
  19. - Review visually complex content with a vision-capable agent or human reviewer.
  20. - Tie each spoken sentence to visible slide evidence.
  21. - Produce two versions: a display version for rehearsal and a clean version for PowerPoint notes.
  22. ## Workflow
  23. ```mermaid
  24. flowchart TD
  25. A[Input .pptx] --> B[Structured Extraction]
  26. B --> C[Render Slides to PNG]
  27. C --> D[OCR and Visual Inventory]
  28. D --> E[Vision Review]
  29. E --> F[Deck Comprehension Brief]
  30. F --> G[Narrative Arc]
  31. G --> H[Slide-by-Slide Display Notes]
  32. H --> I[Clean Notes JSON]
  33. H --> J[Display Version DOCX or Markdown]
  34. I --> K[Inject Notes into PPTX]
  35. K --> L[Output PPTX with Speaker Notes]
  36. ```
  37. ## Evidence Chain
  38. ```mermaid
  39. graph LR
  40. XML[PPTX XML] --> INV[Visible Element Inventory]
  41. TEXT[Text Boxes] --> INV
  42. TABLE[Tables] --> INV
  43. CHART[Native Charts] --> INV
  44. IMAGE[Rendered Slide Images] --> INV
  45. OCR[OCR Text] --> INV
  46. VISION[Vision Review] --> INV
  47. INV --> NOTES[Grounded Speaker Notes]
  48. ```
  49. ## Features
  50. | Feature | Description |
  51. |---|---|
  52. | Text extraction | Extracts titles, body text, placeholders, and text boxes |
  53. | Table extraction | Reads row and column text from PowerPoint tables |
  54. | Chart extraction | Attempts to read native chart titles, categories, series, values, axes, and legends |
  55. | OOXML fallback | Extracts additional slide XML text not exposed by `python-pptx`, including some SmartArt or grouped-shape text |
  56. | Slide rendering | Renders slides to PNG so the final visual presentation can be inspected |
  57. | OCR | Optionally reads text in screenshots, images, small labels, and other visual regions |
  58. | Vision review | Produces a review packet for a vision-capable agent or human reviewer |
  59. | Notes injection | Writes clean speaker notes into the PowerPoint notes pane |
  60. | Display document | Generates a complete rehearsal document as `.docx`, with Markdown fallback when `python-docx` is unavailable |
  61. ## Repository Layout
  62. ```text
  63. ppt-speech-writer/
  64. ├── SKILL.md
  65. └── scripts/
  66. ├── read_slides.py
  67. ├── render_slides.py
  68. ├── visual_inventory.py
  69. ├── vision_review.py
  70. ├── write_display_docx.py
  71. └── inject_notes.py
  72. speaker-v8.skill
  73. ```
  74. Claude Code compatibility:
  75. ```text
  76. .claude/skills/ppt-speech-writer -> ../../ppt-speech-writer
  77. CLAUDE.md
  78. ```
  79. ## Installation
  80. Download or use the packaged skill:
  81. ```text
  82. speaker-v8.skill
  83. ```
  84. 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.
  85. For Claude Code, this repository includes a project skill at `.claude/skills/ppt-speech-writer`. Open Claude Code from the repository root and invoke:
  86. ```text
  87. /ppt-speech-writer
  88. ```
  89. If Claude Code is already running, use `/reload-skills` after pulling updates.
  90. ## Example Prompt
  91. ```text
  92. Use speaker / ppt-speech-writer to write a 15-minute academic presentation script
  93. for this PowerPoint deck. Inject the clean script into speaker notes and also
  94. generate a complete display-version rehearsal document.
  95. ```
  96. The skill will:
  97. 1. Read the full deck.
  98. 2. Render every slide.
  99. 3. Build a visual inventory.
  100. 4. Run vision review for visually complex content.
  101. 5. Produce a Deck Comprehension Brief.
  102. 6. Confirm the narrative arc.
  103. 7. Write display notes and clean notes.
  104. 8. Generate the complete display document.
  105. 9. Inject clean notes into the `.pptx`.
  106. 10. Keep intermediate evidence files inside `work/`.
  107. 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.
  108. ## Outputs
  109. Most users only need the top-level deliverables:
  110. | Top-level output | Purpose |
  111. |---|---|
  112. | `<deck-stem>-with-notes.pptx` | PowerPoint file with speaker notes injected |
  113. | `<deck-stem>-display.docx` | Complete rehearsal script with slide labels, transitions, glossary, and timing table |
  114. | `<deck-stem>-display.md` | Markdown fallback when `python-docx` is unavailable |
  115. | `<deck-stem>-vision-review.md` | Markdown packet for human or vision-agent review |
  116. Intermediate files are grouped under `work/`:
  117. ```text
  118. <deck-stem>-speaker-output/
  119. ├── <deck-stem>-with-notes.pptx
  120. ├── <deck-stem>-display.docx
  121. ├── <deck-stem>-display.md
  122. ├── <deck-stem>-vision-review.md
  123. └── work/
  124. ├── slide_extract.json
  125. ├── visual_inventory.json
  126. ├── vision_review_packet.json
  127. ├── vision_review.json
  128. ├── display_document.json
  129. ├── notes.json
  130. └── rendered_slides/
  131. ```
  132. ## Script Reference
  133. ### 1. Structured extraction
  134. ```bash
  135. python scripts/read_slides.py "/path/to/deck.pptx" \
  136. --output "<deck-stem>-speaker-output/work/slide_extract.json"
  137. ```
  138. Reads text boxes, tables, charts, picture objects, OOXML text, and existing notes.
  139. ### 2. Slide rendering
  140. ```bash
  141. python scripts/render_slides.py "/path/to/deck.pptx" \
  142. --output-dir "<deck-stem>-speaker-output/work/rendered_slides"
  143. ```
  144. Renders slides to PNG. The script tries LibreOffice / `soffice` first and falls back to macOS Quick Look when available.
  145. ### 3. Visual inventory
  146. ```bash
  147. python scripts/visual_inventory.py \
  148. --extract "<deck-stem>-speaker-output/work/slide_extract.json" \
  149. --rendered-dir "<deck-stem>-speaker-output/work/rendered_slides" \
  150. --output "<deck-stem>-speaker-output/work/visual_inventory.json" \
  151. --ocr auto
  152. ```
  153. Combines structured extraction, rendered slide paths, and OCR text into a per-slide coverage inventory.
  154. ### 4. Vision review packet
  155. ```bash
  156. python scripts/vision_review.py \
  157. --inventory "<deck-stem>-speaker-output/work/visual_inventory.json" \
  158. --output "<deck-stem>-speaker-output/work/vision_review_packet.json" \
  159. --markdown "<deck-stem>-speaker-output/<deck-stem>-vision-review.md"
  160. ```
  161. Prepares review prompts and evidence for a vision-capable agent or human reviewer.
  162. ### 5. Display document
  163. ```bash
  164. python scripts/write_display_docx.py \
  165. --input "<deck-stem>-speaker-output/work/display_document.json" \
  166. --output "<deck-stem>-speaker-output/<deck-stem>-display.docx"
  167. ```
  168. Writes the display-version rehearsal document. If `python-docx` is missing, it writes a Markdown fallback.
  169. ### 6. Speaker notes injection
  170. ```bash
  171. python scripts/inject_notes.py \
  172. --input "/path/to/deck.pptx" \
  173. --output "<deck-stem>-speaker-output/<deck-stem>-with-notes.pptx" \
  174. --notes "<deck-stem>-speaker-output/work/notes.json" \
  175. --mode replace
  176. ```
  177. Injects clean notes into the PowerPoint notes pane.
  178. ## Display Version vs Clean Version
  179. ```mermaid
  180. flowchart LR
  181. A[One Grounded Source] --> B[Display Version]
  182. A --> C[Clean Version]
  183. B --> D[DOCX or Markdown for rehearsal]
  184. C --> E[Injected into PPT notes pane]
  185. ```
  186. | Version | Content | Use |
  187. |---|---|---|
  188. | Display version | Slide labels, separators, transitions, pauses, emphasis marks, glossary, timing table | Rehearsal and review |
  189. | Clean version | Spoken text only | Injected into PowerPoint speaker notes |
  190. ## Language And Style Rules
  191. - The output language must be confirmed before drafting.
  192. - The full deliverable must use one language consistently.
  193. - Canonical technical terms may remain in English, but sentence grammar must follow the selected language.
  194. - Slide notes must not start with template phrases such as "This slide shows..." or "On this slide...".
  195. - Chinese notes must not start with phrases such as "这一页展示了..." or "在这一页中..."。
  196. - Each slide should open with the actual claim, finding, method role, or argument step.
  197. ## Dependencies
  198. Useful dependencies:
  199. - `python-pptx` for PPTX structure extraction and speaker-note injection
  200. - LibreOffice / `soffice` for high-quality slide rendering
  201. - macOS `qlmanage` as a rendering fallback
  202. - `tesseract` for OCR
  203. - `python-docx` for Word display documents
  204. If a dependency is missing, the skill uses the strongest available evidence and reports the limitation. For complex charts, screenshots, SmartArt, and image-only slides, final notes should not be produced without vision review.
  205. ## Limits
  206. This skill aims to cover and explain visible slide elements as completely as possible. It does not claim that scripts can automatically understand every visual element with perfect semantic accuracy.
  207. Why:
  208. - Images and screenshots are pixels, not structured semantic objects.
  209. - OCR can fail on small text, formulas, low contrast, or rotated labels.
  210. - SmartArt, arrows, and layout relationships often depend on author intent.
  211. - A chart may be a screenshot rather than a native PowerPoint chart.
  212. The skill improves reliability through script-based discovery, rendering, OCR, vision review, and explicit coverage notes. Uncertain elements must be marked, not invented.
  213. ## Updating The Package
  214. After modifying the source folder, rebuild the `.skill` package:
  215. ```bash
  216. zip -r speaker-v8.skill ppt-speech-writer -x '*/__pycache__/*'
  217. ```
  218. The `.skill` file is a fixed package. Editing `ppt-speech-writer/` does not automatically update an already packaged or installed skill.
  219. ## Best For
  220. - Academic conference talks
  221. - Thesis defenses
  222. - Lab meetings
  223. - Research project briefings
  224. - Slide-grounded speaker scripts
  225. - Decks with charts, screenshots, SmartArt, or method diagrams
  226. ## Not Ideal For
  227. - Free-form speeches that ignore slide content
  228. - Marketing copy that exaggerates beyond slide evidence
  229. - Requests without a real `.pptx` file
  230. - Workflows that cannot perform vision review for complex visual slides

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.