asterism-games 0.18.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8555b735e1a25aff6167fe382f450dd367c4c6d81d13497c932265cf3a61a5f4
-  data.tar.gz: 5185c71e72d56963cebb26d480bf647763dd51156a0285db1104f6a9f600ae22
+  metadata.gz: 0a35db1346246e5d20505026e701fef357536cc75fa53f22bf47878398fb01c3
+  data.tar.gz: 79c4c46763e2104c3e4d03ba521327e9ceb5fa77fc74521cec6041eb3ca48b89
 SHA512:
-  metadata.gz: 48a9fc1196c4f3fb5b2b2b8cf8c9f3c4f0682a4b1beee018ec0518c2c131068c5113ccb309d008f97a8ce479dd2ba994a2e268b5bcd50869bca5ee692144a030
-  data.tar.gz: 8227908a95b02825a6e53ba1c1d75d9008f33b802fca25c82b41c03b0194b3d58e3f7c317ab3e6df7f770140b9a34410467ec3c0ea0a2be189ddc56ffdabca5b
+  metadata.gz: 2b31fdedf12d610dca0c8cbd4f1ae060b5b42eeab54dee46d62f0ced96d8895468b48e84db2eae2904489448329a19ef5888cf9cb2a514684c2610d4e0937d87
+  data.tar.gz: 9908df82204210223cecd09b651da9d12e3a27ee832433d0e57b74d4d895a7a9753c83c20b75cadfeff88ef94eb91f6564290be193b1e501a37ce209124b67d3

data/CHANGELOG.md

@@ -3,6 +3,115 @@
 Versions before 0.11.1 are noted in the README where each feature is
 described ("games 0.10.0" and the like).
 
+## 0.20.0
+
+- **Watch games** (README "Watch games"): the owner of a mahjong table
+  may start a game of CPUs and AI players only, and watch it with the
+  others at the table (and a commentary, `commentate mahjong`). The owner
+  need not be seated: a member that joins a table where nobody is seated
+  and there is no owner is the owner (`join`'s `"owner"`, the new `"mo"`
+  of the member's own view); once somebody sits the first seated is the
+  owner as before, so a game with people seated goes as it did. The new
+  method `watch(token)` starts it when the four seats are CPUs or AI
+  players, nobody is seated and at most one seat is Claude's (Jev may take
+  all four; `"human"`, `"ai limit"`, `"seats"`, `"not owner"` otherwise).
+  The lobby view's `"wc"` says whether it may start (1), is over the AI
+  limit (2) or not (0); views during it have `"wm" => 1` and the host's
+  `@status` `"watch" => true`. Nobody is seated, so the table's
+  abandoning does not apply; instead the game stops (unrecorded) when
+  every member has left. One game, then the lobby with the same seats.
+  The record is kept with `"watch" => true` (also on `records`' entries)
+  and counts in the stats for the CPU and the AI kinds only, never for a
+  person. The AI players' daily limits work as before.
+- **The game's AI decisions are each seat's own**: `ASTERISM_GAMES_AI_CALLS_PER_GAME`
+  (400) is now how many decisions each AI seat may ask in a game (mahjong
+  and othello, every game, watch games or not); a seat past it becomes a
+  CPU alone. Before, the seats of a game shared it, so a game with three
+  or four AI seats stopped them all part way through a tonpuu. A game's
+  most is now 400 times its AI seats; the daily limits are as before.
+- `play mahjong`: `W` (and the command `watch`) starts a watch game, for
+  the owner with or without a seat; `A` then a seat's number turns that
+  seat into a CPU, Claude, Jev and back (the kinds the lobby offers); the
+  owner's commands (`cpu`, `ai`, `watch`, `--commands`) work for an owner
+  without a seat; the lobby marks the owner among those watching and says
+  the AI limit when the seats are over it; a watch game is headed
+  `観戦対局`.
+- Family mruby's mahjong app (fmruby-core) has a `観戦で始める[W]` button
+  for the owner when the host says it may start (`"wc"`); with an older
+  host it is not shown.
+
+## 0.19.1
+
+- The commentary tells where to get VOICEVOX when it finds no engine:
+  the terminal says it is a free app installed and started apart from the
+  gem (with its home page), the page's bar says the same in Japanese, and
+  `commentate --help` and the README's "The voice" say it up front.
+
+## 0.19.0
+
+- **Commentary** (README "Commentary"): `asterism-games commentate
+  mahjong` watches a table from its spectate key (0.18.0) and shows it in
+  the browser: a small web server on `127.0.0.1` (HTTP and Server-Sent
+  Events by hand on `socket`, no new gem; port 7470 or the next free one),
+  a page that draws the table in a canvas with the hand-drawn tile sheets
+  of Family mruby's mahjong app, and commentary in Japanese made by rules
+  from what changed between two views (a round's start, the oorasu,
+  riichi and its waits, calls, a dora or red five discarded, a new dora,
+  the wall at 10, a tenpai, a win with its yaku and points, a draw, the
+  lead changing hands, the end), shown as captions and read by the
+  browser's voice (Web Speech API) in a queue that drops the old small
+  lines first. Space pauses, M silences, H hides the hands; `--public`
+  keeps the hands from the page altogether; `--json` gives the lines on
+  standard output; `--table`, `--namespace` (a room's tables), `--port`,
+  `--no-open`. It only reads (never joins or calls a table) and goes on
+  when the host leaves and comes back.
+- **The voice** (README "Commentary", "The voice"): the commentary speaks
+  with VOICEVOX on this machine (`--voicevox URL`, `VOICEVOX_URL`, default
+  `http://127.0.0.1:50021`), by default as ずんだもん (`--speaker`,
+  `--style`; the numbers looked up by name in `/speakers`). The fixed
+  phrases (riichi, the calls, ron and tsumo, the rounds, 満貫 to 役満, ...)
+  are WAV files made by the user's own engine from the gem's list
+  (`commentate/mahjong_voice.yml`) into
+  `$XDG_CACHE_HOME/asterism-games/voices/<speaker>-<style>/`, named by the
+  phrasing's digest (`asterism-games commentate voices --make`, and the
+  missing ones at the start; `voices --list` lists the characters). The
+  rest of each line is synthesised as it comes and served from the
+  command's web server, kept in a bounded cache. The page says it all in
+  one queue (the fixed phrase, then the line; captions as the voice
+  starts; the old small lines dropped first) and shows the credit
+  `VOICEVOX:ずんだもん`. ずんだもん's lines are in her tone (〜なのだ),
+  kept as a tone of the phrasings (`MahjongPhrases::TONES`). Without an
+  engine the browser's voice reads as before. The engine gets the speech
+  only (サンマン, 30フ 2ハン), with the words it misreads written out
+  (流局, 起家, 跳満: `MahjongPhrases::SPEECH_READ`). No sound is in the gem;
+  `net/http` only, no new gem.
+- **The AI's one-liners** (README "Commentary", "The AI's one-liners"):
+  at a riichi, a win, a draw, the lead changing hands, the oorasu, the end
+  and after a quiet minute, Claude (`claude-haiku-5-5` by default,
+  `--ai-model`) adds a short line after the fixed commentary, in the
+  voice's tone, marked AI on the page. At most one call every 20 s (8 s
+  for a scene bigger than the last one asked about: a win after a riichi),
+  one at a time, only while a page is open. A quiet minute is about one
+  topic the command picks (the lead, a dama tenpai with the hands shown,
+  the dora, the wall, the last discard). Thinking off, effort low,
+  `max_tokens` 200; a cut answer is dropped with its stop reason in the
+  log. The fixed part of the ask (the role,
+  the rules in short, the tone, the length, whether the hands may be
+  told) is cached; the table now and the lines that just came follow.
+  With `--public` or a page's H the AI gets no hand. An answer whose round
+  or phase is over, or that comes after 15 s, is dropped; on the page an
+  AI's line comes after the fixed ones and goes first when the voice
+  falls behind. The money is counted from the tokens (cache writes and
+  reads too) in `$XDG_STATE_HOME/asterism-games/commentary_ai_usage.json`
+  (`AI::Budget`), shown in the bar, and capped at `--ai-daily-usd`
+  (default 3 USD a day). `ANTHROPIC_API_KEY`; the anthropic gem stays
+  outside the gem's dependencies (loaded only with a key);
+  `ASTERISM_GAMES_AI_FAKE=1` tries it without one. `--ai off` turns it off.
+- The gem holds the page (HTML, JS, CSS) and the two tile sheets
+  `tiles_hand.bmp` and `tiles_river.bmp`, copied byte for byte from
+  fmruby-core; in the gem they are MIT (`TILES_LICENSE.txt`). The gem's
+  test checks they are there and unchanged.
+
 ## 0.18.0
 
 - **Spectate** (README "Spectate"): the host puts a table's spectate view

