AGENT SKILL

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

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

  1. Scope. One topic and one audience per video. Pick the next free NN and a kebab-case folder. Define the single question or outcome the video delivers. Update an existing video instead of duplicating a topic.
  2. Research the source material and note exact paths and short excerpts for slides.
  3. Write script.md (format below). Default target ~5-10 minutes (~150 words per minute); longer only if asked.
  4. Write README.md (outline below).
  5. Write slides.html (structure below), cueing each slide to a verbatim phrase in the script.
  6. 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.
  7. Synthesize audio with free edge-tts (Microsoft Edge online read-aloud). It needs Python, the edge-tts package and internet access; no API key, Azure subscription or paid Speech service. Install with python -m pip install edge-tts using the same interpreter as the audio tool (PYTHON tells 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.
  8. Build the video (needs Chrome/Edge - EDGE_PATH overrides - and ffmpeg with libx264 - FFMPEG_PATH overrides):
    • --check: every data-cue is 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.
  9. 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 with ffmpeg -ss <t> -i <mp4> -frames:v 1 <scratch>.png.
  10. Register the video in the folder's index README, if one exists.
  11. Commit only the text files and media; no secrets, no .cache/.

script.md format

  • First line # NN · Title.
  • ## Section headings 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 from script.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-part indexes data-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 <, >, &); add tight for longer excerpts. Keep excerpts to ~16 lines, copied from the real file.
  • Progressive builds: <template id="x"> with class="item" children, then <section data-template="x" data-show="3"> (reveal) or data-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=N or hash navigation so the renderer can screenshot each slide, header label and progress bar from data-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/): parses script.md strictly; --dry-run validates and estimates length without network. Otherwise it uses the edge-tts Python package or python -m edge_tts CLI 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 with python -m edge_tts --list-voices. Edge does not support custom SSML: apply pronunciations.json as 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/): opens slides.html in headless Chrome/Edge, resolves each data-cue to 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 --check and --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

QuinntyneBrown
QuinntyneBrown/quinntyne-brown-studio

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.

★ 1
QuinntyneBrown
QuinntyneBrown/quinntyne-brown-studio

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.

★ 1
QuinntyneBrown
QuinntyneBrown/quinntyne-brown-studio

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/.

★ 1
QuinntyneBrown
QuinntyneBrown/quinntyne-brown-studio

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.

★ 1
QuinntyneBrown
QuinntyneBrown/quinntyne-brown-studio

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/.

★ 1
QuinntyneBrown
QuinntyneBrown/quinntyne-brown-studio

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.

★ 1