diff --git a/README.md b/README.md index d2e3064..9552dcd 100644 --- a/README.md +++ b/README.md @@ -108,8 +108,7 @@ system: - 🍎 **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)_. +New to all of this? Start with the gentle overview: [`docs/getting-started.md`](docs/getting-started.md). --- @@ -190,9 +189,8 @@ It's all explained, with exactly where to get each piece, in ## More help - ❓ **FAQ** β€” "Is this legal?", "Why is there no sound?", "Which characters work?" β†’ - [`docs/faq.md`](docs/faq.md) _(coming soon)_ + [`docs/faq.md`](docs/faq.md) - πŸ› οΈ **Troubleshooting** β€” common hiccups, per platform β†’ [`docs/troubleshooting.md`](docs/troubleshooting.md) - _(coming soon)_ - πŸ“– **Glossary** β€” every technical term, in plain English β†’ [`docs/glossary.md`](docs/glossary.md) --- diff --git a/docs/cycles/cycle-21-help-cluster.md b/docs/cycles/cycle-21-help-cluster.md new file mode 100644 index 0000000..fe08971 --- /dev/null +++ b/docs/cycles/cycle-21-help-cluster.md @@ -0,0 +1,90 @@ +# Cycle 21 β€” the help cluster (getting-started / faq / troubleshooting) + +## Goal +Fill the last three empty stubs at their canonical paths so the README/landing "Help" links stop +dead-ending: + +- `docs/getting-started.md` β€” the gentle, universal on-ramp ("zero to a character on your screen, then + where to go next"). +- `docs/faq.md` β€” the common questions, answered plainly, each routing to the canonical page for depth. +- `docs/troubleshooting.md` β€” common hiccups + fixes, grouped by symptom, de-scared. + +Audience is **zero-assumptions** (possibly non-technical, may never have used a terminal). Voice/tone per +the parked `vision-and-docs-spec.md` (PO pasted it this session): warm, plain, encouraging, more +hand-holding when in doubt; nostalgia only in clearly set-off asides. **Docs only β€” no code; CI stays +green.** + +## No duplication β€” route, don't re-paste (canonical homes) +| Topic | Canonical home | Help pages | +| --- | --- | --- | +| Per-platform step-by-step (install Docker, drop files, run) | `docs/install/{windows,mac,linux}.md` | link to them | +| Sourcing + IP posture | `docs/legal-and-assets.md` | link to it | +| Authentic-voice concepts | `docs/voice/*` | link to them | +| What Microsoft Agent was | `docs/what-is-this.md` | link to it | + +getting-started gives the **shape** of the simplest path and hands off to the per-OS install guide for the +actual hand-holding; faq answers short + links; troubleshooting gives symptomβ†’fix and routes to the +canonical page for the steps. No install steps, no sourcing list, no voice walkthrough is re-pasted. + +## Verified facts the pages use (cross-checked against the repo) +- **Tier 1 (browser voice):** `docker compose up mash` β†’ `http://localhost:8090` β†’ upload a `.acs`, type, + **Speak**. No voice files needed; uses the browser's voice. (`docker-compose.yml`, install pages.) +- **Tier 2 (authentic voice):** `docker compose up` (both services); voice at `http://localhost:8080`, + pre-filled in MASH; needs the 3 user-supplied files in `services/voice-server/vendor/`. +- **MASH status messages (verbatim, `apps/mash/src/app.ts`):** + - load failure β†’ `Couldn't load : `; wrong file β†’ `Please choose a .acs character file.` + - voice unreachable β†’ `Couldn't reach the voice server at () β€” clear the field to speak + silently.`; no URL set β†’ `Speak failed: `. +- **Loud build failures (`services/voice-server/Dockerfile`):** missing `speech.h` β†’ + `FATAL: speech.h missing β€” drop the user-supplied SAPI4 SDK header at + services/voice-server/vendor/sdk/include/speech.h (see docs/legal-and-assets.md)…`; also `FATAL: SAPI4 + Speech.dll not installed` / `TruVoice tv_enua.dll not installed` when the runtime `.exe`s weren't + supplied. β†’ all mean "a supplied file is missing/not in place." +- **First build is slow, then cached** (the voice image compiles its own `dist/` in-image β€” Cycle 15). + **First novel utterance may clip slightly; repeats are instant** (disk cache, Cycle 12). The voice + server returns an **honest 500** (never a faked/silent WAV) if synthesis fails. +- **Privacy:** Tier 1 runs entirely in the browser; Tier 2's `/tts` call goes from your browser to your + **own** `localhost:8080` helper β€” nothing is sent to a third party. +- **Linux** may need `sudo docker …` or the docker group (the Linux install page covers the post-install). + +## CTA accuracy fixes (these pages become real, so the markers are now stale) +Drop `_(coming soon)_` everywhere it points at these three now-real pages β€” **same links, no path churn:** +- `README.md` β€” getting-started (~112), FAQ (~191), Troubleshooting (~193). +- `docs/install/{windows,mac,linux}.md` "Trouble?" footers β€” Troubleshooting + FAQ `_(coming soon)_` + (6 markers). `docs/README.md` landing already links them cleanly (no change). + +## Pages β€” shape +- **getting-started.md:** warm "you can do this" intro β†’ the simplest path in 4 plain beats (get Docker + + the project / run one command / open the page / drop a character and talk) β†’ **pick your OS** for the + click-by-click (link the 3 install pages) β†’ signposts (real voice β†’ voice/overview; new here β†’ + what-is-this; developer β†’ developers/overview; characters β†’ characters.md). Short and confidence-building. +- **faq.md:** Q&A, short answers, each links the canonical page: is this legal? (β†’ legal-and-assets), do I + need to be a programmer? (no β€” Tier 1), why no sound / why extra files? (β†’ voice/overview), which + characters work? (β†’ characters), what is this? (β†’ what-is-this), what platforms?, is my data sent + anywhere? (no), why is the first line a touch slow/clipped? (latency + cache), can I use it in my own + app? (β†’ developers). +- **troubleshooting.md:** grouped by symptom, friendly/de-scary, each with the real behavior + the fix + + a route: no sound; character won't load; Docker isn't running / port already in use (8090/8080); + "scary" build messages (the loud `speech.h`/runtime FATALs β†’ the drop path + legal-and-assets); + first build slow; Linux permission/sudo. A short per-platform note where it differs. + +## Acceptance check +- All three pages have real content (no "🚧 Coming soon"), in the spec voice, cross-linking each other + + the docs landing + the canonical pages. +- No install/sourcing/voice content is re-pasted (route only); troubleshooting matches the **real** error + behaviors quoted above. +- All `_(coming soon)_` markers pointing at these three pages are cleared (README + install footers); + every relative link resolves. +- `pnpm -r typecheck && pnpm -r test && pnpm lint && pnpm format` green (docs only; Markdown + prettier-ignored). + +## Verification +- `code-reviewer`: no duplication of install/sourcing/voice steps; troubleshooting matches real behaviors; + links resolve; the stale markers are cleared. +- `grep -rn "coming soon" README.md docs/ | grep -vE 'cycles/|decisions/'` β†’ no hit points at + getting-started / faq / troubleshooting. + +## Non-goals +Expanding `characters.md` / `architecture.md` (optional later polish). No code. No edits to install / +legal / voice page **content** (only the `_(coming soon)_` marker accuracy). No merge β€” open a PR (base +`main`) and stop. diff --git a/docs/faq.md b/docs/faq.md index a17dd3f..613a86a 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,14 +1,66 @@ # FAQ -> 🚧 **Coming soon.** This page lands in **a later cycle**. It's a placeholder for now, so links -> pointing here already work β€” no dead ends. +Short answers to the questions people ask most. Each one links to a fuller page if you want the detail. -**What it'll cover:** the common questions β€” "Is this legal?", "Why is there no sound?", "Which characters work?" β€” answered plainly. +## What is this, exactly? -In the meantime: +It brings back the little animated characters that lived on the Windows desktop in the late 1990s β€” Genie, +Merlin, Clippy, and friends β€” and runs them right in your web browser. They move, gesture, talk out loud, +and show a comic-style speech balloon. β†’ **[What is this?](what-is-this.md)** tells the whole story from +scratch. -- 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)**. +## Do I need to be a programmer? + +**No.** To see a character on screen and hear it talk, you install one free app (Docker), run a single +command, and open a web page. That's it. β†’ **[Getting started](getting-started.md)**. + +## Is this legal? + +The vivify **software** is free and open-source (MIT) and ships **no** Microsoft files and **no** +characters. The character files and the original voice software are their owners' β€” so vivify never +includes or redistributes them; **you supply your own copies**. That split is exactly what keeps it clean +and shareable. β†’ the full posture is in **[Legal & assets](legal-and-assets.md)**. + +## Why is there no sound? / Why do I need extra files for the voice? + +There are two voices. Out of the box, characters use your **browser's** built-in voice β€” that needs +nothing. The **authentic** original voice is closed 1990s Windows speech software that can't run inside a +browser, so it runs in a small helper you set up once (with a few free files you supply). If you hear +nothing, you're almost certainly missing that helper β€” or just haven't enabled it. β†’ **[The authentic +voice](voice/overview.md)**, and **[Troubleshooting β†’ No sound](troubleshooting.md)**. + +## Which characters work? + +Any Microsoft Agent character file (a `.acs` file) β€” Genie, Merlin, Peedy, Robby, Clippy, and the many +characters fans made. You bring your own; vivify ships none. β†’ **[Characters](characters.md)** explains +what they are and where to find them. + +## What platforms does it run on? + +The characters run in any modern **web browser**. The setup (Docker) works on **Windows, macOS, and +Linux** β€” there's a hand-held guide for each. β†’ **[Getting started](getting-started.md)**. + +## Is my data sent anywhere? + +No. The playground runs entirely in your browser. Even the authentic voice talks only to a helper on +**your own machine** (`localhost`) β€” nothing is sent to vivify or any third party. + +## Why is the very first thing I say a little slow or slightly clipped? + +Only with the authentic voice, and only the **first time** for a brand-new sentence: the engine takes a +moment to generate it, and its very first instant can be ever-so-slightly clipped. Say the same line again +and it's **instant** (the helper remembers every line it has spoken). Totally normal β€” more in +**[Troubleshooting](troubleshooting.md)**. + +## Can I put a character in my own website or app? + +Yes β€” that's a core goal. The engine is a framework-agnostic library you can drop into React, Vue, Svelte, +or plain JavaScript, with a talking character in about ten lines. β†’ **[For +developers](developers/overview.md)**. + +## Where do I go when something breaks? + +β†’ **[Troubleshooting](troubleshooting.md)** β€” common hiccups and friendly fixes. --- diff --git a/docs/getting-started.md b/docs/getting-started.md index 8bb20a4..5879034 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,14 +1,61 @@ # Getting started -> 🚧 **Coming soon.** This page lands in **a later cycle**. It's a placeholder for now, so links -> pointing here already work β€” no dead ends. +Want a cartoon character moving and talking in your web browser? You can have one on screen in **about a +minute**, and you do **not** need to be a programmer. This page shows you the shape of it, then points you +to a step-by-step guide for your exact computer. -**What it'll cover:** the gentle, universal walkthrough β€” from zero to a character on your screen, then where to go next. +Take a breath β€” this is the easy part. πŸ™‚ -In the meantime: +> πŸ’Ύ **Remember when…** you'd pop in a CD-ROM and a little assistant would wave hello? That's the feeling +> we're bringing back. (You can skip this box β€” it changes nothing.) -- 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)**. +## First, the simplest path + +There are two levels, and **you only need the first** to see a character come to life: + +- **Level 1 β€” see it run.** A character on screen, talking with your browser's own built-in voice. Quick + and easy. _(This page.)_ +- **Level 2 β€” the real 1990s voice.** The authentic original voice, with a little extra one-time setup. + Totally optional β€” come back for it later. β†’ **[The authentic voice](voice/overview.md)** + +## What "Level 1" looks like + +Just four small beats β€” and the per-OS guide walks you through each one with no steps skipped: + +1. **Install Docker.** It's one free app that runs everything for you, so you don't have to install a pile + of separate pieces by hand. (Don't worry about what it _is_ β€” just install it like any other app.) +2. **Get the vivify project** onto your computer (a download, or `git clone` if you know what that is). +3. **Run one command** in a terminal, from the project folder: + ``` + docker compose up mash + ``` + The first time, it builds things and takes a few minutes β€” that's normal. Leave it running. +4. **Open your browser to [http://localhost:8090](http://localhost:8090)**, drag a character file (a + `.acs` file) onto the page, click an animation to play it, type a sentence, and hit **Speak**. + +**That's it β€” it's alive!** πŸŽ‰ The character moves, shows its little speech balloon, and talks. + +> You supply your own `.acs` character files β€” vivify ships none. The +> **[Characters](characters.md)** page explains what they are and where to get them. It's quick. + +## Now do it on your computer (the real steps) + +Each guide is written for a total beginner, with every step spelled out. Pick yours: + +- πŸͺŸ **[Install on Windows](install/windows.md)** +- 🍎 **[Install on macOS](install/mac.md)** +- 🐧 **[Install on Linux](install/linux.md)** + +## Where to go next + +- **Curious what this even is?** β†’ **[What is this?](what-is-this.md)** β€” Microsoft Agent explained from + scratch, zero knowledge assumed. +- **Want the real, original voice?** β†’ **[The authentic voice](voice/overview.md)** β€” what it is and the + one-time setup. +- **Which characters can I use?** β†’ **[Characters](characters.md)**. +- **Hit a snag?** β†’ **[Troubleshooting](troubleshooting.md)**, or the **[FAQ](faq.md)**. +- **Hit a word you didn't know?** β†’ the **[Glossary](glossary.md)**, plain English for every term. +- **You're a developer?** β†’ **[For developers](developers/overview.md)** β€” embed vivify in your own app. --- diff --git a/docs/install/linux.md b/docs/install/linux.md index 07ba7b6..418afad 100644 --- a/docs/install/linux.md +++ b/docs/install/linux.md @@ -155,8 +155,8 @@ authentic voice, with the mouth moving in time. πŸͺ„ ## Trouble? -- **[Troubleshooting](../troubleshooting.md)** β€” common hiccups and fixes _(coming soon)_. -- **[FAQ](../faq.md)** β€” "Is this legal?", "Why no sound?", "Which characters work?" _(coming soon)_. +- **[Troubleshooting](../troubleshooting.md)** β€” common hiccups and fixes. +- **[FAQ](../faq.md)** β€” "Is this legal?", "Why no sound?", "Which characters work?" - **[Glossary](../glossary.md)** β€” every term, in plain English. --- diff --git a/docs/install/mac.md b/docs/install/mac.md index d819a6a..933a033 100644 --- a/docs/install/mac.md +++ b/docs/install/mac.md @@ -147,8 +147,8 @@ authentic voice, with the mouth moving in time. πŸͺ„ ## Trouble? -- **[Troubleshooting](../troubleshooting.md)** β€” common hiccups and fixes _(coming soon)_. -- **[FAQ](../faq.md)** β€” "Is this legal?", "Why no sound?", "Which characters work?" _(coming soon)_. +- **[Troubleshooting](../troubleshooting.md)** β€” common hiccups and fixes. +- **[FAQ](../faq.md)** β€” "Is this legal?", "Why no sound?", "Which characters work?" - **[Glossary](../glossary.md)** β€” every term, in plain English. --- diff --git a/docs/install/windows.md b/docs/install/windows.md index fa20b4f..8ff382f 100644 --- a/docs/install/windows.md +++ b/docs/install/windows.md @@ -145,8 +145,8 @@ authentic voice, with the mouth moving in time. πŸͺ„ ## Trouble? -- **[Troubleshooting](../troubleshooting.md)** β€” common hiccups and fixes _(coming soon)_. -- **[FAQ](../faq.md)** β€” "Is this legal?", "Why no sound?", "Which characters work?" _(coming soon)_. +- **[Troubleshooting](../troubleshooting.md)** β€” common hiccups and fixes. +- **[FAQ](../faq.md)** β€” "Is this legal?", "Why no sound?", "Which characters work?" - **[Glossary](../glossary.md)** β€” every term, in plain English. --- diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 769236d..c809404 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,14 +1,85 @@ # Troubleshooting -> 🚧 **Coming soon.** This page lands in **a later cycle**. It's a placeholder for now, so links -> pointing here already work β€” no dead ends. +Something not working? Don't worry β€” almost every snag here is common, harmless, and quick to fix. Find +your symptom below. -**What it'll cover:** the common hiccups and their fixes, grouped by platform and by symptom (no audio, a character won't load, scary-looking messages). +> **A friendly heads-up about "scary" messages.** Build tools print a _lot_ of text, some of it in alarming +> red. That's normal β€” it doesn't mean you broke anything. The few messages that actually need your +> attention are listed below, in plain English. -In the meantime: +## No sound when I click Speak -- 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)**. +The character moves and shows its balloon, but you hear nothing. Work down this list: + +- **You're on the browser voice and your system is muted / volume down.** The default voice is your + browser's own β€” check your volume. +- **You wanted the _authentic_ voice but only started the demo.** The authentic voice needs its helper + running. Make sure you ran **`docker compose up`** (both parts), not `docker compose up mash` (the demo + only). β†’ **[Setting up the authentic voice](voice/setup.md)**. +- **The "Voice server URL" field is empty.** In the playground, that field should read + `http://localhost:8080`. If it's blank, the character speaks **silently** on purpose β€” type that address + back in. If MASH says _"Couldn't reach the voice server… β€” clear the field to speak silently,"_ the + helper isn't running or isn't reachable (see the line above). +- **You haven't supplied the voice files yet.** The authentic voice needs three files you provide once. β†’ + **[Where to get the voice components](voice/sourcing-components.md)**. + +Just want sound _now_? Clear the URL field is the opposite of what you want β€” instead, leave the browser +voice on (no helper needed) and you'll always hear _something_. + +## A character won't load + +- **"Please choose a `.acs` character file."** You picked a file that isn't a `.acs`. Microsoft Agent + characters are `.acs` files β€” grab one as described on the **[Characters](characters.md)** page. +- **"Couldn't load _name_: …"** The file is a `.acs` but vivify couldn't read it β€” it may be corrupted or + an unusual variant. Try a different character (Genie is a reliable first test), and see + **[Characters](characters.md)** for known-good sources. +- **Nothing happens at all.** Make sure the page actually loaded at **http://localhost:8090** and the + command from your install guide is still running in its terminal window. + +## Docker won't start, or the page won't open + +- **"Docker isn't running."** Start Docker Desktop (Windows/macOS) and wait for its whale icon to settle, + then run the command again. On Linux, make sure the Docker service is up. +- **`http://localhost:8090` won't open.** The command needs to be **running** (leave that terminal open). + If it exited, scroll up for a message and re-run it. +- **"Port is already allocated" / "address already in use."** Something else is using **8090** (the + playground) or **8080** (the voice helper). Close whatever's using it, or map a different host port β€” + e.g. `docker compose up` after changing `"8090:8090"` to `"9000:8090"` in `docker-compose.yml`, then open + `http://localhost:9000`. The full per-OS steps are in your **[install guide](README.md)**. + +## A "FATAL" message stopped the build (authentic voice) + +This only happens on the **authentic-voice** setup, and it's the build telling you a supplied file isn't +in place yet. It's helpful, not broken β€” it names the exact fix: + +- **`FATAL: speech.h missing β€” drop the … header at services/voice-server/vendor/sdk/include/speech.h`** β€” + put that one file at exactly that path and build again. +- **`FATAL: SAPI4 Speech.dll not installed`** or **`TruVoice tv_enua.dll not installed`** β€” the speech + runtime files (`spchapi.exe` / `tv_enua.exe`) aren't in `services/voice-server/vendor/` yet. + +All three files and where to get them are on **[Where to get the voice components](voice/sourcing-components.md)** +and **[Legal & assets](legal-and-assets.md)**. + +## The first build is taking forever + +The first `docker compose up` builds everything β€” for the authentic voice it sets up the speech engine, +which takes a few minutes. **This is one-time.** After that it's cached and starts quickly. Grab a coffee; +it's working. + +> πŸ’Ύ **Remember when…** installing anything meant a progress bar and a sandwich? Same energy. It'll finish. + +## Linux: "permission denied" running Docker + +On Linux you may need to run Docker with `sudo` (e.g. `sudo docker compose up`), or add your user to the +`docker` group so you don't have to. The **[Linux install guide](install/linux.md)** has the exact +post-install steps. + +## Still stuck? + +- Re-read your platform's guide β€” every step is spelled out: **[Windows](install/windows.md)** Β· + **[macOS](install/mac.md)** Β· **[Linux](install/linux.md)**. +- Check the **[FAQ](faq.md)** for the "why" behind a behavior. +- Unsure what a word means? β†’ the **[Glossary](glossary.md)**. ---