Arbitrum Brand Video Explainers

Arbitrum brand video explainers

Overview

A rendered video cannot be edited. Its labels are pixels on a raster grid — there is no "Block 1" text object, only pixels shaped like one. The deliverable is always a generator script, never an edited MP4. You rebuild the animation as code, then render it.

That makes the job two separate problems, and the second one is not the hard one:

1. Recover the content from the source (or invent it, from a prompt).
2. Render it in brand styling at the requested pace.

When to use

• "Make this video match our branding" / "restyle this animation"
• "Slow this down so people can follow it" / "re-pace this"
• A video is the wrong aspect ratio, or its text is too small at display size
• Building a new animated explainer for a docs concept

When NOT to use

• Interactive or clickable diagrams → the ReactFlow / DrawioReactFlow pipeline. Those stay editable and respond to the site's dark mode; a video does neither.
• Static concept art → arbitrum-brand-svg-diagrams.
• Screen recordings of real UI → keep the recording, just trim/crop/compress.
• Never Mermaid or any text-DSL animation tool (standing team preference).

The failure this skill exists to prevent

Three independent agents were given "restyle and slow down this explainer" with no guidance. All three correctly chose to rebuild as a generator. All three shipped fabricated numbers anyway, in a video that looked entirely plausible:

None of these are visible by looking at the output. A plausible-looking wrong number is worse than an obviously broken render, because it ships.

The transcription contract

Every value you display must be traceable to a frame you actually read.

Before writing any rendering code, produce SOURCE.md containing:

• one line per datum, with the frame number it came from
• an explicit UNKNOWN for anything you could not read

Then treat that file as the only source of truth. Rules that follow from it:

• Never fit, interpolate, or infer a displayed number. If a counter is not derivable from what is on screen, transcribe the observed values at the frames you sampled and script those. "Fitted so the totals work" is fabrication with arithmetic on top.
• Never expand an acronym the source does not expand. Carry it verbatim and flag it to the user.
• Never assume one displayed number derives from another. In the worked example the chip labels are tips and block gas is independent — chips reading 31 + 9 sit in a block whose gas ends at 34. Assuming gas = sum(chips) would have made every number wrong in a way that looks reasonable.
• Recompute derived labels from the data, not from the source's pixels. A card tagged "sealed early" must be tagged by the same rule that decides whether round 2 ran.

When the brief is a prompt rather than a video, the contract inverts: you own the data, so state it explicitly in SOURCE.md first and get it confirmed before animating. Do not discover the content while writing the renderer.

Reading a source video

See references/reading-a-source-video.md for the extraction technique — ffprobe first, then the select + tile filter to read dozens of frames in a single image, and cropping to a status region to recover a state machine cheaply.

Pipeline

# 1. generate one TRANSPARENT svg per frame
python3 build.py --out "$TMPDIR/mybuild"

# 2. composite over the brand background and encode
tools/render.sh "$TMPDIR/mybuild/f" out.mp4 30

render.sh rasterises frames in parallel and composites them over a once-rendered background (726 frames → MP4 in about 40 s). Keep frame SVGs transparent: inlining the 44 KB background into every frame gives an identical picture several times slower.

Start from examples/pga-rounds/build.py. Replace its source-data block and layout; keep its keyframe/tween engine:

• KEYS is a list of (duration, state). render(a, b, u) interpolates.
• Chips carry stable ids, so a chip that changes slot between two keyframes glides; one that appears fades in; one that leaves fades out.
• Tempo is a single constant (SPEED). Re-pacing is a one-line change.

Brand rules

REQUIRED BACKGROUND: arbitrum-brand-svg-diagrams owns the palette, the measured contrast table, the background asset, and check_contrast.py. Do not copy colour values around — read that skill.

Video-specific additions:

build.py --one N writes a single keyframe with the background inlined, which is what check_contrast.py needs to sample the true backdrop.

Diagram labels are prose

docs/Offchain-pattern-guide.md governs text inside the video. Sentence case, active voice, no "e.g.". All three baseline agents carried HEAVY LOAD and skipped — block filled in round 1 straight through from the source. Restyling is the moment to fix that copy, not preserve it.

Verify against the produced video

Extract frames from the MP4 you made, not from your SVGs, and read them:

ffmpeg -v error -i out.mp4 -vf "select='eq(n\,60)+eq(n\,300)+eq(n\,520)+eq(n\,700)',tile=2x2,scale=iw*0.5:ih*0.5" -frames:v 1 -y grid.png

Then diff what you see against SOURCE.md, value by value. Also sample four consecutive frames mid-transition to confirm motion actually interpolates rather than cutting.

Red flags — stop and go back to the frames

• "I'll fit the numbers so the totals work out"
• "TwP probably stands for..."
• "close enough to the original"
• "I'll re-simulate the same concept" (that is invention, not transcription)
• "The animation looks right" (looking right is what fabrication looks like)
• Any displayed value you cannot name a frame number for

Common mistakes