agentleFS
graphed-incgraphed-inc/marketing-skills/skills/ugc-video/SKILL.md

ugc-video

Skill73 starsChanged 4 days agoMITView on GitHub

Turn a script into a finished UGC talking-head video ad (vertical 1080x1920 MP4, no captions). The bundled avatar's cloned voice reads the script (fal MiniMax TTS via the Graphed CLI), Seedance 2.5 renders her talking to that MP3 (kie via the Graphed CLI, 480p), then local whisper checks every word against the script and local ffmpeg fixes mistakes without a re-render — wrong words are spliced in from the MP3, stutters are cut out as jump cuts — and upscales with a no-AI resize + grain. About $4.80 of Graphed credits per 30 seconds. Use when the user gives a script and asks for a UGC video, a talking-head ad, an avatar video, or a testimonial-style clip, or runs /ugc-video.

  • Installs packages

3 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

7 rules. 0 are common, 2 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Never re-render on your own: If something is not fixed, tell the user the spot, the reason, and the cost of a new take (~470 credits / 30 …

    line 33
  2. Very specific:

    If the user has more than one Graphed account or project, the script stops and lists them.

    line 38
  3. Distinctive:

    After the MP4 is written:

    line 119
  4. Very specific:

    No database: add this to that project's graphed.yaml, tell the user, then deploy so the database is created.

    line 123
  5. Very specific:

    If a database exists, find the table that already holds ad creatives.

    line 131
  6. Very specific:

    If the database has no such table, create skill_asset and insert there.

    line 142
  7. Distinctive:

    Not yet checked against billed runs.

    line 175

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

ugc-video

Script in, finished vertical UGC ad out. Paid steps run through the Graphed CLI; everything else runs on the user's machine (ffmpeg, whisper.cpp).

python3 <skill-dir>/scripts/make_ugc.py --script script.txt --dry-run     # length, cost, prompt — no spend
python3 <skill-dir>/scripts/make_ugc.py --script script.txt               # full run, 5–10 min

<skill-dir> is the folder this SKILL.md is in. Output: ./ugc-videos/<slug>/<slug>.mp4.

Workflow

  1. Write the script clean. Periods, commas, question marks and apostrophes only — no quotation marks (the script removes any it finds). Numbers can be digits; they are spelled out for speech (24/7 → twenty-four seven, 2am → two a.m., 9:45 p.m. → nine forty-five p.m.). Write twelve hundred dollars if that is how it should be said; $1,200 is read "one thousand two hundred dollars".
  2. Dry run first, always. Tell the user the word count, the expected length and the cost. Over ~110 words is tight; over ~115 does not fit 30 s — show them what to cut. If python3 is missing, show brew install python and wait — the dry run cannot start without it. If ffmpeg or whisper is missing, the dry run lists those install commands first. Show those to the user and wait. Do not add --no-fix yourself. That flag is only after the user says to skip the word check.
  3. Run for real in the background (5–10 min).
  4. Read the end of the output. It lists every fix (fixed: / cut:) and anything NOT FIXED with its time in the video. Tell the user exactly where to listen.
  5. Never re-render on your own. If something is not fixed, tell the user the spot, the reason, and the cost of a new take (~470 credits / 30 s). Run --rerender only if they say yes. It keeps the old take and reuses the same MP3.
  6. Hand over ugc-videos/<slug>/<slug>.mp4. Upload that file to the project and record the key. See Find them later.

If the user has more than one Graphed account or project, the script stops and lists them; ask, then pass --account / --project. The choice is remembered in ~/.config/graphed/ugc-video.json.

What the script does

#StepWhereCost
0Preflight: Graphed CLI logged in, ffmpeg, whisper-cli, whisper model. Prints install commands for anything missinglocalfree
1Quotes removed, numbers spelled out, word count + length + cost estimatelocalfree
2MP3: fal:fal-ai/minimax/speech-02-hd with the avatar's cloned voice, speed 1.0Graphed~7 credits
3Fit: pauses over 0.3 s trimmed to 0.25 s, then atempo to ≤ 29.0 s (limit 1.10×). Over the limit it stops and says how many words to cutlocal ffmpegfree
4Seedance: kie:bytedance/seedance-2-5, 480p, 9:16, [Image1] = avatar still, [Audio1] = the MP3, generate_audio: true, duration = MP3 length rounded up. Prompt: prompts/seedance.txtGraphed~16 credits/s
5Check: local whisper on the render and on our MP3, compared with the scriptlocal whisperfree
6Fix: wrong word → same word spliced from the MP3 (video untouched). Stutter / extra words → cut from video + audio as a jump cut. Each fix is tried at several timings and kept only if a whole-file transcript then reads rightlocalfree
7Upscale: resize-grain.sh (Lanczos + light sharpen + phone grain) to 1080x1920local ffmpegfree

Steps are resumable: an existing voice.mp3 or raw-480p.mp4 in the output folder is reused.

Rules (learned from test runs, Oct 2026)

  • Seedance never plays back the MP3. It makes its own read, guided by the MP3's voice and timing, and her lips match its own read. That is why the final audio is Seedance's, patched, and not the MP3 laid on top.
  • No pronunciation hints in the prompt. A spelled hint ("S-L-ack") was read aloud as a stutter, "SL Slack". Hints did not reduce mistakes either. The prompt only says to say every word as written.
  • No quotation marks in the script. The dialogue is already inside quotes in the prompt.
  • --caps Brand1,Brand2 writes those names in caps in the Seedance dialogue only (the MP3 text stays normal). Optional; it was used in the clean test runs.
  • Whisper spellings are not errors. Whisper writes "Klaviyo" as "Clavio" and "focaccia" as "facaccia" in our own MP3 too; the check only flags a word when the render is heard differently from the MP3.
  • Cut times come from short clips, never the full file. whisper.cpp word times drift up to ~0.5 s over a long file, by a different amount in each track. The fixer times every cut on ~3.5 s clips and tries several.
  • Run locally. ffmpeg and whisper run on the user's machine. If either is missing, the dry run and a real run print the install command. Show that to the user and let them install it. --no-fix skips the word check only after they ask, or when Whisper is installed and too slow. A slow machine can instead transcribe with graphed tools run fal:fal-ai/whisper (chunk_level: "word", under 1 credit per clip).

Avatars

Each folder in avatars/ is one speaker:

FilePurpose
avatar.jpgThe still — Seedance [Image1]
avatar.jsonvoice_id (fal MiniMax clone), speaker (prompt line), persona notes
voice-ref.mp3The sample the voice was cloned from
legacy-voice.mp3Pronunciation guide for the old --engine avatar path only
AvatarWho
latina-kitchen (default)Woman in her 30s, long wavy dark hair, black polo, restaurant back kitchen, selfie angle

Voice clone expiry: MiniMax deletes a cloned voice that is not used for about 7 days. If the TTS step fails on the voice id, run make_ugc.py --clone-voice (about 172 credits). It clones voice-ref.mp3 again and saves the new id in avatar.json.

Flags

FlagDefaultNotes
--scriptrequiredA .txt path or the text itself
--dry-runoffLength, cost and the full prompt; no upload, no spend
--avatarlatina-kitchenFolder in avatars/
--capsnoneBrand names to write in caps in the Seedance dialogue
--slug / --out-dirfirst words / ./ugc-videos
--rerenderoffNew Seedance take with the same MP3. Only after the user says yes
--no-fixoffSkip the whisper check. Only if the user asks, or Whisper is installed and too slow
--no-upscaleoffStop at 480p
--clone-voice—New voice id from voice-ref.mp3
--engine avatarseedanceThe old graphed:ugc.avatar path (scripts/legacy_avatar.py, takes --brand)
--account / --projectautoSee above

Output (ugc-videos/<slug>/)

<slug>.mp4 (final, 1080x1920) · raw-480p.mp4 (Seedance take) · fixed-480p.mp4 · voice.mp3 (the fitted MP3) · script.txt · script-spoken.txt · check.json (splices, cuts, and anything not fixed) · seedance.body.json · tts.body.json. A re-render keeps the old take as raw-480p-take<n>.mp4.

Find them later

The script uploads the voice and the still so Seedance can fetch them. It does not upload the finished MP4, and project storage does not list files. A later system on this project can open the video only if the finished file is uploaded and the project's Postgres has the storage key.

After the MP4 is written:

  1. graphed storage upload ugc-videos/<slug>/<slug>.mp4 ugc-video/<slug>/<slug>.mp4 --account <account> --project <project> --content-type video/mp4
  2. graphed databases list --account <account> --project <project>.
  3. No database: add this to that project's graphed.yaml, tell the user, then deploy so the database is created. If you do not have the project files, stop and give them the storage key.
databases:
  primary:
    env: DATABASE_URL
  1. If a database exists, find the table that already holds ad creatives. graphed databases query is read-only:
select table_name, column_name
from information_schema.columns
where table_schema = 'public'
order by table_name, ordinal_position

Use the table that has storage_key. That column is the file name in project storage. If more than one table has it, ask which one holds ad creatives. Insert the finished MP4 into that table, filling the columns it already has, including storage_key (ugc-video/<slug>/<slug>.mp4). Do not create a second table. Do not record the voice or the still.

  1. If the database has no such table, create skill_asset and insert there. Create and insert with graphed exec after the project has a successful deploy (DATABASE_URL is set there). graphed databases query cannot write.
create table if not exists skill_asset (
  storage_key text primary key,
  kind text not null,
  filename text not null,
  content_type text,
  created_at timestamptz not null default now()
);

One row for the finished MP4. kind is ugc-video. filename is <slug>.mp4. content_type is video/mp4. Skip a key that is already stored.

A later system reads the row and downloads that key. It does not scan the file store.

Requirements

NeedInstall
Graphed CLI, logged in, with creditsnpm install -g @graphed-inc/cli · graphed login
Python 3brew install python if python3 is missing. No extra packages
ffmpeg + ffprobebrew install ffmpeg
whisper.cppbrew install whisper-cpp
whisper small modelmkdir -p ~/whisper-models && curl -L -o ~/whisper-models/ggml-small.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin (466 MB; another path via WHISPER_MODEL)

Known limits

  • Rare brand names are the weak spot (Seedance said "Calendly" wrong 3 times out of 3 in tests). The fixer usually splices them; check check.json and listen.
  • About 1 take in 4 needs a fix. A fix that does not read right is not used; that spot is reported instead.
  • A jump cut removes up to ~1 s of video; listen to the join.
  • Cost estimate: Seedance ~16 credits per second at 480p (1 credit = 1 cent) — about $4.80 for 30 s. Not yet checked against billed runs.
  • Planned: WhisperX (forced alignment) for exact word times.

About Graphed

Graphed is a marketing cloud. It includes the infrastructure for an agent to do marketing: a data warehouse, data pipelines, a Postgres database, cron jobs, runtime servers, a tool catalog, custom domains, and internal app tooling.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.