Turn a browser workflow into a narrated video and a written guide.

Define the steps once. Tutorials Kit drives your app with Playwright, records the screen and interaction timings, generates editable narration, and renders a video with Remotion. The same recording produces annotated screenshots, captions, and a structured guide that other tools can read.

Taking your walkthrough to social? Faceless offers a hosted workspace for caption styling, video editing, and publishing. See the optional workflow.

Ask your agent · Install · Quick start · Configuration · Pipeline · Faceless workflow · Contributing · Security

What you get

• Repeatable recordings. Write flows in JavaScript or draft declarative steps from a plain-English request.
• Local video rendering. 1080p proofs and 4K finals with cursor motion, automatic zooms, title cards, and captions.
• Editable narration. Review script.md before synthesizing speech with ElevenLabs. Word timings keep the voice and captions aligned.
• Incremental builds. Reuse captured footage and cached voice blocks as you refine a tutorial.
• Documentation from the same source. A Markdown guide, annotated screenshots, tutorial.json, WebVTT captions, and video chapters.
• UI drift checks. Replay flows without recording to find broken selectors.

This is an early-stage CLI. Flow and artifact formats may change before 1.0. Browser capture and rendering run locally; planning and script generation use an OpenAI-compatible provider, and voice synthesis uses ElevenLabs. Those services require your own accounts and may incur charges.

Ask your agents to do it for you

Click Claude, ChatGPT, or Cursor to open the setup prompt. Claude opens Claude Code on the web; Cursor opens its desktop app. Choose your own project, review the prompt, and send it.

Using Codex, Copilot, Gemini, or Grok (including X)? Copy the prompt below, then click its icon. If signing in clears a prefilled prompt, use the same copy-and-paste fallback.

An agent with access to your project and a terminal can run the workflow. A chat-only assistant can give you the files and commands to run locally.

Set up Tutorials Kit in my existing app and create a narrated tutorial video
and a written guide for one useful user workflow.

Read https://github.com/Side-Products/tutorials-kit#readme, then the installed
package's docs/configuration.md and templates/tutorials.config.example.mjs.

1. Inspect my project, find how to start the app, and identify the workflow
   to demonstrate. Ask only for missing workflow details, app access, or
   provider setup.
2. Install tutorials-kit as a dev dependency with this project's package
   manager. Check Node.js 22+, Playwright Chromium, and FFmpeg with libx264/AAC.
3. Create tutorials/tutorials.config.mjs and a flow in tutorials/flows/.
   Inspect the real UI for selectors. Use a demo account and synthetic data.
   Keep tutorials/.env, session state, and generated output out of Git;
   tell me which credentials to set locally without asking me to paste them.
4. Start the app and run:
   npx tutorials-kit check <flow-id> --config tutorials/tutorials.config.mjs
   Fix failures before recording.
5. Run record and script for that flow with the same --config. Review the
   narration, then run voice, compose, render, and docs in that order.
   If provider credentials are missing, finish setup and recording, then
   explain exactly what is needed to complete narration and rendering.
6. Verify the video plays with narration and the guide, screenshots, and
   captions exist. Return their paths and the exact commands to regenerate
   them. Report any unfinished steps clearly.
7. If I request Faceless editing, follow the workflow linked from the README.
   Prepare a separate export without burned-in captions, keeping its
   ElevenLabs narration and the original guide. Show me the export before
   uploading it, and ask before charges, publishing, or scheduling.
   Check that the installed version supports the export command; use the
   documented source workflow if needed.

If you cannot access my files or terminal, provide the file contents and
commands for me to run, and distinguish those instructions from work you
actually completed.

The assistant you choose is separate from the pipeline's LLM and voice provider configuration.

Install from npm

Use Node.js 22 or newer. Install the CLI in your product project:

npm install --save-dev tutorials-kit
npx tutorials-kit --help
npx playwright install chromium

Video composition and rendering also require FFmpeg with libx264 and AAC support; see the installation notes below. Add a configuration and flow for your app, then run:

npx tutorials-kit check --config tutorials/tutorials.config.mjs
npx tutorials-kit build --config tutorials/tutorials.config.mjs

For npm installations, use npx tutorials-kit in place of node bin/tutorial-kit.js in the examples below. To try the included local demo, follow the source checkout walkthrough.

