demo-video
Assemble ordered frames or clips with narration and optional synchronized scene transitions into an MP4 via FFmpeg
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 355
01 前言 Front Matter
- name
- demo-video
- license
- MIT
- metadata
- { "authors": "microsoft/hve-core", "last_updated": "2026-10-03", "spec_version": "1.0" }
- description
- Assemble ordered frames or clips with narration and optional synchronized scene transitions into an MP4 via FFmpeg
- compatibility
- Requires FFmpeg on PATH
02 资源文件 20
- 资产文件assets/content_calendar_template.md1.6 KB
- 参考文档examples/README.md1018 B
- 参考文档examples/segments.yml341 B
- 其他pyproject.toml491 B
- 参考文档references/brand_guidelines.md6.0 KB
- 参考文档references/content_frameworks.md10.3 KB
- 参考文档references/social_media_optimization.md8.9 KB
- 脚本scripts/assemble_video.py24.5 KB
- 脚本scripts/assemble-video.sh1.2 KB
- 脚本scripts/brand_voice_analyzer.py6.5 KB
- 脚本scripts/Invoke-AssembleVideo.ps13.2 KB
- 脚本scripts/seo_optimizer.py15.3 KB
- 参考文档tests/corpus/empty-segments.yml13 B
- 参考文档tests/corpus/unknown-key.yml73 B
- 参考文档tests/corpus/valid-manifest.yml177 B
- 脚本tests/fuzz_harness.py2.6 KB
- 脚本tests/Invoke-AssembleVideo.Tests.ps11.7 KB
- 脚本tests/test_assemble_video_integrity.py11.7 KB
- 脚本tests/test_assemble_video.py22.2 KB
- 其他uv.lock67.8 KB
03 SKILL.md 正文
Demo Video Assembly Skill
This skill assembles a narrated demo video from ordered visual segments and matching narration audio. It is designed for first-pass walkthrough videos that combine captured prototype frames or clips with per-segment voiceover WAV files.
Overview
The workflow takes a manifest that describes each segment, resolves the visual source, and uses FFmpeg to render each segment into a normalized video clip before assembling the final MP4. It supports hard cuts by default or optional synchronized video and audio fades. The narration track is muxed from WAV files so the output can be reviewed without a separate video-editing tool.
Manifest Schema
Use a segments.yml manifest with optional top-level output settings and an ordered list of segments. Each entry describes a visual source and the narration audio to combine for that portion of the video. All paths resolve relative to the manifest file.
output: ./output/demo.mp4 # optional; destination path for the assembled MP4
resolution: 1280x720 # optional; default 1280x720
fps: 24 # optional; default 24
transition: # optional; omit for hard cuts
type: crossfade
duration: 0.5
fade_in: true
fade_out: true
segments:
- type: frame
visual: ./frames/intro.png
narration: ./audio/intro.wav
duration: 4.5
- type: clip
clip: ./clips/interaction.mp4
narration: ./audio/interaction.wav
Top-level fields
outputsets the destination path for the assembled MP4, resolved relative to the manifest; the--outputor-OutputPathargument overrides it when suppliedresolutioncontrols the output width and height inWIDTHxHEIGHTform (default1280x720); the--resolutionor-Resolutionargument overrides itfpssets the frame rate applied when rendering each segment (default24); the--fpsor-Fpsargument overrides ittransitionenables synchronized scene and narration fades; omit it or set it tononeto retain hard cuts
Transition fields
typeacceptscrossfadeorfade, which both select FFmpeg's fade cross-transitiondurationsets every opening, scene, audio, and closing fade in seconds (default0.5)fade_incontrols the opening video and audio fade (defaulttrue)fade_outcontrols the closing video and audio fade (defaulttrue)
The assembler adds silent handles around speech and holds the matching endpoint pictures. Crossfades overlap those handles, not adjacent spoken instructions; do not pre-pad narration to compensate. The normalized segments must exceed twice the transition duration. Output duration is the sum of unpadded narration durations plus one transition duration per scene boundary and per enabled opening/closing fade. With transitions disabled, no handles are added.
Segment fields
typeidentifies whether the segment is a still image (frame) or a motion clip (clip)visualpoints to an image file for a frame segmentclippoints to a motion clip file for a clip segmentnarrationpoints to the WAV file generated from narration text (the script also acceptsnarration_wavas an alias)durationis optional and overrides the inferred duration when you want a fixed segment length
Quick Start
Use the bash or PowerShell wrappers to invoke the assembler from the skill directory.
scripts/assemble-video.sh --manifest examples/segments.yml --output ./output/demo.mp4
scripts/Invoke-AssembleVideo.ps1 -ManifestPath examples/segments.yml -OutputPath ./output/demo.mp4
Parameters Reference
The assembly step accepts the following high-level controls:
--manifestor-ManifestPathselects the YAML manifest to process--outputor-OutputPathsets the destination MP4 path--fpsor-Fpscontrols the output frame rate for rendered segments--resolutionor-Resolutioncontrols the output width and height in the formWIDTHxHEIGHT--timeoutor-TimeoutSecondssets the maximum seconds for each ffprobe or ffmpeg invocation (1-86400, default 600); a timed-out step stops the run with an error that names the stepdurationper segment lets you override the inferred length when narration timing is known in advance
Failure Behavior
The assembled MP4 is written to a temporary file next to the destination and moved into place only after FFmpeg succeeds. A failed, timed-out, interrupted, or invalid transition run leaves no partial MP4 at the output path and keeps any existing file there unchanged. A successful run replaces an existing file at the output path. Temporary segment files are always removed.
Narration Quality
Narration quality is the single biggest driver of how polished the final video feels. Generate narration with neural voices from Azure AI Speech (part of Azure AI Foundry) through the tts-voiceover skill, for example en-US-Andrew:DragonHDLatestNeural or en-US-Jenny:DragonHDLatestNeural. These produce natural, presentation-grade narration.
This skill assembles video locally with FFmpeg and does not generate video with an AI model. When the narration is synthetic, tell viewers that the voice is AI-generated. HVE demo-material CI publishes silent videos; internal silent timing tracks are removed during finalization.
See the tts-voiceover skill for the neural voice catalog, --voice and --rate controls, and Azure authentication (Microsoft Entra ID recommended, or a key).
Reuse Bridge
This skill is intentionally designed to fit into the existing media workflow:
tts-voiceoverprovides the narration WAV files that this skill muxes into the final output; prefer its Azure AI Speech neural voices for production-quality narrationvscode-playwrightprovides the frame-capture source for prototype walkthroughs and screen-based demos
Prerequisites
FFmpeg and ffprobe must be available on your PATH.
Linux
sudo apt update && sudo apt install ffmpeg
macOS
brew install ffmpeg
Windows
winget install FFmpeg.FFmpeg
04 同仓库更多 Skills
statistical-hypothesis-testing
Compare binary rates or average values across affected and unaffected cohorts during root cause analysis. Use when root-cause-analysis selects an applicable affected-versus-unaffected cohort comparison.
root-cause-analysis
Investigate incidents, software defects, and data or process failures by forming falsifiable hypotheses, executing tests against available evidence, and iterating to a verified causal explanation or an explicit evidence blocker. Use when performing root cause analysis, incident investigation, or postmortem analysis, with cost and model choice confirmed before a full investigation.
causal-evidence-likelihood
Assess how one evidence item changes an RCA hypothesis using an uncalibrated, model-elicited likelihood-ratio band. Use when root-cause-analysis selects an eligible hypothesis-evidence pair.
untrusted-content-boundary
Untrusted-content boundary: treat ingested external content as data, not instructions, and refuse embedded authority changes. Preloaded by agents that read external, tracker, or user-supplied content.
telemetry-foundations
Declarative OpenTelemetry-aligned telemetry vocabulary and instrumentation conventions for traces, metrics, logs, and PII handling
pr-reference
Generates PR reference XML with commit history and unified diffs between branches, with extension and path filtering. Use when creating pull request descriptions, preparing code reviews, analyzing branch changes, discovering work items from diffs, or generating structured diff summaries.