data/README.md

@@ -60,9 +60,10 @@ the console ("Permanent tables"; the server's setup: docs/install.md).
 | Path | What |
 |---|---|
 | `asterism-games.gemspec` | the gem: what it holds and needs ("The gem and the image") |
-| `bin/asterism-games` | the host (loads the framework and the games); `status`; `play <game>`, a table in this terminal ("Playing in a terminal"); `help` |
+| `bin/asterism-games` | the host (loads the framework and the games); `status`; `play <game>`, a table in this terminal ("Playing in a terminal"); `commentate <game>`, a table in the browser with commentary ("Commentary"); `help` |
 | `bin/mahjong-bots` | players without screens, for trying a mahjong table (one process each; not in the gem) |
 | `lib/asterism_games/play.rb`, `lib/asterism_games/play/` | the terminal clients ("Playing in a terminal"): the options, `othello.rb`, `mahjong.rb` with `mahjong_text.rb` (tiles as text, widths, reading the input) and `mahjong_screen.rb` (the screen); they need neither the framework nor riichi_engine |
+| `lib/asterism_games/commentate.rb`, `lib/asterism_games/commentate/` | `asterism-games commentate mahjong` ("Commentary"): the events and their words (`mahjong_events.rb`, `mahjong_phrases.rb`), the hub and the runner (`mahjong.rb`), the web server (`server.rb`), the voice (`voicevox.rb`, VOICEVOX's HTTP; `voice.rb`, the fixed phrases' files and the lines' sound; `mahjong_voice.yml`, the fixed phrases), the page and the tile sheets (`assets/`) |
 | `lib/asterism_games.rb` | the framework, without any game |
 | `lib/asterism_games/game.rb` | the base of a game: the registry, the members and tokens, who joins in a room, the views, the time, saving ("Writing a game") |
 | `lib/asterism_games/remote.rb` | the base of the exposed object: the methods and their numbers of arguments, the caller (`from:`), `join` / `mine` / `leave` |
@@ -89,7 +90,9 @@ the console ("Permanent tables"; the server's setup: docs/install.md).
 game host of your own: the framework, the two sample games that need
 nothing else (othello, the drawing board), `bin/asterism-games` (with
 `play`, the terminal clients of othello and mahjong: a mahjong table needs
-riichi_engine, its client does not). It depends on
+riichi_engine, its client does not; and `commentate`, a mahjong table watched
+in the browser with commentary, with the tile sheets of Family mruby's
+mahjong app). It depends on
 the asterism gem only (0.7.1 or later in
 0.x; what came after 0.7.1, such as `@status` and `on_app_join`, is used
 when there). Not in it: mahjong (`app/`, it needs the riichi_engine fork
@@ -473,7 +476,8 @@ asterism/games/games/@status
 
 `last` is the four in rank order as `[name, rank, score]`, by the names
 the table shows its members anyway (a table app shows them to whoever
-joins); it is there once a game has ended. The rooms' status file
+joins); it is there once a game has ended. During a watch game the
+table's entry has `"watch" => true` (games 0.20.0). The rooms' status file
 (`GET /status` of the rooms' host) stays counts only.
 
 `ais` counts the AI players' seats (they are counted in `cpus` too), and
@@ -698,6 +702,7 @@ connects again after 3 s; while a client of a router only reconnects
 | `stand` | token | `"ok"` or why not (lobby only) |
 | `cpu` | token, seat, on | the owner: a CPU into an empty seat (on) or out of it (a CPU or an AI player); seat -1 with on fills every empty seat; on as a name the lobby offers (`"claude"`, `"jev"`) puts that AI player in ("AI players"), `"no ai"` when it is not offered; on one seat that holds a CPU or an AI player of another kind, on turns it into the one asked for (games 0.12.1) |
 | `start` | token | the owner, once the four seats are taken and one is a member: the seats are drawn (who deals first) and the game starts |
+| `watch` | token | the owner: a watch game ("Watch games", games 0.20.0): the four seats CPUs or AI players, nobody seated, Claude in one seat at most; `"ok"` or why not (`"not owner"`, `"not waiting"`, `"seats"`, `"human"`, `"ai limit"`) |
 | `rule` | token, item, value | the owner, in the lobby: a local rule ("Local rules"); `"ok"` or why not (`"not owner"`, `"not waiting"`, `"no rule"`, `"value"`, `"no change"`) |
 | `view` | token, assist | the member's view (below), or `{"error" => "token"}`; assist: the help its screen shows (Assist, 0-3) |
 | `act` | token, sv, type, tiles | `"ok"`, or why not: `"token"`, `"not seated"`, `"stale"` (sv is not the current one), `"not offered"`, `"not playing"` |
@@ -709,8 +714,9 @@ connects again after 3 s; while a client of a router only reconnects
 
 - People join a table and wait in its lobby (`"st" => "wait"`): a member
   sits in a seat or watches. The first member who sat is the owner (when the
-  owner stands or leaves, the member seated longest takes over). The owner
-  fills empty seats with CPUs and starts. At the end of a game the owner's
+  owner stands or leaves, the member seated longest takes over). While
+  nobody is seated the owner may be a member without a seat (games 0.20.0,
+  "Watch games"). The owner fills empty seats with CPUs and starts. At the end of a game the owner's
   next (or `over_seconds`) brings the table back to the lobby with the same
   seats, for another game.
 - The node that calls is the caller in the call's key (`from:`, filled
@@ -970,6 +976,47 @@ going for everyone (the other away seats are played for as before). A
 table of CPUs only (`humans: 0`, the permanent spectator tables) is never
 abandoned.
 
+### Watch games
+
+A game of CPUs and AI players only, which the people at the table watch
+(games 0.20.0): the owner fills the four seats and starts it without
+sitting down, and a commentary (`commentate mahjong`, "Commentary") can
+follow it like any other table.
+
+- **The owner without a seat.** A member that joins a table where nobody
+  is seated and nobody is the owner is the owner (`join`'s `"owner"`, the
+  member's own view's `"mo"`). When somebody sits, the first to sit is the
+  owner as before: whenever a member is seated the role is where it always
+  was (the seated member who sat first, "Players that drop out"). An owner
+  who stands up with nobody else seated keeps the role; an owner who
+  leaves with nobody seated hands it to the member who joined first, of
+  those there. An older table app, which knows only `"ow"` (the owner's
+  seat), shows an owner without a seat as no owner, as it showed a lobby
+  without one before.
+- **Starting.** `watch(token)`, the owner, in the lobby: the four seats
+  are CPUs or AI players (`cpu`), no member is seated, and at most one seat
+  is Claude's (`WATCH_AI_MAX`: Claude 1, Jev 4). The lobby view's `"wc"`
+  tells the screens whether it may start (1), or the seats are all CPUs
+  and AI players but over the AI limit (2), or not (0); a host before
+  0.20.0 has no `"wc"`, and the screens offer no watch game then. The
+  seats are drawn as for `start`. The AI players' money is as for any
+  game ("AI players"): a kind past its day's limit becomes a CPU.
+- **During it.** Nobody is seated, so nobody is played for and the
+  table's abandoning does not apply ("Players that drop out"); the results
+  move on by themselves as at a table of CPUs (`result_seconds`), and the
+  end of the game after `over_seconds`. The members watch with the four
+  hands ("Spectators", the spectator delay too). Views have `"wm" => 1`
+  and the host's `@status` has `"watch" => true` for the table ("Status").
+  When every member has left the table (`leave`, or forgotten after being
+  away six times `away_seconds`) the game stops: back to the lobby, an
+  unfinished game not recorded. The log says `watch game started (...)`
+  and `watch game stopped: nobody at the table (not recorded)`.
+- **One game.** At the end the table goes back to the lobby with the same
+  seats; the owner starts another with `watch` again.
+- **Records.** The game is recorded as any other with `"watch" => true`
+  (in `records`' entries and in `record(id)`). Its seats count in the
+  stats for their kinds (CPU, Claude, Jev), never for a person ("Stats").
+
 ### Views
 
 A Hash (MessagePack); tiles are one byte each in binary strings (bin).
@@ -983,7 +1030,9 @@ A Hash (MessagePack); tiles are one byte each in binary strings (bin).
 | `sk` | the four seats: 0 empty, 1 a member, 2 a CPU (an AI player too) |
 | `ai`, `ak` | when an AI player sits: each seat's kind (`"claude"`, `"jev"`, `""` for the others); in the lobby, the AI players the owner may seat ("AI players") |
 | `aw` | the seats whose member is away, as bits |
-| `ow` | the owner's seat (-1: nobody seated) |
+| `ow` | the owner's seat (-1: nobody seated, or an owner without a seat) |
+| `mo` | the member's own view only: 1 when this member is the owner, seated or not (games 0.20.0, "Watch games") |
+| `wc`, `wm` | in the lobby, whether a watch game may start: 1 yes, 2 the seats are all CPUs and AI players but over the AI limit, 0 no; during a watch game `wm` 1 ("Watch games", games 0.20.0) |
 | `mb` | the members in the order they joined: `[name, seat (-1 none), flags (1 away, 2 owner)]` |
 | `r` | `[bakaze (0 east, 1 south, 2 west), kyoku, honba, riichi sticks, dealer seat, tiles left, seat to act, phase (0 draw, 1 discard, 2 calls, 3 end)]` |
 | `sc`, `ri` | the scores; riichi as bits |
@@ -1168,7 +1217,7 @@ assistant through `asterism mcp`).
 
 | Method | Arguments | Returns |
 |---|---|---|
-| `records` | from (optional, 0) | `{"records" => [...], "total", "next"}`: the games, newest first, from the from-th, as many as fit one message; `next` is the from of the next page (none: the end). Each: `id`, `at` (the host's local time, `"2026-10-18 21:05"`), `game` (`hanchan` / `tonpuu`), `names`, `ranks`, `scores` (in seat order) |
+| `records` | from (optional, 0) | `{"records" => [...], "total", "next"}`: the games, newest first, from the from-th, as many as fit one message; `next` is the from of the next page (none: the end). Each: `id`, `at` (the host's local time, `"2026-10-18 21:05"`), `game` (`hanchan` / `tonpuu`), `names`, `ranks`, `scores` (in seat order), `watch` (`true` for a watch game, "Watch games"; else absent) |
 | `record` | id | the game's head: `id`, `at`, `time` (Unix seconds), `table`, `game`, `rules` (as `look`'s), `names`, `kinds` (human / cpu / ai), `final` (`[[seat, rank, score, points x 10], ...]`), `reason` (as the view's `fr`), `rounds` (`[[wind, number, honba, kind, [four changes]], ...]`) |
 | `record` | id, round | round `round` (from 0) as below, with `id`, `round`, `of` (how many rounds), `part`, `parts` |
 | `record` | id, round, part | a round too big for one message comes in parts (`parts` > 1): part 0 has everything with the first moves, part k the moves from `move_from` on |
@@ -1328,7 +1377,9 @@ pipe or a file (and the tests) they read lines as before, and
 | `1`..`4` | the lobby: sit there (an empty seat or a CPU's) |
 | `S` | the lobby: stand |
 | `C` | the lobby, the owner: CPUs into the empty seats |
+| `A`, then `1`..`4` | the lobby, the owner: that seat's next player: an empty seat a CPU, a CPU the first AI player offered, an AI player the next one, the last back a CPU (games 0.20.0; another key gives it up) |
 | Enter | the lobby, the owner: start (four seats taken) |
+| `W` | the lobby, the owner (seated or not): a watch game, the four seats CPUs or AI players ("Watch games", games 0.20.0) |
 
 | Othello | |
 |---|---|
@@ -1457,12 +1508,297 @@ Typed (in a pipe or a file each line; on a terminal after `:`):
 | `cpu [1-4]`, `nocpu 1-4`, `ai 1-4 KIND` | the owner: CPUs into the empty seats (or one), a CPU out, an AI player in when the lobby offers one ("AI players") |
 | `tonpuu`, `hanchan`, `rule ITEM VALUE` | the owner: the game's length, any local rule ("Local rules") |
 | `start` | the owner: start |
+| `watch` | the owner, seated or not: a watch game ("Watch games", games 0.20.0); `--commands "cpu,ai 1 claude,watch"` from a client that does not sit |
 | `auto` | the client plays for you: wins when offered, passes calls, discards the drawn tile, OKs the results (again to stop) |
 | `tables`, `view`, `help`, `quit` | |
 
 The host's answers are shown in the table app's words (`今はできない`,
 `卓の主だけができる` ...).
 
+## Commentary
+
+(games 0.19.0) `asterism-games commentate mahjong` watches a mahjong table
+from outside, the way a sports broadcast does: it reads the table's
+spectate key ("Spectate", with the four hands), draws the table in a
+browser with the tiles of Family mruby's mahjong app, and comments on what
+happens in Japanese, as captions under the table and in a voice: a
+VOICEVOX character's (ずんだもん by default) when a VOICEVOX engine runs on
+this machine, else the browser's own (the Web Speech API; "The voice"
+below). It only reads: it never joins the table or calls it. CRuby and
+the asterism gem only; it runs on WSL and on macOS.
+
+```
+asterism-games commentate mahjong --router tcp/127.0.0.1:7447    # a host on this machine or the home network
+asterism-games commentate mahjong --credentials viewer.tar        # a console's network (a viewer's or a spectator's .tar)
+asterism-games commentate mahjong --credentials viewer.tar --namespace room/01   # a room's tables
+asterism-games commentate mahjong --public                        # for a stream: the hands never reach the page
+asterism-games commentate mahjong --json | tee commentary.jsonl   # the lines for another tool too
+```
+
+It starts a small web server on `127.0.0.1` (port 7470, the next free one
+when it is taken), prints the address and opens it in the browser (macOS
+`open`; WSL `wslview`, else Windows' `start`; elsewhere `xdg-open`).
+
+| Option | |
+|---|---|
+| `--router LOCATOR`, `--credentials FILE` | as `play` (with neither, `ASTERISM_ROUTER` / `ASTERISM_CREDENTIALS`, all or nothing; with nothing, `tcp/127.0.0.1:7447`) |
+| `--namespace PREFIX` | a room's tables: `room/01` shows `room01-<table>` (the spectate keys are outside the room, so the connection has no namespace) |
+| `--table TABLE` | the table to show first: `mahjong1`, `games/mahjong1` or `games/spectate/mahjong1`; without it, every table that puts its spectate key is offered and the first one shown |
+| `--node NODE` | the node ID (default `commentate-<host>-<pid>`, or the `.tar`'s name) |
+| `--port N` | the page's port (default 7470) |
+| `--public` | hide the hands: the views sent to the page lose `hand` and `drawn`, and no line tells a hand |
+| `--no-open` | do not open the browser |
+| `--json` | each line of commentary as a JSON line on standard output (`at`, `table`, `type`, `prio`, `text`; an AI's line has `type` `ai` and `ai: true`) |
+| `--voicevox URL` | the VOICEVOX engine (default `VOICEVOX_URL`, else `http://127.0.0.1:50021`) |
+| `--speaker NAME`, `--style NAME` | the VOICEVOX character and its style (default `ずんだもん`, `ノーマル`) |
+| `--ai on\|off` | the AI's one-liners (default `on`; they need `ANTHROPIC_API_KEY` and the anthropic gem; "The AI's one-liners") |
+| `--ai-model MODEL` | the model they ask (default `claude-haiku-5-5`) |
+| `--ai-daily-usd USD` | what they may cost a day (default 3); then the fixed commentary alone |
+
+- **The role.** The spectate keys are `asterism/<host>/spectate/<table>/state`.
+  On a console's network a `viewer` (Read `asterism/**`) or a `spectator`
+  (Read `asterism/*/spectate` and `asterism/*/spectate/**`) reads them; the
+  players' role `games` does not. On a plain zenohd anyone does.
+- **The page.** A bar of states on top (the table, the voice, the delay the
+  host puts on the table, a host that is not there), the table in a
+  canvas (the round, honba, riichi sticks, the wall and the dora
+  indicators; for each seat its wind, name, points, riichi, river with the
+  riichi tile sideways and the called tiles pale, hand and drawn tile,
+  melds; the seat to act framed), the captions below with the time of
+  each, the newest at the bottom. Two seats to a row in a wide window, one
+  in a narrow one (a phone). Keys: **Space** pauses (what comes meanwhile
+  is held and shown when it goes on), **M** turns the voice off and on,
+  **H** hides the hands on that page (backs instead of the tiles, and the
+  lines that tell a hand left out). A table that several hosts put is
+  chosen in the bar.
+- **The AI's one-liners.** Claude's short lines at the big moments,
+  marked AI, after the fixed ones; the bar shows the model and today's
+  money. "The AI's one-liners" below.
+- **The voice.** One queue on the page says the lines in turn, each
+  caption coming up as its voice starts; when the voice falls behind, the
+  old small lines are dropped (their captions still come up) and a win or
+  a big moment is said next. With VOICEVOX, a line plays its fixed phrase
+  first (リーチ, ポン, ロン, the round's name ...) and then the rest of it,
+  synthesised meanwhile; without, the browser reads the lines with a
+  Japanese voice when it has one (the bar says which voice, or that it has
+  none). Browsers play sound only after the page has been clicked once:
+  the page says so until then. "The voice" below.
+- **The commentary.** Made by rules from the difference between one view
+  and the one before (pure functions, `commentate/mahjong_events.rb` and
+  `mahjong_phrases.rb`, so the host can take them over later), each event
+  in two to three phrasings chosen at random, the big moments in strong
+  ones: the first look at the table, a round's start (the dealer and the
+  dora; the game's first; the oorasu, and the oorasu going on), a discard
+  of a dora or a red five, a call (チー, ポン, the kans), a new dora, the
+  wall at 10, riichi with its waits, a tenpai (from the hand, once a round
+  for each seat), a win with its yaku and points (満貫 and over: strong),
+  a draw with who was tenpai, an abortive draw, the lead changing hands,
+  the end with the ranks. The tiles and the yaku are read as a player
+  says them (サンマン, リーチ, タンヤオ). With the hands hidden (`--public`,
+  H) a tenpai is not said and a riichi is said without its waits.
+- **It does not stop.** A host that leaves (`on_leave`, or no put for 15 s)
+  is shown as gone and comes back with its next put; a new round or a new
+  game goes on as before. The delay of the table is the host's
+  ("Spectators"); the page shows it and adds none.
+- **The web server.** HTTP by hand on the standard library's `socket`
+  (no gem): the page, its script and style, the two tile sheets and
+  `/events`, a stream of Server-Sent Events (`status`, `state`, `line`)
+  that pushes the table and the commentary. It listens on `127.0.0.1`
+  only, answers GET (and HEAD) on those paths only, and refuses a request
+  whose Host is not `127.0.0.1` or `localhost`. The page loads nothing from
+  elsewhere.
+- **On a stream (OBS).** Add a Browser Source with the address
+  (`http://127.0.0.1:7470/`), 1280 x 720 or larger. `?obs=1` leaves out the
+  bar and the keys' line and makes the background transparent around the
+  captions; `?hands=0` hides the hands on that page, `?voice=0` silences
+  it, `?table=games/mahjong1` picks the table. Start the command with
+  `--public` when the stream must never show a hand. OBS's browser does not
+  always play the Web Speech voice into the stream: for the voice, capture
+  a browser window and the desktop's sound instead.
+- **The tiles.** `lib/asterism_games/commentate/assets/tiles_hand.bmp` and
+  `tiles_river.bmp` are the hand-drawn sheets of Family mruby's mahjong app
+  (fmruby-core's `flash/app/game/mahjong/`), copied byte for byte; the
+  browser reads the BMPs as they are and only makes their transparent
+  colour (magenta) transparent when it draws them. In this gem they are
+  under the MIT License like the rest of it, by the author's decision
+  (`TILES_LICENSE.txt` next to them).
+
+### The voice
+
+(games 0.19.0) The commentary speaks with VOICEVOX,
+a free Japanese speech synthesiser, when its engine runs on this machine;
+the default character is ずんだもん (style ノーマル). Nothing of its voice is
+in this gem: the gem holds the words (`commentate/mahjong_voice.yml`) and
+the code that has your VOICEVOX say them. **VOICEVOX is a separate app
+you install and start yourself** (https://voicevox.hiroshiba.jp/, free);
+without it the commentary still runs, with the browser's voice. When it
+finds no engine, the command says so on the terminal, with where to get
+VOICEVOX, and so does the page's bar.
+
+- **Finding the engine.** At its start the command asks
+  `GET /version` of `--voicevox URL` (default `VOICEVOX_URL`, else
+  `http://127.0.0.1:50021`). When nothing answers, the browser's voice
+  reads, as before, the terminal says where to get VOICEVOX, and the
+  page's bar says 「VOICEVOX が見つからない (無料のアプリ VOICEVOX を入れて
+  起動すると、ずんだもんの声になる): ブラウザの声で読む」.
+- **The fixed phrases** (リーチ, チー, ポン, カン, ロン, ツモ, the rounds'
+  names, 流局, 途中流局, 満貫 to 役満, オーラス, 逆転, 終局, 対局開始, and
+  「実況を始めます」 when the page is clicked) are WAV files, played at
+  once. The command makes the missing ones at its start (in the
+  background: a phrase not made yet is skipped), or
+  `asterism-games commentate voices --make` makes them all now (about 30
+  files, half a minute on a CPU engine). They go to
+  `$XDG_CACHE_HOME/asterism-games/voices/<speaker>-<style>/`
+  (`~/.cache/asterism-games/voices/ずんだもん-ノーマル/` by default) with a
+  `CREDITS.txt`; each is named by the digest of its phrasing, so a changed
+  list makes the changed ones again and removes the old. **The directory
+  can be deleted at any time**: it is made again.
+- **The rest of a line** is synthesised as the line comes (the engine's
+  `/audio_query` and `/synthesis`) while its fixed phrase plays, and
+  served to the page from the command's own web server at a temporary
+  address (`/voice/<digest>.wav`; only lines the command made, never a
+  text a page sends). A line that begins with its fixed phrase's word
+  leaves it out (ロン！ then 「CPU1、断么九 …」). The same line is
+  synthesised once while it is kept (200 lines and 64 MB at most, the
+  least recently used dropped first). A line the engine fails on is read
+  by the browser's voice.
+- **What the engine reads** is always a line's speech, never its caption:
+  the tiles, the yaku and the points as a player says them (サンマン,
+  リーチ, 30フ 2ハン), and the words VOICEVOX would read wrongly written
+  out (流局 リューキョク, 起家 チーチャ, 跳満 ハネマン;
+  `MahjongPhrases::SPEECH_READ`, used for the fixed phrases too). No user
+  dictionary is needed.
+- **Choosing a character.** `asterism-games commentate voices --list`
+  lists the engine's characters and their styles; `--speaker NAME
+  --style NAME` picks one by name (the engine's numbers are looked up,
+  never assumed; a name that is not there is answered with the ones that
+  are). ずんだもん speaks in her own tone: the lines and the fixed phrases
+  end in 〜なのだ (「リーチなのだ！」「満貫、8000点なのだ！」); any other
+  character speaks plainly. The tones are kept with the phrasings
+  (`MahjongPhrases::TONES`), with a note on how to ask an AI to speak so.
+- **The page** plays the sound itself (never the PC with `paplay` or
+  `afplay`), so a Browser Source in OBS carries it. **M** cuts the voice
+  (the captions go on). When VOICEVOX speaks, the page shows the credit
+  in its corner: `VOICEVOX:ずんだもん`.
+
+Running VOICEVOX:
+
+```
+# Windows (and WSL): install the VOICEVOX app on Windows and start it (its engine
+# listens on 127.0.0.1:50021). From WSL with networkingMode=mirrored (.wslconfig)
+# 127.0.0.1 reaches it; otherwise pass Windows' address:
+asterism-games commentate mahjong --voicevox http://$(ip route show default | awk '{print $3}'):50021
+
+# macOS: install the VOICEVOX app and start it; the default URL reaches it.
+
+# docker (Linux, WSL, macOS): the engine alone, CPU version
+docker run -d --name voicevox -p 127.0.0.1:50021:50021 voicevox/voicevox_engine:cpu-0.25.0
+asterism-games commentate voices --list
+asterism-games commentate voices --make            # optional: the commentary makes them at its start too
+asterism-games commentate mahjong --speaker 四国めたん --style ノーマル
+```
+
+The engine takes a gigabyte or two of memory; one line of commentary
+takes it about a second or two on a laptop's CPU.
+
+**VOICEVOX's terms, in short** (read the current terms of VOICEVOX and of
+your character before you publish anything; they can change):
+
+- The software and the voices it makes may be used free of charge,
+  commercially or not, **with a credit** naming the character, such as
+  `VOICEVOX:ずんだもん`. Each character has terms of its own on top of
+  VOICEVOX's (ずんだもん's: a credit where it can be found, in a video's
+  description or on screen; no use against public order, for political or
+  religious campaigns, for deception, and the like).
+- **When you stream or upload the commentary, put the credit in the
+  description too** (the page shows it in its corner).
+- Whoever you give generated voices to must follow the same terms, so
+  they cannot be mixed into an MIT package. That is why this gem ships no
+  sound: each user makes the files with their own VOICEVOX, and they stay
+  on that machine.
+
+### The AI's one-liners
+
+(games 0.19.0) At the big moments of a table Claude adds a short line of
+its own after the fixed commentary, in the same voice and tone (ずんだもん's
+〜なのだ with her voice), marked **AI** in the captions:
+「この待ち、山にまだ残ってるのだ。勝負はここからなのだ！」. It is also a
+small demonstration of an AI watching a table on the network and telling
+what it sees.
+
+```
+export ANTHROPIC_API_KEY=sk-ant-...          # your own key
+gem install anthropic                        # not a dependency of this gem
+asterism-games commentate mahjong            # Claude Haiku, at most 3 USD a day
+asterism-games commentate mahjong --ai-model claude-sonnet-5-5 --ai-daily-usd 1
+asterism-games commentate mahjong --ai off   # the fixed commentary alone
+```
+
+- **The key and the gem.** The key is `ANTHROPIC_API_KEY`; the anthropic
+  gem is loaded only when it is set, and is not a dependency of this gem.
+  Without a key the page's bar says 「AI: off (キーなし)」; with a key and
+  no gem, 「AI: off (anthropic の gem なし)」 and the command says to
+  `gem install anthropic`. `--ai off` turns them off.
+- **The model.** `claude-haiku-5-5` by default (`--ai-model`), asked with
+  thinking off at effort `low` and `max_tokens` 200 (two short sentences
+  with room; an answer cut there is dropped and the log says its stop
+  reason), one try with no retries, 8 s at most. Every call's line in the
+  log has its seconds, stop reason, tokens and money.
+- **When.** A riichi, a win (a mangan or more counts as bigger), a draw or
+  an abortive draw, the lead changing hands, the last round (オーラス),
+  the end; and a quiet minute in the middle of a round, about one topic
+  the command picks in turn (the leader's lead, a seat in tenpai without
+  riichi when the hands are shown, the dora, the wall left, the last
+  discard; never the same twice running). One call at a
+  time and **at most one every 20 s**, or every 8 s for a scene bigger
+  than the last one asked about (a win after a riichi, the end after a
+  win; the ranks: the end, a big win and the lead changing hands, a win
+  and the oorasu, a draw, a riichi, a quiet minute). A scene that comes
+  sooner waits (the biggest of those waiting, for 15 s at most) and is let
+  go when its round or phase is over. Calls are made only while a page is
+  open (or with `--json`): nobody watching, nothing is spent. A tonpuu of
+  four CPUs gets about two a round, and a line for its wins.
+- **What it is told.** A fixed part, the same to the byte every time and
+  cached (prompt caching: the calls after the first read it at a tenth of
+  the price): the commentator's role, mahjong's rules in short, the tone,
+  the length (40 characters, one or two sentences, the line only: no
+  preamble, quotes or emoji) and whether it may speak of the hands. Then
+  the table now (the round, honba, riichi sticks, the wall, the dora; each
+  seat's name, wind, points, riichi, melds and last discards; with the
+  hands shown, each hand and its waits; a win's yaku and points, the
+  ranks at the end), the scene, the fixed lines that just came, and its
+  own last lines (not to repeat itself).
+- **The hands hidden.** With `--public`, and while a page has **H** on,
+  the AI is not told the hands (nor the waits, nor who is tenpai): it
+  speaks from what everyone can see. A line made while the hands were
+  shown is not shown on a page that hides them.
+- **Late lines are dropped.** An answer that comes when its round or
+  phase is over, or more than 15 s after it was asked, is not said. On
+  the page an AI's line waits behind the fixed lines (its scene's own come
+  first; a round's start waits behind it), and is dropped when a new scene
+  comes before it is said (a riichi, a win, a draw), first when the voice
+  falls behind, and after 40 s in the queue.
+- **The voice.** The caption is the line as it came; the voice reads it
+  through the same readings as the fixed lines (`SPEECH_READ` and the
+  tiles: 三萬 サンマン, 流局 リューキョク).
+- **What it costs.** Counted from the tokens the API reports (input,
+  output, the cache's writes and reads) at the model's published price
+  (Haiku 5.5: 0.10 USD a million input tokens, 0.50 output, 0.125 a cache
+  write, 0.01 a cache read), in
+  `$XDG_STATE_HOME/asterism-games/commentary_ai_usage.json`
+  (`~/.local/state/...` by default; counts and money only, no words). The
+  bar shows today's money and the limit; when today's money reaches
+  `--ai-daily-usd` (default 3 USD) no call is made and the fixed
+  commentary goes on alone; the next day (local date) starts at 0. A
+  call costs about a hundredth of a cent with Haiku (some 1,000 cached
+  tokens, a few hundred new ones, a line out), so a tonpuu costs well
+  under a cent.
+- **Failures** (no answer in time, an error, a refusal) are one line in
+  the command's output and nothing is said; the key and the words are
+  never written out. `ASTERISM_GAMES_AI_FAKE=1` puts a fake in Claude's
+  place (no API is called; its money is counted apart, in
+  `commentary_ai_usage.fake.json`), to try the page without a key.
+
 ## Playing from a program
 
 The mahjong table also speaks to programs (games 0.10.0): an AI assistant
@@ -1538,9 +1874,12 @@ offered), and show the seat by its name (`Claude`, `Jev`, numbered when there ar
   reports, per day (the host's local date), in `state_dir/ai_usage.json`
   (shared by the rooms' hosts and the permanent tables; counts and money
   only). When today's total reaches `ASTERISM_GAMES_AI_DAILY_USD` (3.0) no
-  table offers an AI player any more and the seated ones become CPUs; a
-  game asks at most `ASTERISM_GAMES_AI_CALLS_PER_GAME` (400) decisions,
-  then its AI seats become CPUs. `bin/asterism-games status` prints the
+  table offers an AI player any more and the seated ones become CPUs; each
+  AI seat asks at most `ASTERISM_GAMES_AI_CALLS_PER_GAME` (400) decisions
+  in a game, then that seat becomes a CPU (games 0.20.0: the count is each
+  seat's own, so a game's most is 400 times its AI seats; before, the
+  seats of a game shared the 400 and every AI seat stopped together). A
+  tonpuu takes about 150-200 decisions a seat, a hanchan about twice that. `bin/asterism-games status` prints the
   day's decisions, tokens and money per kind; the host's `@status` has the
   totals (`ai_today`).
 - **A limit per kind** (games 0.15.0). `ASTERISM_GAMES_AI_DAILY_USD_CLAUDE`
@@ -1553,7 +1892,7 @@ offered), and show the seat by its name (`Claude`, `Jev`, numbered when there ar
   0.15.0. A value that is not a number of dollars (0 or more) is ignored,
   with a line in the log. The log says the limits at the start
   (`games: AI players: claude, jev (at most $10.0 a day for claude, $2.0
-  for jev, 400 decisions a game)`) and once for each kind that stops
+  for jev, 400 decisions a seat in a game)`) and once for each kind that stops
   (`today's limit for claude ($10.0) is reached`); a new day lets it play
   again. `ai_today` on `@status` then has `kinds` (README "Status").
 - **Prices.** USD per million tokens, settings with the published prices
@@ -1617,8 +1956,9 @@ game between two machines without a host is fmruby-core's
   "moves" => [{"n", "square", "turns", "text"}]}`; the answer is a move's
   `n`. One out of range, one that does not come in `ai_turn_seconds` (30 s)
   or a failure is played by the CPU, and the game goes on. When the day's
-  money is spent, or the game has asked `ASTERISM_GAMES_AI_CALLS_PER_GAME`
-  decisions, Jev's seat becomes the CPU. The table apps show Jev by its
+  money is spent, or the seat has asked `ASTERISM_GAMES_AI_CALLS_PER_GAME`
+  decisions in the game (each seat its own count, games 0.20.0), Jev's
+  seat becomes the CPU. The table apps show Jev by its
   name with `[AI]` and say when it is thinking; `dl` counts its time down.
 - Nothing in othello is hidden, so every member sees the same view: the
   table's view (the one the host puts on the state key) and `me`, the
@@ -1901,6 +2241,34 @@ ASTERISM_TEST_ROUTER=tcp/127.0.0.1:7447 bundle exec rake test   # also through a
   tonpuu game against three CPUs each to the end from scripted input
   (letters, tiles, calls, passes, OKs; `PLAY_TRANSCRIPT_DIR` keeps what
   they showed).
+- `test_commentate.rb`: `asterism-games commentate` (in `rake test:gem`
+  too): the waits of a hand (seven pairs, thirteen orphans, with melds),
+  the dora of an indicator, each event from views made by hand (a round's
+  start, the oorasu, riichi with its waits, calls and an added kan, a dora
+  and a red five discarded, the wall, a new dora, a tenpai once a round, a
+  big win and the lead changing hands, a draw, an abortive draw, the end)
+  and their words, a recorded tonpuu of four CPUs
+  (`test/fixtures/commentate_tonpuu.json.gz`) through the events and
+  phrases, nothing of a hand with the hands hidden, the hub (the pages'
+  frames, `--public`, `--json`, a page that opens late, a host that leaves
+  and comes back), the web server (the page, the sheets byte for byte,
+  404 / 405 / a foreign Host refused, 127.0.0.1 only, the events stream, a
+  port taken), the options and `--help`; with the table there, a CPU
+  round played here through the hub.
+- `test_commentate_voice.rb`: the commentary's voice (in `rake test:gem`
+  too), against a small VOICEVOX engine started in the test: a character
+  and a style by name (and the names offered when one is not there), the
+  synthesis, no engine (the browser's voice, nothing made), the fixed
+  phrases made once and named by their digest, made again when the list
+  changes (the old files removed), the cache directory, every clip a line
+  asks for in the list in both tones, a line synthesised once and kept
+  (the least recently used dropped, made again when asked), a failing
+  engine, the words a fixed phrase said left out of the line, ずんだもん's
+  tone (every phrasing, every line of the recorded game, the clips that
+  tell no hand), the hub's lines with their sound, the web server's
+  `/clip/` and `/voice/` (only what the list and the hub name), the
+  missing phrases made at the start, the options and `voices --list |
+  --make`.
 - `test_spectate.rb`: the spectate view (README "Spectate"; its
   framework part in `rake test:gem` too): nothing by default (othello, the
   board), the keys of the permanent tables and of a room, what the rooms
@@ -2094,4 +2462,7 @@ each result that long.
 
 ## License
 
-MIT (LICENSE).
+MIT (LICENSE). The tile sheets of the commentary page
+(`lib/asterism_games/commentate/assets/tiles_*.bmp`, the hand-drawn tiles
+of Family mruby's mahjong app) are under the MIT License in this gem too
+(`TILES_LICENSE.txt`).

data/VERSION

@@ -1 +1 @@
-0.18.0
+0.20.0