# vinlic/webvideocreator architecture

> Architecture diagram of the GitHub repository vinlic/webvideocreator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vinlic/webvideocreator
- Repository: https://github.com/vinlic/webvideocreator

## Overview

##### Project Type and Purpose
- This project is a video rendering engine that captures dynamic web animations (using HTML5 animations, CSS, SVG, Lottie, etc.) and converts them into video files. Its primary purpose is to let users generate and compose single, multi-scene, and chunk-based videos with added effects like transitions, audio overlays, and more.
- The README makes it clear that it supports single-shot video rendering, multi-scene transitions, and even distributed (chunk-based) video processing. It leverages external tools (Chrome – via Puppeteer –, FFmpeg, and even GPU hardware acceleration) to ensure accurate, deterministic rendering.

##### File Structure
- The top-level directories (such as api, core, docs, entity, examples, lib, media, preprocessor) give hints on how responsibilities are distributed.
– The “api” folder contains modules like SingleVideo, MultiVideo, ChunkVideo, and WebVideoCreator, which provide high-level user interfaces and orchestration functions.
– The “core” directory holds the heart of the rendering engine with modules like Browser, CaptureContext, Synthesizer, and ResourcePool. These control browser instance management, capture state management, and frame synthesis.
– The “preprocessor” directory further divides into “base” and “video” parts, indicating that pre-render tasks (such as downloading remote resources or processing video-specific tasks) are modularized.
– The “entity” folder defines various objects like Audio, Font, Transition, which encapsulate media properties and behave as data models.
– The “media” folder handles dynamic media elements (images, Lottie animations, MP4 demuxing) that are injected or captured during rendering.
– The “lib” folder contains utility scripts (config, logging, constants, util functions) plus third-party integration modules (e.g., fontfaceobserver, mp4box) that support overall operations.
- Additional files like package.json, index.js, and READMEs confirm that this package is intended to be consumed as an npm package.

##### README for Insights
- The README clearly explains how the system is used to render videos, showing code examples for single shots, multi-scene videos, and chunk-based video composition.
- It outlines system components like the “virtual time environment,” the integration with headless Chrome (including usage of experimental APIs), and the reliance on FFmpeg for encoding.

a. Main Components to Include:
– User/Application Interface: The entry point where a developer instantiates a WebVideoCreator instance and calls API methods (createSingleVideo, createMultiVideo, etc.).
– API Layer (located in the “api” directory): Handles high-level orchestration of different rendering modes.
– Core Rendering Engine (from “core”): Consists of Browser management (core/Browser.js), CaptureContext (core/CaptureContext.js), Page utilities (core/Page.js), Synthesizer (core/Synthesizer.js), and ResourcePool management to oversee shared browser/page instances.
– Media & Entity Handlers: Modules for Audio, Font, Transition (from “entity”) and media support (from “media”) that provide additional visual/audio effects.
– Preprocessing Layer: The “preprocessor” modules, which prepare and download remote resources (assets, videos, fonts) and carry out video-specific processing before actual rendering.
– Utility & Configuration Layer: Modules in “lib” that provide global configuration, logging, constants, and support functions.
– Integration with External Technologies: Represent external dependencies – Node.js runtime, Puppeteer/Chrome for rendering, and FFmpeg (using the integrated hardware-accelerated encoders) for video encoding and synthesis.

b. Relationships and Interactions:
– Within the Core Rendering Engine, the Browser module is responsible for starting headless Chrome instances and managing pages; then CaptureContext directs the frame-capturing process.
– The Captured frames are passed to the Synthesizer component, possibly with applied transitions or overlays from the Entity/Media modules.
– The Preprocessor works in parallel to retrieve or process remote assets and prepare media resources for injection into web pages.
– After synthesis, the frame stream goes to FFmpeg (via functionalities provided by “lib” scripts, which manage command-line invocations) to encode the final video.

c. Architectural Patterns & Design Principles:
– Layered Architecture: Separate API, core processing, pre-processing, and external interfacing.
– Modularity and Extensibility: Each folder (api, core, preprocessor, lib, entity, media) isolates a specific concern for easier maintenance, testing, and potential distributed rendering.
– Resource Pooling: The ResourcePool in the core ensures optimal reuse of Browser and Page instances.

