# Output formats and sizes

When to read this: you choose a format, a size, a frame rate or a quality for a render, or a result is too large, blurry or cut off.
It covers which options each format takes, canvas vs `--width` vs `--scale`, frame rate, quality presets with measured file sizes, what makes a GIF large, looping and troubleshooting.

Output options are flags of `tweenframe recipes render` (the `output` object of `POST /renders`). Every option you omit keeps the recipe's default from `recipes show`. Ranges and defaults are in `tweenframe recipes render --help`.

## Formats and their options

| Format                | Kind                | Takes                                      |
| --------------------- | ------------------- | ------------------------------------------ |
| `gif`, `webp`, `apng` | Animated image      | `width`, `scale`, `quality`, `fps`, `loop` |
| `mp4`, `webm`         | Video               | `width`, `scale`, `quality`, `fps`         |
| `png`, `jpeg`         | Still (one moment)  | `width`, `scale`, `quality`, `time`        |
| `svg`, `pdf`          | Still, vector       | nothing: the canvas size, no other option  |
| `storyboard`          | Sheet of key frames | `width`, `scale`                           |

An option you pass that the format does not take is refused with `invalid_output` and `details.path` naming it, for example `--loop` with `--format mp4` or `--width` with `--format svg`. A recipe default that does not apply to the format you chose is dropped silently, so switching the format never trips over a recipe default.

Choosing a format:

- **gif** plays everywhere (email, chat, docs) and is the largest file for photos.
- **webp** is an animated image too, much smaller than gif at `normal` or `minimal` quality; modern browsers show it.
- **mp4** is the smallest for photos and long animations; it is a video, so it plays in a video player or a `<video>` tag rather than as an image.
- **apng** (animated PNG) and **webm** (an open video format) are alternatives; pick them when the user asks for them.
- **png** and **jpeg** give one moment of a timeline recipe as a still: the first frame, or the one at `--time` (ms); of a scene recipe (`produces: "scene"`, a still by itself) they give the canvas and take no `--time`.
- **svg** and **pdf** print a scene recipe as a vector document; a timeline recipe refuses them (`invalid_output`), so a vector file needs a document with `"produces": "scene"` (see [authoring.md](/docs/agent/authoring.md#a-still-a-scene-recipe)).

The first frame of an animated recipe comes before its entrance animations, so headlines that fly in are not there yet. For a still of such a recipe pass `--time` with a moment after them, for example the end of the first slide.

**storyboard** is a look before a long render: one PNG sheet with a frame for every clip, at its last moment alone on screen, and for every transition, at the middle of its window, captioned with the time and what it is (`p0`, `p0→p1 fade`). A clip that moves inside (a stepping carousel, a trio or perimeter slideshow, a conveyor strip) shows the end of every rest, labelled `<clip> hold k`; a loop that never rests (a ticker) shows four even points, `<clip> k/4`; a clip gets a few frames at most. Each frame is captioned with its time in the file; `--format png --time <time_ms>` gives the same picture. The render answer lists the same frames as `storyboard: {duration_ms, frames: [{n, time_ms, label}]}`. `width` is the sheet's (by default the canvas width, capped at what an anonymous token may render), and it counts as one render.

## Render and look

A recipe document, or a catalog recipe with new inputs, is not done until you have looked at the result. The CLI prints the render answer as `{"data": <answer>}`; with `--output` it prints `{"data": {"render": <answer>, "download": {"path", "bytes"}}}`, so the URL is `.data.render.result_url` there and `.data.result_url` otherwise. The `result_url` is temporary: deliver the downloaded file, not the URL. When the user wants a link to the file, publish it: `tweenframe publish create --result-url <result_url>` answers a lasting `url` (an account only); `publish list` and `publish delete <id>` manage them.

The loop:

1. Storyboard: `tweenframe recipes render --document work/recipe.json --input work/inputs.json --format storyboard --output work/board.png`. Open the image, check every slide and every transition, and fix what is wrong before you go on. It shows each slide and each transition in one image for the price of one render.
2. Render: `tweenframe recipes render --document work/recipe.json --input work/inputs.json --output work/draft.gif`. Output options are flags as for any render (`--format`, `--width`, `--fps`); the document's `default_output` holds the defaults.
3. Look at the file: a frame after the entrance animations and the frames around every seam. For one moment, render a still: `--format png --time <ms>` captures that moment (without `--time` a still is the first frame, before any entrance animation). A still does not show transitions, so look at the seams in the animated file: extract its frames, for example `ffmpeg -i work/draft.gif -fps_mode passthrough work/frames/%03d.png`.

## Canvas, width and scale

The recipe owns the canvas: its layout is computed at the canvas size, which comes from recipe inputs (a `canvas` object, a `width` input or a measured height, depending on the recipe). The output options only resize the finished canvas:

- `--width <px>` scales the result to that width; the height follows the canvas aspect.
- `--scale <factor>` multiplies the canvas size. When you pass `--scale`, any width is ignored.
- Neither: the result has the canvas size, or the recipe's default `output.width` when it has one.

`--aspect <W:H>` (`canvas.aspect` over HTTP) changes the canvas itself: the width stays the recipe's canvas width, the height follows the aspect (`9:16` for a story, `1:1`, `4:5`, `1.91:1` for a link preview), and the layout fills the new canvas without being rebuilt. Combine it with `--width` to resize the result. For a recipe whose canvas height follows a picture or its content, the aspect fixes the height and the layout shares the space; `canvas` of `recipes show` says whether a recipe takes an aspect and lists its inputs named for an aspect.

Change a canvas input when the user wants a different layout or aspect (where text wraps, how photos are cropped). Change `--width` or `--scale` when the user wants the same design at another resolution: one inputs object serves every size. Do not set both a canvas width input and `--width` unless the recipe's description says so: the canvas input already sets the size, and resizing it again changes the resolution of a layout made for another size.

## Frame rate

- `--fps 0`, or no `--fps`, keeps the frame rate the recipe was authored at.
- A lower `--fps` drops source frames: the animation keeps its duration and looks choppier, and the file usually gets smaller.
- A GIF stores a delay per frame and merges frames that do not change, so a GIF often has fewer frames than duration × fps. That is expected, not a defect.
- The `fps` in a render response and its `stats` is the nominal rate. Measure the file when you report frames or frame rate.

## Quality presets and file size

`--quality` is `maximum`, `normal` or `minimal`; lower quality gives a smaller file. It applies to every format except `svg` and `pdf`.

Measured sizes for one reference render: `before-after/default`, its `minimal` example with two photos, a 900 × 600 canvas at 20 fps, a 3.2-second loop.

| Width         | Format | `maximum` | `normal` | `minimal` |
| ------------- | ------ | --------- | -------- | --------- |
| 600 (600×400) | gif    | 983 kB    | 683 kB   | 210 kB    |
| 600 (600×400) | webp   | 945 kB    | 187 kB   | 111 kB    |
| 600 (600×400) | mp4    | 175 kB    | 106 kB   | 59 kB     |
| 900 (900×600) | gif    | 1.97 MB   | 1.35 MB  | 405 kB    |
| 900 (900×600) | webp   | 1.71 MB   | 292 kB   | 172 kB    |
| 900 (900×600) | mp4    | 308 kB    | 181 kB   | 99 kB     |

The same render at 600 px, `normal` quality and `--fps 10`: gif 614 kB, webp 119 kB, mp4 103 kB.

Read the table as proportions, not promises: size grows with the pixel count, the duration and how much of the picture changes from frame to frame. Photos, gradients and full-frame motion cost more than flat colors and small moving text. When the user gives a size budget, render once, measure, then adjust.

## GIF size: what makes it large

A GIF stores a held picture once and then only what changes, so its size depends on how much of the frame changes and for how long, not on how long the result plays. Measured on a slideshow of photos at 900 px, `normal` quality: 4 photos with 400 ms fades at 15 fps make 11.1 MB; 5 photos with 400 ms slides at 20 fps make 20.5 MB.

- **Animation that changes the whole frame.** Transitions between photos (`fade`, `slide_*`, `cover_*`, `zoom_*`, `crosswarp`, `pixelate`) and any full-frame motion re-encode the whole picture on every frame. The cost is seams × transition length × fps × pixels: it grows in proportion to each, so twice the seams costs about twice as much. Holding a photo costs almost nothing, whatever the hold length.
- **Reveal transitions** (`wipe_*`, `split_*`, `iris_*`, `clock_wipe`, `blinds`) encode only the area that changes: about half of a fade or slide of the same length, and they barely grow with duration. In one 4-photo test, fades of 200 → 1500 ms grew the file from 3.2 to 12.1 MB, wipes from 2.3 to 3.0 MB. A cut (`none`) costs one frame per photo.
- **Continuous motion.** Content that moves at a constant speed (a strip or a row of photos flowing sideways, `motion: "ticker"`) changes every frame for the whole loop. A 900 px row of photos made 36 MB as a ticker and 2.4 MB with stepped motion (`motion: "conveyor"`, which holds between moves). Use continuous motion for video (`mp4`, `webm`); for a GIF prefer stepped motion.
- **Width.** Size follows the pixel count: 600 → 900 px is about 2× the bytes. The aspect counts the same way: 9:16 at 900 px wide is about 60% larger than 1:1 (20.5 → 33.0 MB in the slide example).
- **Quality.** `minimal` is about a third smaller than `normal` at 900 px (17.5 → 11.6 MB with slides), `maximum` 5–15% larger.
- **fps.** The moving frames scale with it; held frames do not (the slide example: 20.5 MB at 20 fps, 13.6 MB at 12 fps).

`normal` quality at about 900 px wide is the norm for a photo GIF. Never start with `minimal` quality or a smaller width: both are visibly worse. When the target takes it, `webp` or `mp4` is several times smaller for the same picture (see the table above). For a GIF size budget, go in this order:

1. **The animations first.** Hard cuts (`none`) or cheaper reveal transitions instead of long full-frame ones (a full-frame transition you keep stays short, 300–400 ms); fewer slides and seams, a cut between slides that belong together; fewer, shorter and smaller animated areas (animate a caption or a badge rather than the whole frame).
2. **Then a lower fps.** It shrinks the moving frames only and keeps the timing.
3. **Then compress.** `tweenframe gif compress <result_url> --target-size <bytes> --output …`. To hit the budget it may lower the quality, the frame rate and the width; `--width` cannot be combined with it. Check the result (`stats.gif_info.width`, or measure the file) and say in the report when the width went down. See [gif-tools.md](/docs/agent/gif-tools.md).

## Looping

`--loop true` repeats forever, `--loop false` plays once. Only `gif`, `webp` and `apng` store it. A video (`mp4`, `webm`) has no loop flag: whether it repeats is up to the player or the page that embeds it.

## Troubleshooting

| Problem                         | What to do                                                                                                                                                                                                                        |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The file is too large           | See [GIF size](#gif-size-what-makes-it-large): shorter or reveal transitions, fewer seams, or webp or mp4 when the target allows it. Over a size budget: `gif compress --target-size` ([gif-tools.md](/docs/agent/gif-tools.md)). |
| The result looks blurry         | The source images are smaller than the area they fill, or the output is larger than the canvas. Use larger sources, or render at the canvas size (no `--width`, or `--scale 1`).                                                  |
| Content is cut off              | The recipe caps its height (for example a `maxHeight` input); raise the cap or shorten the text. Check the recipe's input descriptions in `recipes show`.                                                                         |
| `invalid_output`                | An option is outside its range or does not apply to the format (see the table above). Fix the option at `details.path`; the [errors guide](/docs/agent/errors.md#invalid_output) has the details.                                 |
| Frame count lower than expected | A GIF merges unchanged frames, and `--fps` below the authored rate drops frames. Measure the file; the response `fps` is nominal.                                                                                                 |