UCG — UGC Video Factory

An AI pipeline that turns a short campaign brief into vertical UGC-style recruitment ads. Give it a YAML brief and it generates reference images, masks faces for identity safety, engineers Seedance 2.0 prompts, and produces 9:16 videos — from the command line or a web UI.

• CLI (src/) — ucg command: brief → reference images → face masks → Seedance 2.0 video.
• Studio (web/) — a Next.js UI over the same pipeline. See web/README.md.
• Skill (skill/) — an agent skill with the prompt-engineering rules. See skill/SKILL.md.

Naming note: the package/CLI is UCG; the product it makes is UGC (user-generated-content)-style video.

Requirements

• Node.js ≥ 20 (developed on 20–25).
• Native modules are compiled on install: @tensorflow/tfjs-node, canvas, sharp, @vladmandic/face-api. On macOS/Linux these usually build from prebuilt binaries; if canvas fails, install its system deps (see the node-canvas wiki).
• API keys for OpenRouter (images) and Atlas Cloud (video) — only needed for real runs; ucg prompt works with no keys.

Install

git clone <repo-url> UCG
cd UCG
npm install            # also compiles src/ -> dist/ via the "prepare" hook

Configure

cp .env.example .env

Then fill in .env:

Variable	Required for	Notes
SEEDANCE_PROVIDER	ucg generate	Set to atlas-cloud
OPENROUTER_API_KEY	images / video	Reference image generation
ATLAS_CLOUD_API_KEY	video	Seedance 2.0
ATLAS_CLOUD_ENDPOINT	video	Defaults to https://api.atlascloud.ai

.env is gitignored — never commit real keys.

Quick start (CLI)

An example brief ships at briefs/twins-tiktok.yaml.

# Preview the engineered prompts — no API calls, no cost:
npm run dev -- prompt briefs/twins-tiktok.yaml

# Generate only the reference images:
npm run dev -- images briefs/twins-tiktok.yaml

# Full run — images -> face masks -> Seedance video:
npm run dev -- generate briefs/twins-tiktok.yaml

# List campaigns and their output status:
npm run dev -- list

npm run dev -- <args> runs the CLI via tsx (no build step needed). After npm run build you can also run the compiled binary directly: node dist/cli.js generate <brief>, or npm link to expose it globally as ucg.

Useful generate flags: --dry-run (prompts only), --skip-images (reuse existing references), --skip-mask, --duration <5|10|15>, --variants <n>, --provider <atlas-cloud>.

All output lands under output/<campaign>/ (gitignored).

Brief format

A brief is a YAML file in briefs/. Schema (validated by src/pipeline/brief.ts):

campaign: my-campaign            # [a-zA-Z0-9_-]+, used as the output dir name
platform: tiktok                 # tiktok | youtube-shorts | meta
style: ugc-casual                # ugc-casual | high-energy-ad
duration: 15                     # 5 | 10 | 15 (seconds)
variants: 3                      # 1–10 (default 3)
hook: "We got paid $600 each just for being twins"
cta: "Link in bio to apply"
compensation: "$600 per twin"    # optional
subject:
  description: "Young twins (18–25), casual clothes, filming themselves"
  setting: "living room couch, natural lighting, phone selfie angle"
scenes:                          # optional shot list
  - time: "0-3s"
    action: "Twin holds phone, excited, talking to camera"
    text_overlay: "POV: you get paid for being a twin"   # or null
mood: "genuine excitement, relatable"
music: "trending upbeat lo-fi, subtle"
reference_guidance:
  image_count: 4                 # 1–9 (default 4)
  style_notes: "phone-quality aesthetic, warm tones"     # optional

Web Studio

A browser UI over the same pipeline. It imports the compiled pipeline from dist/, so build first:

npm run build              # compile src/ -> dist/ (also done by `npm install`)
cd web && npm install      # the web app has its own dependencies
cd .. && npm run web       # start the Next.js dev server (run from the repo root)

Open http://localhost:3000. Full details in web/README.md.

Testing

npm test                   # runs the CLI/pipeline unit tests (tests/ + src/)

The root test config (vitest.config.ts) is scoped to the pipeline. The web app has its own suite (cd web && npm test).

Project layout

src/            CLI + pipeline (brief, image-gen, face-mask, prompt-engine, video-gen)
web/            Next.js Studio UI over the pipeline
skill/          Agent skill: Seedance prompt-engineering rules
briefs/         Example campaign briefs
tests/          Pipeline unit tests
docs/           Design specs and implementation plans
output/         Generated assets (gitignored)

Toward an autonomous factory

Today the loop is human-driven: you write a brief, generate variants, and judge the results. The same pipeline is built to close that loop. Plug a Meta Marketing API integration into the system and you can run a self-improving, autonomous UGC factory:

1. Generate ad variants from a brief (this pipeline).
2. Publish them to Meta (Facebook/Instagram) as ad creatives via the Marketing API.
3. Measure real performance — CTR, watch-time, cost-per-result, conversions.
4. Learn — feed those signals back into brief generation and prompt engineering, so the next batch automatically favours the hooks, styles, and shots that actually convert.

With that feedback loop in place the factory runs itself: continuously producing, testing, and refining creatives with no manual step in between. The Meta integration is the missing connector — the generation, prompting, and output stages already exist here.

License

MIT © Steven Junop