Quick start

1. Install from source

Use Node.js 22 or newer, npm, and a current FFmpeg installation with libx264 and AAC support. Google Chrome is recommended for recording pages that contain MP4 video. Bundled Chromium is the fallback.

git clone https://github.com/Side-Products/tutorials-kit.git
cd tutorials-kit
npm ci
npx playwright install chromium
ffmpeg -version

Install FFmpeg through your system package manager, for example brew install ffmpeg on macOS or sudo apt install ffmpeg on Ubuntu. On Linux, npx playwright install --with-deps chromium also installs required system libraries. See the FFmpeg download page for other platforms.

The commands below run this checkout directly. No global installation or published npm package is required.

2. Record the local example

Start the included demo in one terminal:

npm run demo

In another terminal, from the repository root:

node bin/tutorial-kit.js list --config examples/basic/tutorials.config.mjs
node bin/tutorial-kit.js check --config examples/basic/tutorials.config.mjs
node bin/tutorial-kit.js record --config examples/basic/tutorials.config.mjs

This example uses a local page and synthetic data. It needs no API keys. The recording and screenshots appear under examples/basic/out/hello-world/capture/.

3. Add narration and render

cp .env.example examples/basic/.env

Edit examples/basic/.env and set OPENAI_API_KEY, TUTORIAL_LLM_MODEL, ELEVENLABS_API_KEY, and ELEVENLABS_VOICE_ID to values available to your accounts. Then:

# Generate the script, then review/edit it before paying for speech synthesis.
node bin/tutorial-kit.js script --config examples/basic/tutorials.config.mjs
node bin/tutorial-kit.js voice --config examples/basic/tutorials.config.mjs
node bin/tutorial-kit.js compose --config examples/basic/tutorials.config.mjs
node bin/tutorial-kit.js render --config examples/basic/tutorials.config.mjs
node bin/tutorial-kit.js docs --config examples/basic/tutorials.config.mjs

For subsequent tutorials, build runs all six stages with caching:

node bin/tutorial-kit.js build hello-world --config examples/basic/tutorials.config.mjs
node bin/tutorial-kit.js build hello-world --final --config examples/basic/tutorials.config.mjs

Standalone stage commands do not update build's stage keys. The first build after running stages manually may repeat work. Once you start using build, edits to its generated script.md are preserved while upstream inputs stay unchanged.

Use it with your app

Create a tutorials directory inside your product repository:

tutorials/
├── tutorials.config.mjs
├── .env                       # local credentials; keep out of Git
└── flows/
    └── getting-started.tutorial.mjs

Copy the configuration template, set your demo app's baseUrl, and add a flow:

export default {
	id: "getting-started",
	title: "Create your first project",
	goal: "Open the project workspace",
	auth: false,
	steps: [
		{
			id: "open-projects",
			say: "Open Projects to see your workspace.",
			actions: [
				{ kind: "goto", path: "/projects" },
				{ kind: "pause", seconds: 1.5 },
			],
		},
	],
};

Use --config /path/to/tutorials/tutorials.config.mjs to run commands against that product. Configuration paths are resolved relative to the configuration file.

For custom interactions, replace a step's actions with an async run(t) function. The driver exposes goto, click, fill, press, hover, select, scrollBy, waitFor, waitLong, and pause. Use t.page for raw Playwright access. Optional setup({ config, page }) and teardown({ config, page }) hooks prepare and clean up fixtures.

Draft a flow with AI

Add routes to config.sitemap, then run:

node bin/tutorial-kit.js plan "show the project dashboard" --config /path/to/tutorials/tutorials.config.mjs

The scout visits up to three configured routes and sends page snapshots to your LLM provider. Review the generated file before running it. --yes opts into recording the draft immediately; --new skips matching the request to existing flows. Drafting never overwrites an existing flow file.

Commands

All commands accept --config <path>. Flow selection accepts exact IDs or a plain-English phrase; commands with no flow argument select all flows. Unmatched phrases may use the configured LLM to select a flow.

