Extensions/ComfyUI_UniversalMediaLoader
ComfyUI Extension

ComfyUI_UniversalMediaLoader

An universal media loader for ComfyUI (Size, Image, Audio, Video)

By Fictiverse·Created about 21 hours ago·Updated about 21 hours ago· 7
Fictiverse/ComfyUI_UniversalMediaLoader
Nodes5
On cloudLocal install
Categoryloaders/universal_media
Stars7
Updatedabout 21 hours ago

Nodes (5)

Universal Audio Unpack
loaders/universal_media
Universal Image Unpack
loaders/universal_media
Universal Media Loader
loaders/universal_media
Universal Size Unpack
loaders/universal_media
Universal Video Unpack
loaders/universal_media
Readme

ComfyUI_UniversalMediaLoader

An all-in-one media loading suite for ComfyUI. Instead of switching between different loader nodes for images, videos, GIFs, audio, or canvas aspect ratios, ComfyUI_UniversalMediaLoader lets you drop any media file (or create custom canvas dimensions) directly inside an interactive visual UI.

https://github.com/user-attachments/assets/d0886d6d-dc10-410c-b9df-51970c88f124

📦 Nodes Overview

1. Universal Media Loader

The main interactive loader node. It accepts drag-and-dropped media files or acts as an empty canvas generator. It bundles all visual manipulations, cropping, masks, timeline trims, custom framerates, playback speeds, and metadata into a single lightweight MEDIA_DATA output.

  • Inputs: Interactive UI (Drag & drop media / Canvas configuration).
  • Outputs: media_data (MEDIA_DATA type).

2. Universal Size Unpack

Extracts dimension and aspect ratio information directly from media_data. Ideal for configuring Empty Latent Image sizes or conditioning generation dimensions without decoding heavy pixel tensors.

  • Inputs: media_data (MEDIA_DATA)
  • Outputs:
    • width (INT): Target output width.
    • height (INT): Target output height.
    • megapixels (FLOAT): Resolution in Megapixels (MP).
    • aspect_ratio (FLOAT): Aspect ratio value (e.g. 1.7778 for 16:9).
    • ratio_str (STRING): Ratio name (e.g. "16:9", "1:1", "free").
    • has_media (BOOLEAN): True if a valid media file exists on disk, False for canvas generator mode.

3. Universal Image Unpack

Extracts image and mask tensors from images, videos, animated GIFs, or blank canvases.

  • Inputs: media_data (MEDIA_DATA)
  • Outputs:
    • image (IMAGE): RGB tensor (normalized 0.0 - 1.0).
    • mask (MASK): Mask tensor (painted with inpaint brush or generated by outpainting).
    • rgba_image (IMAGE): 4-channel RGBA tensor.
    • width / height (INT): Current output dimensions.
    • orig_width / orig_height (INT): Original source dimensions.
    • megapixels (FLOAT): Target resolution in MP.
    • crop_x / crop_y / crop_w / crop_h (INT): Bounding box coordinates.
    • filename (STRING): Source file name.
  • Special Video & GIF Feature: When a video or GIF is connected to this node, it automatically extracts a batch of 3 keyframes: [Trim Start, Current Playhead Position, Trim End].

4. Universal Audio Unpack

Extracts waveforms, trimming ranges, and playback adjustments from audio or video files.

  • Inputs: media_data (MEDIA_DATA)
  • Outputs:
    • audio (AUDIO): ComfyUI audio dictionary {"waveform", "sample_rate"}.
    • sample_rate (INT): Audio sample rate (e.g. 44100).
    • duration (FLOAT): Duration of the trimmed/time-stretched audio in seconds.
    • orig_duration (FLOAT): Total duration of the original file.
    • trim_start / trim_end (FLOAT): Start and end trim points in seconds.
    • channels (INT): Number of audio channels.
    • filename (STRING): Source file name.

5. Universal Video Unpack

