html2pix 0.6.3

Fast HTML to pixel rendering using Rust and Blitz. Generate production slates, overlays, and presentations.

html2pix

Fast HTML to pixel rendering using Rust and Blitz. Generate production slates, video overlays, and presentation graphics from HTML/CSS templates.

✨ Features

• 🎨 Modern CSS Support: Gradients, flexbox, grid, border-radius, shadows
• 📝 Professional Templates: Presentation templates (title cards, credits, quotes, chapters)
• 🎬 Video Slate Generation: Production-ready metadata overlays for videos
• 🖼️ Image Compositing: Alpha blend HTML over images and video frames
• 🎯 RGB/RGBA Output: Full transparency support
• 💅 CSS Styling: Complete CSS customization
• ⚡ SIMD-Accelerated: 4x faster compositing using vector instructions
• 🚀 Native Performance: Built with Rust/PyO3 for speed
• 🔌 ComfyUI Integration: Optional node for ComfyUI workflows

🚀 Installation

From PyPI

# Standard installation
pip install html2pix

# With ComfyUI support
pip install html2pix[comfyui]

CLI binary

Prebuilt binaries for macOS, Linux (glibc + static musl), and Windows are on the downloads page. Once installed, the CLI updates itself in place:

html2pix --self-update          # install the latest release
html2pix --self-update --check  # only report whether one is available

From Source

Requires:

• Rust toolchain: Install from rustup.rs
• Python 3.10+

git clone https://github.com/melMass/html2pix.git
cd html2pix

# Install with uv (recommended - avoids caching issues)
uv pip install maturin
uv run maturin develop --uv --release

# Or with pip
pip install maturin
maturin develop --release

📖 Usage

Python API

Basic HTML Rendering

from html2pix_ext import render_html
from pathlib import Path
import numpy as np

# Render HTML to pixels
html = "<h1>Hello World</h1>"
image = render_html(
    html=html,
    css_override=None,
    width=800,
    height=600,
    bg_color=(255, 255, 255, 255),
    input_image=None,
    output_format="RGBA",
    scale_factor=1.0,        # DPI scaling (1.0=normal, 2.0=retina)
    color_scheme="light",    # "light" or "dark"
    time=0.0,                # Animation time in seconds
    resources=None           # Optional: custom fonts/images
)

# Result is numpy array (batch, height, width, channels)
print(image.shape)  # (1, 600, 800, 4)

Using Custom Fonts

from pathlib import Path

# Load custom font
font_data = Path('fonts/Inter-Bold.woff2').read_bytes()

html = """
<style>
@font-face {
  font-family: 'Inter';
  src: url('Inter-Bold.woff2');
}
h1 { font-family: 'Inter', sans-serif; }
</style>
<h1>Custom Typography!</h1>
"""

image = render_html(
    html=html,
    width=800,
    height=600,
    resources={
        'Inter-Bold.woff2': font_data  # Clean API with Path().read_bytes()
    }
)

Using Templates

from templates import render_template

# Render a title card
html, css = render_template('title_card', {
    'title': 'Neural Dreams',
    'subtitle': 'A journey through artificial imagination',
    'info': 'Production Company',
    'bottom_text': '2024 • Runtime 4:48'
})

# Render to pixels
image = render_html(
    html=html,
    css_override=css,
    width=1920,
    height=1080,
    bg_color=(10, 10, 10, 255),
    input_image=None,
    output_format="RGBA"
)

Available Templates

Professional Design System - All templates follow a minimalist, sophisticated aesthetic:

1. title_card - Bold, centered title cards for opening sequences
2. chapter_card - Minimal section markers with timestamps
3. quote_card - Elegant text presentation with attribution
4. credits_card - End credits style with role/name pairs
5. minimal_overlay - Subtle corner text (4-position support)

Video Processing

Simple watermark (3 lines):

from html2pix.video import apply_html_overlay

html = '<div style="position: absolute; top: 20px; left: 20px;">My Watermark</div>'
apply_html_overlay('input.mp4', 'output.mp4', html)

Dynamic per-frame overlays:

from html2pix.video import process_video

def add_frame_counter(frame, frame_num, info):
    html = f'<div>Frame: {frame_num}/{info["total_frames"]}</div>'
    frame_batch = frame[np.newaxis, ...]
    result = render_html(html, width=info['width'], height=info['height'], input_image=frame_batch)
    return result[0]

process_video('input.mp4', 'output.mp4', add_frame_counter)

VFX breakdown slates:

from html2pix import generate_video_slate_html
from html2pix.video import process_video

metadata = {
    'title': 'VFX Shot Breakdown',
    'fps': 25,
    'total_frames': 121,
    'inference_settings': {'model': 'SDXL', 'steps': 50},
    'prompt': 'Cinematic establishing shot...'
}

html, css = generate_video_slate_html(metadata, layout='side-by-side')

def add_slate(frame, frame_num, info):
    # Your slate compositing logic here
    ...

process_video('input.mp4', 'output_with_slate.mp4', add_slate)

See examples/showcase_video.py for complete examples.

ComfyUI Integration

When installed with pip install html2pix[comfyui]:

1. Copy __init__.py to ComfyUI/custom_nodes/html2pix/
2. Restart ComfyUI
3. Find node under mtb/render → HTML Render (Blitz)

🎬 Template Examples

All templates render at 1920x1080 with professional typography and spacing:

Title Card

render_template('title_card', {
    'title': 'Neural\nDreams',
    'subtitle': 'A journey through artificial imagination',
    'info': 'Production Company',
    'bottom_text': '2024 • Runtime 4:48'
})

Quote Card

render_template('quote_card', {
    'context': 'On Creation',
    'quote': 'The machine does not dream, but it learns to paint our dreams.',
    'attribution': '— Unknown Artist, 2024'
})

Credits Card

render_template('credits_card', {
    'title': 'Neural Dreams',
    'credits': [
        {'role': 'Directed by', 'name': 'Mel Massadian'},
        {'role': 'Generated with', 'name': 'Stable Diffusion XL'},
        {'role': 'Rendered by', 'name': 'html2pix'},
    ],
    'closing': 'Thank you for watching'
})

🏗️ Architecture

html2pix/
├── __init__.py                  # Python API + ComfyUI node (optional)
├── templates.py                 # Professional template system
├── slate_compositor.py          # Reference image compositing
├── frame_scaler.py              # Video/image scaling utilities
├── render_full_video.py         # Full video processing
├── extension/                   # Rust rendering engine
│   ├── Cargo.toml               # Dependencies (Blitz, wide for SIMD)
│   └── src/lib.rs               # SIMD-optimized compositor
└── pyproject.toml               # Package configuration

How It Works

1. HTML/CSS Parsing → Blitz HtmlDocument with style resolution
2. Layout Engine → Compute flexbox, grid, and positioning
3. Rendering → Blitz paints to RGBA buffer via CPU renderer
4. SIMD Compositing → Alpha blend using vectorized operations (4 pixels/instruction)
5. Batch Processing → Composite HTML over video frames or images
6. Output → Return as numpy arrays (batch, height, width, channels)

SIMD Acceleration

The compositor uses SIMD (Single Instruction, Multiple Data) for 4x faster alpha blending:

// Traditional: Process 1 pixel at a time
for pixel in pixels {
    out = html * alpha + bg * (1 - alpha)  // 1 pixel per cycle
}

// SIMD: Process 4 pixels with ONE instruction
let pixels_vec = f32x4::new([p1, p2, p3, p4]);
let out = html * alphas + bg * one_minus_alpha;  // 4 pixels per cycle!

Performance:

• 1920×1080 render: ~65ms (down from ~100-150ms)
• Uses f32x4 vectors via the wide crate
• Maps to native CPU instructions (SSE/AVX on x86, NEON on ARM)

🔧 Technical Details

Dependencies

Core:

• numpy >=1.24.4
• pillow >=10.4.0

Optional (ComfyUI):

• torch >=2.0.0

Rust (Bundled in wheels):

• Blitz (commit 2044d690) - HTML/CSS rendering
• PyO3 (0.22) - Python bindings
• anyrender_vello_cpu (0.7) - CPU renderer with multithreading
• wide (0.7) - Portable SIMD intrinsics

Performance

• Rendering: SIMD-accelerated, ~65ms for 1920x1080
• Compositing: 4x faster with f32x4 vector operations
• Video Processing: Efficient frame-by-frame with progress
• Build Time: ~6-8 seconds (incremental), ~2 minutes (clean)
• Tested: Up to 1920x1080 @ 25fps, 121-frame videos

Supported CSS Features

✅ Flexbox & Grid layouts ✅ Gradients (linear, radial) ✅ Border radius & box shadows ✅ Typography (font-size, weight, color, line-height) ✅ Padding, margin, spacing ✅ Colors (hex, rgb, rgba) ✅ Text anti-aliasing & smooth rendering

🚧 Limitations

• Custom resources must be pre-loaded (no live HTTP/filesystem loading)
• CPU rendering only (no GPU acceleration yet)
• No JavaScript support (static HTML/CSS only)
• Blitz is pre-alpha (some advanced CSS features may be incomplete)

🗺️ Roadmap

• Multi-platform wheel builds (Linux, macOS, Windows)
• Professional template system
• Video slate generation
• SIMD-accelerated compositing
• Custom font/image loading (pre-bundle API)
• Publish to PyPI
• GPU renderer option
• Auto-loading resources from filesystem/HTTP
• More template styles
• CSS animation support (time parameter ready)

📚 Documentation

• BLITZ_API.md: Blitz rendering API
• CLAUDE.md: Development log and technical decisions

🤝 Contributing

Contributions welcome! The package is structured to make ComfyUI integration optional while providing a powerful standalone Python library.

📄 License

MIT License - See LICENSE file

🙏 Credits

• Blitz by DioxusLabs - Blazing fast HTML/CSS rendering engine
• wide by Lokathor - Portable SIMD intrinsics for Rust
• Built with Rust, PyO3, and love for beautiful design

🔗 Links

• PyPI: https://pypi.org/project/html2pix/
• GitHub: https://github.com/melMass/html2pix
• Issues: https://github.com/melMass/html2pix/issues