From 36c265df8ab462c3ca3235d2c452ad37094cb5f9 Mon Sep 17 00:00:00 2001 From: Kris Bennett <13557788+kbennett2000@users.noreply.github.com> Date: Sun, 21 Jun 2026 19:40:22 -0600 Subject: [PATCH] =?UTF-8?q?docs:=20build=20the=20docs/=20backbone=20?= =?UTF-8?q?=E2=80=94=20landing=20+=20"What=20is=20this=3F"=20+=20skeleton?= =?UTF-8?q?=20(Cycle=2014)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cycle 13 signposted docs/ pages from the README as "(coming soon)" but they didn't exist, so the front-door links 404'd. This cycle builds the docs/ backbone: in-repo Markdown that renders on GitHub (no site framework, no build step), with the canonical page map matching every README signpost exactly (no link churn). Written for real: - docs/README.md — docs landing: orientation + platform picker (Win/Mac/Linux) + table of contents grouped by intent. - docs/what-is-this.md — zero-knowledge Microsoft Agent explainer (what it was, the cast, removed in Windows 7, what vivify does). - docs/glossary.md — plain-English terms. - docs/credits.md — gracious acknowledgments. Stubbed (consistent "coming soon" template, so every link resolves now — no 404s): install/{windows,mac,linux} (Cycle 15), developers/{overview,quickstart,api, providers,bundles} (Cycle 16), characters (Cycle 17), voice/{overview,setup, sourcing-components}, faq, troubleshooting, getting-started. The developer page is the NESTED docs/developers/overview.md to match the README signpost. README: two additive discoverability links (docs landing + a "What is this?" read-more) and dropped the "(coming)" qualifier on glossary/credits now that those pages exist. No existing signpost path changed. Docs only — no code. CI green; a link-audit confirms all relative .md links resolve. Docs: docs/cycles/cycle-14-docs-skeleton.md (page-map table) + ADR-0026. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 13 ++-- docs/README.md | 69 ++++++++++++++++++++ docs/characters.md | 15 +++++ docs/credits.md | 49 +++++++++++++++ docs/cycles/cycle-14-docs-skeleton.md | 76 ++++++++++++++++++++++ docs/decisions/0026-docs-skeleton.md | 37 +++++++++++ docs/developers/api.md | 15 +++++ docs/developers/bundles.md | 15 +++++ docs/developers/overview.md | 15 +++++ docs/developers/providers.md | 15 +++++ docs/developers/quickstart.md | 15 +++++ docs/faq.md | 15 +++++ docs/getting-started.md | 15 +++++ docs/glossary.md | 91 +++++++++++++++++++++++++++ docs/install/linux.md | 15 +++++ docs/install/mac.md | 15 +++++ docs/install/windows.md | 15 +++++ docs/troubleshooting.md | 15 +++++ docs/voice/overview.md | 15 +++++ docs/voice/setup.md | 15 +++++ docs/voice/sourcing-components.md | 15 +++++ docs/what-is-this.md | 87 +++++++++++++++++++++++++ 22 files changed, 643 insertions(+), 4 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/characters.md create mode 100644 docs/credits.md create mode 100644 docs/cycles/cycle-14-docs-skeleton.md create mode 100644 docs/decisions/0026-docs-skeleton.md create mode 100644 docs/developers/api.md create mode 100644 docs/developers/bundles.md create mode 100644 docs/developers/overview.md create mode 100644 docs/developers/providers.md create mode 100644 docs/developers/quickstart.md create mode 100644 docs/faq.md create mode 100644 docs/getting-started.md create mode 100644 docs/glossary.md create mode 100644 docs/install/linux.md create mode 100644 docs/install/mac.md create mode 100644 docs/install/windows.md create mode 100644 docs/troubleshooting.md create mode 100644 docs/voice/overview.md create mode 100644 docs/voice/setup.md create mode 100644 docs/voice/sourcing-components.md create mode 100644 docs/what-is-this.md diff --git a/README.md b/README.md index 20b3a3a..209a093 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,9 @@ > _Before "Agent" had anything to do with AI… there were Genie, Merlin, and Clippy._ +📖 **New here, or just curious?** Browse the **[documentation](docs/README.md)** — start with the +plain-English **["What is this?"](docs/what-is-this.md)**. + --- ## ▶ See it move @@ -40,11 +43,14 @@ computer to just _look_ at it. > 💾 **Remember when…** software came on a stack of floppy disks, "downloading" meant going to make a > sandwich, and a tiny cartoon would pop up to "help" you write a letter? Yeah. This brings _that_ back. +👉 **Want the full story?** Read **[What is this?](docs/what-is-this.md)** — Microsoft Agent explained from +scratch, zero knowledge assumed. + #### A couple of words, in plain English - **`.acs` file** — the single file that holds one character: all its pictures, animations, and sounds. - (Microsoft's format. You supply your own — more on that below.) _A full glossary is coming in - [`docs/glossary.md`](docs/glossary.md)._ + (Microsoft's format. You supply your own — more on that below.) _See the + **[glossary](docs/glossary.md)** for every term in plain English._ - **Lip-sync** — the character's mouth moving in time with the words it speaks. --- @@ -183,7 +189,6 @@ It's all explained, with exactly where to get each piece, in - 🛠️ **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) - _(coming soon)_ --- @@ -193,7 +198,7 @@ vivify stands on a lot of shoulders, gratefully: the original **Microsoft Agent* characters; **DoubleAgent** (Cinnamon Software) and **Lebeau's MSAgent Decompiler** as references for the `.acs` format; **clippy.js** for proving the characters could live again in a browser; **TETYYS/SAPI4** for charting the path to the authentic voice; and **TMAFE** for keeping the character archive alive all these -years. A fuller credits page is coming in [`docs/credits.md`](docs/credits.md). +years. See the full **[credits page](docs/credits.md)**. --- diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..f2f70e0 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,69 @@ +# vivify documentation + +Welcome! 👋 This is the home for everything beyond the [main README](../README.md). Whether you just want +to _see a character on your screen_ or you're a developer who wants to embed one in your own app, there's a +path here for you. + +New to all of this? You're in exactly the right place — start with **[What is this?](what-is-this.md)** and +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). + +| 🪟 Windows | 🍎 macOS | 🐧 Linux | +| --- | --- | --- | +| **[Install on Windows](install/windows.md)** | **[Install on macOS](install/mac.md)** | **[Install on Linux](install/linux.md)** | + +> Just want a quick look first, without installing anything? The [main README](../README.md) shows you how +> to run the playground in about a minute. + +--- + +## Everything else + +**New here?** + +- **[What is this?](what-is-this.md)** — what Microsoft Agent was, and what vivify does. Zero knowledge + assumed. +- **[Glossary](glossary.md)** — every technical term, in plain English. + +**Get it running** + +- **[Getting started](getting-started.md)** — the gentle, universal walkthrough. +- **[Install guides](install/windows.md)** — Windows · macOS · Linux (see the picker above). + +**The characters** + +- **[Characters](characters.md)** — the cast, and how to get your own `.acs` files. + +**The real voice** _(the deeper, optional upgrade)_ + +- **[The authentic voice — overview](voice/overview.md)** — what it is and why it needs a helper. +- **[Setting it up](voice/setup.md)** · **[Where to get the components](voice/sourcing-components.md)** + +**For developers** + +- **[For developers — overview](developers/overview.md)** — embed vivify in your own app. +- **[Quickstart](developers/quickstart.md)** · **[API reference](developers/api.md)** · + **[TTS providers](developers/providers.md)** · **[Character bundles](developers/bundles.md)** + +**Help** + +- **[FAQ](faq.md)** · **[Troubleshooting](troubleshooting.md)** · **[Glossary](glossary.md)** + +**About** + +- **[Credits](credits.md)** — the shoulders we stand on. +- **[Legal & assets](legal-and-assets.md)** — what you supply, and why. +- **[Architecture](architecture.md)** · **[Roadmap](roadmap.md)** — how it's built and where it's going. + +--- + +> 💾 **Remember when…** every good program came with a fat printed manual you could flip through on the +> floor? Consider this the friendly, searchable version. (You can still read it on the floor.) + +← Back to the **[main README](../README.md)** diff --git a/docs/characters.md b/docs/characters.md new file mode 100644 index 0000000..9ea9b1a --- /dev/null +++ b/docs/characters.md @@ -0,0 +1,15 @@ +# Characters + +> 🚧 **Coming soon.** This page lands in **Cycle 17**. It's a placeholder for now, so links +> pointing here already work — no dead ends. + +**What it'll cover:** a gallery of the classic characters, plus how to get your own `.acs` character files. + +In the meantime: + +- 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)**. + +--- + +← Back to the **[documentation home](README.md)** diff --git a/docs/credits.md b/docs/credits.md new file mode 100644 index 0000000..b080795 --- /dev/null +++ b/docs/credits.md @@ -0,0 +1,49 @@ +# Credits + +vivify stands on a lot of shoulders, and we're grateful for every one of them. This revival wouldn't exist +without the people who made the originals, the people who reverse-engineered the formats, and the people +who kept the files and the know-how alive for decades. + +## The originals + +- **The Microsoft Agent team.** They created the characters and the technology this project lovingly + revives. Genie, Merlin, Peedy, Robby, Clippy, and the whole desktop-assistant era are theirs. +- **Lernout & Hauspie**, for the **TruVoice** text-to-speech engine that gave the characters their + distinctive voices. + +## Format references + +Figuring out exactly how a `.acs` file is laid out — down to the byte — would have been far harder without +these. We studied them as references; vivify's parser is written from scratch. + +- **[DoubleAgent](https://github.com/CinnamonSoftware/DoubleAgent)** (Cinnamon Software) — an open + reimplementation of the Agent server that reads `.acs` files. Our ground-truth reference for the format. +- **Lebeau's MSAgent Decompiler** — extracts the original bitmaps and sounds from a `.acs`. We use it as a + validation oracle: decode a character with vivify, then check it against what the decompiler extracts. + +## Proof it could be done + +- **[clippy.js](https://www.smore.com/clippy-js)** — showed the world that these characters could live + again in a web browser. It blazed the trail; vivify aims for full-fidelity faithfulness on top of that + inspiration. + +## The authentic voice + +- **[TETYYS/SAPI4](https://github.com/TETYYS/SAPI4)** — charted the path for running the vintage SAPI4 + + TruVoice speech software under Wine and exposing it over HTTP. vivify extends that approach to also + capture the mouth/lip-sync timing. + +## Keeping it alive + +- **TMAFE** (The Microsoft Agent Fan community) — for archiving and preserving the character files all + these years, so there's anything left to revive at all. + +--- + +A note on ownership: the characters, the speech engine, and related assets belong to their respective +owners. vivify ships **none** of them — you supply your own copies. See **[Legal & +assets](legal-and-assets.md)** for the details. + +--- + +← Back to the **[documentation home](README.md)** diff --git a/docs/cycles/cycle-14-docs-skeleton.md b/docs/cycles/cycle-14-docs-skeleton.md new file mode 100644 index 0000000..a158ae8 --- /dev/null +++ b/docs/cycles/cycle-14-docs-skeleton.md @@ -0,0 +1,76 @@ +# Cycle 14 — docs skeleton + landing page + +## Goal +Cycle 13 polished the README front door and signposted a set of `docs/` pages as _(coming soon)_ — but +those targets didn't exist, so every front-door "coming soon" link 404'd. This cycle builds the **docs/ +backbone**: the full folder layout + navigation that later cycles fill in, plus the docs landing and the +zero-assumptions "What is this?" explainer written for real. In-repo Markdown only — renders on GitHub, no +site framework, no build step. **Docs only; no code; CI stays green.** + +Voice/structure follow the parked **`vision-and-docs-spec.md`** (the project's north star, intentionally +not committed): assume nothing; nostalgia is _deletable seasoning_, never the spine; tiered onboarding; +second person, warm, encouraging. + +## Page map (this is the reviewable structure) +Landing is **`docs/README.md`** — GitHub auto-renders it when you browse to `docs/`, which is exactly right +for "renders on GitHub, no build step." Every path below matches the README's existing signposts exactly, +so there's **no link churn**. + +| Path | This cycle | Notes | +| --- | --- | --- | +| `docs/README.md` | **written** | Landing: orientation + TOC + **platform picker** front-and-center | +| `docs/what-is-this.md` | **written** | Zero-knowledge Microsoft Agent explainer (deep version of the README teaser) | +| `docs/glossary.md` | **written** | Pure content — plain-English terms | +| `docs/credits.md` | **written** | Pure content — gracious acknowledgments (expands the README list) | +| `docs/getting-started.md` | stub | README signposts it; gentle walkthrough lands later | +| `docs/install/windows.md` · `mac.md` · `linux.md` | stub | **Cycle 15** | +| `docs/characters.md` | stub | gallery + how to get `.acs` (**Cycle 17**) | +| `docs/voice/overview.md` · `setup.md` · `sourcing-components.md` | stub | overview + sourcing are README signposts | +| `docs/developers/overview.md` · `quickstart.md` · `api.md` · `providers.md` · `bundles.md` | stub | overview + quickstart are README signposts (**Cycle 16**) | +| `docs/faq.md` | stub | depends on later pages | +| `docs/troubleshooting.md` | stub | README signposts it | +| `docs/architecture.md` · `docs/roadmap.md` · `docs/legal-and-assets.md` | pre-existing | linked, not touched | + +After this cycle, **every** README `(docs/…)` link resolves to a real file (a stub or a written page) — no +more 404s from the front door. The `developers/` page is the nested **`docs/developers/overview.md`** (not +a flat `docs/developers.md`) to match the README signpost — decided with the PO. + +### Stub template (consistent across all 15 stubs) +Title → a `🚧 Coming soon (Cycle N / a later cycle)` note → a one-line "what it'll cover" → two interim +pointers (What is this? / main README) → a "← Back to the documentation home" link. Relative links are +depth-correct (`../` for nested pages under `install/`, `voice/`, `developers/`). + +## Written pages +- **`docs/README.md`** — friendly orientation; a Windows/macOS/Linux **platform picker** up top routing to + the install pages; then a table of contents grouped by intent (New here? · Get it running · The + characters · The real voice · For developers · Help · About). All relative `.md` links; one deletable + nostalgia aside. +- **`docs/what-is-this.md`** — Microsoft Agent from zero: what it was, how people met the characters + (Clippy & co.), the cast, what happened (removed in Windows 7), and what vivify does. Jargon defined + inline + linked to the glossary; nostalgia confined to a hook + one aside; ends by routing the reader + onward. +- **`docs/glossary.md`** — plain-English definitions (Microsoft Agent, `.acs`, animation, frame, sprite + sheet, balloon, TTS, SAPI/SAPI4, TruVoice, lip-sync/viseme, bundle, provider/fallback, Wine, Docker). +- **`docs/credits.md`** — the MS Agent team; DoubleAgent + Lebeau's decompiler (format references); + clippy.js (proof of concept); TETYYS/SAPI4 (the voice path); TMAFE (the archive). + +## Root README touch-ups (additive — no link churn) +- A top-level **📖 Documentation** pointer (→ `docs/README.md`) and a **"What is this?"** read-more link + (→ `docs/what-is-this.md`), per the PO. +- Accuracy: the two `glossary.md` mentions and the `credits.md` mention dropped their "_(coming)_" + qualifier now that those pages exist (same paths — not churn). + +## What is verified where +- **CI (this repo):** `pnpm -r typecheck && pnpm -r test && pnpm lint && pnpm format` stays green — no code + touched; Markdown is prettier-ignored by design. +- **Link audit (load-bearing):** a read-only pass confirms every relative `.md` link in `README.md` and all + `docs/**/*.md` resolves to a file that exists — zero broken links — and that every README `(docs/…)` + signpost now resolves. `code-reviewer` re-verifies, plus that the created paths match the README signposts + exactly. +- **Operator:** browse to `docs/` on GitHub → the landing renders with a working platform picker + TOC; + click through a few links to confirm navigation. + +## Non-goals (later cycles — stubbed only) +Per-platform install steps (Cycle 15); developer page content (Cycle 16); the deeper voice page bodies; +Playwright screenshots/GIFs + gallery thumbnails (Cycle 17). No code / `@vivify/core` / browser change. +See ADR-0026 for the structure decision. diff --git a/docs/decisions/0026-docs-skeleton.md b/docs/decisions/0026-docs-skeleton.md new file mode 100644 index 0000000..78e85c7 --- /dev/null +++ b/docs/decisions/0026-docs-skeleton.md @@ -0,0 +1,37 @@ +# ADR-0026: docs/ skeleton — in-repo Markdown that renders on GitHub, a README.md landing, a canonical page map matching the README signposts exactly, stubs everywhere with only the no-dependency pages written for real +Status: Accepted · Date: 2026-06-21 + +## Context +Cycle 13 (ADR-0025) polished the README front door and signposted a set of `docs/` pages as _(coming soon)_ — install guides, voice pages, developer docs, glossary, credits, FAQ — but **those targets didn't exist**, so every front-door "coming soon" link 404'd. This cycle builds the `docs/` backbone: the full folder layout + navigation later cycles fill in, plus the docs landing and the zero-assumptions "What is this?" explainer written for real. + +The binding voice/structure authority is the parked **Vision & docs spec** (the project's north star, intentionally **not committed** to the repo; pasted in-session when a docs cycle needs it). Its rules carry: assume nothing; nostalgia is _deletable seasoning_, never the spine; tiered onboarding; second person, warm, present tense. **Docs only; no code touched; CI stays green.** + +## Decision + +**1. `docs/` is in-repo Markdown that renders on GitHub — no site framework, no build step.** +The docs are plain `.md` files committed to the repo and read directly in the GitHub file browser; there is no Docusaurus/MkDocs/static-site layer and no compile/publish step. WHY: zero friction to author and to read — it works in the GitHub file browser today, and it honors the standing "no build step" constraint so a docs cycle never drags in tooling. + +**2. The landing page is `docs/README.md` (not `docs/index.md`).** +The docs home is `docs/README.md`. WHY: GitHub auto-renders a folder's `README.md` when you browse to that folder, so `docs/README.md` _is_ the docs home with no tooling — an `index.md` would just be another file the visitor has to click. The spec's "index.md or README in docs/" explicitly allows this, and the README path keeps the no-build-step promise honest. + +**3. The page map matches the README's existing signposts EXACTLY — canonical paths, no link churn.** +Every path in the map is the exact path the README already links. Notably the developer page is the **nested `docs/developers/overview.md`** (not a flat `docs/developers.md`), and the voice pages are nested under `docs/voice/` (`overview.md`, `setup.md`, `sourcing-components.md`). WHY: the README (ADR-0025) already links these exact paths; renaming a page later would break the front door it was built to feed. Decided with the PO when the Cycle 14 brief's flat path conflicted with the match-the-README rule — match-the-README wins. + +**4. Stub every page in the map now (consistent "coming soon" template); write only the no-dependency pages for real this cycle.** +Written for real now: `docs/README.md` (landing), `docs/what-is-this.md` (zero-assumptions explainer), `docs/glossary.md`, `docs/credits.md`. Everything else — `install/{windows,mac,linux}.md`, `characters.md`, `voice/*`, `developers/*`, `faq.md`, `getting-started.md`, `troubleshooting.md` — ships as a stub (title → `🚧 Coming soon` note → one-line "what it'll cover" → interim pointers → back-link, with depth-correct relative links). WHY: every README "(coming soon)" link resolves immediately — no 404s from the front door — and later cycles fill the bodies in place with zero link churn. Writing the install/dev/voice bodies now would be premature: they need screenshots, the demo, and per-platform testing that don't exist yet. + +**5. `what-is-this.md` is a new standalone page added to the spec's map.** +The spec treated "What is this?" as a README _section_; this cycle promotes it to a full page, with the README keeping a teaser + a "read more →" link to it. WHY: the deep zero-knowledge explainer (what Microsoft Agent was, the cast, what happened, what vivify does) is too long to live on the front door but is essential for the zero-assumptions audience — so it gets its own page rather than bloating the README. + +**6. Two additive root-README links + accuracy fixes only — no link churn.** +The root README gains a top-level **📖 Documentation** pointer (→ `docs/README.md`) and a **"What is this?"** read-more link (→ `docs/what-is-this.md`), and the `glossary.md`/`credits.md` mentions drop their "_(coming)_" qualifier now that those pages exist (same paths). WHY: discoverability from the front door without renaming or moving any existing link. + +## Consequences +- **The front door no longer 404s.** Every README `(docs/…)` signpost now resolves to a real file — a stub or a written page — and later cycles drop bodies into the stubbed paths with zero link churn. +- **This page map is now the canonical contract for later docs cycles.** Cycle 15 (install), Cycle 16 (developers), and Cycle 17 (screenshots/gallery) fill the stubbed pages in place at these exact paths; this ADR is the standing reference for why the layout is what it is and why the developer/voice pages are nested. +- **Verification boundary (CI vs operator).** CI proves `pnpm -r typecheck && pnpm -r test && pnpm lint && pnpm format` stay green with **no code touched** (Markdown is prettier-ignored by design), and a read-only **link-audit script** confirms all 109 relative `.md` links across `README.md` and `docs/**/*.md` resolve to a file that exists — zero broken links, every README signpost now landing. The **operator** verifies what CI cannot: browse to `docs/` on GitHub → the landing renders with a working platform picker + TOC, and click through a few links to confirm navigation works. +- **No third-party IP.** Docs-only Markdown; no `.acs` files, engine binaries, or Wine prefix are added. The repo's IP posture (ADR-0006) is preserved unchanged. + +## Related +- ADR-0025 — repo front door; adopted the parked Vision & docs spec as the binding authority and signposted these `docs/` paths as _coming_. This cycle makes those paths real. +- `docs/cycles/cycle-14-docs-skeleton.md` — the cycle this ADR records, including the full page-map table, the stub template, and the verified-where breakdown. diff --git a/docs/developers/api.md b/docs/developers/api.md new file mode 100644 index 0000000..9861af9 --- /dev/null +++ b/docs/developers/api.md @@ -0,0 +1,15 @@ +# Engine API reference + +> 🚧 **Coming soon.** This page lands in **Cycle 16**. It's a placeholder for now, so links +> pointing here already work — no dead ends. + +**What it'll cover:** the full `@vivify/core` API — every method on the Agent control. + +In the meantime: + +- 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)**. + +--- + +← Back to the **[documentation home](../README.md)** diff --git a/docs/developers/bundles.md b/docs/developers/bundles.md new file mode 100644 index 0000000..6c19d97 --- /dev/null +++ b/docs/developers/bundles.md @@ -0,0 +1,15 @@ +# Character bundles + +> 🚧 **Coming soon.** This page lands in **Cycle 16**. It's a placeholder for now, so links +> pointing here already work — no dead ends. + +**What it'll cover:** the `acs2bundle` CLI and hosting prebuilt characters on a CDN. + +In the meantime: + +- 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)**. + +--- + +← Back to the **[documentation home](../README.md)** diff --git a/docs/developers/overview.md b/docs/developers/overview.md new file mode 100644 index 0000000..56025bf --- /dev/null +++ b/docs/developers/overview.md @@ -0,0 +1,15 @@ +# For developers — overview + +> 🚧 **Coming soon.** This page lands in **Cycle 16**. It's a placeholder for now, so links +> pointing here already work — no dead ends. + +**What it'll cover:** the openness pitch — a framework-agnostic engine you can drop into anything. + +In the meantime: + +- 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)**. + +--- + +← Back to the **[documentation home](../README.md)** diff --git a/docs/developers/providers.md b/docs/developers/providers.md new file mode 100644 index 0000000..4ebd03c --- /dev/null +++ b/docs/developers/providers.md @@ -0,0 +1,15 @@ +# Writing a TTS provider + +> 🚧 **Coming soon.** This page lands in **Cycle 16**. It's a placeholder for now, so links +> pointing here already work — no dead ends. + +**What it'll cover:** how the voice providers work, and how to write your own (fallback vs authentic). + +In the meantime: + +- 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)**. + +--- + +← Back to the **[documentation home](../README.md)** diff --git a/docs/developers/quickstart.md b/docs/developers/quickstart.md new file mode 100644 index 0000000..c304251 --- /dev/null +++ b/docs/developers/quickstart.md @@ -0,0 +1,15 @@ +# Developer quickstart + +> 🚧 **Coming soon.** This page lands in **Cycle 16**. It's a placeholder for now, so links +> pointing here already work — no dead ends. + +**What it'll cover:** `npm i` to a talking character in about ten lines, copy-paste ready (browser voice by default). + +In the meantime: + +- 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)**. + +--- + +← Back to the **[documentation home](../README.md)** diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..a17dd3f --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,15 @@ +# 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. + +**What it'll cover:** the common questions — "Is this legal?", "Why is there no sound?", "Which characters work?" — answered plainly. + +In the meantime: + +- 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)**. + +--- + +← Back to the **[documentation home](README.md)** diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..8bb20a4 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,15 @@ +# 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. + +**What it'll cover:** the gentle, universal walkthrough — from zero to a character on your screen, then where to go next. + +In the meantime: + +- 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)**. + +--- + +← Back to the **[documentation home](README.md)** diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 0000000..9d436e6 --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,91 @@ +# Glossary + +Every technical term vivify's docs use, in plain English. New to all this? Read +**[What is this?](what-is-this.md)** first, then keep this page handy. + +### Microsoft Agent + +The late-1990s Microsoft technology that put animated cartoon characters on the Windows desktop — they +moved, talked, and showed a speech bubble. Microsoft retired it and removed it from Windows starting with +Windows 7. vivify is a faithful, browser-based revival. (Full story: [What is this?](what-is-this.md).) + +### Character (or "agent") + +One of those animated personalities — Genie, Merlin, Clippy, and so on. In vivify, you load a character and +then tell it to show itself, play animations, and speak. + +### `.acs` file + +The single file that holds one character — all of its pictures, animations, sounds, and settings bundled +together. (`.acs` stands for "Agent Character Storage.") It's Microsoft's format; **you supply your own** +`.acs` files (see [Legal & assets](legal-and-assets.md)) — vivify ships none. + +### Animation + +A named sequence the character can play — like `Greet`, `Wave`, or `Think`. Each character comes with its +own list of animations built into its `.acs` file. + +### Frame + +A single still picture in an animation. Play frames in sequence, at the right speed, and the character +appears to move — exactly like a flip-book. + +### Sprite sheet + +A single big image that packs many of a character's frames together in a grid. It's an efficient way to +store and load lots of small pictures at once. + +### Speech balloon + +The comic-strip-style bubble that shows the character's words while it talks. vivify draws each character's +balloon in its original style. + +### Text-to-speech (TTS) + +Software that reads written words aloud in a synthesized voice. When a vivify character "speaks," TTS is +what turns your text into sound. + +### SAPI / SAPI4 + +The **Speech API** — Microsoft's system for text-to-speech on Windows. **SAPI4** is the specific +(mid-1990s) version the original characters used. It's old Windows software, which is why the authentic +voice needs a small helper to run today (see [The authentic voice](voice/overview.md)). + +### TruVoice + +The specific text-to-speech engine (made by a company called Lernout & Hauspie) that produced the classic +character voices — including Genie's. It's the "authentic" voice vivify can use. + +### Lip-sync (and "viseme") + +**Lip-sync** is the character's mouth moving in time with the words it speaks. A **viseme** is the mouth +shape for a particular speech sound — the visual counterpart of a sound you hear. vivify lines these up so +the mouth matches the audio. + +### Bundle + +A web-ready version of a character that vivify can load quickly in a browser. vivify can run a raw `.acs` +file directly, or a pre-converted bundle (made with the `acs2bundle` tool — see +[Character bundles](developers/bundles.md)). + +### Provider (and "fallback voice") + +A **provider** is the source of a character's speech. vivify has two: the **authentic** provider (the real +TruVoice voice, via the helper service) and a **fallback** provider that uses your **browser's own +built-in voice**. The fallback means a character can talk with nothing extra installed; the authentic voice +is an optional upgrade. + +### Wine + +Free software that lets old Windows programs run on macOS and Linux. vivify uses it behind the scenes to +run the vintage Windows speech software for the authentic voice. (You don't interact with it directly.) + +### Docker + +A free tool that packages a program with everything it needs so it runs the same on any computer, with one +command. vivify uses it to run the voice helper (and the playground) without you having to install a pile +of parts by hand. + +--- + +← Back to the **[documentation home](README.md)** diff --git a/docs/install/linux.md b/docs/install/linux.md new file mode 100644 index 0000000..64c3d62 --- /dev/null +++ b/docs/install/linux.md @@ -0,0 +1,15 @@ +# Install 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. + +**What it'll cover:** step-by-step setup on Linux, with a screenshot for every major step. + +In the meantime: + +- 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)**. + +--- + +← Back to the **[documentation home](../README.md)** diff --git a/docs/install/mac.md b/docs/install/mac.md new file mode 100644 index 0000000..7a358dd --- /dev/null +++ b/docs/install/mac.md @@ -0,0 +1,15 @@ +# Install 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. + +**What it'll cover:** step-by-step setup on macOS, with a screenshot for every major step. + +In the meantime: + +- 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)**. + +--- + +← Back to the **[documentation home](../README.md)** diff --git a/docs/install/windows.md b/docs/install/windows.md new file mode 100644 index 0000000..d164913 --- /dev/null +++ b/docs/install/windows.md @@ -0,0 +1,15 @@ +# Install 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. + +**What it'll cover:** step-by-step setup on Windows, with a screenshot for every major step. + +In the meantime: + +- 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)**. + +--- + +← Back to the **[documentation home](../README.md)** diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..769236d --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,15 @@ +# 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. + +**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). + +In the meantime: + +- 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)**. + +--- + +← Back to the **[documentation home](README.md)** diff --git a/docs/voice/overview.md b/docs/voice/overview.md new file mode 100644 index 0000000..efa6662 --- /dev/null +++ b/docs/voice/overview.md @@ -0,0 +1,15 @@ +# The authentic voice — overview + +> 🚧 **Coming soon.** This page lands in **a later cycle**. It's a placeholder for now, so links +> pointing here already work — no dead ends. + +**What it'll cover:** what the "authentic voice" is, in plain language, and why it runs in a small background helper. + +In the meantime: + +- 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)**. + +--- + +← Back to the **[documentation home](../README.md)** diff --git a/docs/voice/setup.md b/docs/voice/setup.md new file mode 100644 index 0000000..078d0c8 --- /dev/null +++ b/docs/voice/setup.md @@ -0,0 +1,15 @@ +# Setting up the authentic voice + +> 🚧 **Coming soon.** This page lands in **a later cycle**. It's a placeholder for now, so links +> pointing here already work — no dead ends. + +**What it'll cover:** the full, hand-held walkthrough for the TruVoice + Wine + Docker voice service, per platform. + +In the meantime: + +- 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)**. + +--- + +← Back to the **[documentation home](../README.md)** diff --git a/docs/voice/sourcing-components.md b/docs/voice/sourcing-components.md new file mode 100644 index 0000000..b2d4413 --- /dev/null +++ b/docs/voice/sourcing-components.md @@ -0,0 +1,15 @@ +# Where to get the voice components + +> 🚧 **Coming soon.** This page lands in **a later cycle**. It's a placeholder for now, so links +> pointing here already work — no dead ends. + +**What it'll cover:** a friendly, consumer-focused guide to the free speech components you supply yourself. + +In the meantime: + +- 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)**. + +--- + +← Back to the **[documentation home](../README.md)** diff --git a/docs/what-is-this.md b/docs/what-is-this.md new file mode 100644 index 0000000..f7cd9de --- /dev/null +++ b/docs/what-is-this.md @@ -0,0 +1,87 @@ +# What is this? + +Let's start from zero. No background needed. + +> _Before "Agent" had anything to do with AI… there were little cartoon helpers who lived on your +> computer._ + +## The short version + +**vivify brings back the animated cartoon characters that used to live on the Windows desktop in the late +1990s — and runs them right in your web browser.** They move, they gesture, they talk out loud, and they +show a little speech bubble with their words. vivify recreates them faithfully: the real pictures, the real +animations, even their original voices. + +That's it. The rest of this page fills in the story, in case the words "Microsoft Agent" don't ring a bell +— and for a lot of people, they won't. + +## What was Microsoft Agent? + +Back in the late 1990s, Microsoft made a technology called **Microsoft Agent**. It put small animated +characters on your screen — not stuck inside one window, but right there on your desktop, on top of +everything else. + +These characters could: + +- **Move around** the screen and play little animations — waving, thinking, pointing, doing a trick. +- **Talk out loud**, using a computer-generated voice (this is called **text-to-speech**, or + [TTS](glossary.md) — software reading words aloud). +- **Show a speech balloon** with the words they were saying, like a comic-strip bubble. + +The idea was that a friendly character could guide you through software, react to what you were doing, or +just keep you company while you worked. + +> 💾 **Remember when…** a tiny cartoon would pop up while you were writing a letter and cheerfully ask if +> you needed help? For a whole generation, _that_ was the future. This brings that feeling back. + +## How you probably met them + +If you used a Windows computer around then, you almost certainly ran into one of these characters — even if +you never knew the technology behind them had a name. + +The most famous was **Clippy**, the bouncing paperclip in Microsoft Office who offered (constant, +unsolicited) help. But there was a whole cast: + +- **Genie** — a blue genie who appeared from a puff of smoke. +- **Merlin** — a wizard. +- **Peedy** — a green parrot. +- **Robby** — a robot. +- …and many more, including characters that fans made themselves. + +Each character lived in a single file — a **`.acs` file** (see the [glossary](glossary.md)) — that held all +of its pictures, animations, and sounds in one place. + +## What happened to them? + +Tastes changed. Clippy became a punch-line, the characters started to feel dated, and Microsoft moved on. +The technology was officially retired and **removed from Windows starting with Windows 7** (released in +2009). After that, the characters simply… stopped working. The files were still out there, but nothing +modern could run them. + +## What vivify does + +**vivify brings them back — faithfully — and runs them in a web browser**, so you don't need an old version +of Windows (or any special software just to look at one). + +It reads the original `.acs` character files and: + +- draws and animates the character exactly as it was, +- shows its classic speech balloon, and +- can even speak in the character's **original synthesized voice**, with its mouth moving in time with the + words (that mouth-matching is called **[lip-sync](glossary.md)**). + +"Faithfully" is the whole point. This isn't a cartoon _inspired by_ the originals — it's the real pixels, +the real animations, and the real voice, brought forward to today's web. + +## Where to next + +- **Want to see one move?** The [main README](../README.md) shows you how to run the playground in about a + minute. +- **Ready to set it up properly?** Pick your platform from the [documentation home](README.md) → + Windows · macOS · Linux. +- **Curious about the cast?** See **[Characters](characters.md)**. +- **Hit a word you didn't know?** The **[Glossary](glossary.md)** explains every term in plain English. + +--- + +← Back to the **[documentation home](README.md)**