asterism-games 0.17.1 → 0.19.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74d2dd1c8e013edfbce9943fa6a725a5173f5acfdaabbc42d93907759fd287b4
-  data.tar.gz: e8325208b814ef8e5e7a1d98286c828c287977f8698f1ccf049fd8a6917a4a04
+  metadata.gz: d10ded9e6550829d2169bb7be24ba662f11d69cec3eaf0fe676923104aa44727
+  data.tar.gz: '039b615f91c53f50c6bb10500b4e9516c7893bd213af57d1f7823c2bc67e84f5'
 SHA512:
-  metadata.gz: 36982adb8c6655a83e6f5a007647f1fa814ad9719d6d4f92ceebee2e18131c5297b42576c24692ed8e388afa42f8a62b186a264bd1bec7a2d696565f5f03d74c
-  data.tar.gz: 2102d3e914d962b470008e8ffce3b8d4366243aa5962b0b124f91e5fbdf993cd36e49e97af735c8f861e412465ac3d0af8b93c777ae5c3133e3b4356d1d3d48d
+  metadata.gz: c2571c2374914e2f9bb3d299e0482cd3f2f43b9c6ebe7fb4f5423b5c37c121cd5b06c06eb058ee91ecb5b05ddd0d6db22ce89e9b8b06eaf40cd3ab6ac6081f65
+  data.tar.gz: 260165d7df98b105ec8070f0c850d80f783b220cf4cf819c3a17de189c0ed7b0ccb78f43dc7ce29fe8f31f08aa4d4793c0eca1a2e600a265e52c61c67833852e

data/CHANGELOG.md

@@ -3,6 +3,105 @@
 Versions before 0.11.1 are noted in the README where each feature is
 described ("games 0.10.0" and the like).
 
