Update to Frameo.AI

{
  "description": "A phone-video style product ad in one of five formats: a creator review, the product alone with a voiceover, an unboxing, a try-on or a step-by-step tutorial. Use for UGC and creator-style ads, from a quick review to a how-to, or a week of posts from one creator; pick the format from the request.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 372
    },
    {
      "relative_path": "assets/icon.svg",
      "size_in_bytes": 323
    },
    {
      "relative_path": "formats/product.md",
      "size_in_bytes": 1440
    },
    {
      "relative_path": "formats/review.md",
      "size_in_bytes": 884
    },
    {
      "relative_path": "formats/try-on.md",
      "size_in_bytes": 1145
    },
    {
      "relative_path": "formats/tutorial.md",
      "size_in_bytes": 966
    },
    {
      "relative_path": "formats/unboxing.md",
      "size_in_bytes": 1011
    },
    {
      "relative_path": "references/script-craft.md",
      "size_in_bytes": 4016
    },
    {
      "relative_path": "references/series.md",
      "size_in_bytes": 2688
    }
  ],
  "name": "ugc-video",
  "skill_md_contents": "---\nname: ugc-video\ndescription: \"A phone-video style product ad in one of five formats: a creator review, the product alone with a voiceover, an unboxing, a try-on or a step-by-step tutorial. Use for UGC and creator-style ads, from a quick review to a how-to, or a week of posts from one creator; pick the format from the request.\"\n---\n\n## When\n\nA short phone-video style ad for a product, in one of five formats. Pick the format from what the\nuser asks for; review is the default when nothing else fits:\n\n| Format | What it is | File |\n|---|---|---|\n| review | a creator presents the product on camera | `formats/review.md` |\n| product | the product alone with a voiceover, no creator | `formats/product.md` |\n| unboxing | the creator opens the package and reacts | `formats/unboxing.md` |\n| try-on | a wearable on the creator: a turn, a close-up, a verdict | `formats/try-on.md` |\n| tutorial | a step-by-step how-to with \"Step N\" captions | `formats/tutorial.md` |\n\nNot for: one person delivering a script that is not about a product (`talking-presenter`),\nproduct stills (`product-photoshoot`), a scripted story with characters (`script-to-video`), or an existing ad re-shot (`ad-remake`).\n\n## Ask first\n\n1. **The product** — photos (`show_upload` for files on the user's device, `import_media_url` for a web link; images attached to the chat reach Frameo only through `import_attachments`, in apps that pass them such as ChatGPT, and `create_upload_url` is for clients that send the file themselves), the name, and the claims the video\n   may make, in the user's words (**Truth** below).\n2. **The creator** (every format but product) — design one (age, vibe, setting), use the user's\n   photo (with that person's consent), or reuse a creator already in the project\n   (`list_characters`: its first image is the step-1 still and its `voice_id` the voice in step 3,\n   with nothing to generate or choose). For the product format: **the voice** — the tone of the\n   voiceover (warm, brisk, playful) and its language.\n3. **Frame and length** — 9:16, 15 / 30 / 45 s.\n4. **Captions** — off unless the user wants them; the tutorial format always keeps its\n   \"Step N\" labels.\n5. **One video or a series** — a series is several separate posts from one creator (\"a week of\n   content\"); it is planned from `get_skill_file(skill_id=\"ugc-video\", path=\"references/series.md\")`\n   before anything else.\n\nThe format file adds anything only that format needs. Say the rough cost in the same turn as the\nquestions; the user's yes comes with the plan (Steps, **The plan first.**).\n\n## Truth\n\n- The creator is a generated host who presents and demonstrates the product, never a customer.\n  Scripts speak as a presenter: what the product is, what it does, how it is used.\n- Never invent a purchase, use over time, results, ratings, reviews, testimonials or\n  before-and-after outcomes. First-person experience (\"I've used it for a month\") only when the\n  user is the creator and gives that experience.\n- The user's claims are the only claims: used as written, nothing stronger, and no numbers,\n  prices or certifications they did not give. A claim that is missing is asked for, not made up.\n- A real person's face only from that person's own photo, with their consent.\n- The hand-over says the video uses an AI-generated presenter, so it can be labelled as such\n  where a platform requires it.\n\n## Steps\n\n**Before any paid step.** The project: `list_projects` (or `create_project`) gives the `project_id`\nand, when the project has several modules, the `module_id`; every call below that takes a project —\n`estimate_cost` included — gets that same pair; without the project those tools answer `project_needed`, and without the\nmodule of a project that has several, `module_needed`, which lists its modules. The\nquote: one `estimate_cost(items=[…])` prices a stage in one call, with the same project, model,\nsize and number of `image_urls` or `reference_image_urls` (`reference_count`) as each generate call, and returns a `quote_id` per item plus the total. Each generate call\nthen passes its own item's `quote_id` and `confirmed_by_user=true`. A quote is single-use and lasts\n15 minutes, so a long plan is priced stage by stage, right before each stage runs; a stage that\ncomes to more than the user approved is asked about again first. Generate calls return\n`generation_ids`; `wait_task` returns the links, and `show_generations` shows each stage's running\nand finished work in one card where the chat app displays Frameo cards: all the stage's ids at\nonce, before its first `wait_task`; the card updates itself as the work finishes, so the same ids are not shown again.\n\n**The plan first.** Before the first paid call, the plan goes to the user in the chat as plain\ntext: what will be made, in order, one line per generation (for a script, the shot list; for a\nset, each shot), with each line's credits and the total. The credits come from\n`estimate_cost(items=[…])`, up to 10 items a call, so a long plan takes several calls; those\nquotes may expire unused, since each stage is quoted again right before it runs. Nothing is\ngenerated until the user says yes. The user can drop or change lines; a changed line is priced\nagain.\n\n**Shot order.** Pass `shot_number` on every `generate_image` and `generate_video` of a shot (1, 2, 3… in story order; the same number for a retake and for that shot's video), so the project keeps each shot apart, in order. Cast, prop and location references take `placement_kind` (`character`, `prop` or `location`) and the subject's name as `placement_group` instead: they are kept with the project's references, apart from the shots built from them.\n\n**Review (on by default).** Every still and clip is checked before it is built on, and the\nfinished cut before it is handed over, following `review-shots`: its checklist and steps come\nfrom `get_skill(\"review-shots\")`, loaded before step 1. The checks run on the step-1 still\nbefore step 2 builds on it, after step 2 (`review-shots` steps 0, 1 and 4), after step 4 (steps 2 and 4) and after the cut (step 5); the\nproduct's label, shape and colour are checked against the product photos in every shot, and a\nfailed shot is retaken once. The checks of stills and silent clips are free; a retake is paid like\nthe shot it replaces, from the retake allowance the plan carries as its own line for the user to\napprove with everything else. The paid check of clips with speech (`review-shots` step 3) runs\nonly when the user asks for it, since the talking beats are lipsynced to one fixed voice, and its\nrough cost (a few credits per minute of clip) is said and agreed first; without it, the note on\neach talking clip says its sound was not checked. The product format has no speech on screen, so\nall its checks are free. The user can turn the review off.\n\n**A series.** Each post is a full run of the steps below, in its own module, after the arc from\n`get_skill_file(skill_id=\"ugc-video\", path=\"references/series.md\")` is agreed.\n\n**The format.** Before step 0, read the chosen format's file, and only that one:\n`get_skill_file(skill_id=\"ugc-video\", path=\"formats/<format>.md\")`. It sets the beats and which of them talk on camera\n(lipsynced) and which are silent footage under the voice, the stills for steps 1 and 2, the move\nin each silent clip, and anything extra at the cut.\n\n**0. Script.** Write a script of the length chosen in Ask first, as a presenter (**Truth**), following\n`get_skill_file(skill_id=\"ugc-video\", path=\"references/script-craft.md\")` (word budget, story shape, hook, delivery): hook in\nthe first line, the one claim from the user's claims, a close, in the beats the format file\nsets. Show it; the user edits before anything is generated.\n\n**1. First still (~18).** `generate_image`, as the format file describes (the creator still, or\nfor the product format an establishing still), phone-video framing.\n\n**2. Beat stills (~18 each).** `generate_image` for each beat that shows the product, as the\nformat file lists, with `image_urls=[step-1 creator still, product photos…]` when the creator or\ntheir hands are in frame (the same person every time) and `image_urls=[product photos…]` when\nonly the product is; the prompt names nothing the beat does not show.\n\n**3. Voice (~1 per 50 characters).** First the beat list, no tool call: estimate each beat\nat 2.8 words per second (2.5 for Hindi) plus one second of headroom, say it is\napproximate, and split any beat that is too long — a silent beat at the video model's max\n(`list_models(kind=\"video\")`; 30 s on the default) because the mix at the cut cannot stretch\nthe picture, a talking beat at the smaller of that max and 15 s, the lipsync's cap —\nuntil every piece is within it, so every clip's `duration` is its length on the timeline. Then\n`search_voices` for the creator's age and language (for the product format, the tone and\nlanguage), 3 candidates, then `generate_speech` per final beat (each paid call, here and below,\nhas its own quote); `wait_task` for the links. The creator the user keeps is saved with\n`save_character` (a name, `image_urls=[creator still]` and the chosen `voice_id`), so the next\nvideo in this project reuses the same face and voice. Each speech result's `duration_seconds` is\nits measured spoken length; from here on the estimate means that length when the result has one,\nand the words-per-second figure only when it has none. That estimate is the clip's `duration` in\nstep 4 and the `duration` / `audio_duration` of its lipsync.\n\n**4. Clips (~65 per 5 s + ~20 per second of lipsync).** Talking beats: `generate_video` from the\nstill the format file names, then `generate_lipsync` with the step-3 speech for that beat. Silent\nbeats: `generate_video` from that beat's still with the move the format file names in the prompt,\nsilent; their speech is mixed over them at the cut. A split beat is one clip per piece: the first\npiece on its source beat's still, each later one on the previous piece's last frame (below). Every\n`generate_video` takes `duration` = that beat's speech estimate rounded up to whole seconds and\nkept inside the model's range (`list_models(kind=\"video\")` gives it; 4–30 s on the default), 5 s\nfor a beat with no speech; every `generate_lipsync` takes that same whole `duration` (never above\n15 s — the lipsync's own cap, whatever the video model allows), `audio_duration` = the estimate,\nand the clip's `aspect_ratio` and `resolution`. `wait_task` each. Test the first beat before the\nrest.\n\nOn Seedance models (the default) the product photos go along as `reference_image_urls` on every\nclip that shows the product, and the creator still on every product clip the creator is in,\nwhich holds the label and the face through the motion. The frame is the first reference image,\nso the prompt names the others from the second image on, and it counts toward the model's cap;\nthe quote carries `first_frame=true` and `reference_count` = the number of\n`reference_image_urls`, not counting the frame. Each later piece of a split beat opens on the\nprevious piece's last frame (`extract_frames` on the clip that goes into the cut, the lipsync\nresult on a talking beat) once that piece's look has been checked, instead of the beat's still,\nso the join reads as one take. Each prompt names where the clip ends and nothing the beat does\nnot show: on a lipsynced beat the creator facing the lens; on a silent beat the product in frame,\nwith the creator's eyes on it and never on the lens when the creator is in frame, since the voice\nplays over lips that do not move.\n\n**5. Cut (free).** `run_ffmpeg` takes at most 10 inputs and 4 outputs, so the cut is passes, `wait_task`\nafter each (its outputs are the next pass's inputs): per beat — lipsynced beats bring only their clip — mix its step-3 speech over its clip (`amix`, speech on top) into `beatN.mp4` at exactly\nthe clip's `duration` (`tpad`/`apad` over-pad, `-t <duration>` sets the length), up to four beats per call (one output\neach) and fewer when their files would pass ten inputs\n(a clip plus its speech is two inputs and four such beats fill a call); then concatenate all the beats in\norder in groups of at most 10; then one last call joins the groups and burns an `.ass` sidecar with the captions when they are on\n(casual style) and anything the format file adds (the tutorial's step labels); with neither, it\nonly joins. Output `final.mp4`, review the finished cut (`review-shots` step 5), and return the\nlink and `open_in_frameo`.\n\n**Captions (when on).** Timed from the real speech, never from the words-per-second estimate:\neach beat starts on the timeline where the beats before it end (their `duration`s), and its cues\nrun inside its speech's `duration_seconds`, spread across the line by word count. For timing to\nthe word, `analyze_media` can transcribe the finished cut with timestamps instead; it is paid by\nlength (a few credits per minute) and taken only when the user agrees. Each cue is at most about\n5 words and 32 characters, one line, and sits off the creator's face, the hands and the product's\nlabel: low in the frame by default, high when the product or hands fill the lower third.\n\n## Done\n\nThe UGC clip, the script, and every still and clip in the Frameo project, with the review note\nper shot: passed, retaken and why, or kept with a known flaw; and the note that the video uses an\nAI-generated presenter (**Truth**).\n`open_in_frameo` on the result opens the project in the Frameo app, where every take is ready for retakes and edits.\n\n## Files\n\n- `formats/review.md` — the default: a creator presents the product on camera.\n- `formats/product.md` — the product alone, with a voiceover and no creator.\n- `formats/unboxing.md` — the creator opens the package and reacts.\n- `formats/try-on.md` — a wearable on the creator: a turn, a close-up, a verdict.\n- `formats/tutorial.md` — a step-by-step how-to with \"Step N\" captions.\n- `references/script-craft.md` — how to write the spoken lines: word budget, story shape, hook, delivery.\n- `references/series.md` — a run of separate posts from one creator: the arc, the reused creator, how hard each post sells.\n"
}