Skip to content
ScreenCI

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 record command.

You will learn

Initialize ScreenCI project

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

Terminal window
npm init screenci@latest

If that does not work, install Node.js 18 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:

Terminal window
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
  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 },
  })
  .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.setContent(landingPageHtml())
  })


  // 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()
  })
})


function landingPageHtml(): string {
  return `<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>ScreenCI smoke page</title>
    <style>
      body { margin: 0; font-family: Inter, system-ui, sans-serif; background: #111827; color: white; }
      main { min-height: 100vh; display: grid; place-items: center; text-align: center; }
      a { color: #111827; background: #fbbf24; padding: 14px 18px; border-radius: 8px; text-decoration: none; font-weight: 700; }
    </style>
  </head>
  <body>
    <main>
      <div>
        <h1>ScreenCI</h1>
        <p>Record docs, onboarding, and changelog walkthroughs from code.</p>
        <a href="https://screenci.com/docs">View Documentation</a>
      </div>
    </main>
  </body>
</html>`
}

Run the example

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

Terminal window
cd screenci

Then test the starter video locally:

Terminal window
npx 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:

Terminal window
npx screenci test --ui

Record the final result

When you are ready to record the videos in the screenci/recordings/ directory, run:

Terminal window
npx screenci record

screenci record needs no account or secret to work: without one, it uploads under a local, anonymous trial session, and prints a link to view the result. Open that link, then sign up to keep the video and get a shareable URL. See Anonymous Trial for what the trial allows (including a preview of expressive narration and multiple languages) and its limits.

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.

Free renders include a ScreenCI watermark. Upgrading removes it (and raises your render 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.
  • 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.