+## 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
+  on `asterism/<node>/spectate/<table>/state` (a room's table as
+  `room<slot>-<table>`), a key outside the players' role
+  (`asterism/*/games/**`) and outside every room, for a console's
+  spectators and viewers and for the asterism gem's command line and MCP
+  bridge. The framework's `Game#spectate_view` (nil by default: nothing
+  is put) and `Game#spectate_delay_ms`; the host takes the view when it
+  puts the state, keeps it for the delay and puts each one in order, and
+  puts the last one again every 5 s. A room's host puts its tables' views
+  on a second connection of its own (the host's own certificate, no
+  namespace), never into the room; with a slot's certificate (a console
+  before 0.3.0) nothing. The application `spectate` is on the network (a
+  liveliness token) while the host puts.
+- The mahjong table's spectate view: the table in words as `look` gives
+  it, with every seat's hand and drawn tile (the hands a spectator member
+  sees); never the wall, the ura dora, an indicator not turned yet, a node
+  or a token. Held for the table's spectator delay (none by default).
+  Othello and the drawing board put nothing.
+- The console's role `games-host` needs two more lines for it (Read and
+  write `asterism/${node}/spectate`, `asterism/${node}/spectate/**`); the
+  console's docs/rooms.md has them and the `spectator` role. Without them
+  the router drops the puts and nothing else changes.
+- The host's last log line counts the spectate puts and their largest
+  size apart from the players' messages.
+
 ## 0.17.1
 
 - `bin/othello-tty` is gone: `asterism-games play othello` is the same

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
@@ -512,6 +515,84 @@ the host offers: its money of the day (`usd`), the limit it stops at
 - **Size.** Five tables take about 300 bytes (the largest put is in the
   log's `largest message` with the others).
 
+## Spectate
+
+A table can also be watched from outside it, with what the players do not
+see of each other (games 0.18.0): the host puts a game's spectate view on
+a key no player's role reads and no room reaches, for an admin, a
+spectator's row of the console, or an AI assistant that only looks (the
+asterism gem's command line and MCP bridge). The mahjong table puts the
+four hands there; othello and the drawing board put nothing (they hide
+nothing: their state is the whole game).
+
+- **The key.** `asterism/<node>/spectate/<table>/state`: the host's node,
+  the application `spectate` (not the host's `games`, so the players' role
+  `asterism/*/games/**` does not match it), and the table. A room's table
+  is `room<slot>-<table>` there (`asterism/games/spectate/room01-mahjong1/state`),
+  so the rooms' tables and the permanent ones never meet. The value is
+  MessagePack, like the state.
+- **Outside the rooms.** Every key a room's host writes on its own
+  connection gets the room's namespace (`room/<slot>/...`), which every
+  seat of the room reads whole. So a room's host opens a second connection
+  of its own for the spectate keys, with its own certificate and without
+  the namespace: the key is then on the registered side, where the seats'
+  rules do not reach. It does so only with the host's own certificate (a
+  console from 0.3.0 lists the host in `rooms.json`'s `"hosts"`); with the
+  slot's certificate of an older console it puts nothing (that
+  certificate is the room's). The permanent tables' host and a host of its
+  own put on their one connection.
+- **What the mahjong table puts.** The table in words, as `look` gives it
+  ("Playing from a program") to a member without a seat, with each seat's
+  `hand` and `drawn` tile, the same four hands a spectator member's view
+  has (`sh`, `sd`): the seats (name, kind, wind, score, riichi, river,
+  melds, hand count, hand, drawn), the round (wind, number, honba, riichi
+  sticks, dealer, wall left, turn, phase), the dora indicators turned so
+  far, the last discard, the result and the final ranks, the rules, and
+  `delay_s`. Never the wall, the ura dora, an indicator not turned yet, a
+  member's node or token (`test/test_spectate.rb` looks for them):
+
+  ```
+  games/spectate/mahjong1/state
+  {"table":"mahjong1","status":"play","sv":212,
+   "seats":[{"seat":0,"name":"CPU1","kind":"cpu","score":21000,"wind":"north","riichi":false,
+             "river":["2z","4z","5z","1m",...],"melds":[{"type":"pon","tiles":["7z","7z","7z"],"from":1}],
+             "hand_count":10,"hand":["7m","7m","2p","3p","3p","4p","4p","5s","6s","7s"],"drawn":null}, ...],
+   "round":{"wind":"east","number":2,"honba":0,"riichi_sticks":1,"dealer":1,"wall_left":19,"turn":3,"phase":"discard"},
+   "dora_indicators":["9p"],"last_discard":{...},"rules":{...},"delay_s":0}
+  ```
+- **The delay.** The table's spectator delay ("Spectators": the setting
+  `spectator_delay_minutes`, or the owner's choice in the lobby; none by
+  default). The host takes the view when it puts the state (after a change,
+  and every 5 s), keeps each one in order and puts it once it is the delay
+  old, each in turn: what is put is what the table was the delay ago,
+  never sooner, also across a round's end or when the delay is chosen
+  again (a shorter delay lets out what is old enough at once). A host
+  started again starts with nothing kept (nothing is put for the delay).
+  At most 8 MB is kept per table; past that the oldest is dropped (never
+  shown rather than shown early). The last one put is put again every
+  5 s, so a new subscriber has it within that.
+- **Who reads it.** The console's docs/rooms.md, "Watching the tables
+  from outside": the host's role `games-host` needs
+  `asterism/${node}/spectate` and `asterism/${node}/spectate/**` in "Read
+  and write" (without them the router drops the puts, and nothing else
+  changes); a role `spectator` (Read `asterism/*/spectate` and
+  `asterism/*/spectate/**`, Watch `asterism/**`) reads them with the
+  command line, and the `viewer` role (Read `asterism/**`) with the
+  command line and the MCP bridge. The players' role `games` and the
+  rooms' seats do not reach them.
+- **Looking.** With the asterism gem's command line (asterism 0.10.0's
+  `object` commands): `asterism object echo 'games/spectate/*' --credentials
+  spectator.tar` (each put as it comes; `-o json` a line each), `asterism
+  object get games/spectate/mahjong1 --credentials viewer.tar` (the next
+  one). The MCP bridge (`asterism mcp --credentials viewer.tar`):
+  `asterism_values` with the pattern `games/spectate/*/state`. The bridge
+  subscribes to `asterism/**`, which a `spectator` row may not, so it
+  needs the viewer role. The host's application `spectate` is on the
+  network (a liveliness token) while it puts, so the values show as an
+  application that is there.
+- **Writing a game.** `spectate_view(now)` (nil, the default: nothing) and
+  `spectate_delay_ms` (0) of `AsterismGames::Game`.
+
 ## Writing a game
 
 A game is two classes on the framework: the table (`AsterismGames::Game`:
@@ -591,6 +672,7 @@ What the framework gives a game:
 | `changed`, `dirty?`, `unsaved?` | a change to save and put; a change only one member's view shows (`@unsaved = true`) is saved, not put |
 | `to_saved` / `restore` / `resume_clock`, `SAVE_FORMAT` | the saved form (one JSON file per table, `state_dir/<table>.json`, written to a temporary file and renamed); a state of another format is not read. Times are saved as the time left and resumed with the host's clock |
 | `tell(sub, value)`, `SAVE_HOLD_MS` | more than the state: the host puts `value` on `asterism/<node>/<app>/<table>/<sub>` on its next step, in the order told, before the state (the board's strokes). A game that changes many times a second writes its saved state at most once per `SAVE_HOLD_MS` (the host writes what is held when it stops) |
+| `spectate_view(now)`, `spectate_delay_ms` | what the host puts on `asterism/<node>/spectate/<table>/state` for those who watch from outside the table ("Spectate"), held for the delay; nil (the default): nothing. It may hold what the players do not see of each other, never what nobody knows yet |
 | `summary(now)` | the counts the status shows (`st`, `members`, `humans`, `cpus`, `away`, and the game's own): no names, no nodes, no tokens. `busy` (`bin/asterism-games status --idle`) is `humans - away` |
 | `settings`, `tables`, `screens`, `DEFAULTS` | the table keys of the settings file and the environment, the tables a host serves by default, the table apps that get the tables in a room, the table's options |
 
@@ -758,6 +840,10 @@ hand.
   CPU) or every 20 s (a person) does not change how far behind the
   spectators are. A host started again starts the delay over (the past is
   not saved).
+- **From outside the table.** The same four hands, in words and as old
+  as the spectators' view, go on `asterism/<node>/spectate/<table>/state`
+  for a console's spectators and viewers ("Spectate"), a key the players
+  cannot read.
 - **The default is no delay.** The spectators see the hands as they are:
   good for watching a game, and for an audience in the same room. A seated
   player who joins the same table from a second screen sees the others'
@@ -1380,6 +1466,290 @@ Typed (in a pipe or a file each line; on a terminal after `:`):
 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
@@ -1818,6 +2188,41 @@ 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
+  give their hosts, the mahjong view (the four hands, no token, node, wall
+  or ura dora), a CPU game on the host, the delay (0, and 3 s across a
+  round's end, in order, never sooner), a room's table on the connection
+  outside the room only, and the last put again after 5 s.
 - `test_play_commands.rb`: `--commands "sit,cpu,start"` against a table
   in this process: they wait for the lobby when a game is going on as
   the client joins (and then sit, fill and start), the owner's wait for
@@ -2004,4 +2409,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.17.1
+0.19.1

data/bin/asterism-games

@@ -13,6 +13,9 @@
 #                                               # --idle: exit 0 when nobody sits at a table
 #   bin/asterism-games play <game> [options]    # play at a table in this terminal (othello,
 #                                               # mahjong; README "Playing in a terminal")
+#   bin/asterism-games commentate <game> [options]
+#                                               # watch a table in a browser with commentary
+#                                               # (mahjong; README "Commentary")
 #   bin/asterism-games help                     # this text (also --help, -h)
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 
@@ -26,6 +29,8 @@ USAGE = <<~TEXT
                                                          (--idle: exit 0 when nobody sits at a table)
     asterism-games play <game> [options]                 play at a table in this terminal
                                                          (othello, mahjong; play --help for the options)
+    asterism-games commentate <game> [options]           watch a table in a browser, with commentary in
+                                                         captions and voice (mahjong; commentate --help)
     asterism-games help                                  this text (also --help, -h)
 TEXT
 
@@ -36,6 +41,9 @@ when "help", "--help", "-h"
 when "play"
   require "asterism_games/play"
   exit AsterismGames::Play.main(ARGV.drop(1))
+when "commentate"
+  require "asterism_games/commentate"
+  exit AsterismGames::Commentate.main(ARGV.drop(1))
 when "status"
   nil
 else