d. Relevant Technologies:
– Node.js is the runtime.
– Puppeteer and Headless Chrome (with experimental BeginFrame API) are used for rendering web content.
– FFmpeg is used for encoding video with hardware acceleration (e.g., NVIDIA NVENC support).
– Utilities for media management (e.g., lottie-web, fontfaceobserver, mp4box) augment core functionality.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface
    subgraph "User/Application Interface"
        UUI("WebVideoCreator"):::ui
    end

    %% API Layer
    subgraph "API Layer"
        A1("SingleVideo"):::api
        A2("MultiVideo"):::api
        A3("ChunkVideo"):::api
    end

    %% Core Rendering Engine
    subgraph "Core Rendering Engine"
        B("Browser"):::core
        PG("Page"):::core
        RP("ResourcePool"):::core
        CC("CaptureContext"):::core
        S("Synthesizer"):::core
    end

    %% Media & Entity Handlers
    subgraph "Media & Entity Handlers"
        E1("Audio"):::media
        E2("Font"):::media
        E3("Transition"):::media
        M1("DynamicImage"):::media
        M2("LottieCanvas"):::media
        M3("MP4Demuxer"):::media
        M4("SvgAnimation"):::media
        M5("VideoCanvas"):::media
    end

    %% Preprocessing Layer
    subgraph "Preprocessing Layer"
        %% Base Preprocessing
        PB("PreprocessorBase"):::pre
        DT("DownloadTask"):::pre
        PT("ProcessTask"):::pre
        T("Task"):::pre
        %% Video-specific Preprocessing
        VP("VideoPreprocessor"):::pre
        VDT("VideoDownloadTask"):::pre
        VPT("VideoProcessTask"):::pre
        VC("VideoConfig"):::pre
    end

    %% Utility & Configuration Layer
    subgraph "Utility & Configuration Layer"
        GC("global-config"):::util
        CST("const"):::util
        LG("logger"):::util
        IU("inner-util"):::util
        UT("util"):::util
        CL("cleaner"):::util
        FO("fontfaceobserver"):::util
        LT("lottie"):::util
        MP("mp4box"):::util
    end

    %% External Dependencies
    subgraph "External Dependencies"
        N("Node.js"):::external
        CP("Chrome/Puppeteer"):::external
        F("FFmpeg"):::external
    end

    %% Connections
    %% User Interface to API Layer
    UUI -->|"invoke"| A1
    UUI -->|"invoke"| A2
    UUI -->|"invoke"| A3

    %% API Layer to Core Rendering Engine
    A1 -->|"orchestrate"| B
    A2 -->|"orchestrate"| B
    A3 -->|"orchestrate"| B

    %% External control of Browser
    CP -->|"launch"| B

    %% Core internal flow
    B -->|"initPage"| PG
    B -->|"resourcePool"| RP
    B -->|"capture"| CC
    CC -->|"frameOutput"| S

    %% Preprocessing feeds into Core
    PB -->|"prepareAssets"| S
    VP -->|"prepareAssets"| S

    %% Media & Entity integration into synthesis
    M5 -->|"mediaInput"| S
    E1 -->|"audioOverlay"| S

    %% Utility support (representative connection)
    LG -->|"support"| S

    %% Core to External Encoding
    S -->|"encode"| F

    %% External runtime support
    N -->|"runtime"| UUI

    %% Styles
    classDef ui fill:#87CEEB,stroke:#000,stroke-width:1px;
    classDef api fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef core fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef media fill:#F4A460,stroke:#000,stroke-width:1px;
    classDef pre fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef util fill:#FFFF99,stroke:#000,stroke-width:1px;
    classDef external fill:#DDA0DD,stroke:#000,stroke-width:1px;

    %% Click Events
    click UUI "https://github.com/vinlic/webvideocreator/blob/master/api/WebVideoCreator.js"
    click A1 "https://github.com/vinlic/webvideocreator/blob/master/api/SingleVideo.js"
    click A2 "https://github.com/vinlic/webvideocreator/blob/master/api/MultiVideo.js"
    click A3 "https://github.com/vinlic/webvideocreator/blob/master/api/ChunkVideo.js"
    click B "https://github.com/vinlic/webvideocreator/blob/master/core/Browser.js"
    click PG "https://github.com/vinlic/webvideocreator/blob/master/core/Page.js"
    click RP "https://github.com/vinlic/webvideocreator/blob/master/core/ResourcePool.js"
    click CC "https://github.com/vinlic/webvideocreator/blob/master/core/CaptureContext.js"
    click S "https://github.com/vinlic/webvideocreator/blob/master/core/Synthesizer.js"
    click E1 "https://github.com/vinlic/webvideocreator/blob/master/entity/Audio.js"
    click E2 "https://github.com/vinlic/webvideocreator/blob/master/entity/Font.js"
    click E3 "https://github.com/vinlic/webvideocreator/blob/master/entity/Transition.js"
    click M1 "https://github.com/vinlic/webvideocreator/blob/master/media/DynamicImage.js"
    click M2 "https://github.com/vinlic/webvideocreator/blob/master/media/LottieCanvas.js"
    click M3 "https://github.com/vinlic/webvideocreator/blob/master/media/MP4Demuxer.js"
    click M4 "https://github.com/vinlic/webvideocreator/blob/master/media/SvgAnimation.js"
    click M5 "https://github.com/vinlic/webvideocreator/blob/master/media/VideoCanvas.js"
    click PB "https://github.com/vinlic/webvideocreator/blob/master/preprocessor/base/Preprocessor.js"
    click DT "https://github.com/vinlic/webvideocreator/blob/master/preprocessor/base/DownloadTask.js"
    click PT "https://github.com/vinlic/webvideocreator/blob/master/preprocessor/base/ProcessTask.js"
    click T "https://github.com/vinlic/webvideocreator/blob/master/preprocessor/base/Task.js"
    click VP "https://github.com/vinlic/webvideocreator/blob/master/preprocessor/video/VideoPreprocessor.js"
    click VDT "https://github.com/vinlic/webvideocreator/blob/master/preprocessor/video/VideoDownloadTask.js"
    click VPT "https://github.com/vinlic/webvideocreator/blob/master/preprocessor/video/VideoProcessTask.js"
    click VC "https://github.com/vinlic/webvideocreator/blob/master/preprocessor/video/VideoConfig.js"
    click GC "https://github.com/vinlic/webvideocreator/blob/master/lib/global-config.js"
    click CST "https://github.com/vinlic/webvideocreator/blob/master/lib/const.js"
    click LG "https://github.com/vinlic/webvideocreator/blob/master/lib/logger.js"
    click IU "https://github.com/vinlic/webvideocreator/blob/master/lib/inner-util.js"
    click UT "https://github.com/vinlic/webvideocreator/blob/master/lib/util.js"
    click CL "https://github.com/vinlic/webvideocreator/blob/master/lib/cleaner.js"
    click FO "https://github.com/vinlic/webvideocreator/blob/master/lib/fontfaceobserver.js"
    click LT "https://github.com/vinlic/webvideocreator/blob/master/lib/lottie.js"
    click MP "https://github.com/vinlic/webvideocreator/blob/master/lib/mp4box.js"
```