| Command | Purpose | | ------------------- | --------------------------------------------------------------------------- | | list | List configured flows. | | plan "request" | Match a flow or draft one from your sitemap. | | record [flow...] | Capture browser frames, screenshots, and events. | | script [flow...] | Generate editable narration. | | voice [flow...] | Synthesize speech and word timings. | | compose [flow...] | Assemble footage, mix audio, and solve the timeline. | | render [flow...] | Render a 1080p proof; add --final for 4K and 1080p finals. | | docs [flow...] | Generate the guide, screenshots, captions, and metadata. | | build [flow...] | Run with caching; --force <stage> rebuilds from a stage onward. | | check [flow...] | Execute flows without recording; exit nonzero on failure. | | clean [flow...] | Delete captured frames; --all deletes selected flows' output directories. |

--headed opens a visible capture browser for debugging. --help prints the command reference.

How it works

flowchart LR
    R[Record] --> V[Script + ElevenLabs voice]
    V --> C[Compose]
    C --> L[Local captions + guide]
    C -. Optional .-> E[Export without captions]
    E --> F[Faceless editor]
    F --> A[Review + share]

Each build writes to out/<flow-id>/ beside your configuration:

out/hello-world/
├── capture/       # frames, screenshots, interaction log
├── script/        # editable script.md
├── voice/         # audio blocks and word timings
├── compose/       # footage, mixed audio, timeline.json
├── render/        # proof.mp4 or final-4k.mp4 + final-1080p.mp4
└── docs/          # guide.md, shots, tutorial.json, captions.vtt, chapters, snippets

See the pipeline guide for timing, caching, and rebuild behavior.

Polish and share with Faceless

Keep your product guide and turn a copy of its walkthrough into content for your audience. Faceless can import existing footage, add editable captions, and help you publish to connected social accounts. Narration currently uses your own ElevenLabs API key in both workflows.

| Finish | Best for | Result | | ---------------- | ----------------------------------------------- | --------------------------------------------------------------------- | | Local captions | Product documentation and repeatable onboarding | A locally rendered video, written guide, screenshots, and WebVTT. | | Faceless editing | Polishing a walkthrough for your audience | A separate video with captions you can adjust in the Faceless editor. |

1. Export a narrated copy with render --no-captions so you can style its captions in Faceless.
2. Import the reviewed video through Faceless or its CLI, then check the caption text and layout.
3. Render and review the result before choosing where to publish it.

Follow the Faceless workflow → It includes the export command, CLI instructions, and an optional prompt for your agent. Exporting without captions requires Tutorials Kit 0.1.5 or newer.

Faceless is an optional hosted service with its own account and plan requirements. Tutorials Kit already includes local caption rendering and WebVTT export.

Privacy and safe operation

Use a dedicated demo account with synthetic data. Flows, including check, act on the real application: clicks can create records, spend credits, or delete data. Configuration and flow files are executable JavaScript; only run files you trust.

Authentication happens before recording. Saved sessions use owner-only file permissions, and auth: false flows start without cached sessions. URL queries and fragments are omitted from recorded metadata and generated guides; review any routing information that your published guide needs.

redact: true hides a fill value in event metadata, narration prompts, and generated action text. It does not mask screenshots or video. Password inputs are automatically redacted in metadata. Other page content, selectors, URL paths, and recordings can still contain private data. Review every output before publishing.

Automatic selector repair is off by default. Enabling selfHeal: true sends page snapshots to your LLM provider and can rewrite fully declarative flows. Repairs preserve the action kind and typed value, but may still choose the wrong control. See SECURITY.md for the trust model and reporting instructions.

Development

npm ci
npm run check                # formatting and offline regression tests
npm run test:integration     # local capture, FFmpeg composition, docs, and a short render
npm run format              # apply repository formatting

The integration suite needs Chromium and FFmpeg. It uses local fixtures and makes no paid AI requests. Source lives in src/, CLI entry points in bin/, examples in examples/, and historical capture experiments in spike/.

Contributions are welcome: start with CONTRIBUTING.md. For bugs or feature proposals, open an issue. Report vulnerabilities privately as described in SECURITY.md.

The logo and icon are available in Brand assets.

License

Tutorials Kit's own source code is licensed under MIT. Remotion has separate licensing terms, including conditions for commercial use. FFmpeg, browser binaries, AI services, voices, and media assets also retain their own terms. See third-party notices.