asterism-games 0.18.0 → 0.19.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8555b735e1a25aff6167fe382f450dd367c4c6d81d13497c932265cf3a61a5f4
-  data.tar.gz: 5185c71e72d56963cebb26d480bf647763dd51156a0285db1104f6a9f600ae22
+  metadata.gz: d10ded9e6550829d2169bb7be24ba662f11d69cec3eaf0fe676923104aa44727
+  data.tar.gz: '039b615f91c53f50c6bb10500b4e9516c7893bd213af57d1f7823c2bc67e84f5'
 SHA512:
-  metadata.gz: 48a9fc1196c4f3fb5b2b2b8cf8c9f3c4f0682a4b1beee018ec0518c2c131068c5113ccb309d008f97a8ce479dd2ba994a2e268b5bcd50869bca5ee692144a030
-  data.tar.gz: 8227908a95b02825a6e53ba1c1d75d9008f33b802fca25c82b41c03b0194b3d58e3f7c317ab3e6df7f770140b9a34410467ec3c0ea0a2be189ddc56ffdabca5b
+  metadata.gz: c2571c2374914e2f9bb3d299e0482cd3f2f43b9c6ebe7fb4f5423b5c37c121cd5b06c06eb058ee91ecb5b05ddd0d6db22ce89e9b8b06eaf40cd3ab6ac6081f65
+  data.tar.gz: 260165d7df98b105ec8070f0c850d80f783b220cf4cf819c3a17de189c0ed7b0ccb78f43dc7ce29fe8f31f08aa4d4793c0eca1a2e600a265e52c61c67833852e

data/CHANGELOG.md

@@ -3,6 +3,78 @@
 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

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
@@ -1463,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
@@ -1901,6 +2188,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 +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.18.0
+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

data/lib/asterism_games/ai.rb

@@ -380,6 +380,70 @@ module AsterismGames
       end
     end
 
+    # A line an AI said (the commentary's one-liners, README "Commentary",
+    # "The AI's one-liners"): its text, the tokens as the API counted them
+    # ({"in", "out", "cache_write", "cache_read"}), how long it took and
+    # why it stopped (the API's stop_reason, e.g. "end_turn").
+    Said = Struct.new(:text, :tokens, :ms, :stop, keyword_init: true)
+
+    # Claude asked for a short line of free text (the commentary's
+    # one-liners): the fixed part as the system prompt (cached, so the
+    # calls after the first read it from the cache), the changing part as
+    # the user's message, the answer the text itself. One try, no retries:
+    # a line that comes late is worth nothing. The anthropic gem is
+    # loaded here, only when there is a key (it is not a dependency).
+    #
+    # Thinking is off and effort low: the answer is one or two sentences
+    # of 40 characters, and with adaptive thinking Haiku 5.5 spent up to
+    # 600 output tokens and 7 s thinking on an open question (the quiet
+    # scene). Off is accepted at effort low to high; the request has no
+    # tools and no structured output, so none of its limits applies.
+    # MAX_TOKENS fits two sentences of 60 characters (about 100 tokens)
+    # twice over; an answer cut there is dropped, its stop reason logged.
+    class Commentator
+      MAX_TOKENS = 200
+      THINKING = { type: :disabled }.freeze
+
+      attr_reader :model
+
+      def initialize(key, model:, effort: "low", base_url: nil)
+        require "anthropic"
+        kw = { api_key: key, max_retries: 0 }
+        kw[:base_url] = base_url if base_url
+        @client = ::Anthropic::Client.new(**kw)
+        @model = model
+        @effort = effort
+      end
+
+      def say(system:, user:, timeout: 8)
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        msg = @client.messages.create(
+          model: @model.to_sym,
+          max_tokens: MAX_TOKENS,
+          system_: [{ type: "text", text: system, cache_control: { type: "ephemeral" } }],
+          thinking: THINKING,
+          output_config: { effort: @effort.to_sym },
+          messages: [{ role: "user", content: user }],
+          request_options: { timeout: timeout }
+        )
+        u = msg.usage
+        tokens = { "in" => u.input_tokens.to_i, "out" => u.output_tokens.to_i,
+                   "cache_write" => u.cache_creation_input_tokens.to_i, "cache_read" => u.cache_read_input_tokens.to_i }
+        stop = msg.stop_reason.to_s
+        raise TokenError.new("claude: refused (stop_reason refusal)", tokens) if stop == "refusal"
+        unless %w[end_turn stop_sequence].include?(stop)
+          raise TokenError.new("claude: cut (stop_reason #{stop}, out #{tokens['out']})", tokens)
+        end
+        text = msg.content.select { |b| b.type == :text }.map(&:text).join
+        Said.new(text: text, tokens: tokens, stop: stop,
+                 ms: ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).round)
+      rescue ::Anthropic::Errors::APIStatusError => e
+        raise Error, "claude: HTTP #{e.status} #{e.class.name.split('::').last}"
+      rescue ::Anthropic::Errors::APIConnectionError => e
+        raise Error, "claude: #{e.class.name.split('::').last}"
+      end
+    end
+
     # A failure after the API counted tokens (they still cost).
     class TokenError < Error
       attr_reader :tokens