ScreenPilot

FAQ and troubleshooting

Short answers to common questions about ScreenPilot, plus fixes for the problems people hit most: permissions, dialogs, freezes and missing zooms.

Short answers first, fixes after. If your question is not here, ask your AI app to run the ScreenPilot doctor: it checks the machine and says what to fix.

The basics#

Do I need an API key or an account?#

No. Your AI app does the thinking, and ScreenPilot gives it the screen, the recorder and the video editor. There is no ScreenPilot account, no key and no sign-in.

Which AI apps work?#

The installer adds ScreenPilot to each of these that it finds:

  • Claude Desktop and Claude Code
  • Codex, OpenCode, Gemini CLI, Qwen Code, GitHub Copilot CLI, Amazon Q, Goose, Warp
  • Cursor, Windsurf, Devin Desktop, Antigravity, Kiro, Zed, LM Studio
  • VS Code, VS Code Insiders and VSCodium, with the Cline and Roo Code extensions

JetBrains AI Assistant has no settings file, so use its Import from Claude button after you install. Any other app that supports MCP servers works too. See Install.

Can I record just one window?#

You record a monitor, and the video can follow one window. Three ways to get the shot you want:

  • Frame the window. The default camera is "window": it shows only the window in use and hides the panel, tray and other apps. This needs the desktop to report the active window (KDE, X11, Windows, macOS). On GNOME and other Wayland desktops it falls back to showing the monitor.
  • Fit the window to 16:9. Ask for fitWindow (command line: screenpilot record --fit-window <class or title>). The window is resized to 16:9 during the recording and put back afterwards.
  • Record one monitor only. Pass the monitor name (--screens HDMI-A-5), and the other monitors never appear.

Can the voiceover be in Arabic?#

Yes. By default ScreenPilot uses Edge voices in English, Arabic and many other languages. For Egyptian Arabic use ar-EG-SalmaNeural (female) or ar-EG-ShakirNeural (male). List more with screenpilot voices --lang ar-EG, or ask your AI app to list voices. If you prefer free voices that run on your own computer, you can install VoiceTut (Egyptian Arabic and English) or NAMAA (Egyptian Arabic) with screenpilot voice-setup. See Voices. A single narration line can override the voice, so one video can mix languages. Captions can be bilingual too: write "English\nعربي" as the caption text.

Typing Arabic into the demo app works on Windows, macOS and X11. On Wayland it goes through the clipboard and needs wl-clipboard (wl-copy).

Does it work offline?#

Mostly. Recording, analysis, editing and rendering run on your computer. Three things need the internet:

  • The default voiceover. Edge voices are an online service. Local voices need no internet once they are installed (the setup itself downloads about 10 GB; see Voices). A video with no narration lines needs no voice. Generated clips are cached in a .screenpilot-cache folder next to the storyboard or take.
  • The first render. It downloads the video renderer, about 100 MB, once.
  • Pages you ask the demo browser to open, and any Google Fonts a storyboard uses.

Your AI app itself usually needs the internet too. See Privacy for what leaves your computer.

Where are my files saved?#

Recordings and finished videos go to the ScreenPilot folder inside your Videos folder (on a Mac: Movies). Each recording is a session folder holding the video, events.jsonl and a storyboard.json. When you use the command line, sessions go to sessions/<timestamp> in the current folder, or to the folder in SCREENPILOT_OUTPUT. The installer option --output <dir> sets that folder. Settings and the audit log are in ~/.config/screenpilot (Windows: %APPDATA%\screenpilot).

Checks and permissions#

What does doctor check?#

Ask your AI app to "run the ScreenPilot doctor", or run screenpilot doctor. It prints a list of checks and a summary such as "12 ok, 0 failed, 2 skipped". Each failed check says how to fix it. A skipped check is optional or does not apply to your desktop.

  • Node 22 or newer, ffmpeg and ffprobe.
  • Your desktop type and monitors, and whether it can record, drive the mouse and keyboard, control windows, and log the pointer.
  • The demo browser (Chrome, Edge or Brave), the voices (the default Edge voices need internet; local voices get their own "local voice" check once you have set them up), and the video renderer.
  • OBS, only if you use --recorder obs. GStreamer on Linux.
  • On a Mac: Accessibility, Screen Recording, Input Monitoring and avfoundation.

Add --input to also test mouse control. That test moves the real pointer for a moment.

What are the macOS permissions?#

