# doctordiffusion/comfyui-mediamixer architecture

> Architecture diagram of the GitHub repository doctordiffusion/comfyui-mediamixer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/doctordiffusion/comfyui-mediamixer
- Repository: https://github.com/doctordiffusion/comfyui-mediamixer

## Overview

1. **Repository role and boundary**
   - This is a **ComfyUI custom node package** called **MediaMixer**.
   - It is not a standalone application; it extends ComfyUI with video-centric utility nodes that plug into ComfyUI’s graph/runtime.

2. **Core integration point**
   - `__init__.py` is the package entry point that ComfyUI loads to discover node classes and display names.
   - The rest of the Python files each implement a node, following ComfyUI’s custom-node contract.

3. **Primary subsystems**
   - **Video composition**: `video_merge.py`
   - **Frame extraction / selection**: `final_frame_selector.py`
   - **Frame order manipulation**: `reverse_frame_sequence.py`
   - **Text batching / prompt management**: `prompt_journal.py`
   - **External media acquisition**: `youtube_video_downloader.py`

4. **Video composition flow**
   - `video_merge.py` combines two video inputs, matching the README’s “Video_A” + “Video_B” use case.
   - Architecturally, this is the node that supports the “extend video” workflow: one clip is treated as the existing source, the other as the newly generated continuation.

5. **Frame-sequence utilities**
   - `final_frame_selector.py` and `reverse_frame_sequence.py` operate on image sequences or video-derived frames rather than on full editing timelines.
   - The selector node extracts a boundary frame for downstream image-to-video generation.
   - The reverse node transforms frame order so a sequence can be played backward or used to invert motion.

6. **Prompt batching subsystem**
   - `prompt_journal.py` manages text lists and emits a single selected line plus the full text.
   - This is a workflow utility for batching or randomizing prompts inside ComfyUI, especially for repeated video generation runs.

7. **External download path**
   - `youtube_video_downloader.py` introduces an external source boundary: it pulls media from YouTube through **yt-dlp**.
   - This is the only node in the set that clearly reaches outside the local ComfyUI graph to acquire source media from the internet.

8. **Example workflow artifact**
   - `workflows/VideoExtend_PFMF_v1.json` is a saved ComfyUI workflow demonstrating how these nodes are composed together.
   - From the repository shape and README, this workflow likely connects frame selection, generation, and merge stages into a video-extension pipeline.

9. **Runtime and dependency model**
   - The package runs inside the **ComfyUI Python environment**.
   - `requirements.txt` pins the runtime dependencies, with **yt-dlp** called out explicitly in the README because it may need manual installation in ComfyUI’s embedded Python setup.

10. **Data model across the graph**
   - The dominant data types are:
     - **video clips**,
     - **frame/image sequences**,
     - **single images** for key-frame handoff,
     - **text prompts** for generation control.
   - The architectural pattern is: ingest media → manipulate frames or prompts → hand off to generation nodes → merge/output final video.

11. **Important boundary for diagramming**
   - Treat this repo as a set of **graph nodes**, not a monolithic pipeline.
   - The key architectural boundary is between:
     - **ComfyUI orchestration** on one side, and
     - **utility/media transformations** performed by these nodes on the other.

12. **What to show in an architecture diagram**
   - A ComfyUI host box containing the MediaMixer node suite.
   - Separate nodes for merge, frame selection, reverse, prompt journaling, and YouTube download.
   - Arrows showing media flowing from download or local inputs into frame utilities, then into generation/merge.
   - A distinct external service boundary for YouTube/yt-dlp.