Decodes video files and animated GIFs into frame batches with synchronized audio and masks.

  • Inputs: media_data (MEDIA_DATA)
  • Outputs:
    • frames (IMAGE): Batched tensor of all decoded frames [B, H, W, C].
    • mask (MASK): Batched mask tensor matching the frame count.
    • audio (AUDIO): Synchronized, trimmed audio track (silent audio for GIFs/muted videos).
    • frame_count (INT): Total number of extracted frames.
    • fps (FLOAT): Output FPS (custom resampled or native).
    • orig_fps (FLOAT): Native file framerate.
    • duration / orig_duration (FLOAT): Trimmed and original durations in seconds.
    • width / height (INT): Frame dimensions.
    • megapixels (FLOAT): Resolution in MP.
    • trim_start / trim_end (FLOAT): Trim boundaries in seconds.
    • filename (STRING): Source file name.

🚀 Universal Media Loader Features

📁 Automatic Media Detection & Drag-and-Drop

Drop any file directly onto the node:

  • Images: .png, .jpg, .jpeg, .webp, .bmp
  • Videos & GIFs: .mp4, .webm, .mov, .mkv, .avi, .gif
  • Audio: .wav, .mp3, .flac, .ogg, .m4a, .aac

🎨 Canvas Generator Mode (No Media Loaded)

When no file is loaded, the node operates as an aspect ratio and latent resolution planner:

  • Aspect Presets: 1:1, 4:3, 3:2, 16:9 (Click active preset again to switch to Free mode).
  • Orientation Switcher: Instant toggle between Landscape ⇄ Portrait (3:4, 2:3, 9:16).
  • Target MP Clamping: Automatically calculates optimal width and height for any target megapixel limit.
  • 32px Grid Snapping: Ensures dimensions stay multiples of 32 (optimized for SD1.5, SDXL, and Flux latents).

✂️ Visual Crop & Outpaint Tool

  • Interactive Crop Box: Drag borders or corner handles to reframe visually.
  • Aspect Ratio Locking: Lock proportions to standard ratios or adjust freely.
  • Outpaint Mode: Expand the bounding box outside the original frame. Missing areas are automatically filled and masked for seamless outpainting workflows.
  • Grid Magnet: Snaps crop boundaries to multiples of 32 pixels.

🖌️ Inpainting Brush & Mask Editor

  • Paint masks directly over static images or video/GIF frames.
  • Eraser Mode: Toggle between mask brush and eraser.
  • Brush Size Control: Adjust radius via stepper buttons or mouse wheel scroll.
  • Clear: Reset mask in one click.

🎬 Video & GIF Timeline Controls

  • Timeline Bar & Waveform: Full visual track overview for videos and animated GIFs.
  • Trim Handles: Yellow boundary handles to define precise Start and End timestamps.
  • Playhead & Scrubbing: Left-click to scrub to any frame; Right-click drag to slide the entire trim window.
  • Custom Output FPS: Upsample or downsample playback framerate (e.g. convert 60 FPS video to 24 FPS).
  • Audio Mute & Loop: Preview audio in real-time or mute, with seamless looping playback.

🎵 Audio Trimming & Speed Scaling

  • High-definition waveform display.
  • 1-Second Magnet Snapping: Snap trim boundaries to exact integer seconds.
  • Playback Speed Scaling: Real-time time-stretching (0.10x to 4.00x) with pitch preservation powered by FFmpeg atempo.

🗂️ Direct Folder Access

  • Click the filename link in the bottom-left corner to open your operating system's native file explorer (Windows Explorer, macOS Finder, Linux file manager) with the source file selected.

🛠️ Installation

  1. Navigate to your ComfyUI custom nodes directory: 
    cd ComfyUI/custom_nodes/
  2. Clone the repository: 
    git clone https://github.com/Fictiverse/ComfyUI_UniversalMediaLoader.git
  3. Restart ComfyUI.