macOS grants privacy permissions to the app that starts ScreenPilot (Claude, Cursor, VS Code, Terminal), not to ScreenPilot itself. Open System Settings, Privacy & Security and turn that app on under:

  • Screen & System Audio Recording (called Screen Recording on macOS 14 and older): needed to record, take screenshots and read window titles.
  • Accessibility: needed when the AI uses your apps for you, with mouse and keyboard.
  • Input Monitoring: optional. It lets recordings zoom in on your own clicks.

Then quit and reopen the AI app. When a permission is missing, ScreenPilot opens the right settings pane and the error names the app to allow.

Why does my desktop show an approval dialog?#

On Wayland (KDE, GNOME and others) apps cannot capture the screen or control the mouse without your approval. The first time you record, or let the AI use your desktop, the desktop asks once to allow screen sharing or remote control. Allow it, and on KDE select all monitors. ScreenPilot saves the approval, so later runs are silent. If you chose only one monitor, the others are missing from recordings. Deleting state.json in the config folder makes ScreenPilot ask again.

On sway and Hyprland, recording works but the AI cannot drive the desktop, because those desktops have no remote control interface.

Making the video#

Why does the video freeze while a narration line plays?#

The render never lets two narration lines overlap. When a line is longer than the time before the next cut or line, the render freezes the video until the line ends. The render result lists these pauses as autoHolds. To avoid them, make lines shorter: one sentence, under about 12 words, one idea. Narration placed in a cut region is dropped, so keep lines inside the parts of the video you keep.

What is the difference between draft and delivery?#

There are three render qualities. draft is fast and rougher: use it while you change timing, zooms and wording. looks is the default, a normal render. delivery is the final file: use it once, at the end. Rendering is slow, so iterating on draft saves a lot of time. From the command line: screenpilot render storyboard.json -q draft, then -q delivery -o demo.mp4.

How do I cut idle time?#

Run analyze on the recording. It lists idle spans, where nothing happens. Then create the storyboard with suggest on (screenpilot init <session> --suggest), which cuts the idle time and zooms on clicks for you. In the storyboard, segments are the parts you keep. Give a segment a speed of 4 to 8 to fast-forward a loading screen instead of cutting it. Remove mistakes the same way. See Storyboard reference.

How do I keep the video under about 90 seconds?#

Aim for 30 to 90 seconds. Cut or speed up idle time and loading, keep narration to one short sentence per step, and caption with two to six words. When the agent drives the desktop, keep the take itself under about 90 seconds and use waitFor instead of long waits. A video that is too long is usually one that shows every step: show the main path and skip the rest. See the tips for takes.

How do I add a new feature to a demo I already made?#

Do not re-record the demo. Record only the new feature, give it a storyboard that extends the demo's, and join them with a sequence.json that splits the demo at the right second: [{demo, to: 42}, {feature}, {demo, from: 42}]. See Insert a feature clip into a demo.

How do I get a vertical or square version?#

Render with --formats, for example screenpilot render storyboard.json --formats 16:9,9:16,1:1. You get one file per format from the same edit. A portrait cut of a landscape recording crops views that frame a window, so look at a draft first. See Several formats.

Troubleshooting#

My AI app does not know ScreenPilot#

Quit the AI app completely and open it again. For Claude Desktop on Windows, right-click its icon next to the clock and choose Quit. Still nothing? Run the ScreenPilot installer again. It lists the apps it added ScreenPilot to. If it says "No AI tool found", install your AI app, open it once, then run the installer again. See Install.

The recording has no zoom on my clicks#

Zooms come from click logging, and logging depends on the desktop:

  • KDE Wayland: click capture needs your user in the input group. That group can read all keyboard and mouse input, so add yourself only on a machine you trust.
  • macOS: allow Input Monitoring for the AI app.
  • GNOME and other Wayland desktops: the desktop hides the pointer, so own recordings have no click log. Takes that the agent performs still log their own clicks, and the agent can place zooms in the storyboard by hand.

The doctor says the video renderer is not ready#

The renderer downloads once, about 100 MB, and needs internet. Your first render downloads it, so there is nothing to do except wait. If it fails, check the connection and render again.

The agent stopped when I touched the mouse#

That is on purpose. Moving the pointer stops the agent so you can take over. Ask it to call resume to carry on from where the pointer is now, or abort to stop. To stop it from reacting to the mouse on an unattended machine, see Unattended runs.