What I Learned Building Diagram Slides for a CI Video Pipeline
I recently added diagrams and charts to my automated YouTube video pipeline.
The main takeaway is simple: pre-render everything to a PNG file first.
Do not try to generate visuals inside your video engine or via ffmpeg. Use a shared PNG handoff instead. This makes every part of your pipeline testable and easy to replace.
Here is how I built it and what I learned.
The Architecture
My pipeline uses a two-host system. One host handles the visuals and audio. The other host uses ffmpeg to combine everything into a video.
Since ffmpeg cannot run JavaScript or call a browser, I had to solve the gap between different tools:
• Mermaid (for flowcharts) runs via Puppeteer and Chromium. • Matplotlib (for charts) runs via Python. • Pillow (for the slides) draws directly on images.
Because these tools cannot talk to each other directly, I use a single pattern: render to a PNG, then paste that PNG onto a Pillow canvas. One code path is better than two.
Key Technical Lessons
Configuring Chromium When running in GitHub Actions, Chromium will fail if you do not use specific flags. You must include --no-sandbox and --disable-setuid-sandbox. Without these, the container will block the process.
Mermaid Theming If you want custom colors, do not use the built-in dark or forest themes. Those themes override your settings. Use the "base" theme. This is the only way to ensure your custom palette works reliably.
Matplotlib Backgrounds Getting charts to match your slide background is tricky. You must do three things:
- Call matplotlib.use("Agg") before you import pyplot.
- Set the facecolor for both the figure and the axes.
- Use bbox_inches="tight" when saving the file to remove white borders.
- Reliability and Failsafes A missing diagram should not break your entire video build. I built a scaffold that catches errors. If a render fails, the pipeline simply shows a "visual unavailable" placeholder. The video still finishes. This allows you to review the content even if one part fails.
The Trade-off
Pre-rendering adds time. Each Mermaid diagram takes about 2 to 4 seconds to render. For a 20-segment video, this adds about 20 seconds to the total build time. For my needs, this is a fair trade for a stable system.