Video pipeline: from script to a YouTube-ready MP4

Why use this video pipeline?

Here is the practical problem: you have something worth sharing, but producing a watchable video takes time and skills you may not have.

Perhaps you want to share an overview of a new robot vacuum with friends, demonstrate a one-tap “Away” automation on your Home Assistant dashboard, or record instructions showing a child how to control the living-room lights from a tablet. Editing, narration, and captions can turn a simple idea into hours of work—and operating the interface while speaking often takes several attempts.

The built-in video pipeline addresses that problem. The add-on provides the underlying tools—ffmpeg, Playwright with Chromium, edge-tts, and rclone—while an installed Skill coordinates them. Community versions are often called pitch_video or pi-video; the actual slug depends on the version you install (see Chapter 15). Tell the AI, in English, what kind of video you want, how long it should be, and who will watch it. The pipeline then works through these stages:

• Draft the script—organize the opening, main content, and closing, with a duration for each section.
• Generate narration—use Microsoft's edge-tts engine to convert the English script into speech.
• Capture the screen—open an invisible browser with Playwright and record the scripted actions scene by scene.
• Edit the video—combine the visuals, narration, and subtitles with ffmpeg, then add transitions.
• Upload the result—send the completed video to a configured Google Drive folder with rclone so that it is available on your other devices.

The rendering work runs on your Home Assistant host, so you do not need a separate editing computer or another software subscription. Your two main tasks are to define the video clearly and decide whether the finished result meets your needs. The AI and the tools handle the production steps.

What happens behind the scenes: six stages

To use the pipeline effectively, first understand what it does. Think of it as a production line in which six stages turn your request into a finished file:

Altogether, a 3-minute video usually takes about 5 to 10 minutes from the moment you approve the job until it reaches Google Drive. The exact time depends on your hardware, network, and installed Skill. You can do something else while the pipeline runs quietly on the Home Assistant host.

Why does first startup download 720 MB?

When first installed (see Chapter 2), Pi Agent itself is only a few dozen MB. The first time you start the add-on, however, it downloads approximately 600–720 MB in the background. That might take 1–2 minutes on a 100 Mbps home connection and will be more noticeable on a mobile hotspot. One common misconception is worth correcting: the video pipeline does not trigger this download. The add-on's video-tools-init process starts it in the background on first launch. Nor does the 720 MB contain every pipeline tool; it is the portion downloaded to the /data/pi-agent/ volume. The other portion—ffmpeg, libass, fonts, and rclone—is already built into the add-on's container image and arrives with the roughly 300 MB image download.

This is the download commonly described as “about 720 MB”; the actual total is between 600 and 720 MB, depending on the Playwright version and pip dependencies. The following tools require no additional download because they are part of the container image:

If you never install Pi Agent, it never uses this additional 720 MB. Once you start the add-on, however, the files are downloaded to the volume even if you never create a video; there is currently no “chat-only mode” switch. Chapter 18 explains the details.

Where this pipeline works well

Match the pipeline's strengths to practical situations and you will find more uses than you might expect:

These examples have one feature in common: they are short videos driven by explanation rather than on-camera performance. You do not need to appear on screen, choreograph complex camera moves, or buy expensive equipment. The pipeline turns knowledge into narration, visuals, and subtitles—a format that can be easier to follow than plain text and far quicker to produce than a manually edited video.

Where this pipeline falls short

No tool can do everything. Avoid forcing pitch_video into the following situations, where a different production method will give you a much better result:

Hands-on: create your first video

Assume you have completed all 3 prerequisites: the first-start download in Chapter 18, rclone setup for Google Drive in Chapter 19, and pitch_video Skill installation in Chapter 15. Here is how to produce a video:

1. Open a new Session and choose a reasoning-capable AI

   Return to the main Pi Agent screen and select “New conversation” in the upper-left corner to create a Session (see Chapter 8). Choose a reasoning model from the model menu—for example, GLM-4.6, Anthropic Claude Sonnet, or DeepSeek-R1. Do not use the least capable budget model: the script determines the video's quality, so this is one place where a stronger model is worthwhile. As Chapter 12 explains, reasoning models plan before answering and tend to produce better-structured scripts.

