Getting Started

Scaffold a project, edit your first composition, preview it, and render an MP4.

This guide takes you from an empty directory to a five-second video with one visible text edit and an interactive preview.

Prerequisites

  • Node.js 22.12 or later
  • macOS (Apple silicon or Intel) or Linux x86-64 for local MP4 rendering
  • Google Chrome or Chromium for local MP4 rendering; set CHROME_PATH to its executable if it isn't installed in the standard location

See what you will make

This is the same shape as the scaffold: a 1920 × 1080, five-second timegroup with one text element. Use the controls below to play it, scrub it, and check its time readout before opening your project.

Interactive example

1. Create a project

bash
npm create @editframe@latest

When prompted, enter a project directory name such as my-video, then choose a template:

  • html uses web components. Its composition is in index.html and its Editframe setup is imported by src/index.js.
  • react uses TypeScript and React. Its composition is in src/Video.tsx, and src/main.tsx mounts it with TimelineRoot.

The scaffold installs the dependencies and creates a start script for the preview. To choose the HTML template without prompts, use the CLI's supported flags:

bash
npm create @editframe@latest -- html -d my-video -y --skip-skills

2. Make one visible edit

Change the starter text from Your video starts here to Hello, Editframe!:

  • In the html template, edit the <ef-text> in index.html.
  • In the react template, edit the <Text> in src/Video.tsx.

The scaffold already contains the imports, a 1920 × 1080 composition, and a five-second timegroup. Keep those pieces in place for this first pass.

The two edits are the same change in each template:

html
<!-- index.html -->
<ef-text duration="5s" class="text-white text-4xl">Hello, Editframe!</ef-text>
tsx
// src/Video.tsx
<Text duration="5s" className="text-white text-4xl">
  Hello, Editframe!
</Text>

3. Preview the composition

bash
cd my-video
npm start

The preview opens in a browser with hot reload and a timeline scrubber. Save your edit and confirm that the canvas shows Hello, Editframe!. Use the scrubber to inspect the composition at different times.

4. Render an MP4

Install the local runtime once per computer. setup downloads the signed runtime that matches the project's CLI and verifies it before installing:

bash
npx editframe setup

Then, from the project root, run:

bash
npx editframe render -o output.mp4

The render command uses the project's index.html by default and writes output.mp4 to the current directory. Confirm that the file exists and is non-empty:

bash
ls -lh output.mp4

Opening the file should show a five-second 1920 × 1080 MP4 with Hello, Editframe! on screen.

Troubleshooting

  • If npm start cannot find the project dependencies, run npm install from my-video. The scaffold installs them unless you used its --skip-install option.
  • If rendering asks you to run npx editframe setup, the local runtime isn't installed for this computer yet; run it from my-video, then rerun the render command.
  • If local rendering reports that it needs Google Chrome or Chromium, install one, or set CHROME_PATH to the absolute path of its executable, then rerun the render command.
  • If the preview is blank, confirm that the root timegroup still has its 1920px × 1080px classes and that the text is inside the timegroup in index.html or src/Video.tsx.

Next steps