Repository navigation
Releases
Tourwright 2.6.2
Every built-in voice measured on its own, so tech words, acronyms and shortcuts come out right with each one.
Fixed
- A multilingual voice (
andrew,ava,emma,brian) narrating in Spanish got the English lexicon and numbers
("1.200" was not said as "mil doscientas"): it now speaks with the script's language. - Two voices of one engine do not read an acronym the same way, and every voice used its engine's writings. Each
built-in voice now keeps the ones that worked for it (voicesinsrc/voice/calibrated.json). Measured with a
speech-to-text model on a set of narration sentences, the words said wrong went from 5.8 % to 3.6 % with
alonso, 6.2 % to 4.4 % withjorge, 10.2 % to 6.9 % withdaliaand 8 % to 6.2 % withpaloma;davefx
(Piper, Spain) gets its own writings for API, JSON, webhook and curl, and the multilingual voices for JSON,
webhook, Python and JavaScript. The Spanish terms no writing got right before (API key, HTML, CSS, SSL, GitHub,
software, Teams on Piper; SaaS, ID, IA, email on Edge) were measured again with new writings, and English is
calibrated on Piper too. - On Piper, a term no writing got right lost its respelling and was read as written; it keeps the hand-made one.
- Keyboard shortcuts were read letter by letter or swallowed ("crlk"): in Spanish
Ctrl+Kis now "control ca" and
Cmd+V"comando ve".
Tourwright 2.6.1
A sandbox that checks every connection of the browser, renders that stop at their time limit, and fixes to
the API, voices, nested steps and the browser lock.
Fixed
- Sandbox:
[::ffff:127.0.0.1]and the other ways of writing a private IPv4 inside an IPv6 address (NAT64, 6to4,
compatible) were let through byTOURWRIGHT_BLOCK_PRIVATE, and so were all offe80::/10, multicast and
reserved ranges. - Sandbox: a redirect to a private or not allowed host, a WebSocket and a name that resolved elsewhere a moment
after it was checked (DNS rebinding) were not checked. WithTOURWRIGHT_ALLOWED_HOSTSor
TOURWRIGHT_BLOCK_PRIVATE, every connection of the browser now goes through a proxy that checks it and connects
to the address it checked. - Webhooks no longer follow redirects, and connect to the address the network policy checked.
- An API or MCP asset named
script.jsonreplaced the checked script. - API job
optionsare checked when the job is created (width/height320–3840, a knownqualityand
capture, a voice name,dryRun/safeas booleans): a bad one is a 400 that names the field, not a failed
render minutes later. GET /v1/jobs?limit=with a value that is not a whole number above zero returned nothing, or almost every job:
it now gets the default (50).HEADon a file with aRangeheader sent the file's bytes.- A
TOURWRIGHT_LINK_TTLthat is not a number made download links that never expired; with the API on::the
links pointed tohttp://:::port. - A worker on a host whose name has dots (
worker.example.com) put the jobs of a stopped worker back in the local
queue under a wrong name. - A slides
theme.backgroundwent into an ffmpeg filter as written, so a script could add filters of its own
(movie=reads a file of the server): only a color gets there now. - A render past its time limit went on in the background (browser open) while its work folder was deleted: it
now stops. A worker that kills a render at the limit also ends the browser and ffmpeg it started. - A step inside
if,tryoroffCamerawas named by its place inside the block (step 2); it is now
step 4.2, in errors,checkand its report. tourwright guide(andnarrate) failed on a script withexport: [audio]or[silent].TOURWRIGHT_TTS_COMMANDbroke on a cache path with spaces (common on Windows):{out}is quoted for the shell,
andTOURWRIGHT_TTS_VOICE/TOURWRIGHT_TTS_OUTcarry the same values.- The browser lock outside Linux could fail when it was released at the wrong moment, take a lock whose owner had
not written its pid yet, or let two waiters take a dead owner's lock at once. - Sentences cached with an OpenAI-compatible model, a TTS command or a Pocket voice recording that later changed
were reused: those settings are now part of the cache key (other engines keep their cache). Plugin engines can
add theirs withfingerprint.
Tourwright 2.6.0
Narration at one volume from the first sentence to the last, videos made again without touching the app, and a
dry run that presses nothing.
Added
tourwright render --keepkeeps the recording, each sentence and atimeline.jsonnext to the video, and
tourwright recompose <folder>makes the video again without the browser: another voice or--polish,
--no-clicks, captions and sentences edited, andblurs(boxes of the video blurred between two seconds).--safe(andoptions.safein the API and MCP): a dry run that finds every element and checks it could be
used, but clicks, types, chooses and uploads nothing; steps that come after a skipped action are listed as not
checked instead of failed.mask: [date]: dates in the text become other dates in the same format, and filled date fields are blurred.- The review now reports a sentence more than 4 LU from the narration (
loudness), a true peak over -1 dBFS
(clipping), a filled date field on camera (privacy) and a target that matches several elements (ambiguous). tourwright validate --no-varschecks the format and the names without values for variables and secrets.
Fixed
- Short sentences with a sharp consonant came out 5 to 15 dB quieter than the rest: each sentence is now leveled
with a measured gain and a true-peak limiter, and measured again, instead of loudnorm (which gave up the gain
to keep the peaks). Leveled sentences are cached. - Clicks and typing made off camera piled up where the video jumps and could reach +12 dBFS: they are left out,
and a true-peak limiter closes the whole mix. - A target with a hidden copy (the same link in a closed menu) failed as "cannot be used": the visible one is
used. A target whose words are part of a longer text now prefers the exact one. Steps that click wait until
the element can be clicked, and the error says what is in the way. - With
mask, a step looking for a text the mask changed on screen (an amount read as an ID) found nothing. - The
.default()values of a plugin step's schema did not reach itsrun. render --stepfailed on a script withfocus … click: truebefore the chosen steps: off camera that click was
never made.
Changed
src/is split by domain (core,script,voice,video,plugins,render,ai,install,
authoring,server,cli), each with an alias inpackage.json(#core/…) and a layer it may import from.
npm run checknow checks the rules: at most 400 lines a file, a comment at the top, kebab-case names, no
../imports and no import from a higher layer.AGENTS.md(andCLAUDE.md) say where each thing goes. The
library API (import … from 'tourwright') is the same.
Tourwright 2.5.0
Videos that look like the app on a phone without working out numbers, lists with a search box in one step, and
a review that names a tiny page, a covered element or a long silence before anyone watches the video.
Added
- The review of every video now also reports text too small to read and pages wider than the video (
layout),
a caption that covers the element shown even at the top (caption), and 6 s or more with nothing to hear in a
narrated video (silence): the mistakes of a vertical video filmed with a desktop layout are named before
anyone watches it. device: iphone | iphone-se | android | ipadin a browser script: the app filmed as that device shows it, with
its width, its browser (user agent, touch, mobile layout) and a video in its shape, without working out ascale.selectworks on lists of their own too (React Select, MUI, Ant, a search box over a list of cities), with
search: one step opens the list, types the search into the field it brings, waits for the results off the
video and picks the option by its text. An option that never shows up names the ones the list offers.
Tourwright 2.4.0
Vertical videos that fill the screen with the app's phone layout, captions that never cover what is being used,
and walkthroughs without long silences on heavy pages.
Added
scalein a browser script: how big the page is drawn (the page iswidth / scaleCSS pixels wide, at that
density).scale: 2.75on a vertical video shows the app as on an iPhone;scale: 1.5on Full HD makes
everything bigger and stays sharp.
Fixed
- Vertical videos rendered with Xvfb (the Docker image) showed the app's desktop layout, tiny in the middle of the
screen:capture: autonow films them as a screencast at twice the density, the way a phone shows the app. - Captions wrapped at half the screen width into a tall box of five or six lines that covered the page; they now
take the width they need (up to 70 %, 88 % on vertical), and move to the top while the element the cursor goes to
sits under them (an option of a list, a field low on a phone). - On heavy pages (long lists with hover styles, servers without GPU) each cursor glide could take several seconds
of silence: it now takes a set time (0.28–0.65 s), with fewer moves when the page is slow. - Waiting for an element to show up (a search result, a list still loading) is cut from the video once the voice
has stopped, like a page that loads.
Tourwright 2.3.0
Videos with a studio look, narration that sounds clear and even, a natural voice chosen for each script's language,
record that hands you the finished video, translation into other languages, and verified downloads.
Added
theme: { frame: window }: the recording inside a browser window with rounded corners, a shadow and the title in
its bar, on a wallpaper of lights in the theme colors.- A camera that stays close after a zoomed focus and glides to the next element instead of pulling back and
pushing in again; it never zooms closer than the element fits whole. uploadshows the cursor clicking the drop zone and a drawn file chooser picking the files;selectclicks the
list before choosing.- Vertical videos are filmed the way a phone shows the app (half as wide at twice the density): the app uses its
mobile layout, big and sharp, and captions sit above the area Reels, Shorts and TikTok cover. - With no voice chosen, each render picks the most natural voice for the script's
language: Pocket TTS when
installed, else Microsoft's neural voices when they answer (Salomé in Spanish, Ava in English), else Piper. tourwright recordwrites the script and makes the narrated video at once: the login typed during the tour is
saved as encrypted secrets, the AI rewrites the narration when one is set up, and the video gets the studio look
in the app's own main color.--no-videowrites only the script;--plainleaves out the studio look.tourwright translate <script> --to en(es, en, pt, fr, de, it): the same video in another language, translated
by your AI; targets and typed text stay, and a line whose variables or marked word changed stays as it was.- MCP tools
tourwright_jobs(jobs on the server, with the links of finished videos) andtourwright_delete_job. - The archives
tourwright installdownloads from fixed releases (Piper, uv) are checked against their SHA-256.
Changed
recordnow makes the video too;--no-videokeeps the old behavior.- The subtitle files are
captions.srtandcaptions.vtt(captions-stepNfor a preview), not named after the
video, and the.mp4has no subtitle track: players loaded them over the captions drawn on the video. The
manifest keeps the keysfiles.srtandfiles.vtt; through the API the files arecaptions.srtand
captions.vttinstead ofvideo.srtandvideo.vtt. - The
defaultsound has no room any more (the echo blurred the words), more presence and softer "s"; every preset
butnonelevels each sentence to -16 LUFS on its own, so no sentence is louder than the next. - Title cards with a voice hold 0.7 s after it instead of 3.5 s.
- Glass captions, a bigger cursor, smoother focus ring and bubbles.
- The npm package no longer ships
scripts/install.shandinstall.ps1, which only work from a clone. - The demo is Facturero, a billing app with a professional design and a mobile layout, filmed with the new look.
Fixed
- Two captions on screen in mpv, VLC and Totem (the drawn one and the subtitle track or file).
- A script in English with no voice chosen was spoken by the Spanish Piper voice.
Tourwright 2.2.0
A Docker image whose Redis queue works and whose voice is twice as fast, images tagged with each version, and
MCP tools that say what they touch.
Added
- Every MCP tool says what it touches (MCP annotations: read-only, opens websites, may replace a file) and every
parameter has a description, so agents fill them in without guessing and clients know when to ask first. - The Docker image is tagged with each release (
2.1.0,2.1,2) besideslatest, so a server or a Kubernetes
deployment can pin a version; the Kubernetes manifest and the deployment guide use:2.
Changed
- The Docker image speaks with
piper-ttskept loaded, liketourwright install, instead of the archived standalone
Piper: ten sentences take 5 s instead of 9.5 s. Voice samples and the demo video no longer go into the image.
Fixed
- The 2.1.0 Docker image came without BullMQ, ioredis and the Claude SDK, so its Redis queue (the one
docker composeuses) andnarratewith Claude did not start. They are installed from the lockfile again.
Tourwright 2.1.0
Faster renders, a progress line, Tourwright for Claude Code and GitHub Actions, a logo and a project page, and a
plain install without the Redis queue or the Claude SDK.
Added
- A Claude Code plugin:
/plugin marketplace add CXmiloxx/tourwright, then/plugin install tourwright@tourwright
brings the MCP server and amake-tourskill that writes, checks and renders a script. - A GitHub Action (
uses: CXmiloxx/tourwright@v2): render the tours on every release, orcommand: checkto fail
the build when a deploy broke one. server.jsonandmcpName, to list the MCP server in the official MCP Registry.rendershows its progress on one line in a terminal: the stage, the step being filmed and the time so far.
Jobs of the API report the step too (progress.step,progress.steps).TOURWRIGHT_TTS_PARALLEL(default 4): how many narration lines are made at once.- A logo (a pen nib that is a play button) and web icons in
brand/, used by the README, the project page and
the social preview. - A demo video and GIF in the README, a project page (
site/, Tailwind CSS) and a social preview image.
Changed
- Faster renders with a new script: every line a walkthrough says is made ahead, several at once, while the
browser starts and logs in, instead of one by one during the recording. With an online voice the demo app
went from 108 s to 74 s. Slides make their narration in parallel too. - A page still loading after
goto,backorreloadis cut from the video (unless the voice is speaking),
and an app that never goes quiet (polling, live events) waits 10 s at most instead of 30 s, on camera. - The review of the finished video (blank or black screens) runs both passes at once on a small picture:
about 3× faster. - The length of each narration is read from its WAV header instead of starting
ffprobeevery time. - The Redis queue (
bullmq,ioredis) and Claude fornarrate(@anthropic-ai/sdk) are optional peer
dependencies instead of optional dependencies: a plain install no longer downloads them, so it is lighter,
andpnpm add tourwrightfinishes without the "Ignored build scripts: msgpackr-extract" error that
BullMQ's native helper caused. Install them next to Tourwright when you use the queue or Claude; the
Docker image brings them, at the versions of the lockfile.
Tourwright 2.0.0
A script written by doing the tour, a guide from the same script, narration by your own AI, nothing
downloaded twice, and videos that keep pace with what happens on screen.
Breaking
- Node.js 22 or newer (Node 20 reached its end of life in April 2026). The install scripts stop on older
versions with "Tourwright needs Node.js 22 or newer".
Installing
tourwright installuses what the PC already has before downloading anything: Chrome, Edge or Chromium
(also a build left by another Playwright or Puppeteer version, andCHROME_PATH,CHROME_BIN,
PUPPETEER_EXECUTABLE_PATH), ffmpeg from winget, scoop, Chocolatey, Homebrew, MacPorts or Nix, Piper and
edge-tts installed with pip, pipx, conda or pyenv, Piper voices in the Hugging Face cache or in
TOURWRIGHT_PIPER_VOICE_DIRS, and the system's Python 3.10–3.13. Snap and Flatpak browsers are skipped.- It shows what it will use and what it will download, with sizes, and asks first in a terminal
(--yesskips the question,--planonly shows it). At the end it prints one line;doctorhas the list. - Its own Chromium goes into
TOURWRIGHT_HOME/browsers: a folder other tools share
(PLAYWRIGHT_BROWSERS_PATH,/opt/ms-playwright) is only read, never written to. - Piper is now
piper-tts1.8 (OHF-Voice/piper1-gpl; rhasspy/piper is archived), kept loaded during a
render: about 5× faster per sentence. The standalone build remains for 32-bit ARM and Windows on ARM. - ffmpeg comes from a release series (9.0) instead of the development branch; the Linux build moved to
BtbN (johnvansickle.com answered with a web page). A download that returns a web page says so.
Recording
--lock <file>(TOURWRIGHT_BROWSER_LOCK): one browser at a time on the machine. On Linux it is the same
lock asflock <file>, so other tools take turns with Tourwright.- A browser that does not start in time is started again twice (after 10 s and 30 s).
- Your own defaults:
tourwright config set quality fullhd(alsovoice,fps,capture,pause,polish,
preset…) for every project on the machine, checked before they are saved;tourwright configshows each
value and where it comes from.TOURWRIGHT_QUALITY,TOURWRIGHT_FPSandTOURWRIGHT_CAPTUREdo the same.
The built-in default stays 720p. An unknown--qualitynow says which ones exist. - Narration and actions keep pace: a
focusacts as the voice stops (no extra 2 s), its voice starts while
the cursor travels, and an element already on screen is not waited for. A login on camera went from 22 s
to 13 s with the same narration.
Writing and keeping scripts
tourwright record <url>: do the tour by hand in a browser window; each click, field and choice becomes a step
with a stable target and a first narration that says where the element is ("Abre Clientes en el menú",
"Para buscar, escribe en…"), achapterper screen, and the user, password and 2FA code of a login as
${secret:…}and${totp:…}.tourwright guide <script>: the same script as a step-by-step guide with a marked screenshot per step — one
HTML file to send or print, and Markdown with its pictures. Secrets and codes never show.tourwright narrate <script> [--write]: the narration rewritten from what each screen shows, by the AI the user
brings — Claude (official SDK, optional), any OpenAI-compatible server, or Ollama on the same PC. Every line is
checked (the focus word stays, no secrets) and the old script is kept when it is saved.chapter: Namestarts a chapter of the video (and a section of the guide) with nothing on screen.tourwright check <scripts…>: every script as a dry run, every broken step and its likely fix; exit code 1
when one broke,--reportwrites Markdown and GitHub Actions gets a job summary.tourwright fix <script> [--write]: the new target for each broken step (the closest element of the same
kind, or the only one), written into the YAML keeping its comments. The MCP tooltourwright_checkdoes the
same for agents and returns the fixed script.render --step 7(or7-9): film only those steps with their voice; the steps before run fast off camera.mask: emails, phones, ID numbers, names or any pattern on screen replaced by invented data, the same for the
same value. Only what is drawn changes; an editable field keeps its real value.- Every video is reviewed: page errors, 5xx answers, clicks that changed nothing and blank or black screens are
printed with their step and saved in the manifest underreview. examples/app: a demo app with a 2FA login, personal data, an upload, a long process and a live notice;
examples/app.yamlfilms it and CI checks and renders it on Linux, macOS and Windows.
Errors
- A missing element names what was looked for and lists what the page offers, as targets to paste.
{ label: … }finds a field whose label is not linked to it (an input wrapped to add an icon) by its
placeholder, accessible name or the text before it, and warns with the direct target.- A dry run waits 5 s per element, goes on to the end and lists every step that failed. The screenshot of a
failure marks every field, button and link on the page with the target that finds it. - A value split by an unquoted comma in YAML says how to quote it.
Tourwright 1.2.0
Logins of every kind on video, and title cards that move.
Logins
tourwright explore --login camera: the draft shows the login in the video, field by field, each with a
focus that says what goes in it, instead of logging in off camera insetup.- Secrets can be typed on camera: a password field shows dots and any other field is blurred while it holds
a secret. The warning is now only for a secret in a narration, a caption or anything else in view. ${totp:NAME}: the code of an authenticator app, made from its key the moment it is typed (RFC 6238); a
code about to expire waits for the next one.tourwright session login <script>: log in by hand in a browser window (Google or Microsoft accounts, a
captcha, a code by SMS) and save it as the script'ssession. A render whose session is missing or
expired, with nosetupto log in again, stops and says to run it.
Title cards
- Title cards are animated:
animation(riseword by word, the default;typeletter by letter with a
caret;zoominto focus;splitfrom the sides;fade), abackground(gradient, driftingaurora
lights, a movinggrid, or thepageitself blurred) and akickerlabel above the title. They leave
with a short blur. The theme sets the defaults withtitleAnimationandtitleBackground. - In slides the animation is drawn frame by frame, so it is smooth whatever the machine.
- Bigger, bolder titles.
Changed
- The voices come calibrated, so
tourwright voices --checkandinstall --whisperare no longer needed:
both are still accepted and only print a notice.tourwright clean --whisperremoves Whisper if an earlier
version installed it. - A lighter npm package (0.6 MB instead of 3.3 MB): the voice samples are listened to on GitHub, and
tourwright voices --openopens them there when they are not on disk.
Fixed
exploreon a site by IP (http://127.0.0.1:…) or with a host that starts with a digit named its secrets
_127_USER, which is not a valid name: they areSITE_127_USERnow.exploreno longer lists a site's home twice when its menu links to/index.htmland the home is/.
npm install -g tourwright@1.2.0
docker pull ghcr.io/cxmiloxx/tourwright