Documentation

Everything Bloredi does, in one reference.

Architecture, the zero-cost deployment path, GPU tiers, platform API approvals, self-hosting, error handling, and how to write your own provider.

System architecture & the 8-step pipeline

Bloredi is an autonomous, asynchronous short-form media generator and multi-platform publisher. The domain model enforces a strict hierarchy from users down to series, videos, and individual post attempts.

Domain model hierarchy

Schema

User (id, email, name, credits_balance, plan)
 └── Account (id, user_id, platform, handle, token_state, token_expires_at, rate_limit_remaining)
 └── Series (id, user_id, title, niche, art_style, voice_id, caption_style, music_track, schedule_freq, pipeline_mode)
      ├── series_accounts (many-to-many link between Series and target Accounts)
      └── Video (id, series_id, title, hook, status, duration, render_url, thumbnail_url, script_json, scenes_json)
           └── PostAttempt (id, video_id, account_id, platform, status, scheduled_at, posted_at, external_id)

The 8-step autonomous pipeline

Stages

[1. IDEATE]    -> Gemini 2.5 Flash / Claude / ChatGPT / Ollama hook generation with deduplication
[2. SCRIPT]    -> Structured script breakdown (0-2s hook, 4 retention beats, call to action)
[3. VOICE]     -> Neural speech synthesis and forced alignment (Kokoro-82M)
[4. VISUALIZE] -> Multi-pipeline scene direction (stock B-roll, diffusion, Seedance 2.5, Higgsfield)
[5. ASSEMBLE]  -> 60fps camera trajectories, word-glow ASS subtitles, -18.4 dB audio ducking
[6. RENDER]    -> Vertical 1080x1920 60fps H.264 MP4 encoding via an FFmpeg subprocess
[7. METADATA]  -> Cross-platform SEO tags, hashtags, and AI content disclosure metadata
[8. AUTOPILOT] -> Multi-channel autonomous publishing queue with +/-10m anti-bot jitter

FFmpeg composition & audio ducking

Videos are composited with 60fps focal motion sweeps, burned ASS word-glow subtitles, and automated voiceover-over-music ducking at -18.4 dB.

ffmpeg filtergraph

# 60fps focal motion filter
zoompan=z='min(zoom+0.0014,1.22)':x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':d=150:s=1080x1920:fps=60

# Subtitle burn and audio sidechain ducking filtergraph
[0:v]subtitles='captions.ass'[v];
[2:a]aloop=loop=-1:size=2e+09,volume=0.12,atrim=0:30.0,afade=t=out:st=28.5:d=1.5[music];
[1:a][music]amix=inputs=2:duration=first:dropout_transition=2[a]

Zero-cost stack deployment

Bloredi runs at $0 per month in ongoing software and hosting fees by leaning on free-tier ARM cloud compute, zero-egress object storage, commercial-safe APIs, and CPU-side speech synthesis.

Component	Zero-cost provider	Tier limits & features
Worker & compute	Oracle Cloud Always Free ARM	4 OCPUs, 24 GB RAM, Ubuntu 24.04 LTS aarch64
Video CDN & storage	Cloudflare R2	10 GB storage free, zero egress transfer fees
Script generation	Google Gemini 2.5 Flash API	15 RPM free tier, or local Ollama Llama 3.3
Voice & alignment	Kokoro-82M + faster-whisper	Apache-2.0 / MIT, real-time CPU synthesis
Stock footage & music	Pexels & Pixabay APIs	Commercial-safe stock video and soundtrack loops

30-day storage lifecycle

Configure Bloredi to auto-delete rendered MP4s after 30 days while keeping poster thumbnails. Once a video is published, the platform hosts the canonical file, so local storage stays under 10 GB indefinitely.

NVIDIA GPU acceleration & ComfyUI setup

For visual diffusion (FLUX.1, SDXL) and video motion models, Bloredi talks to ComfyUI over a local HTTP API with dynamic VRAM eviction.

Starting the GPU container stack

bash

cd /home/user/bloredi
docker compose -f docker/docker-compose.gpu.yml up -d

This starts bloredi-gpu-node on port 3000 and bloredi-comfyui on port 8188, with NVIDIA CUDA passthrough enabled.

