Formats

What is a format?

A format is a ready way to make one kind of video, like a product launch. It comes with a whole example video and a short guide for your agent. It also brings settings for video.json and helpers for the scenes.

The agent starts from the format that fits your request. Then it changes the words and the pictures for your topic.

Which formats come with explainroo?

Format	For	Size	Look
product-launch	a launch video of about a minute that shows the app at work	16:9	studio
narrated-explainer	one idea in about a minute, from a question to what to remember	16:9	paper
vertical-short	a tall short of 20 to 60 seconds, with the hook in the first second	vertical	midnight
product-ad	an ad of 15 to 30 seconds for a feed, from a question to one offer	square	studio

vertical-short and product-ad also have bold captions. explainroo formats lists these four with the formats you installed. explainroo formats product-ad prints the guide of one.

How do I start a video from a format?

npx --yes explainroo init videos/acme-launch --format product-launch --title "Acme Notes"

init writes these files into the new folder:

• video.json with the format’s settings, and your flags on top of them, like --size linkedin
• script.md and scenes.js with the format’s example, so the project is a whole video from the start
• format.js with the helpers, which scenes.js imports
• format.md with the guide, which init also prints

The agent reads the guide and writes the narration for your topic. It keeps the scene names in script.md and scenes.js the same, and replaces the example’s words and pictures. A format never makes up facts for you. The example’s product and its claims are made up, so none of them may stay in your video.

The helpers place words from the content area, s.safe, so most scenes also work in another size. Look at the stills after you change the size.

For vertical-short, give init the size of the app the video goes on, like --size tiktok. Without it, the video stays vertical, a tall frame for no app in particular. See publishing a video for the sizes.

How do I install a format from Git?

Anyone can publish a format in a Git repository. Install one with its address:

npx --yes explainroo formats add https://github.com/<user>/<repo>.git

Without --yes, formats add installs nothing. It prints the git commands it will run and where the format goes. Run the same command with --yes once you agree. --commit 3f2a9c1 installs the format as it is at that commit. Without it, formats add takes the newest commit and keeps it, so the format doesn’t change under you later.

Git runs with its hooks off, so nothing in the repository runs while it installs. Then formats add checks the folder and refuses a format that:

• misses one of the files every format has, which the next section lists
• has a guide of 4 KB or more
• has a symbolic link, even to a file in the format
• sets a voice that costs money
• has the name of a built-in format

The format goes into explainroo’s cache folder, next to the speech models. Installing it again replaces it.

Nothing from a format runs until you make a project from it. Then its format.js and scenes.js run in the page that draws the frames, like the scenes.js of any project. formats add names those files. Read them before you use a format from someone you don’t know.

How do I make my own format?

A format is a folder that is also a project, so its example renders as it is:

my-format/
  format.json   name, description, author and version
  guide.md      the guide for the agent, under 4 KB
  format.js     scene helpers that scenes.js imports
  video.json    the settings a new video starts with
  script.md     the example narration
  scenes.js     the example scenes, which import './format.js'
  assets/       files the example uses, if any

A format may hold more files, like a look file that its video.json names. init --format copies every file into the new project in the same place, apart from format.json and guide.md. The guide goes in as format.md.

format.json looks like this:

{
  "name": "recipe-card",
  "description": "A recipe in one minute: the dish, what you need, the steps and the result.",
  "author": "Jane Doe",
  "version": "1.0.0"
}

The name uses small letters, digits and -. Keep the description under 200 characters.

These rules make a format work well for everyone:

• Write the guide for an agent that has never seen the format. Say what each scene is for and how to use each helper.
• Place words from s.safe, with sizes from a hundredth of its short side, like the formats that come with explainroo. With "defaults": "0.6", pictures in a tall frame may fill the whole frame, s.full.
• Show the subject on the first frame with at: -1, because feeds show the first frame as the cover.
• Use the free voice in video.json. The person who makes a video picks a paid service.
• Run voice, check and render on the folder itself. The example passes check without errors or warnings.
• Leave build/, out/ and history/ out of the repository.

Push the folder to a public Git repository, with a license that lets others use it. Then people can install it with explainroo formats add <address>.

Who gets credit for a format?

The author does. explainroo formats shows the author of each format. init writes a line like “Format: recipe-card by Jane Doe” into post.json, so every package of a video made from the format names the author in its credits.