From 0949bcd6603b6397d0a70ca390ab69269211f92c Mon Sep 17 00:00:00 2001 From: Kris Bennett <13557788+kbennett2000@users.noreply.github.com> Date: Sun, 21 Jun 2026 20:51:07 -0600 Subject: [PATCH] =?UTF-8?q?docs(install):=20write=20per-platform=20install?= =?UTF-8?q?=20pages=20=E2=80=94=20Windows=20/=20macOS=20/=20Linux=20(Cycle?= =?UTF-8?q?=2016)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fill the three install stubs at their canonical paths (the docs landing's platform picker links them). Zero-assumptions, hand-holdy walkthrough from nothing → a talking character in the browser, in two clearly-separated tiers, identical structure across all three pages: - Tier 1 (easy on-ramp, browser voice): install Docker (Desktop on Win/Mac, Engine + Compose plugin on Linux — official docs linked), get the project (clone or Download ZIP), open a terminal, `docker compose up mash` → http://localhost:8090 → upload a .acs, Speak. - Tier 2 (optional authentic TruVoice): plain-language why-files, the THREE user-supplied files into services/voice-server/vendor/ (spchapi.exe, tv_enua.exe, sdk/include/speech.h), then ONE `docker compose up` — matches the merged Cycle 15 one-command build (Docker is the only host tool; first build slower then cached; first synth of a new phrase ~few seconds, repeats instant; novel first utterance may clip slightly). Per-platform specifics verified (not guessed): Win Docker Desktop/WSL2 + PowerShell; Mac Docker Desktop + Apple-chip vs Intel + Terminal via Spotlight; Linux Docker Engine + Compose plugin (`docker compose`, not the hyphen) + run-without-sudo (docker group) with sudo fallback. All Docker links are current docs.docker.com pages. IP rule holds: NO download links to the proprietary binaries/speech.h — sourcing defers to docs/legal-and-assets.md only. Screenshots/GIFs signposted as coming (Cycle 17), not faked. Additive accuracy (same paths, no churn): docs/README.md picker line + root README drop the "(coming soon)" on the now-live install links. Docs only — no code. CI green; link audit clean (144 relative links resolve); reviewed. Cycle doc: docs/cycles/cycle-16-install-pages.md. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 6 +- docs/README.md | 4 +- docs/cycles/cycle-16-install-pages.md | 63 ++++++++++ docs/install/linux.md | 165 ++++++++++++++++++++++++-- docs/install/mac.md | 157 ++++++++++++++++++++++-- docs/install/windows.md | 155 ++++++++++++++++++++++-- 6 files changed, 521 insertions(+), 29 deletions(-) create mode 100644 docs/cycles/cycle-16-install-pages.md diff --git a/README.md b/README.md index 209a093..b0cfa0f 100644 --- a/README.md +++ b/README.md @@ -101,9 +101,9 @@ Running the playground above is the fast path. When you're ready to set things u computer — including the authentic voice — there's a friendly, step-by-step guide for each operating system: -- 🪟 **Windows** → [`docs/install/windows.md`](docs/install/windows.md) _(coming soon)_ -- 🍎 **macOS** → [`docs/install/mac.md`](docs/install/mac.md) _(coming soon)_ -- 🐧 **Linux** → [`docs/install/linux.md`](docs/install/linux.md) _(coming soon)_ +- 🪟 **Windows** → [`docs/install/windows.md`](docs/install/windows.md) +- 🍎 **macOS** → [`docs/install/mac.md`](docs/install/mac.md) +- 🐧 **Linux** → [`docs/install/linux.md`](docs/install/linux.md) New to all of this? Start with the gentle overview: [`docs/getting-started.md`](docs/getting-started.md) _(coming soon)_. diff --git a/docs/README.md b/docs/README.md index f2f70e0..44ef65c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,8 +11,8 @@ we'll explain it from scratch. ## Pick your platform -Setting it up on your own computer? Start here — each guide _will be_ step-by-step, with screenshots -(they're being written now). +Setting it up on your own computer? Start here — each guide is step-by-step (screenshots are coming in a +later update). | 🪟 Windows | 🍎 macOS | 🐧 Linux | | --- | --- | --- | diff --git a/docs/cycles/cycle-16-install-pages.md b/docs/cycles/cycle-16-install-pages.md new file mode 100644 index 0000000..b985d0c --- /dev/null +++ b/docs/cycles/cycle-16-install-pages.md @@ -0,0 +1,63 @@ +# Cycle 16 — per-platform install pages (Windows / macOS / Linux) + +## Goal +Fill the three install stubs the docs landing's platform picker links — at their **canonical paths** +(`docs/install/windows.md`, `mac.md`, `linux.md`; no renames) — so a **zero-assumptions** reader (possibly +non-technical, may never have opened a terminal) can go from nothing → a talking character in the browser. +Voice follows the parked `vision-and-docs-spec.md`: assume nothing; simple, then simpler; when in doubt, +more hand-holding; nostalgia is _deletable seasoning_. **Docs only — no code; CI stays green.** + +The authentic-voice path was simplified in Cycle 15 (merged): one `docker compose up`, **no host +Node/pnpm** (the image builds itself). These pages match that exactly. + +## Verified facts the pages use (no guessing) +- **Ports:** MASH `http://localhost:8090`, voice `http://localhost:8080` (MASH pre-fills the voice URL). +- **Tier 1** (demo, browser voice): just Docker → `docker compose up mash` → 8090 → upload a `.acs`, type, + Speak. MASH builds in-image; no vendor files needed. +- **Tier 2** (authentic voice): drop **3** user-supplied files into `services/voice-server/vendor/` — + `spchapi.exe`, `tv_enua.exe`, `sdk/include/speech.h` — then `docker compose up` (both). Docker is the + only host tool (first build slower, then cached). First synthesis of a new phrase ~3–4s; repeats instant + (cache); a novel first utterance may clip slightly (minor). Missing `speech.h` → build fails with the + exact drop path. +- **Sourcing:** all three files via [`docs/legal-and-assets.md`](../legal-and-assets.md) (§2 lists the + SAPI4/TruVoice sources + the SAPI4 SDK archive that contains `speech.h`). **No proprietary download + links** in the install pages; Docker's own official docs links are fine. +- **Official Docker install docs (confirmed current, June 2026):** Desktop overview + `https://docs.docker.com/desktop/`; Windows + `https://docs.docker.com/desktop/setup/install/windows-install/`; macOS + `https://docs.docker.com/desktop/setup/install/mac-install/` (Apple-chip vs Intel builds); Linux Engine + `https://docs.docker.com/engine/install/`, Compose plugin `https://docs.docker.com/compose/install/linux/`, + run-without-sudo `https://docs.docker.com/engine/install/linux-postinstall/`. + +## Shared page skeleton (all three identical; only platform bits differ) +1. Title + warm intro (names the two tiers). +2. **Tier 1 — See it run** (browser voice, easy on-ramp): install Docker → get the project (clone or + Download ZIP) + open a terminal + `cd` → `docker compose up mash` → 8090 → upload `.acs`, Speak → + expectation note (browser voice) → celebrate. +3. **Tier 2 — Authentic TruVoice voice** (opt-in): why files (plain language) → the 3 files into + `services/voice-server/vendor/` (sourcing → legal-and-assets) → `docker compose up` → authentic Genie → + notes (Docker-only, first-build/cache, novel-utterance clip). +4. Trouble? → `troubleshooting.md` / `faq.md` / `glossary.md` (stubs, _coming_). +5. Screenshots + GIF **coming in Cycle 17** (no faked images). +6. Footer nav: docs home + the other two platform pages + main README (identical on all three). + +**Per-platform differences:** Windows — Docker Desktop (WSL2 backend), PowerShell/Windows Terminal. macOS — +Docker Desktop, **Apple-chip vs Intel** download note, Terminal via Spotlight. Linux — Docker **Engine** + +the **Compose plugin** (`docker compose`, not `docker-compose`) + **run-without-sudo** post-install (docker +group), with `sudo` as the no-setup fallback. + +## What is verified where +- **CI (this repo):** `pnpm -r typecheck && pnpm -r test && pnpm lint && pnpm format` stays green (docs + only; Markdown prettier-ignored). A link-audit script confirms every relative `.md` link resolves; a grep + confirms **no** proprietary download links in the install pages. +- **Operator:** open `docs/install/*` on GitHub; follow Tier 1 to a character on screen, Tier 2 to the + authentic voice. (Screenshots that would make this even easier arrive in Cycle 17.) + +## Notes / follow-ups +- `docs/legal-and-assets.md` §2 frames the speech files as "two installers" and mentions the SAPI4 SDK + archive only in passing — it doesn't name `speech.h` explicitly. The install pages point to it as-is + (no contradiction); a future cycle could update that doc to list `speech.h` as the third supplied file. + +## Non-goals +Developer page (next cycle); screenshots/GIFs (Cycle 17 — signposted); the `voice/*` deep pages; editing +`docs/legal-and-assets.md`. No code / `@vivify/core` change. diff --git a/docs/install/linux.md b/docs/install/linux.md index 64c3d62..7448ef7 100644 --- a/docs/install/linux.md +++ b/docs/install/linux.md @@ -1,15 +1,164 @@ -# Install on Linux +# Install vivify on Linux -> 🚧 **Coming soon.** This page lands in **Cycle 15**. It's a placeholder for now, so links -> pointing here already work — no dead ends. +Welcome! 👋 This guide takes you from a Linux machine to a cartoon character moving and talking in your web +browser. We'll explain every step, and you can stop after the easy part. -**What it'll cover:** step-by-step setup on Linux, with a screenshot for every major step. +There are **two tiers**, and you can do just the first: -In the meantime: +- **Tier 1 — See it run.** A character on screen, talking with your browser's built-in voice. Quick and + easy. +- **Tier 2 — The authentic voice.** The original 1990s character voice. A little more setup, totally + optional. -- New to all of this? Start with **[What is this?](../what-is-this.md)**. -- Want to try it right now? See the **[main README](../../README.md)**. +> New to all of this? The 60-second overview is **[What is this?](../what-is-this.md)**. Stuck on a word? +> The **[Glossary](../glossary.md)** explains every term in plain English. + +> 📸 _Screenshots for every step are coming in a later update — for now the steps are written out in full._ + +--- + +## Tier 1 — See it run + +This uses your **browser's built-in voice**. It's the easy on-ramp — not a lesser version — and it needs no +special files. + +### Step 1 — Install Docker + +**Docker** is free software that runs vivify for you, so you don't have to install a pile of separate pieces +by hand. On Linux, install **Docker Engine** plus the **Compose plugin**: + +1. Follow the official guide for your distribution: **[Install Docker + Engine](https://docs.docker.com/engine/install/)**. Use your distro's instructions (Ubuntu, Debian, + Fedora, etc.) — the recommended setup includes the Compose plugin. +2. If you installed Docker some other way, make sure you also have the Compose plugin: **[Install the + Compose plugin](https://docs.docker.com/compose/install/linux/)**. (Modern Docker uses **`docker + compose`**, two words — _not_ the old `docker-compose` hyphen.) +3. _(Recommended)_ So you don't have to type `sudo` every time, add yourself to the `docker` group by + following **[the post-install + steps](https://docs.docker.com/engine/install/linux-postinstall/)** (then log out and back in). Prefer + not to? No problem — just put **`sudo`** in front of the `docker` commands below. + +> Prefer a graphical app like on Windows/Mac? **[Docker Desktop for +> Linux](https://docs.docker.com/desktop/setup/install/linux/)** works too. + +**Check it's working:** open a terminal and run: + +```bash +docker --version +docker compose version +``` + +If both print a version number, you're good. + +### Step 2 — Get the vivify project + +You need a copy of the project. Two ways — pick whichever sounds easier: + +- **Easy (no tools):** on the project's GitHub page, click the green **`< > Code`** button → **Download + ZIP**, then extract it. You'll get a folder named `vivify` (or similar). +- **If you have Git:** `git clone `. + +Open your terminal and move into the project folder with `cd`, for example: + +```bash +cd ~/Downloads/vivify +``` + +### Step 3 — Start it + +In that terminal, run: + +```bash +docker compose up mash +``` + +_(If you skipped the `docker` group step, use `sudo docker compose up mash`.)_ + +The **first** time, Docker builds everything — this can take a few minutes. (After that it's cached and +starts fast.) When you see it settle and keep running, it's ready. Leave this terminal open. + +### Step 4 — Open it and say hello + +1. Open your web browser to **http://localhost:8090**. +2. You'll need a character file (a `.acs` file). vivify ships none — see **[where to get + one](../legal-and-assets.md)** (and the **[Characters](../characters.md)** page, _coming soon_). Drag + the `.acs` file onto the page. +3. Click any animation in the list to play it. Type a sentence and click **Speak**. + +**That's it — it's alive!** 🎉 The character moves, shows its speech balloon, and talks using your +browser's voice. + +> To stop it: go back to the terminal and press **Ctrl + C**. --- -← Back to the **[documentation home](../README.md)** +## Tier 2 — The authentic TruVoice voice _(optional)_ + +Want to hear the character's **real** 1990s voice instead of your browser's? That's this tier. + +### Why you need to supply a few files + +The original voice comes from closed 1990s Microsoft / Lernout & Hauspie speech software. It's not ours to +give away, so vivify can't include it — **you supply your own copies**, once. (This is also why vivify +stays free and clean to share.) + +### Step 1 — Drop in three files + +vivify looks for these in the folder **`services/voice-server/vendor/`** inside the project: + +| File | What it is | +| --- | --- | +| `spchapi.exe` | The Microsoft SAPI 4 speech runtime | +| `tv_enua.exe` | The L&H TruVoice voice (Genie & friends) | +| `sdk/include/speech.h` | The SAPI 4 SDK header (goes in `vendor/sdk/include/`) | + +**Where to find them:** see **[Legal & assets](../legal-and-assets.md)** — it lists the sources. _(We don't +link the files here, on purpose.)_ + +So the finished layout is: + +``` +services/voice-server/vendor/ + spchapi.exe + tv_enua.exe + sdk/include/speech.h +``` + +### Step 2 — One command + +In your terminal, in the project folder: + +```bash +docker compose up +``` + +_(Or `sudo docker compose up` if you skipped the `docker` group step.)_ That's the same command as before, +**without** `mash` — it now starts both the demo _and_ the voice. The first build is slower because it sets +up the voice engine; after that it's cached. + +Then open **http://localhost:8090** as before. The voice connection is pre-filled for you +(`http://localhost:8080`), so just upload your `.acs`, type, and click **Speak** — and you'll hear the +authentic voice, with the mouth moving in time. 🪄 + +**Good to know:** + +- **Docker is the only tool you need** — no programming tools to install. +- The **first time** you speak a brand-new sentence, it takes a few seconds to generate. The **same** + sentence again is instant (vivify remembers it). +- A brand-new sentence may clip its very first instant slightly — minor, and it won't happen on a repeat. +- If the build stops with a message about **`speech.h` missing**, it means that file isn't in + `services/voice-server/vendor/sdk/include/` yet — the message tells you the exact spot. + +--- + +## Trouble? + +- **[Troubleshooting](../troubleshooting.md)** — common hiccups and fixes _(coming soon)_. +- **[FAQ](../faq.md)** — "Is this legal?", "Why no sound?", "Which characters work?" _(coming soon)_. +- **[Glossary](../glossary.md)** — every term, in plain English. + +--- + +**Other platforms:** [Windows](windows.md) · [macOS](mac.md) + +← Back to the **[documentation home](../README.md)** · [main README](../../README.md) diff --git a/docs/install/mac.md b/docs/install/mac.md index 7a358dd..7c9eadd 100644 --- a/docs/install/mac.md +++ b/docs/install/mac.md @@ -1,15 +1,156 @@ -# Install on macOS +# Install vivify on macOS -> 🚧 **Coming soon.** This page lands in **Cycle 15**. It's a placeholder for now, so links -> pointing here already work — no dead ends. +Welcome! 👋 This guide takes you from a fresh Mac to a cartoon character moving and talking in your web +browser. No experience needed — we'll explain every step, and you can stop after the easy part. -**What it'll cover:** step-by-step setup on macOS, with a screenshot for every major step. +There are **two tiers**, and you can do just the first: -In the meantime: +- **Tier 1 — See it run.** A character on screen, talking with your browser's built-in voice. Quick and + easy. +- **Tier 2 — The authentic voice.** The original 1990s character voice. A little more setup, totally + optional. -- New to all of this? Start with **[What is this?](../what-is-this.md)**. -- Want to try it right now? See the **[main README](../../README.md)**. +> New to all of this? The 60-second overview is **[What is this?](../what-is-this.md)**. Stuck on a word? +> The **[Glossary](../glossary.md)** explains every term in plain English. + +> 📸 _Screenshots for every step are coming in a later update — for now the steps are written out in full._ + +--- + +## Tier 1 — See it run + +This uses your **browser's built-in voice**. It's the easy on-ramp — not a lesser version — and it needs no +special files. + +### Step 1 — Install Docker Desktop + +**Docker** is a free app that runs vivify for you, so you don't have to install a pile of separate pieces by +hand. On Mac it's called **Docker Desktop**. + +1. Go to the official guide: **[Install Docker Desktop on + Mac](https://docs.docker.com/desktop/setup/install/mac-install/)**. +2. Download the right build for your Mac: + - **Apple Silicon** (M1/M2/M3/M4 — most Macs since 2020) → the **Apple chip** download. + - **Intel** (older Macs) → the **Intel chip** download. + - Not sure? Click the **Apple menu** (top-left corner) → **About This Mac**: "Chip" = Apple Silicon, + "Processor" = Intel. +3. Open the downloaded `.dmg` and drag **Docker** into **Applications**. Launch it and leave it running. + You'll see a little **whale icon** 🐳 in the menu bar when it's ready. + +_Saw a scary-looking technical message during install? Totally normal — just follow Docker's prompts._ + +**Check it's working:** open a terminal (next step) and run `docker --version`. If it prints a version +number, you're good. + +### Step 2 — Get the vivify project + +You need a copy of the project on your Mac. Two ways — pick whichever sounds easier: + +- **Easy (no tools):** on the project's GitHub page, click the green **`< > Code`** button → **Download + ZIP**. Double-click the downloaded file to unzip it. You'll get a folder named `vivify` (or similar). +- **If you have Git:** `git clone `. + +Now **open a terminal** in that folder: + +1. Press **⌘ + Space** (Spotlight), type **Terminal**, and press Return. +2. Move into the project folder with `cd`. For example, if it's in your Downloads: + ```bash + cd ~/Downloads/vivify + ``` + _(Tip: type `cd ` then drag the folder onto the Terminal window to paste its path.)_ + +### Step 3 — Start it + +In that terminal, run: + +```bash +docker compose up mash +``` + +The **first** time, Docker builds everything — this can take a few minutes. (After that it's cached and +starts fast.) When you see it settle and keep running, it's ready. Leave this window open. + +### Step 4 — Open it and say hello + +1. Open your web browser to **http://localhost:8090**. +2. You'll need a character file (a `.acs` file). vivify ships none — see **[where to get + one](../legal-and-assets.md)** (and the **[Characters](../characters.md)** page, _coming soon_). Drag + the `.acs` file onto the page. +3. Click any animation in the list to play it. Type a sentence and click **Speak**. + +**That's it — it's alive!** 🎉 The character moves, shows its speech balloon, and talks using your +browser's voice. + +> To stop it: go back to the Terminal and press **Control + C**. --- -← Back to the **[documentation home](../README.md)** +## Tier 2 — The authentic TruVoice voice _(optional)_ + +Want to hear the character's **real** 1990s voice instead of your browser's? That's this tier. + +### Why you need to supply a few files + +The original voice comes from closed 1990s Microsoft / Lernout & Hauspie speech software. It's not ours to +give away, so vivify can't include it — **you supply your own copies**, once. (This is also why vivify +stays free and clean to share.) + +### Step 1 — Drop in three files + +vivify looks for these in the folder **`services/voice-server/vendor/`** inside the project: + +| File | What it is | +| --- | --- | +| `spchapi.exe` | The Microsoft SAPI 4 speech runtime | +| `tv_enua.exe` | The L&H TruVoice voice (Genie & friends) | +| `sdk/include/speech.h` | The SAPI 4 SDK header (goes in `vendor/sdk/include/`) | + +**Where to find them:** see **[Legal & assets](../legal-and-assets.md)** — it lists the sources. _(We don't +link the files here, on purpose.)_ + +So the finished layout is: + +``` +services/voice-server/vendor/ + spchapi.exe + tv_enua.exe + sdk/include/speech.h +``` + +### Step 2 — One command + +In your Terminal, in the project folder: + +```bash +docker compose up +``` + +(That's the same command as before, **without** `mash` — it now starts both the demo _and_ the voice.) The +first build is slower because it sets up the voice engine; after that it's cached. + +Then open **http://localhost:8090** as before. The voice connection is pre-filled for you +(`http://localhost:8080`), so just upload your `.acs`, type, and click **Speak** — and you'll hear the +authentic voice, with the mouth moving in time. 🪄 + +**Good to know:** + +- **Docker is the only tool you need** — no programming tools to install. +- The **first time** you speak a brand-new sentence, it takes a few seconds to generate. The **same** + sentence again is instant (vivify remembers it). +- A brand-new sentence may clip its very first instant slightly — minor, and it won't happen on a repeat. +- If the build stops with a message about **`speech.h` missing**, it means that file isn't in + `services/voice-server/vendor/sdk/include/` yet — the message tells you the exact spot. + +--- + +## Trouble? + +- **[Troubleshooting](../troubleshooting.md)** — common hiccups and fixes _(coming soon)_. +- **[FAQ](../faq.md)** — "Is this legal?", "Why no sound?", "Which characters work?" _(coming soon)_. +- **[Glossary](../glossary.md)** — every term, in plain English. + +--- + +**Other platforms:** [Windows](windows.md) · [Linux](linux.md) + +← Back to the **[documentation home](../README.md)** · [main README](../../README.md) diff --git a/docs/install/windows.md b/docs/install/windows.md index d164913..64fcad9 100644 --- a/docs/install/windows.md +++ b/docs/install/windows.md @@ -1,15 +1,154 @@ -# Install on Windows +# Install vivify on Windows -> 🚧 **Coming soon.** This page lands in **Cycle 15**. It's a placeholder for now, so links -> pointing here already work — no dead ends. +Welcome! 👋 This guide takes you from a fresh Windows PC to a cartoon character moving and talking in your +web browser. No experience needed — we'll explain every step, and you can stop after the easy part. -**What it'll cover:** step-by-step setup on Windows, with a screenshot for every major step. +There are **two tiers**, and you can do just the first: -In the meantime: +- **Tier 1 — See it run.** A character on screen, talking with your browser's built-in voice. Quick and + easy. +- **Tier 2 — The authentic voice.** The original 1990s character voice. A little more setup, totally + optional. -- New to all of this? Start with **[What is this?](../what-is-this.md)**. -- Want to try it right now? See the **[main README](../../README.md)**. +> New to all of this? The 60-second overview is **[What is this?](../what-is-this.md)**. Stuck on a word? +> The **[Glossary](../glossary.md)** explains every term in plain English. + +> 📸 _Screenshots for every step are coming in a later update — for now the steps are written out in full._ + +--- + +## Tier 1 — See it run + +This uses your **browser's built-in voice**. It's the easy on-ramp — not a lesser version — and it needs no +special files. + +### Step 1 — Install Docker Desktop + +**Docker** is a free app that runs vivify for you, so you don't have to install a pile of separate pieces by +hand. On Windows it's called **Docker Desktop**. + +1. Go to the official guide: **[Install Docker Desktop on + Windows](https://docs.docker.com/desktop/setup/install/windows-install/)**. +2. Download and run the installer, following Docker's own prompts. (It uses a Windows feature called WSL 2; + the installer sets it up for you. If it asks you to restart, do.) +3. When it's done, launch **Docker Desktop** from the Start menu and leave it running. You'll see a little + **whale icon** 🐳 near the clock when it's ready. + +_Saw a scary-looking technical message during install? Totally normal — just follow Docker's prompts._ + +**Check it's working:** open a terminal (next step) and run `docker --version`. If it prints a version +number, you're good. + +### Step 2 — Get the vivify project + +You need a copy of the project on your PC. Two ways — pick whichever sounds easier: + +- **Easy (no tools):** on the project's GitHub page, click the green **`< > Code`** button → **Download + ZIP**. Then unzip it (right-click → _Extract All_). You'll get a folder named `vivify` (or similar). +- **If you have Git:** `git clone `. + +Now **open a terminal** in that folder: + +1. Press the **Start** button, type **PowerShell**, and open **Windows PowerShell** (or **Windows + Terminal**). +2. Move into the project folder with `cd`. For example, if you unzipped it to your Downloads: + ```powershell + cd "$HOME\Downloads\vivify" + ``` + _(Tip: type `cd ` then drag the folder onto the window to paste its path.)_ + +### Step 3 — Start it + +In that terminal, run: + +```powershell +docker compose up mash +``` + +The **first** time, Docker builds everything — this can take a few minutes. (After that it's cached and +starts fast.) When you see it settle and keep running, it's ready. Leave this window open. + +### Step 4 — Open it and say hello + +1. Open your web browser to **http://localhost:8090**. +2. You'll need a character file (a `.acs` file). vivify ships none — see **[where to get + one](../legal-and-assets.md)** (and the **[Characters](../characters.md)** page, _coming soon_). Drag + the `.acs` file onto the page. +3. Click any animation in the list to play it. Type a sentence and click **Speak**. + +**That's it — it's alive!** 🎉 The character moves, shows its speech balloon, and talks using your +browser's voice. + +> To stop it: go back to the terminal and press **Ctrl + C**. --- -← Back to the **[documentation home](../README.md)** +## Tier 2 — The authentic TruVoice voice _(optional)_ + +Want to hear the character's **real** 1990s voice instead of your browser's? That's this tier. + +### Why you need to supply a few files + +The original voice comes from closed 1990s Microsoft / Lernout & Hauspie speech software. It's not ours to +give away, so vivify can't include it — **you supply your own copies**, once. (This is also why vivify +stays free and clean to share.) + +### Step 1 — Drop in three files + +vivify looks for these in the folder **`services/voice-server/vendor/`** inside the project: + +| File | What it is | +| --- | --- | +| `spchapi.exe` | The Microsoft SAPI 4 speech runtime | +| `tv_enua.exe` | The L&H TruVoice voice (Genie & friends) | +| `sdk/include/speech.h` | The SAPI 4 SDK header (goes in `vendor/sdk/include/`) | + +**Where to find them:** see **[Legal & assets](../legal-and-assets.md)** — it lists the sources. _(We don't +link the files here, on purpose.)_ + +So the finished layout is: + +``` +services/voice-server/vendor/ + spchapi.exe + tv_enua.exe + sdk/include/speech.h +``` + +### Step 2 — One command + +In your terminal, in the project folder: + +```powershell +docker compose up +``` + +(That's the same command as before, **without** `mash` — it now starts both the demo _and_ the voice.) The +first build is slower because it sets up the voice engine; after that it's cached. + +Then open **http://localhost:8090** as before. The voice connection is pre-filled for you +(`http://localhost:8080`), so just upload your `.acs`, type, and click **Speak** — and you'll hear the +authentic voice, with the mouth moving in time. 🪄 + +**Good to know:** + +- **Docker is the only tool you need** — no programming tools to install. +- The **first time** you speak a brand-new sentence, it takes a few seconds to generate. The **same** + sentence again is instant (vivify remembers it). +- A brand-new sentence may clip its very first instant slightly — minor, and it won't happen on a repeat. +- If the build stops with a message about **`speech.h` missing**, it means that file isn't in + `services/voice-server/vendor/sdk/include/` yet — the message tells you the exact spot. + +--- + +## Trouble? + +- **[Troubleshooting](../troubleshooting.md)** — common hiccups and fixes _(coming soon)_. +- **[FAQ](../faq.md)** — "Is this legal?", "Why no sound?", "Which characters work?" _(coming soon)_. +- **[Glossary](../glossary.md)** — every term, in plain English. + +--- + +**Other platforms:** [macOS](mac.md) · [Linux](linux.md) + +← Back to the **[documentation home](../README.md)** · [main README](../../README.md)