2. Describe the video clearly in plain language

   Type your request directly into the conversation. For example: “Create a 90-second video in English explaining how much electricity our smart plug could save for a typical 3-person household. Use a relaxed tone for an older general audience.” Include 4 elements: (1) length, (2) topic, (3) tone, and (4) audience. The more specific your request, the closer the English script will be to what you want.

3. Review the outline and request changes

   The AI should first show you an outline and draft script rather than immediately starting production—for example, a 10-second opening that introduces the problem, a 60-second main section with 3 points about saving energy, and a 20-second call to action. Review it carefully: Is the order right? Does the tone sound like you? Has it included anything you do not want? Reply with specific English instructions such as “In the English script, rewrite the second section to focus on XX” or “Shorten the English opening to 5 seconds.” The AI will revise it. Several rounds of revision are normal and much faster than rebuilding the final video later.

4. Approve the script and let the AI call the pitch_video Skill

   Once you reply, “Yes, use this English script,” the AI calls the pitch_video Skill installed in Chapter 15. A tool card appears in the conversation (see Chapter 9) and reports the current stage: generating narration, capturing the screen, or editing. You can leave the window while it works; the job continues even when you are not watching it.

5. Retrieve the finished video a few minutes later

   If you configured Google Drive upload (see Chapter 19), the finished MP4 appears in the selected folder and may trigger a notification in the Google Drive mobile app. Without Google Drive, the file remains at /data/pi-agent/projects/<project-name>/ on the Home Assistant host. Download it with a file-management add-on such as Samba or File Editor.

6. If you are not satisfied, ask for another version

   If the narration is too fast, the subtitles are poorly positioned, or a section is too long, give the AI a new English instruction in the same Session: “Create another English version with slower narration and no opening section.” It can adjust the settings and rerun the same script. If the script itself needs work, say, “Rewrite the entire script in English in an XXX style,” and the pipeline will start again from the beginning. You do not have to edit the configuration file yourself; describe the revisions in the conversation.

Where the final and intermediate files are stored

The pipeline produces more than a single MP4. It also retains intermediate files that you can edit, reuse, or process independently. They are stored under /data/pi-agent/projects/<project-name>/; the add-on creates the projects/ directory on first startup, and you can verify it in File Editor. The filenames and extensions below represent a typical layout for a community pitch_video Skill. The webm, wav, and srt extensions match common Playwright, edge-tts, and ffmpeg outputs. Your installed version or custom configuration may differ, so treat the files in your project directory as authoritative:

This structure means that you are not limited to accepting the final video or starting again from scratch. To change the script, edit script.md and rerun the workflow. To use a different voice, replace the contents of voice/. To reuse a single section, take it from segments/. This is a composable workflow: every stage leaves an asset that you can work with.

Complete these 3 prerequisites first

A common first-time frustration is asking the AI, in English, to create a video and being told that it cannot. In most cases, one of these prerequisites is missing:

Completing all 3 gives you the full end-to-end workflow. You can skip Google Drive while testing; the output remains in /data/pi-agent/projects/ and can be retrieved with a file-management add-on, but it will not synchronize automatically to your other devices.

What does one video cost?

The pipeline itself has little direct monetary cost. The primary usage-based expense is the API call used to write and revise the English script. Always check the current terms and prices for your chosen services:

For a 90-second video, the model and the number of revisions determine most of the direct cost. A lower-cost provider can reduce that amount, although a less capable model may produce a weaker script. Choose according to the quality you need and verify the live rate before running a large batch.

Advanced: parameters you can customize

The default pipeline output should already be usable. Once you have completed several successful runs, you can consider adjusting the following settings:

