creating-narrated-videos
Create a narrated video (slide deck + MP3 narration + captioned 1080p MP4) from text files - a transcript script, a timed HTML slide deck and an outline - using free edge-tts for the audio and a headless browser plus ffmpeg for the video. Use when asked to make, script, record, regenerate or fix a video, tutorial, walkthrough, demo, explainer, training lesson, screencast or slide deck for this repository or product. Not for screen recordings of running applications; use recording-demo-videos for those.
- License 许可
- MIT
- 最近更新
- 2026-10-19
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- creating-narrated-videos
- description
- Create a narrated video (slide deck + MP3 narration + captioned 1080p MP4) from text files - a transcript script, a timed HTML slide deck and an outline - using free edge-tts for the audio and a headless browser plus ffmpeg for the video. Use when asked to make, script, record, regenerate or fix a video, tutorial, walkthrough, demo, explainer, training lesson, screencast or slide deck for this repository or product. Not for screen recordings of running applications; use recording-demo-videos for those.
02 资源文件 1
- 参考文档agents/openai.yaml328 B
03 SKILL.md 正文
Creating narrated videos
A video is narration audio + a slide deck timed to it + captions, all generated from text files checked into one folder. You author three text files; tooling turns them into media.
docs/videos/NN-kebab-topic/
script.md transcript the audio is synthesized from (you write)
slides.html one <section> per slide, each cued to a script phrase (you write)
README.md outline: purpose, objectives, assets on screen, run sheet (you write)
NN-kebab-topic.mp3 free edge-tts synthesis (generated)
NN-kebab-topic.mp4 slides rendered to PNG + audio + captions (generated)
Paths above are the default. If the repo already has a videos/lessons folder or tooling, follow it instead. Large media should go through Git LFS if .gitattributes configures it; .cache/ folders are never committed.
Before writing, read any existing video in the repo (tone, length, structure) and the code/docs the video covers. Every file path, name, number and quote on screen or in the script must be verified against the repository, never recalled.
Workflow
- Scope. One topic and one audience per video. Pick the next free
NNand a kebab-case folder. Define the single question or outcome the video delivers. Update an existing video instead of duplicating a topic. - Research the source material and note exact paths and short excerpts for slides.
- Write
script.md(format below). Default target ~5-10 minutes (~150 words per minute); longer only if asked. - Write
README.md(outline below). - Write
slides.html(structure below), cueing each slide to a verbatim phrase in the script. - Validate offline with the repo's audio tool in dry-run mode (script format, word count and estimated duration; edge-tts has no synthesis charge). If no tool exists yet, create the two small tools described under "Tooling" before continuing.
- Synthesize audio with free
edge-tts(Microsoft Edge online read-aloud). It needs Python, theedge-ttspackage and internet access; no API key, Azure subscription or paid Speech service. Install withpython -m pip install edge-ttsusing the same interpreter as the audio tool (PYTHONtells the generator which one). Edge is the generator's default engine; the only other engine is offline Piper (--engine piper), and there is no Azure engine. Synthesis also writes a timing manifest (per-section and per-paragraph start/end, in.cache/) that the video is synced to. Keep acronyms and code identifiers in a pronunciation lexicon (pronunciations.json) as plain-text spoken replacements and check them with a pronunciation test. - Build the video (needs Chrome/Edge -
EDGE_PATHoverrides - and ffmpeg with libx264 -FFMPEG_PATHoverrides):--check: everydata-cueis found; prints the schedule.--slides-only: renders PNGs to.cache/<folder>/. View them before encoding; overflowing code, clipped tables and unreadable text are the common failures.- full build: encodes the 1920x1080 MP4 with burned-in captions.
- Verify:
ffprobe -v error -show_entries format=duration:stream=codec_name,width,height <mp4>gives 1920x1080, h264 + audio, duration about equal to the MP3. Spot-check frames at cue times withffmpeg -ss <t> -i <mp4> -frames:v 1 <scratch>.png. - Register the video in the folder's index README, if one exists.
- Commit only the text files and media; no secrets, no
.cache/.
script.md format
- First line
# NN · Title. ## Sectionheadings group narration; synthesize each paragraph separately and keep sections under ~9 minutes of speech.- Plain paragraphs and
-list items are spoken by the narrator.**Name:** ...paragraphs for a second speaker (e.g.**Interviewer:**,**Host:**) use a second voice. [pause 5s]on its own line inserts silence.- Inline
`code`is allowed and spoken via the pronunciation lexicon. - Not allowed: tables, fenced code blocks, links, HTML. It must make sense with eyes closed: describe code, don't read it. Spell numbers as they should be spoken when it matters.
Suggested section order (adapt to the topic): untitled intro paragraph (what and why) → the questions/outcomes → concept sections → how it applies in this repo (exact paths) → the recommended approach in steps → pitfalls → optional Q&A/practice → recap ("things to remember", then a one-sentence preview of what's next).
Voice: second person, conversational, concrete, opinionated with trade-offs stated aloud. No filler or marketing tone. Time-sensitive facts carry "as of <month year>".
README.md (outline) structure
# NN · Title
> **Runtime:** ~N min · **Audience:** ... · **Prerequisites:** ...
**Video:** [NN-topic.mp4](NN-topic.mp4) · [Slides](slides.html) · **Audio:** [NN-topic.mp3](NN-topic.mp3) · [Transcript](script.md)
## Why this video exists
## Learning objectives (bulleted "By the end, the viewer can:")
## Key questions (| Question | What a strong answer includes |)
## Code / assets on screen (| File | What to show |)
## Run sheet (| Time | Segment | Content |, mm:ss-mm:ss summing to the runtime)
## Demo commands (exact, copy-pasteable)
## Pitfalls
## References (official docs; no invented URLs)
slides.html structure
Use one shared stylesheet and runtime (assets/slides.css, assets/slides.js) next to the video folders; copy the head and footer of an existing deck. Never inline new global styles.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Video NN Slides</title>
<link rel="stylesheet" href="../assets/slides.css">
</head>
<body data-video-number="NN" data-video-title="Title" data-parts="Introduction|Concepts|...|Recap">
<section id="title" data-part="0">
<div class="kicker">Product · Video NN</div>
<h1>Title</h1>
<p class="lead">One-line subtitle</p>
</section>
<section id="concepts" data-part="1" data-cue="Phrase copied verbatim from script.md">
<h2>Heading</h2>
<ul><li>...</li></ul>
</section>
<script src="../assets/slides.js"></script>
</body>
</html>
Rules:
- Every slide except the first has a
data-cue: a phrase copied verbatim fromscript.md(a heading or the start of a sentence), unique in the script, with cues in narration order. A slide appears when narration reaches its cue. data-partindexesdata-parts(header label and progress bar); parts line up with##sections.- Roughly one slide every 20-40 seconds. Cue changes inside a section are estimated from word counts (within a second or two); section boundaries are exact.
- Slides support the narration, they don't transcribe it: a heading, 3-5 short bullets, a diagram, or a short code excerpt.
- Code:
<pre class="code" data-lang="cs|ts|json|yaml|sql|sh|md|xml" data-mark="2,5">(escape<,>,&); addtightfor longer excerpts. Keep excerpts to ~16 lines, copied from the real file. - Progressive builds:
<template id="x">withclass="item"children, then<section data-template="x" data-show="3">(reveal) ordata-highlight="2-4">(focus). - Reuse existing classes in
slides.css(e.g.kicker,lead,quote,muted,small,cols,card,file,tag,steps,question,recap). Add a class only if none fits, and check it doesn't change other decks. - If no shared stylesheet/runtime exists, create them first: 1920x1080 slides, one visible at a time,
?slide=Nor hash navigation so the renderer can screenshot each slide, header label and progress bar fromdata-parts.
Tooling
Keep two small scripts under tools/ (language of the repo's choice; a .NET single-file app, Node or Python all work):
- Audio generator (
tools/video-audio/): parsesscript.mdstrictly;--dry-runvalidates and estimates length without network. Otherwise it uses theedge-ttsPython package orpython -m edge_ttsCLI with plain text per paragraph: a neural narrator voice (e.g.en-US-AndrewMultilingualNeural) and a second voice for other speakers (e.g.en-US-AvaMultilingualNeural). Check available voices withpython -m edge_tts --list-voices. Edge does not support custom SSML: applypronunciations.jsonas spoken text replacements before synthesis, synthesize speaker paragraphs separately, and insert[pause 5s]as ffmpeg-generated silence. Normalize clips to a common audio format, measure their actual durations with ffprobe, concatenate clips and silence into the MP3, and write the timing manifest from those durations. - Video builder (
tools/video-build/): opensslides.htmlin headless Chrome/Edge, resolves eachdata-cueto a time using the manifest (section boundaries exact, in-section by word count), screenshots each slide at 1920x1080, writes an SRT/ASS caption file from the script, and runs ffmpeg (libx264, aac) to produce the MP4 with burned-in captions. Supports--checkand--slides-only.
Prefer an existing equivalent if the repo already has one. With Node tools in the layout above, run from the repo root (Edge is the default engine, so --engine edge is optional):
# Use the same Python interpreter for installation and the generator.
export PYTHON=python3
python3 -m pip install edge-tts
node tools/video-audio/generate-audio.mjs docs/videos/NN-kebab-topic --dry-run
node tools/video-audio/generate-audio.mjs --say "<product name>" --out .cache/pronunciation-test.wav
node tools/video-audio/generate-audio.mjs docs/videos/NN-kebab-topic
node tools/video-build/build-video.mjs docs/videos/NN-kebab-topic --check
node tools/video-build/build-video.mjs docs/videos/NN-kebab-topic --slides-only
node tools/video-build/build-video.mjs docs/videos/NN-kebab-topic
In PowerShell, set the interpreter with $env:PYTHON = "python" and use python in place of python3. Replace NN-kebab-topic with the actual folder and <product name> with a word the narrator must pronounce correctly. EDGE_VOICE and EDGE_VOICE_2 override the narrator and second-speaker voices. For package usage and supported options, see the edge-tts documentation. A working implementation of both tools and the shared slide assets, written for one product, is in the Saturdaze repository under tools/video-audio/, tools/video-build/ and docs/videos/assets/; adapt its branding and pronunciation lexicon rather than copying them unchanged.
Quality checklist
- [ ] Every path, identifier, number and quote checked against the repo.
- [ ] Audio dry-run clean; estimated length matches the target.
- [ ] Cue check clean; no slide shorter than ~4 s or longer than ~90 s.
- [ ] Rendered PNGs reviewed: nothing clipped or overflowing at 1920x1080.
- [ ] MP4 is 1080p with audio and captions; duration matches the MP3.
- [ ] Index README updated, if present.
- [ ] No secrets or
.cache/files committed; media via LFS if configured.
When the tooling can't run
Behind a TLS-intercepting proxy, edge-tts fails with a certificate error because it trusts only Python's certifi bundle, not SSL_CERT_FILE; append the proxy CA to the file python -c "import certifi; print(certifi.where())" prints and retry.
If dotnet/Node/Python, the edge-tts package, internet access, a browser or ffmpeg isn't available, still deliver the three text files, run whatever validation is possible, and tell the user precisely which commands remain and what they need. Never fabricate an MP3/MP4 or claim media was built or checked when it wasn't.
04 同仓库更多 Skills
writing-screen-composition
Create or update docs/screen-composition.md, a document that itemizes every page, dialog, notification and shell part from the HTML mocks and lists, for each, the component-library components it shall be composed of plus the UI that must be built locally. Also ensures AGENTS.md has the "Components library is mandatory (CRITICAL)" section. Use when the user mentions screen composition, which components a page uses, mapping mocks to a component library, local vs library UI, or before implementing an application against a component library; and whenever docs/mocks and a component catalogue exist but docs/screen-composition.md does not or is out of date.
writing-requirements
Create and manage software requirements documents (L1 high-level and L2 detailed with acceptance criteria) in docs/specs/. Use this skill whenever the user mentions requirements, specs, specifications, user stories, features to build, acceptance criteria, ATDD, or wants to define what a system should do before coding. Also use when the user says things like 'what should we build', 'let's plan the feature', 'write up what this needs to do', 'define the behavior', or describes functionality they want implemented -- even if they don't explicitly say 'requirements'. If the user is about to start coding a feature and there are no requirements yet, proactively suggest using this skill first. Requirements come before code. Always.
writing-html-mocks
Write static HTML mocks in docs/mocks/ for EVERY page, dialog and notification of a product in EVERY state (default, loading, empty, error, invalid, busy, success, no-results, forbidden, stacked...), responsive, light and dark, keyboard-accessible, with real copy and a coverage matrix. Use this skill BEFORE writing any frontend code, component, template, view or page; whenever the user says mock, mockup, wireframe, prototype, UI, UX, screen, layout, dialog, modal, toast, banner, empty/error/loading state, "what should this look like", "show me the UI", or describes a feature with a visible result; and whenever docs/specs or docs/detailed-designs exist but docs/mocks does not. Also use it to add missing states to existing mocks. Mocks come before implementation: if asked for frontend code with no mocks, say so and offer this first. Pair with extracting-design-systems to turn finished mocks into docs/design-system/.
writing-feature-prompts
Write a ready-to-run implementation prompt for a feature request or a bug fix in the current repository, save it outside the repository and open it in a text editor (Notepad on Windows). A feature prompt drives mocks, design system, requirements, detailed design, estimate update and incremental acceptance-test-driven implementation end to end without stopping; a bug-fix prompt drives reproduce, root cause, fix and documentation alignment. Use whenever the user asks to "create a prompt", "write a prompt for this feature" or "for this bug", wants a "prompt to build X" or "prompt to fix Y", or asks to open a prompt in Notepad.
writing-design-documents
Create software design documents and architecture write-ups from existing L1/L2 requirements in docs/specs/. Use for detailed designs organized by subsystem and feature, with requirement traceability and rendered PlantUML C4, class, and sequence diagrams in docs/detailed-designs/.
writing-agent-instructions
Writes the agent instruction files a repository needs so coding agents know how to work in it - AGENTS.md plus the CLAUDE.md, GEMINI.md, and .github/copilot-instructions.md pointers - generated from a description of what the project shall be, for a project that does not exist yet. Use this whenever someone mentions AGENTS.md, CLAUDE.md, GEMINI.md, copilot-instructions, "agent instructions", "agent context files", "coding agent guidance", or asks to set up, scaffold, bootstrap, or initialise the conventions for a new project or repository. Use it too when someone describes a project they are about to start and wants an agent to follow its conventions, even if they never name any of these files - if they are standing at an empty directory describing what they intend to build, this is the skill.