Main entry points: [`__init__.py`](https://github.com/doctordiffusion/comfyui-mediamixer/blob/main/__init__.py) (MediaMixer), [`final_frame_selector.py`](https://github.com/doctordiffusion/comfyui-mediamixer/blob/main/final_frame_selector.py) (Frame Selector), [`workflows/VideoExtend_PFMF_v1.json`](https://github.com/doctordiffusion/comfyui-mediamixer/blob/main/workflows/VideoExtend_PFMF_v1.json) (Extend Workflow), [`youtube_video_downloader.py`](https://github.com/doctordiffusion/comfyui-mediamixer/blob/main/youtube_video_downloader.py) (YouTube Downloader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_comfyui["ComfyUI host"]
  node_comfyui_host["ComfyUI<br/>runtime host"]
end

subgraph group_media["MediaMixer nodes"]
  node_mediamixer_init["MediaMixer<br/>package entry<br/>[__init__.py]"]
  node_video_merge["Video Merge<br/>video composition node<br/>[video_merge.py]"]
  node_final_frame_selector["Frame Selector<br/>frame utility node"]
  node_reverse_frame_sequence["Reverse Frames<br/>frame utility node"]
  node_prompt_journal["Prompt Journal<br/>text batching node<br/>[prompt_journal.py]"]
  node_youtube_video_downloader["YouTube Downloader<br/>ingest node"]
end

subgraph group_external["External source"]
  node_youtube_service(("YouTube / yt-dlp<br/>external source"))
end

subgraph group_workflows["Example workflow"]
  node_workflow_example["Extend Workflow<br/>saved workflow"]
end

node_comfyui_host -->|"loads"| node_mediamixer_init
node_mediamixer_init -->|"registers"| node_video_merge
node_mediamixer_init -->|"registers"| node_final_frame_selector
node_mediamixer_init -->|"registers"| node_reverse_frame_sequence
node_mediamixer_init -->|"registers"| node_prompt_journal
node_mediamixer_init -->|"registers"| node_youtube_video_downloader
node_youtube_video_downloader -.->|"fetches from"| node_youtube_service
node_youtube_video_downloader -->|"supplies media"| node_final_frame_selector
node_final_frame_selector -->|"sequences frames"| node_reverse_frame_sequence
node_prompt_journal -->|"feeds prompts"| node_workflow_example
node_final_frame_selector -->|"feeds keyframe"| node_workflow_example
node_reverse_frame_sequence -->|"feeds frames"| node_workflow_example
node_workflow_example -->|"demonstrates merge"| node_video_merge

click node_mediamixer_init "https://github.com/doctordiffusion/comfyui-mediamixer/blob/main/__init__.py"
click node_video_merge "https://github.com/doctordiffusion/comfyui-mediamixer/blob/main/video_merge.py"
click node_final_frame_selector "https://github.com/doctordiffusion/comfyui-mediamixer/blob/main/final_frame_selector.py"
click node_reverse_frame_sequence "https://github.com/doctordiffusion/comfyui-mediamixer/blob/main/reverse_frame_sequence.py"
click node_prompt_journal "https://github.com/doctordiffusion/comfyui-mediamixer/blob/main/prompt_journal.py"
click node_youtube_video_downloader "https://github.com/doctordiffusion/comfyui-mediamixer/blob/main/youtube_video_downloader.py"
click node_workflow_example "https://github.com/doctordiffusion/comfyui-mediamixer/blob/main/workflows/VideoExtend_PFMF_v1.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_comfyui_host toneBlue
class node_mediamixer_init,node_video_merge,node_final_frame_selector,node_reverse_frame_sequence,node_prompt_journal,node_youtube_video_downloader toneAmber
class node_youtube_service toneMint
class node_workflow_example toneRose
```

## Components

### ComfyUI host

The Python runtime and graph host that loads MediaMixer custom nodes.

- **ComfyUI**: runtime host · Host environment that loads custom nodes and executes graphs.

### MediaMixer nodes

The custom node package boundary and its media utilities.

- [MediaMixer](https://github.com/doctordiffusion/comfyui-mediamixer/blob/main/__init__.py): package entry · Package entry point discovered by ComfyUI to register node classes and display names. · `__init__.py`
- [Video Merge](https://github.com/doctordiffusion/comfyui-mediamixer/blob/main/video_merge.py): video composition node · Combines two video inputs to support video extension workflows. · `video_merge.py`
- [Frame Selector](https://github.com/doctordiffusion/comfyui-mediamixer/blob/main/final_frame_selector.py): frame utility node · Selects a boundary frame from a sequence or clip for downstream generation. · `final_frame_selector.py`
- [Reverse Frames](https://github.com/doctordiffusion/comfyui-mediamixer/blob/main/reverse_frame_sequence.py): frame utility node · Reorders frame sequences so motion can be played backward or inverted. · `reverse_frame_sequence.py`
- [Prompt Journal](https://github.com/doctordiffusion/comfyui-mediamixer/blob/main/prompt_journal.py): text batching node · Manages prompt lists and emits a selected line alongside the full text. · `prompt_journal.py`
- [YouTube Downloader](https://github.com/doctordiffusion/comfyui-mediamixer/blob/main/youtube_video_downloader.py): ingest node · Fetches external media through yt-dlp for use inside ComfyUI graphs. · `youtube_video_downloader.py`

### External source

Outside services reached by the downloader node.

- **YouTube / yt-dlp**: external source · Remote media source accessed by the downloader node.

### Example workflow

Saved ComfyUI workflow showing how the nodes compose into a video-extension pipeline.

- [Extend Workflow](https://github.com/doctordiffusion/comfyui-mediamixer/blob/main/workflows/VideoExtend_PFMF_v1.json): saved workflow · Example ComfyUI workflow demonstrating frame selection, generation, and merge stages. · `workflows/VideoExtend_PFMF_v1.json`

## Connections

- ComfyUI → MediaMixer: loads · ComfyUI imports the package entry point to discover available nodes.
- MediaMixer → Video Merge: registers · The entry point exposes the video merge node to the host.
- MediaMixer → Frame Selector: registers · The entry point exposes the frame selector node to the host.
- MediaMixer → Reverse Frames: registers · The entry point exposes the frame reversal node to the host.
- MediaMixer → Prompt Journal: registers · The entry point exposes the prompt batching node to the host.
- MediaMixer → YouTube Downloader: registers · The entry point exposes the external media ingestion node to the host.
- YouTube Downloader → YouTube / yt-dlp: fetches from · Media is retrieved from YouTube via yt-dlp.
- YouTube Downloader → Frame Selector: supplies media · Downloaded clips can be passed into frame selection workflows.
- Frame Selector → Reverse Frames: sequences frames · Selected frame sets can be reordered for motion inversion or backward playback.
- Prompt Journal → Extend Workflow: feeds prompts · Prompt batches drive repeated generation runs in the example workflow.
- Frame Selector → Extend Workflow: feeds keyframe · The example workflow uses a boundary frame for continuation generation.
- Reverse Frames → Extend Workflow: feeds frames · The example workflow can invert or reuse frame order as part of the pipeline.
- Extend Workflow → Video Merge: demonstrates merge · The saved workflow culminates in the video composition node.
