Install
What vawe needs, how to install it from source, and how to fix the failures that `doctor` finds.
By the end of this page, bin/vawe doctor reports no missing tool and you can render a draftA draft is a fast render at half size and 30 fps, with sound, made by vawe dev.. vawe runs from a source checkout. It has no installer.
Requirements
bin/vawe doctor checks these seven items. The list comes from harness/dev/doctor.mjs.
| Item | Needed | What it is for |
|---|---|---|
| Node 22 or newer | yes | Runs bin/vawe and the renderer. |
| git | yes | Version control for the checkout. |
| ffmpeg with libx264 and drawtext | yes | Encodes the frames and mixes the audio. |
| ffprobe | yes | Part of the ffmpeg package. |
| puppeteer Chrome | yes | Draws every frame of the page. |
assets/fonts | yes | The free font faces. The folder must hold files. |
| tesseract | no | OCR for vawe see (also see --spec) and vawe check coverage --text. |
Install
Install the outside tools
Install Node 22 or newer, git and ffmpeg with your system package manager. On macOS with Homebrew:
brew install node git ffmpegAdd tesseract if you want OCR. doctor prints the exact line for Debian, Ubuntu, Fedora, Arch, Alpine, openSUSE and Windows.
Clone vawe and install the packages
git clone https://github.com/vawe-hq/vawe.git && cd vawe
npm install
npx puppeteer browsers install chromeThe puppeteer postinstall step downloads a full Chrome. The third command installs it again when the download was skipped. The npm install ends with doctor.
Run doctor
bin/vawe doctorWhen all is well, you see one line: ok, 7 checks (macOS). The system name changes with your system. The exit code is 0.
The doctor verb
vawe doctor probes each tool, and for each missing tool it prints one line with the cause and one fix: line. It exits with code 1 only when a required tool is missing. A missing optional tool prints optional and does not change the exit code.
| Flag | What it does |
|---|---|
--quiet | Prints only problems and writes .vawe/doctor.json. |
--json | Prints [{tool, required, ok, version, fix}] instead of text. |
The output for a Node that is too old, on macOS, has this form. <version> is the version that doctor finds.
MISSING node 22+: found v<version>, need 22 or newer
fix: brew install node
1 required tool(s) missing.The postinstall step runs doctor --quiet, so the result is in .vawe/doctor.json after an install.
If it fails
| What you see | Why | What to do |
|---|---|---|
found v<version>, need 22 or newer | Node is too old. | Install Node 22 or newer. |
ffmpeg not on PATH | ffmpeg is not installed, or not in PATH. | Run the fix: line of doctor. |
this ffmpeg build cannot run libx264 encode or drawtext | The ffmpeg build lacks an encoder or a filter. | Install a full ffmpeg build. On Fedora and RHEL, enable the RPM Fusion repository first. |
puppeteer has no Chrome download | The install skipped the Chrome download. | Run npm install, then npx puppeteer browsers install chrome. |
Chrome did not launch: ... | Chrome downloaded but does not start on this system. | Read the text after the colon. It is the first line of the Chrome error. |
assets/fonts is missing | The font folder is empty or absent. | Run git checkout -- assets/fonts, or node generators/media/fonts.mjs. |