diff --git a/sdk/guides/craft/motion.md b/sdk/guides/craft/motion.md index da5c221e..a485bbe0 100644 --- a/sdk/guides/craft/motion.md +++ b/sdk/guides/craft/motion.md @@ -26,6 +26,8 @@ Read the files a task needs with `raea guide motion/NAME`, one or two at a time, | meshes, lights, cameras, modelled solids | `motion/3d`, then `bevy` (the 3D library: lights, materials, models, effects, 3D games) | | input, rules, scores, sound on game events | `motion/games` | | rendering stills or the video, and checking them | `motion/rendering` | +| the shapes, lengths and platforms it ships to, the files, posting deliverables | `motion/delivery` | +| an app's interface (its own window, not a composition): every state, built and checked by walking it | `motion/interface` | ## The core rules diff --git a/sdk/guides/craft/motion/delivery.md b/sdk/guides/craft/motion/delivery.md new file mode 100644 index 00000000..78ac17c6 --- /dev/null +++ b/sdk/guides/craft/motion/delivery.md @@ -0,0 +1,107 @@ +# Delivery: shapes, platforms, the files and handing them over + +## What to do + +- Start from what's asked for. The brief's deliverables say the pieces; the workspace's delivery controller, when + there is one (`raea controller ls`, or `controllers_read` in the app), says the shapes, lengths, platforms, caption + rule and loudness for every piece. Work to it. When neither says where a piece goes, ask once with your best guess, + or write the guess and add it to the brief's `assumed`. +- Make each shape as its own composition from the same scenes (`motion/compositions`), laid out for that shape: a + vertical cut puts its type and faces where a vertical frame has room, it doesn't crop the wide one. Name them by + shape (`launch-9x16`, `launch-1x1`, `launch-16x9`). +- Make the shape a platform is made for first: the first shape listed for it in the skill's reference/platforms.md + (9:16 for TikTok, Reels and Shorts). A network that shows several shapes takes the one the brief favours. +- Fit the length to where it goes: inside the platform's limits, and near the length its feed favours when the brief + doesn't set one. A cutdown (6 s, 15 s, 30 s) is its own edit with its own hook, not the long one stopped early. +- Keep text and faces out of the platform's UI zones for that shape (reference/platforms.md; `motion/placement` for + how), then check the export against the platform: + `raea check out/launch-9x16.mp4 --manifest out/render.json --shape 9:16 --platform tiktok`. +- Captions: burn them in for feeds that play without sound, unless the delivery controller says captions off; then + burn none, and leave the words file beside the export for the platform's own captions. +- Sound to -14 LUFS integrated with true peak at or below -1 dBTP: one `` per + composition does it (`motion/sound`). A spec that names another number wins. +- Render the export at `--quality master`, named in lowercase letters, digits and hyphens, with its shape and length: + `spring-launch-9x16-15s.mp4`. Each version is a new file beside the last, never written over it. +- In the raea app, post each deliverable with `feed_post` and `export: true`, tagged with the same keys across the + project (`platform:tiktok`, `aspect:9x16`, `cut:15s`, `market:uk`): they become the project's Table, which is how + the person sees what's done and what's missing. `item_tags` tags one that's already posted. Headless, list the + files with their shape, length and platform for the person. +- Publishing is the person's. The app's Publish view sends a post to a network, now or at a time, after checking it + against that network's guidelines; nothing goes out until they press Publish or Schedule. Have the file, its tags + and, when asked, a caption within the network's limit ready for them. +- When the deliverable isn't a video: a game as its own program is `raea export-game` (`games`), an app is + `raea app bundle` signed with the person's own identity (`apps`), and a live composition for another raea is + `raea bundle --composition-bundle`. + +## Why + +Every network shows a video inside its own interface, and a frame made for one shape loses its type, its faces or +its hook in another. The numbers that decide this (shapes, lengths, file sizes, caption limits, where the buttons sit) +are the app's own publishing guidelines, generated into reference/platforms.md, so a delivery made to them is one +Publish accepts without a fix. Tags with the same keys across a project are what make the Table a delivery list +rather than a pile of files. + +## Common mistakes + +- A 16:9 master cropped to 9:16 at the end. The type runs off the sides and the face sits under the buttons. Lay the + vertical out as its own composition. +- Text in the bottom quarter of a vertical frame, where every short-video network puts its caption and buttons. +- A 15 s cutdown that is the first 15 seconds of the long cut, with no ending. +- Captions burned in on a piece whose delivery controller says captions off, or burned in twice: once by the piece, + once by the platform's auto-captions the person turned on. +- `final-v2-FINAL.mp4`, `Launch Video (1).mp4`, or a new render written over the version the person last saw. +- Tags that change keys between items (`tiktok`, `platform:TikTok`, `network:tiktok`): the Table makes three columns. +- Posting to a network, or asking the person for their password to. Publishing is the person's, from Publish. + +## Example: one piece in the three shapes it ships in + +```tsx +import { AbsoluteFill, Composition, Sequence, registerRoot, useVideoConfig } from "raea"; +import { css } from "./styles.gen"; + +const fps = 30; +const s = (sec: number) => Math.round(sec * fps); + +/** The hook and the end card, laid out from the frame's own shape. */ +export default function Launch({ cut }: { cut: number }) { + const { width, height } = useVideoConfig(); + const tall = height > width; + const u = width / 1080; + return ( + + + + {/* a vertical frame keeps its line in the upper middle, clear of the caption and buttons below */} + +
+ Sun in a can. +
+
+
+ + + Try Sunmelt + + +
+ ); +} + +function Root() { + return ( + <> + + + + + ); +} +registerRoot(Root); +``` + +Then each one rendered, checked against where it goes and posted as a deliverable: + +```sh +raea render launch.tsx --composition launch-9x16-15s --quality master -o out/launch-9x16-15s.mp4 --manifest out/9x16.json +raea check out/launch-9x16-15s.mp4 --manifest out/9x16.json --shape 9:16 --platform tiktok +``` diff --git a/sdk/guides/craft/motion/interface.md b/sdk/guides/craft/motion/interface.md new file mode 100644 index 00000000..1da65745 --- /dev/null +++ b/sdk/guides/craft/motion/interface.md @@ -0,0 +1,113 @@ +# Interfaces: an app on @raea/ui, built state by state and checked by walking it + +`modes/tool` says what an interface has to do for the person using it; this file is how to build one in raea and +show that it does. The verbs and the two targets are in the raea skill's "Apps: web or native". + +## What to do + +- Write down the task before the screen: who opens it, what they came to do, and the two or three steps that do it. + The first screen opens on that task, with its next step in plain view. +- Pick the target from what the app needs, in its own file: `export const app = { target: "web", title, size, + minSize }`. Web unless it is small, motion-heavy, has no 3D and passes the check on native. Give it a `size` it + opens at and a `minSize` it never goes under, and lay it out to work across that range (flex, `md:` and up). +- Build every state as real UI the person can reach: empty (an invitation to start, with the action that starts), + one item, many, a very long name, loading, an error that says what happened and what to do, done. Each one is a + branch in the component, not a picture. +- Give the parts a check names `data-testid`, and give everything the person acts on a role and a label: a button is a + ` + + {error &&

{error}

} + {shots.length === 0 ? ( +
+ No shots yet + Name the first one above: what the camera sees, in a few words. +
+ ) : ( +
    + {shots.map((s, i) => ( +
  • + {i + 1} + {s} + +
  • + ))} +
+ )} + + ); +} +``` + +`raea app check shots.tsx --png out/` writes out/00-mount.png (the empty state) and one PNG per step: the long name +wrapping in the list, the error under the field when Add is pressed with nothing typed, the list after a removal. diff --git a/skills b/skills index 4db36f63..261e8542 160000 --- a/skills +++ b/skills @@ -1 +1 @@ -Subproject commit 4db36f63504273595cfcea4a14a2895b04465fc3 +Subproject commit 261e854281fa8fe30e03a11ba07f43b8bbccc75d diff --git a/tools/skills.sh b/tools/skills.sh index 5cbf0229..d7ef409e 100755 --- a/tools/skills.sh +++ b/tools/skills.sh @@ -4,7 +4,7 @@ # links these instead of repeating them, so a verb, a flag, a feed tool or an export changes its reference in the # same commit. # -# tools/skills.sh gen write skills/skills/raea/reference/{cli,feed,files,sdk,app}.md, and copy the craft guides +# tools/skills.sh gen write skills/skills/raea/reference/{cli,feed,files,sdk,app,platforms}.md, and copy the craft guides # (sdk/guides/craft, what `raea guide` prints) into the skill (copies() below: bevy/ as 3d/, # motion.md and motion/, and the router, floor, rubric, modes/ and verbs/ under craft/), so a # clone of raea-skills reads whole without raea; commit them in raea-skills, then the pointer here @@ -88,6 +88,34 @@ gen_cli() { else empty end))' } +gen_platforms() { + # the app's publishing guidelines (apps/app src/publish/specs.ts at the recorded commit; it imports nothing) + local p; p=$(mktemp -d "${TMPDIR:-/tmp}/skills-platforms.XXXXXX") + git -C "$APP" show "$APP_REV:src/publish/specs.ts" > "$p/specs.ts" + bun -e ' + const { SPECS } = await import(process.argv[1] + "/specs.ts") + console.log(JSON.stringify(Object.entries(SPECS).filter(([, s]) => s.aspects.length).map(([name, s]) => ({ name, ...s })))) + ' "$p" | jq -r --arg head "$HEAD_LINE" ' + def secs: if . == null then "" elif . >= 3600 and . % 3600 == 0 then "\(. / 3600) h" elif . >= 60 and . % 60 == 0 then "\(. / 60) min" else "\(.) s" end; + def size: if . == null then "" elif . >= 1073741824 then "\(. / 1073741824) GB" else "\(. / 1048576) MB" end; + def pct: (. * 100 | round | tostring) + "%"; + $head, "", + "# Platforms", + "", + "What each network the raea app publishes to shows and takes, from the app'"'"'s publishing guidelines (apps/app", + "src/publish/specs.ts): the Publish view checks a post against them before it goes. Shapes are w:h, the first the", + "one the network is made for. Length is the shortest and longest it takes, and the length its feed favours. The", + "safe zone is how much of a vertical frame its own buttons, caption and profile row cover on a phone, from each", + "edge: keep text and faces out of it (`raea check --platform` measures it).", + "", + "| network | shapes | length | favours | file | caption | hashtags | links in caption | safe zone (top, bottom, left, right) |", + "|---|---|---|---|---|---|---|---|---|", + (.[] | "| \(.name) | \(.aspects | join(", ")) | \(if .minDuration and .maxDuration then "\(.minDuration | secs) to \(.maxDuration | secs)" elif .maxDuration then "up to \(.maxDuration | secs)" else "" end) | \(.sweetSpot | secs) | \(.maxBytes | size) | \(.caption)\(if .graphemes then " graphemes" else " chars" end) | \(if .hashtags then ([(if .hashtags.advice then "\(.hashtags.advice[0])-\(.hashtags.advice[1]) advised" else empty end), (if .hashtags.max then "\(.hashtags.max) max" else empty end)] | join(", ")) elif .topicTags then "\(.topicTags) topic tag" else "" end) | \(if .deadLinks then "not clickable" else "" end) | \(if .safe then "\(.safe.top | pct), \(.safe.bottom | pct), \(.safe.left | pct), \(.safe.right | pct)" else "" end) |"), + "", + (.[] | select(.notes) | "- \(.name): \(.notes | join(" "))")' + rm -rf "$p" +} + gen_feed() { # protocol.ts at the recorded commit (it imports nothing), evaluated from a scratch copy local p; p=$(mktemp -d "${TMPDIR:-/tmp}/skills-feed.XXXXXX") @@ -261,7 +289,7 @@ check() { fi local stale_help=0; help_stale && stale_help=1 SKILLS_OUT=$tmp/ref SKILLS_COPY_OUT=$tmp/copies R=$R SKIP_CLI=$stale_help "$0" gen-into >/dev/null || { echo "FAIL skills: tools/skills.sh gen failed"; rm -rf "$tmp"; return 1; } - for f in cli feed files sdk app; do + for f in cli feed files sdk app platforms; do [ "$f" = cli ] && [ $stale_help = 1 ] && continue if ! diff -q "$tmp/ref/$f.md" "$SK/raea/reference/$f.md" >/dev/null 2>&1; then # the shared GitButler tree holds every applied lane's code, so what gen writes there isn't what main + one lane @@ -414,6 +442,7 @@ case "${1:-}" in gen_files > "$OUT/files.md" gen_sdk > "$OUT/sdk.md" gen_app > "$OUT/app.md" + gen_platforms > "$OUT/platforms.md" copies | while IFS=$'\t' read -r g c; do mkdir -p "$COPY_OUT/$(dirname "$c")" && cp "$g" "$COPY_OUT/$c"; done if [ "$1" = gen ]; then wc -l "$OUT"/*.md; fi ;;