How mmagdyelsafty/faceless-video-pipeline works
1. Overall shape
- This is a local, file-driven production pipeline for faceless YouTube videos.
- The main orchestration point is pipeline.py, which runs the workflow in four phases: TTS prep, patch build, final assembly, and deliverables.
- The repo is organized by pipeline stage: core/, tts/, video/, and post/.
2. Primary data model
- The source inputs are an episode script and a slide plan, stored per episode under episodes/<channel>/<episode>/.
- The slide plan is JSON, with examples/sample_plan.json showing the expected structure.
- Generated artifacts flow through the episode folder: formatted TTS text, slide HTML, exported PNGs, audio, subtitles, patch videos, then a final assembled video.
3. Orchestration boundary
- pipeline.py is the system integrator, not the business logic holder.
- It sequences validation, slide generation, export, audio/video assembly, watermarking, subtitle generation, thumbnail generation, and metadata creation.
- The phase split makes each stage independently rerunnable, which is a key architectural decision: patch-level outputs are treated as durable checkpoints.
4. Script and TTS preparation
- tts/format_script_tts.py prepares the raw script for voice recording or TTS rendering.
- tts/tts_patch_splitter.py divides the episode into smaller patches, adding recording instructions per patch.
- This subsystem isolates narration preparation from visual production, enabling review and re-recording without rebuilding the whole episode.
5. Slide generation core
- core/slide_builder.py converts the JSON slide plan into HTML slides using a built-in design system.
- The slide system supports multiple slide types such as headers, stats, comparisons, timelines, and closing cards.
- core/validate_script.py and core/validate_slides.py act as quality gates before export, enforcing content and structure expectations.
6. Rendering boundary
- core/export_slides.py is the HTML-to-image bridge.
- The README indicates Playwright/Chromium is used to export slides as PNGs, so this stage depends on a browser runtime even though the output is static media.
- This is the main handoff from content/layout logic into renderable assets for video assembly.
7. Video assembly
- video/build_video.py is the core compositor that combines slide images and audio into a patch video.
- video/audio_mixer.py handles voiceover plus background music, including automatic ducking so narration stays dominant.
- video/watermark.py overlays branding, and video/intro_outro_builder.py generates branded opening and closing segments.
8. Subtitle and timing layer
- video/subtitle_generator.py generates SRT subtitles and merges subtitles across patch outputs.
- This indicates the pipeline treats narration timing as part of the video product, not as a separate afterthought.
- Subtitle generation sits downstream of TTS/audio preparation and upstream of final assembly.
9. Post-production deliverables
- The post/ subsystem handles publishing prep rather than video content creation.
- post/thumbnail_generator.py creates A/B thumbnail variants.
- post/metadata_generator.py builds YouTube-facing metadata such as title, description, chapters, tags, and hashtags.
- These outputs are designed for upload readiness, but the repo does not include the upload step itself.
10. Branding and configuration
- Local brand assets live under brand/ and are intentionally git-ignored: logos, audio cues, and fonts.
- config.example.json defines the expected configuration shape, while a local config.json provides channel-specific settings and paths.
- The architecture supports multi-language channels, including RTL layouts, by separating language/channel configuration from episode content.
11. Execution model
- The pipeline is patch-based, typically splitting an episode into five independently produced segments.
- This reduces risk: each segment can be reviewed, corrected, and regenerated without redoing the entire episode.
- Final assembly stitches intro + patches + outro into the finished video, then merges subtitles and produces deliverables.
12. External tooling and runtime dependencies
- The pipeline is Python-based and relies on ffmpeg for audio/video processing.
- Playwright Chromium is required for HTML rendering and thumbnail generation.
- These tools materially define the architecture because the system is a content pipeline built on static asset generation plus local media processing, not a server application.
Main entry points: build_video.py Video Builder · pipeline.py Pipeline · export_slides.py Export Slides · validate_script.py Script Check
Components 19
Orchestration
Top-level workflow and execution boundary.
- Pipeline · Main entrypoint that runs the episode workflow through staged checkpoints.
pipeline.py
Content Prep
Script, slide plan, and slide generation.
- Script Check · Validates the episode script before narration and slide generation.
core/validate_script.py - Slide Check · Validates slide structure and content before rendering.
core/validate_slides.py - Slide Builder · Converts slide plans into HTML slides using the built-in design system.
core/slide_builder.py - TTS Script · Formats raw script text for voice recording or TTS rendering.
tts/format_script_tts.py - Patch Splitter · Breaks the episode into recording patches and adds patch-level instructions.
tts/tts_patch_splitter.py
Rendering
HTML export and media assembly.
- Export Slides · Renders HTML slides into PNG assets for video assembly.
core/export_slides.py - Browser Runtime · Chromium/Playwright runtime used for slide and thumbnail rendering.
- Audio Mixer · Combines narration and music with ducking so voice stays dominant.
video/audio_mixer.py - Video Builder · Builds patch videos from slide images, audio, and timing information.
video/build_video.py - Intro/Outro · Creates branded opening and closing segments for the final assembly.
video/intro_outro_builder.py - Subtitles · Generates SRT subtitles and merges subtitles across patch outputs.
video/subtitle_generator.py - Watermark · Adds brand watermarking to video outputs.
video/watermark.py - FFmpeg · External media processing tool used for audio and video composition.
Post
Thumbnail and metadata deliverables.
- Thumbnails · Creates A/B thumbnail variants for upload readiness.
post/thumbnail_generator.py - Metadata · Builds title, description, chapters, tags, and hashtags for the episode.
post/metadata_generator.py
Assets
Episode workspace and shared inputs.
- Episode Files · Per-episode folder holding script, plan, rendered assets, audio, subtitles, and final outputs.
- Config · Local channel and path configuration used across the pipeline.
config.example.json - Sample Plan · Example slide plan showing the expected episode plan structure.
examples/sample_plan.json
Connections 28
- Config → Pipeline: settings · Provides channel, language, and path configuration to the workflow.
- Sample Plan → Slide Builder: plan shape · Defines the expected structure for episode slide plans.
- Episode Files → Script Check: script · Supplies the episode script as the first validation input.
- Episode Files → TTS Script: script · Feeds the raw episode script into narration preparation.
- Script Check → Patch Splitter: approved script · Allows split-and-patch narration preparation after script validation.
- TTS Script → Patch Splitter: tts text · Provides cleaned narration text for patch segmentation.
- Episode Files → Slide Check: slide plan · Supplies the episode plan for structural validation.
- Slide Check → Slide Builder: validated plan · Allows HTML slide generation after plan validation.
- Slide Builder → Export Slides: html slides · Hands off generated slides for browser-based export.
- Export Slides → Browser Runtime: render · Uses the browser runtime to rasterize slides to images.
- Export Slides → Video Builder: pngs · Provides rendered slide images to the compositor.
- Patch Splitter → Audio Mixer: patch audio · Feeds narration segments into audio mixing.
- Audio Mixer → FFmpeg: mixing · Relies on ffmpeg for audio processing and ducking.
- Video Builder → FFmpeg: composition · Uses ffmpeg for video assembly and patch rendering.
- Intro/Outro → Video Builder: segments · Supplies branded intro and outro segments for final assembly.
- Watermark → Video Builder: branding · Adds watermark overlays during video composition.
- Subtitles → Video Builder: captions · Provides subtitles for patch and final outputs.
- Video Builder → Pipeline: patch video · Returns durable patch-level video checkpoints to orchestration.
- Video Builder → Subtitles: timing · Supplies timing context used to generate subtitles.
- Video Builder → Thumbnails: frames · Provides visual assets that can support thumbnail creation.
- Video Builder → Metadata: episode output · Feeds completed episode context into publish-prep metadata generation.
- Pipeline → Thumbnails: deliverables · Triggers thumbnail generation as part of the final phase.
- Pipeline → Metadata: deliverables · Triggers metadata generation as part of the final phase.
- Pipeline → Episode Files: read/write · Reads inputs and writes staged artifacts back into the episode folder.
- Pipeline → Script Check: phase 1 · Starts the workflow with script validation and TTS preparation.
- Pipeline → Slide Check: phase 2 · Validates slide structure before rendering.
- Pipeline → Export Slides: phase 3 · Runs slide export and downstream media assembly.
- Pipeline → Video Builder: phase 4 · Assembles patch videos and final video deliverables.