Babulus — Technical Overview

Status: Alpha

Top-level architecture

Babulus is intentionally split into two halves:

  • Control plane (SaaS): org/project/video state, versioning, approvals, runs, and UI.
  • Execution plane (workers): generation and rendering jobs that produce artifacts.

This separation keeps the UI safe/responsive and makes execution portable (cloud or local) without redesigning the product.

Source of truth: “video as code”

Babulus uses an XML DSL (.babulus.xml) as the authoring surface. This is deliberate:

  • Composable: utilities, imports, shared helpers.
  • Reviewable: diffs are real code diffs.
  • Agent-friendly: agents propose patches, not opaque edits.
  • Deterministic: artifacts are generated from source.

See VideoML standard for DSL details.

Artifacts and determinism

The system produces multiple artifacts because each has a job:

  • Script JSON: scene/cue structure and timing (preview + render input).
  • Timeline JSON: audio tracks/mix metadata (render input).
  • Audio assets: voice segments, SFX, music beds, concatenations.
  • Frames and MP4: deterministic rendering outputs.

Determinism matters because it makes approvals meaningful: “what you approved” is reproducible.

Project storage: unified filesystem abstraction

A project is modeled as a folder of files:

  • *.babulus.xml (non-underscore): visible videos
  • _*.babulus.xml: utility files (hidden by default, importable)
  • assets/: uploaded media

Cloud storage paths

org/{orgId}/projects/{projectId}/
  ├── intro.babulus.xml
  ├── _helpers.babulus.xml
  └── assets/
      ├── logo.png
      └── music.wav

Files are tracked with a ProjectFile model for metadata and security. See:

Versioning: source text vs files

Alpha straddles two representations on purpose:

  • StoryboardVersion stores versioned source text (history + review).
  • ProjectFile stores the same source as a file (portability + workflow).

This makes it possible to ship today while moving toward a cleaner “file-first” world where versions are derived from diffs and explicit checkpoints.

Security model (multi-tenant)

Multi-tenancy is enforced with defense in depth:

  • Application layer: server-side membership checks before file operations.
  • Delivery layer: CloudFront for stable delivery without opening S3 publicly.
  • Edge enforcement: JWT validation and org membership checks for CDN requests.

See Security verification for the current testing plan.

Execution plane: jobs and workers

Work is dispatched as jobs that run generation/rendering and upload artifacts back to storage.

Portable job contract

The job shape is designed to be queue-friendly and portable across machines/providers. See Worker job spec.

Generation vs rendering

  • Generation: produces audio/timing artifacts (script/timeline/audio) that make previews meaningful.
  • Rendering: turns those artifacts into frames and MP4 outputs.

Preview model (alpha)

  • If artifacts exist, preview uses them.
  • If artifacts don’t exist, preview may fall back to placeholder content.

Providers, caching, and environments

External providers (TTS/music/SFX) are expensive, so Babulus treats cost control as a workflow feature:

  • environment-specific settings and outputs,
  • segment reuse when unchanged,
  • fast iteration in development, higher fidelity in production.

See Environments and the provider guides under Docs.