Concepts
View as MarkdownThe words Blitframe uses, and how the pieces fit together.
| Term | What it is |
|---|---|
| Project | One piece of motion graphics: the composition you edit and render, with its history. |
| Version | An unchangeable snapshot of every file of a project: data.json, images, video, fonts, audio and 3D models. Every change to a project keeps one. |
| Head | The version a project is at now. Edits start from it, and a render of the project renders it. A project has one head per variation. |
| Variation | A named head with its own history, inside one project. Every project has main, which a request uses when it names none. |
| Render | Turns one exact version into a video or images. |
| Replacement | Text, a font, an image or a video changed by layer, either in an edit or for one render only. |
| Upload | A large file you send straight to storage, then name in an edit, a ZIP import or a render. Each upload is used once. |
| Render seconds | What rendering costs: the video's length times a multiplier for its size. |
How they fit together
Project "Summer ad"
v1 ── v2 ── v3 ── v4 (head: v4)
│ ├── render of v4
│ └── render of v4 with a Spanish headline ── v5, the render's own version
└── render of v2
- A new project is empty, or starts from a ZIP or a copy of another version.
- Editing the project creates a new version from the head plus your changes, and moves the head to it. Files you don't mention are kept.
- Each version points to its parent, the version it was made from. The first version has none.
- Version numbers (
v1,v2…) count up across the project. A render with replacements gets a version of its own, which takes a number too. So do edits to other variations. A history can therefore skip a number. - A version's files never change. To undo a change, edit the project with
restoreFromVersionIdset to the version to go back to (Undoing a change). - A version's
renderableandproblemscan change. When Blitframe's checks improve, an older version is checked again before it renders.
Edits and the head
An edit applies to the head as it is when the edit runs. When two edits arrive at once, the second is applied on top of the first.
An edit that sends a whole data.json replaces the head's, including changes made since you read it. To be sure you change the version you looked at, send expectedHeadVersionId, the head you read. If someone has edited the project since, your edit is refused with 409 head_moved instead. Get the project, apply your change on the new head, and send it again. Edits and the head has the details.
Variations
A project can keep more than one head. Each is a variation, with a name and a history of its own. Every project has main, and you can add others, such as spanish, starting at any version of the project.
An edit, ZIP import, render or share link that names a variation in variation uses that variation's head. Editing one variation never moves another's head. Versions still belong to the project. A version made on one variation can be rendered, restored or started from on any other. See Variations.
Renders
A render pins one version: the versionId you name, or the project's head when you name the projectId. That is main's head, or the head of the variation you name. The render's versionId says exactly which version it rendered, so later edits never change a render that is queued or running. You can render the same version as often as you like, in different formats.
A render can also carry its own replacements, for that video only. Blitframe makes a version for it from the pinned one, sourceVersionId, and renders that. The project's head does not move. Rendering the render's versionId again reproduces the video. See Replacements in a render.
One project, many videos
| You want | Use |
|---|---|
| Many videos at once, such as one per row of a data sheet | A batch render of the project, with each render's own replacements (many videos from a data sheet) |
| A version you keep editing, such as the video in Spanish or in a partner's brand | A variation of the project. To keep it apart in a project of its own, a duplicate. |
Render seconds
Rendering is paid in render seconds, which the pricing page and the console show as render minutes (60 seconds each). A render costs its video length times a resolution multiplier. A 10-second 1080p video costs 10 render seconds, and the same video at 1280×720 costs 5. The cost is taken when you queue the render, and refunded if it fails or you cancel it. Pricing has the full table and the few cases where no refund is made.
Your first workspace starts on a free trial. Your balance covers the trial, plans and the low-balance warning.