screenci__screenci/docs/manual-setup.mdx

# Manual Setup & First Video

import { Tabs, TabItem } from '@astrojs/starlight/components'

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

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

- [how to initialize a ScreenCI project](#initialize-screenci-project)
- [what initializing creates](#what-initializing-creates)
- [how to run the starter script locally](#run-the-example)
- [how to record the first video](#record-the-final-result)

## Initialize ScreenCI project

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

<Tabs syncKey="package-manager">
  <TabItem label="npm">

```bash
npm init screenci@latest
```

  </TabItem>
  <TabItem label="pnpm">

```bash
pnpm create screenci
```

  </TabItem>
  <TabItem label="yarn">

```bash
yarn create screenci
```

  </TabItem>
</Tabs>

If that does not work, install [Node.js 18 or newer](https://nodejs.org/en/download),
which comes with npm.

## 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:

```text
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
  videos/
    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](/docs/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](https://github.com/vercel-labs/skills#readme).

The starter video source is generated at `screenci/videos/example.screenci.ts` and looks
like this. For an explanation of how it works, see [Video Script
Basics](/docs/video-script-basics#generated-starter-video):

<!-- screenci-doc-code-sample:installation:start -->

```ts
import { autoZoom, hide, video, voices } from 'screenci'

// The default voice (how narration is spoken) for every language.
video.use({ renderOptions: { narration: { voice: { name: voices.Sophie } } } })

// Localized narration cues by language, plus a brand intro overlay. The fixture
// exposes narration markers and overlay controllers to the body.
//
// The logo image (recordings/assets/logo.png) is gitignored: it is uploaded to
// the ScreenCI backend on the first record and reused on later runs (CI
// included), so the binary does not need to be committed.
video
  .overlays({
    logo: { path: './assets/logo.png', fill: 'recording', durationMs: 2000 },
  })
  .narration({
    en: {
      docs: 'Here is where to find ScreenCI [pronounce: screen see eye] docs.',
    },
    es: {
      docs: 'Aqui es donde encontrar la documentacion de ScreenCI [pronounce: screen see eye].',
    },
  })('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/')
    await page.waitForLoadState('networkidle')
  })

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

  // Play the matching 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()
  })
})
```

<!-- screenci-doc-code-sample:installation:end -->

## Run the example

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

```bash
cd screenci
```

Then test the starter video locally:

<Tabs syncKey="package-manager">
  <TabItem label="npm">

```bash
npx screenci test
```

  </TabItem>
  <TabItem label="pnpm">

```bash
pnpm exec screenci test
```

  </TabItem>
  <TabItem label="yarn">

```bash
yarn screenci test
```

  </TabItem>
</Tabs>

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](https://playwright.dev/docs/test-ui-mode), use:

<Tabs syncKey="package-manager">
  <TabItem label="npm">

```bash
npx screenci test --ui
```

  </TabItem>
  <TabItem label="pnpm">

```bash
pnpm exec screenci test --ui
```

  </TabItem>
  <TabItem label="yarn">

```bash
yarn screenci test --ui
```

  </TabItem>
</Tabs>

## Record the final result

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

<Tabs syncKey="package-manager">
  <TabItem label="npm">

```bash
npx screenci record
```

  </TabItem>
  <TabItem label="pnpm">

```bash
pnpm exec screenci record
```

  </TabItem>
  <TabItem label="yarn">

```bash
yarn screenci record
```

  </TabItem>
</Tabs>

If `SCREENCI_SECRET` is missing, `screenci record` prints a one-time ScreenCI
link, waits for browser sign-in, saves the secret into the project env file,
and then continues recording automatically. This waiting is the default both at
an interactive terminal and in a plain non-interactive run (for example a coding
agent), so you do not need a flag. Under CI (`CI=true`) it does not wait: it
prints the link and exits cleanly, so set `SCREENCI_SECRET` (from your ScreenCI
secrets page) ahead of time for CI runs. If you wait for sign-in and it does not
complete within the timeout, `record` exits with a non-zero status (the link
stays valid, so rerun once signed in). Pending auth state is cached in
`.screenci/link-session.json`, so rerunning `record` reuses the same link until
it expires or completes. The upload contains the raw recording, not your source
code.

It should look something like this:

<!-- screenci-doc-video:docs/manual-setup -->

## What's next

- [Video Script Basics](/docs/video-script-basics) to learn how video scripts
  work, including how to generate a first draft with codegen.
- [CI Setup](/docs/ci-setup) to configure recording in GitHub Actions and keep
  CI runs predictable.
- [Public URLs and Embeds](/docs/guides/public-urls-and-embeds) to publish a
  stable URL for documentation or websites that can automatically serve the
  latest selected video version.
- [Narration](/docs/guides/narration) to add spoken cues and voices.
- [Languages](/docs/guides/languages) to add and manage language versions.