• Resolution: The default is 1080p (Full HD). At 720p, files are smaller and uploads are faster, which suits group-chat sharing. A 4K file is much larger and is generally worthwhile only for platforms such as YouTube.
• Frame rate: The default is 30 fps (30 frames per second). A 60 fps video is smoother but larger; 24 fps can create a cinematic feel, although screen motion may look less fluid.
• Narration voice: Choose an English edge-tts voice that suits your audience. The source-language examples are zh-TW-HsiaoChenNeural (female), zh-TW-YunJheNeural (male), zh-TW-HsiaoYuNeural (female, younger), and the zh-CN-* family. For an English video, consult the current voice catalog and select an English voice ID.
• Narration speed: edge-tts supports rate="+20%" to speed up speech and -20% to slow it down. A slightly slower pace can make explanatory narration easier to follow.
• Subtitle font: The default is Noto Sans CJK. To use another font, place the font file in the path expected by the Skill and update the configuration.
• Transition duration: The xfade filter defaults to 0.5 seconds. Use 0.2 seconds for faster cuts or 1 second for a slower, more cinematic transition.
• Subtitle position: The default is bottom-center. You can move subtitles to the top, lower-left, or center by changing the libass ASS style.

These settings are stored in the installed video Skill under /data/pi-agent/skills/<skill name>/. The configuration is usually in config.yaml or YAML frontmatter within SKILL.md; consult the Skill's README for the version you installed. Open the file with the File Editor add-on, make the change, and save it. Run 3 to 5 videos successfully before customizing anything so that you have a known-good baseline and can identify which change caused a failure.

Common problems and solutions

1. “AI is writing the script” takes a long time, or the script lacks depth

   The selected model is probably not capable enough for the task. A budget model such as GLM-Flash, or another non-reasoning model, may return a shallow list rather than a well-structured script. Switch to a reasoning model such as GLM-4.6, Claude Sonnet, or DeepSeek-R1 (see Chapter 12). Use the model menu in the lower-left corner of the Pi Agent conversation, then ask: “Rewrite this script in English with the same requirements and a clearer structure.”

2. The recording is black, or the entire video has no picture

   The Playwright environment was not installed correctly. This is the most common Chapter 18 problem: the first-start download was interrupted, Chromium was not fully extracted, or a shared library is missing. Follow the “Trigger the download again” instructions in Chapter 18. Delete both the Chromium download directory at /data/pi-agent/playwright-cache/ and the sentinel file at /data/pi-agent/.video-tools-installed, then restart the add-on to reinstall them.

3. The video has pictures and narration, but no subtitles—or the subtitles appear as boxes or question marks

   There are 2 likely causes: (a) ffmpeg did not burn the SRT file into the video—check the Skill configuration for a subtitle or burn-in option, whose exact name depends on the installed version; or (b) the subtitles were added, but the selected font is missing. The add-on includes fonts-noto-cjk, so a missing-font error usually means that the Skill specifies a non-default font file that does not exist. Solution: change the Skill's font setting back to Noto Sans CJK TC, or run fc-list :lang=zh-tw in a ttyd terminal to see which Traditional Chinese fonts the system recognizes.

4. The video finished, but it did not appear in Google Drive

   rclone may be misconfigured, or the Google account may have exceeded its storage quota. Run the diagnostics in the “Check rclone status” section of Chapter 19. The most common causes are (a) an expired rclone token that requires authorization again, or (b) a full Google Drive account. Follow the exact error message to renew authorization or free storage.

5. The pipeline crashes halfway through, and Home Assistant becomes very slow

   The Home Assistant host may be short of CPU or memory. The pipeline needs a dual-core CPU and at least 2 GB of memory for acceptable performance; a Raspberry Pi 3 or very old mini PC may struggle. Solutions: (a) check memory use under Home Assistant System → Hardware; (b) stop other resource-intensive add-ons such as Frigate or Whisper; (c) move to a Pi 5 or x86 mini PC if the host is too limited; or (d) reduce the video to 720p at 24 fps. The source estimates that the last option can halve resource requirements.

6. The narration stutters or contains noise

   The connection from edge-tts to Microsoft's service may be unstable. Confirm that the Home Assistant host has a reliable internet connection; use ping speech.platform.bing.com to check for packet loss. The source uses zh-TW-HsiaoChenNeural as its local example; for this English workflow, choose an English voice from the current edge-tts catalog or wait for the connection to improve before running the English narration again. This is an external-service issue rather than an ffmpeg rendering problem.

Frequently asked questions