Build from source
What you need, and the commands to clone, install, run, test and package Cutscript on a Mac, from the public source on GitHub.
Cutscript is an Electron app with a React interface, a TypeScript main process and a few small Swift helpers. This page takes you from a clone of the repository to a running app and a local build. The source is public at github.com/kwebby/cutscript under the GNU AGPL-3.0-only. See Licences.
Get the source
git clone https://github.com/kwebby/cutscript.git
cd cutscriptThe repository holds the app only. The website and the internal design notes are not in it, apart from the ffmpeg build scripts. See How the code is organised.
What you need
- A Mac with Apple silicon. The app, its ffmpeg and its Swift helpers are built for arm64 macOS.
- macOS 14 or later to run the app. Recording needs macOS 15 or later, so test the recorder on that.
- Node.js 22 or later, and npm. The README asks for Node.js 22 or later. The app's
package.jsonhas noenginesfield, but the tools it uses (Electron 44, Vite 7 and Vitest 5) each need Node 22.12 or newer, so use 22.12 or newer. - The Xcode Command Line Tools, for the Swift helpers. Install them with
xcode-select --install. You need them for recording, tracking blur, Blur all faces, Blur all emails and background removal. You do not need full Xcode, except to notarize a release.
The ffmpeg that Cutscript ships is a build of ffmpeg 7.1.5 in resources/ffmpeg/darwin-arm64. It has VideoToolbox, libass and libvpx, and no x264 or x265. Keep it that way when you change packaging. The build is LGPL-2.1-or-later. Its corresponding source is attached to the ffmpeg-7.1.5-source release, and the scripts that build it are in docs/record-motion/ffmpeg-lgpl.
Install
npm cinpm ci installs exactly the versions in package-lock.json. The install step also runs electron-builder install-app-deps.
Build the Swift helpers
npm run build:helpersThis compiles the helpers in native/ (the screen and audio capture helper, the cut-out helper and the tracking helper) into resources/native/darwin-arm64/. It needs the Command Line Tools and is safe to run again, because it recompiles nothing when the sources have not changed. Nothing compiles when the app runs.
Skip it if you are not working on recording, tracking or background removal. Without it, the recorder says "The capture helper does not match this build. Run npm run build:helpers to rebuild it."
Run it
npm run devThis builds the design kit and its host, then starts electron-vite dev. A change in the renderer reloads the window. After you change the main process or the preload script, stop the command and start it again.
Cutscript allows one running instance. If the installed app is open, a dev instance quits at once. To run beside it, give the dev instance its own data folder:
CUTSCRIPT_USER_DATA=/path/to/scratch-folder npm run devThat instance has its own settings, API keys and projects, and it never touches the data of your installed app. The variable works only in a development run.
In npm run dev, macOS ties the Screen Recording permission to the Electron development binary, not to Cutscript. Grant it to that binary when the recorder asks.
The commands
| Command | What it does |
|---|---|
npm run dev | Builds the design kit and host, then runs the app with hot reload |
npm run build | Type-checks everything, builds the design kit and host, then runs electron-vite build |
npm start | Previews the built app from out/ (run npm run build first) |
npm run typecheck | Type-checks the main process, the renderer and the design runtime |
npm run lint | Runs ESLint |
npm run format | Runs Prettier over the repository |
npm test | Runs the unit tests with Vitest |
npm run check:skills | Checks the AI director's skills and the Design pack |
npm run build:helpers | Builds the Swift helpers |
npm run build:unpack | Builds the helpers and the app, then packages an app into dist/ |
npm run build:icons | Rebuilds the icon index |
npm run verify:packaging | Checks a packaged app |
Make an app you can open
npm run build:unpackThis builds the helpers and the app, then packages an app into dist/. The app is signed and notarized only when a Developer ID certificate and a notarytool keychain profile are present. Otherwise you get an unsigned local build.
To choose the output folder and run the packaging checks as well, use the build script:
node scripts/build-local-app.mjs --unsigned --out /path/to/build-folderThis type-checks the code, builds the helpers, collects licences, builds the app, packages it with electron-builder and runs the packaging checks. The result is Cutscript.app in mac-arm64 inside the folder you gave. Without --out, the script writes to dist/stage4-<time> and prunes older builds there.
An unsigned build is for your own testing. Gatekeeper warns when you open it. A new ad-hoc signature on every build can also make macOS forget the permissions you granted, so you may need to grant Screen Recording again. Do not give it to anyone else.
Signing, notarizing and the DMG are for maintainers. See Pull requests and releases.
Run the tests
npm run typecheck
npm run lint
npm testUnit tests sit beside the code they test, as *.test.ts and *.test.tsx files, and as *.test.mjs files for the scripts. There are hundreds of them. To run one file:
npx vitest run src/shared/edit.test.tsThe end-to-end scripts live in tests/e2e/<area>/. Each one builds the app into a scratch folder, starts an isolated instance with its own user data and debugging port, and drives it. Run one with node, and give it a scratch folder:
node tests/e2e/firstrun/look.mjs --out /path/to/scratch-folderEach script's first comment lists its options and what it checks. Most use mocks for AI providers and downloads. A script that can spend money says so in that comment, so read it before you run it.
Related
Was this page helpful?
Comments
Longer questions go better in the forum.
No comments yet. Ask a question or add what you found.
Sign in with GitHub or Google to comment.
Sign in to comment