Hardware & VRAM tier matrix

Bloredi inspects the host's hardware on startup and binds to the best profile it can finish without crashing.

Tier	Hardware profile	Visual engine	Speech engine	Motion engine
Tier 0	CPU only	Pexels / Pixabay stock API	Kokoro TTS on CPU	FFmpeg Ken Burns
Tier 1	6 to 8 GB VRAM (RTX 3060 / 4060)	SDXL Turbo, quantised Flux	Kokoro with Whisper	FFmpeg Ken Burns
Tier 2	10 to 12 GB VRAM (RTX 3080 / 4070)	Full SDXL, Flux-schnell FP8	Kokoro with WhisperX	Short AnimateDiff
Tier 3	16 GB VRAM (RTX 4080 / T4)	Flux.1-schnell FP16	Kokoro with WhisperX	Full AnimateDiff
Tier 4	24 GB+ VRAM (RTX 4090 / A100)	Flux.1-schnell plus batched SDXL	Kokoro with WhisperX	SVD open video models

Social platform API approvals

YouTube Shorts, YouTube Data API v3

The free tier provides 10,000 units per day, roughly six uploads at 1,600 units per videos.insert. Request a quota increase in Google Cloud Console once volume scales.

TikTok Content Posting API

Un-audited developer apps can upload directly to TikTok drafts. Passing the TikTok Developer App Audit unlocks direct autonomous feed posting.

Instagram Reels, Meta Graph API

Requires an Instagram Business or Creator account connected to a Facebook Page, using the Meta Graph API's two-step container upload (/media then /media_publish).

Production self-hosting

Native systemd unit file

/etc/systemd/system/bloredi.service

[Unit]
Description=Bloredi Autonomous Video Generator & Scheduler
After=network.target

[Service]
Type=simple
User=user
WorkingDirectory=/home/user/bloredi
ExecStart=/usr/bin/node /home/user/bloredi/server/server.js
Restart=always
RestartSec=10
Environment=NODE_ENV=production
Environment=PORT=3000

[Install]
WantedBy=multi-user.target

Caddy reverse proxy with automatic HTTPS

/etc/caddy/Caddyfile

app.yourdomain.com {
    reverse_proxy 127.0.0.1:3000
    encode gzip zstd
}

Error handling, backoff & fallback policy

Pipeline stages are strictly idempotent. Intermediate audio clips, word-alignment JSON, and visual plates are cached in SQLite and on disk, so a retry never re-runs synthesis or diffusion it has already paid for.

Zero out-of-memory crash policy

If PyTorch raises CUDA out of memory during scene generation, Bloredi catches it immediately, clears the VRAM cache, degrades that one scene to the zero-cost stock B-roll engine, and finishes the render without failing the video job.

Authoring custom providers

Every stage, text, speech, alignment, visual, motion, music, and publish, exports a pluggable TypeScript contract.

providers/visual.ts

export interface VisualProvider {
  id: string;
  generateScene(params: {
    prompt: string;
    niche: string;
    style: string;
    width: number;
    height: number;
    outPath: string;
  }): Promise<{ assetPath: string; duration: number }>;
}

Troubleshooting & system diagnostics

Run the built-in diagnostic tool any time to verify toolchains, GPU drivers, FFmpeg libass support, and model weight caches.

bash

./bin/bloredi doctor

Sample output

=================================================================
   [+] BLOREDI SYSTEM & HARDWARE DIAGNOSTIC (DOCTOR)
=================================================================
 OS:             Linux (x86_64)
 CPU:            4 logical cores
 RAM:            24.0 GB
 GPU:            Running Tier 0: CPU only (zero-cost stack)
-----------------------------------------------------------------
 Toolchain checks:
   - ffmpeg      : [OK] (libass, libfreetype enabled)
   - ffprobe     : [OK]
   - python3     : [OK] (edge-tts, faster-whisper loaded)
   - sqlite3     : [OK] (WAL mode enabled)
=================================================================

libass missing

If doctor reports FFmpeg without libass, word-glow subtitles cannot burn in. Rebuild FFmpeg with --enable-libass or install a distro package that ships it, then re-run the check.