Manual Setup & First Video

This is the by-hand path for adding ScreenCI. If you would rather have a coding agent do it for you, see Agent integration. For how recording and rendering are split (and why the service never sees your source code), see the Overview.

ScreenCI is a Playwright-based workflow for producing product videos as code. If you already know Playwright, the startup path should feel familiar: initialize a project and run the generated E2E tests locally using the test command. Then ScreenCI converts these tests into product videos with the preview and export commands.

Initialize ScreenCI project

Run the command at the root of an existing repository (or in a new empty directory) to initialize a ScreenCI project:

npm init screenci@latest

pnpm create screenci

yarn create screenci

If that does not work, install Node.js 20 or newer, which comes with npm.

No account or setup token is needed: the scaffolded project records immediately (see Record the final result). If you already have a SCREENCI_SECRET from an existing account, pass it as an argument and init writes it straight into screenci/.env:

npm init screenci@latest PASTE_YOUR_SCREENCI_SECRET_HERE

The secret is shared across your organization, so the same value connects every project.

What initializing creates

ScreenCI scaffolds a self-contained screenci/ directory with its own dependencies, plus a couple of files at the repository root that have to live there:

screenci/                   # Self-contained ScreenCI project
  screenci.config.ts        # ScreenCI and Playwright configuration
  tsconfig.json             # Minimal TypeScript config so editors type-check the project
  package.json              # Its own package.json (own dependencies + scripts)
  package-lock.json         # Or pnpm-lock.yaml / yarn.lock, depending on package manager
  .prettierrc               # Style for editor codegen edits; edit it, or delete it to disable formatting
  recordings/
    example.screenci.ts        # Minimal starter video
.github/workflows/
  screenci.yaml             # Optional workflow (at the repo root, scoped to screenci/)

The screenci/ directory is deliberately isolated: it installs its own copy of @playwright/test and ScreenCI instead of relying on a surrounding workspace. This is what makes installation reliable inside complex monorepos. ScreenCI never touches your app’s package.json and is immune to pnpm/yarn workspace hoisting. It still drives your app the normal Playwright way, using your project’s standard Playwright settings. See Configuration.

Two things must live at the repository root rather than inside screenci/, because that is where they are discovered:

.github/workflows/screenci.yaml: GitHub only runs workflows from the repo root. Its steps cd into screenci/ automatically.
Agent skills (.claude/skills, etc.): installed at the repo root so coding agents pick them up. See Vercel Skills.

The starter video source is generated at screenci/recordings/example.screenci.ts and looks like this. For an explanation of how it works, see Video Script Basics:

import { autoZoom, hide, video } from 'screenci'

video
  .overlays({
    logo: {
      path: './assets/logo.png',
      duration: 2000,
      overMouse: true,
      fill: 'recording',
    },
  })
  .narration({
    docs: 'Here is where to find ScreenCI [pronounce: screen see eye] docs.',
  })('How to find docs', async ({ page, narration, overlays }) => {
  // Run setup without showing these actions in the final recording.
  await hide(async () => {
    await page.goto('https://screenci.com/')
  })

  // Open with a brief brand intro card before the walkthrough begins.
  await overlays.logo.for(2000)

  // Play the narration line for this step.
  await narration.docs()

  // Automatically zoom into interactions so they are easier to follow.
  await autoZoom(async () => {
    await page.getByRole('link', { name: 'View Documentation' }).click()
  })
})

Run the example

All screenci commands run from inside the screenci/ directory, so switch into it first:

cd screenci

Then test the starter video locally:

npx screenci test

pnpm exec screenci test

yarn screenci test

The test command is for fast video script verification. It runs the .screenci.ts file with ScreenCI’s Playwright base but skips the final recording pipeline, which slows down recording to produce correct timings for mouse animations.

screenci test accepts the same arguments as playwright test. For example, to debug the videos visually in Playwright UI Mode, use:

npx screenci test --ui

pnpm exec screenci test --ui

yarn screenci test --ui

Record and refine in the editor

When the script is green, open the video in the editing flow:

npx screenci preview

pnpm exec screenci preview

yarn screenci preview

preview records every video whose live preview is stale, uploads the previews, and prints the link: a single recorded video gets its preview page directly, several get a run listing page that links each one. Run it with --watch to connect your machine as the code-sync bridge for one video, which unlocks editing in the browser: narration text and voices, overlays, cuts and pacing on the timeline, and render options. Every edit is written back into your .screenci.ts script through the connected machine, so the code always matches what you see. The live preview is free to iterate on: record, watch, adjust, and record again without spending anything. See Editor for the full tour. To narrow the run to one video, pass a title pattern (npx screenci preview "Onboarding").

For an account you already have, copy SCREENCI_SECRET from your secrets page into screenci/.env (the same value you set for CI runs) so recordings upload directly to your organization. The upload contains the raw recording, not your source code.

Export the final video

When the preview looks right, export the finished videos:

npx screenci export

screenci export requires an account with an active paid subscription: without one it prints a sign-up link instead of recording (the anonymous trial is preview-only; keep iterating for free with screenci preview, see Anonymous Trial). Signing up claims your trial and links the project automatically on the next run.

With an account and a plan, export re-records anything whose sources changed, renders, waits, and downloads the finished files into ./exports/. Exporting renders the video in the service and spends export minutes; higher tiers raise export and active-video limits.

It should look something like this:

What’s next

Video Script Basics to learn how video scripts work, including how to generate a first draft with codegen.
Editor to edit the video visually in the browser with screenci preview.
CI Setup to configure recording in GitHub Actions and keep CI runs predictable.
Public URLs and Embeds to publish a stable URL for documentation or websites that can automatically serve the latest selected video version.
Narration to add spoken cues and voices.
Languages to add and manage language versions.