video-thumbnail-template

# video-thumbnail-template Turn a channel's thumbnail style into a design guideline (a brand kit) and a CoDesign template with named slots, then fill the template for each new video. Builds on, without restating: the handbook loop, the `brand` skill's kit format, the `layerize` skill (Seedream decomposition), the `models` skill, the `formats` skill (`youtube-thumbnail.md`) and the `judge` gate. ## Input One of three, resolved with the intake contract (`../handbook/intake.md`): - **Channel link** — its latest 10 thumbnails set the style. - **Example thumbnails or designs** — one or more images, or design files (`.imgly`, `.psd`, …). - **Nothing** — start fresh; ask for the visual direction per the intake contract. The format defaults to `youtube-thumbnail` (1280 × 720). Everything goes into one output folder (default `./<channel-or-topic>-thumbnails/`): `reference/`, `brand-kit/`, the template and the thumbnails. References live in the CoDesign workspace, not on disk: `reference/refs.md` lists them. A thumbnail style is the channel's brand: never invent it when references exist. ## 1 — Collect references Every reference comes in through `import` as a one-page design; nothing is downloaded or copied to disk. Take them one at a time, because the next `import` moves on to a new design: `import` it, `preview()` it and record its layout (step 2), then read the image's `uri` in a read-only `edit` (`render: false`) — the imported image is the page's fill, `(await engine.design.getProps(page, ['fill'])).fill.image.imageFileURI`. `reference/refs.md` lists, per reference, the video id or file name, the page size and that uri, which stays valid after you move on. A reference is never saved: if the next `import` refuses over unsaved edits, repeat it with `discard: true`. **Channel link.** CoDesign cannot read web pages, so the video ids come from your host's built-in web-fetch tool — used only to read the channel's `/videos` page (e.g. `https://www.youtube.com/@handle/videos`); no shell, no downloads. That tab lists regular uploads only, newest first; the ids are in the page source as `"videoId":"<11 chars>"`. Take the first 10 distinct ids. Without a web-fetch tool, or when the page cannot be read, ask the user for links to their latest videos and take the id from each (`watch?v=<id>`, `youtu.be/<id>`, `/shorts/<id>`). Then `import({ source: { url: 'https://i.ytimg.com/vi/<id>/maxresdefault.jpg' } })` for each id — public URLs, no API key or login. A 404 means the video has no full-size thumbnail: import `hqdefault.jpg` instead, a 480 × 360 frame whose 16:9 picture sits between black bars. **Example thumbnails.** `import({ source: { path } })` each file the user named. A design file goes through `import` the same way — its layers show the structure directly. **Nothing.** No references; go to step 3 with the direction the user chose. ## 2 — Analyse the layouts Look at every reference yourself — its `preview` from step 1. For **each** one, record its layout — positions and sizes as fractions of the canvas, so they compare across images: - zones: where the host, the headline and the subject sit, and how much of the canvas each takes - headline: the words, line count, the role of each line (hook vs punch word), case, relative size, colour, stroke, shadow, closest Google Font - host: side, crop, expression, gaze, outline or glow - background: image or colour, mood, whether it repeats - devices: arrows, badges, frames, blur, emoji Then compare the set: what repeats in most references is the **system**, what appears once is an option, and what changes from video to video becomes a **slot**. A set that splits into two or three distinct layouts gets one template per layout — name them and ask which to build if unsure. ## 3 — Design guideline (brand kit) Write the guideline as a brand kit in the `brand` skill's format — `brand-kit/tokens.json` + `brand-kit/BRAND.md`. Read `../brand/reference/brandkit-spec.md` for the shape and `reference/authoring.md` for the rules (screenshots are its source form D). Fill it from the analysis: - `colorPrimitives` / `semanticColors` — the colours sampled from the references (say they are sampled) - `typography` — the headline font(s), weights, case and the size ratio between the lines - `layout` / `composition` — the zones from step 2, as fractions of the canvas - `safeArea` — the platform's (the duration badge, bottom right, for YouTube) - `imagery` — host crop and treatment, background mood - `device` — the recurring devices - `voice` — headline formulas: words per line, the punch words in use - `logo` — the channel's mark if the thumbnails carry one; otherwise record it in `$meta.gaps` Draft the `avoid` list from what the references never do and confirm it with the user, as `authoring.md` requires. **Starting fresh**, the guideline comes first too: turn the chosen direction into the same kit, show the user its key choices (palette, fonts, layout) and confirm them before building. ## 4 — Layers and assets When a reference supplies a host, subject or background worth reusing, split it with the `layerize` skill's Stage 1 (Seedream) and follow its rules, with the reference's `uri` from `refs.md` as the source image — it is already in the workspace. Keep the person, subject and residual background layers; drop the text layers — the headline is rebuilt as live text. A user's host photo that is not cut out goes through background removal (`models` skill, `bria-rmbg.md`). A missing background can be generated from the kit's `imagery` mood, `format: '16:9'`, with "no people, no text, no logos" in the prompt. ## 5 — Build the template Build from the kit: one page at the format size, the zones from `layout`, back to front. Name the slots so they can be filled later: | name | kind | notes | | ---------- | ------- | ------------------------------------------------------ | | `bg` | graphic | full-bleed image fill, `Cover` | | `host` | graphic | cut-out, `Contain`, anchored to the edge it grows from | | `subject` | graphic | optional cut-out, `Contain` | | `line1` | text | the hook | | `line2` | text | optional punch word, `text.case: 'Uppercase'` | | `headline` | group | `line1` + `line2` | Drop `host` when the style has no presenter; decoration from the style gets its own descriptive name. When a headline line is too long for its column, shrink it until it fits — never let it run to the edge or into the safe-area corner. Test the template with a long punch word, a word with a capital diacritic (`ÜBERNIMMT`) and a thumbnail without the optional slots, then run the `judge` loop with the kit as the brief. The references are the style: tight headlines or a host bleeding off the canvas are not faults. Export it with `export({ format: 'imgly', outPath })` into the output folder and report the kit, the slots and any `$meta.gaps`. ## 6 — New thumbnails For each thumbnail, start from the **saved template** — `import({ source: { uri } })` with the `uri` its save returned — never chain one thumbnail onto the previous. Fill the slots, hide the empty ones, fit the headline, and export JPEG (`export({ format: 'jpeg', blockId: <page>, outPath })`; YouTube rejects uploads over 2 MB). Each `import` is a copy, so the template stays as it was; `export({ format: 'imgly' })` a filled thumbnail only when the user wants it editable too. Look at every export and check it against the kit's `avoid` list. For a batch, agree on a simple table with the user (e.g. a CSV with one row per video: headline lines and image files) and repeat the above per row. If they want to render outside the agent, write them a small `@cesdk/node` script that loads the exported `.imgly`, fills the same slots by name and exports each row; without a CE.SDK licence key it watermarks its output — say so. ## Common mistakes | Mistake | Fix | | --------------------------------------- | ---------------------------------------------------------------------- | | Styling from one thumbnail of ten | analyse every reference; the system is what repeats | | Building before the guideline exists | write and confirm the kit first — the template is built from it | | New image fill comes out zoomed/cropped | `forceLoadResources([slot])`, then `resetCrop`, then re-apply the mode | | Moving `line1`/`line2` while grouped | positions are relative to the group — ungroup, position, regroup | | Typing capitals into `line2` | keep the text as typed; the slot's `text.case` sets it | | Sizing Seedream cut-outs by pixel size | place by `bounding_box.absolute` | | A person placed with `Cover` | `Contain`, anchored to the bottom edge |