pairvoice 0.1.0__tar.gz

pairvoice-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "pairvoice",
+  "description": "pairvoice（ローカル要約・音声合成サーバー）と組み合わせて使う Claude Code プラグイン",
+  "owner": {
+    "name": "matzkoh"
+  },
+  "plugins": [
+    {
+      "name": "pairvoice",
+      "source": "./plugin",
+      "description": "Claude Code の応答をローカルの pairvoice で要約・音声化して読み上げる"
+    }
+  ]
+}

pairvoice-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,41 @@
+# v* のタグを push すると、studio をビルドしてから wheel と sdist を作り、PyPI に公開する。
+# PyPI 側には Trusted Publishing（matzkoh/pairvoice・release.yml・environment pypi）を登録してあり、
+# トークンは置かない
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+        with:
+          package_json_file: studio/package.json
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: "24"
+          cache: pnpm
+          cache-dependency-path: studio/pnpm-lock.yaml
+      # タグと pyproject の版がずれたまま公開すると、PyPI の版は取り消せない
+      - name: タグと版がそろっているか確かめる
+        run: |
+          version=$(uv version --short)
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "タグ $GITHUB_REF_NAME と pyproject の版 $version が違う" >&2
+            exit 1
+          fi
+      - run: pnpm install --frozen-lockfile
+        working-directory: studio
+      - run: pnpm build
+        working-directory: studio
+      - run: uv build
+      - run: uv publish

pairvoice-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.claude/worktrees/
+studio/node_modules/
+studio/web/node_modules/
+studio/web/dist/
+studio/web/.vitest/
+.superpowers/

pairvoice-0.1.0/CLAUDE.md

@@ -0,0 +1,21 @@
+# CLAUDE.md
+
+常駐サーバー（`src/pairvoice/`）・studio（`studio/`）・読み上げフック（`plugin/`）・メニューバー（常駐サーバーの子）の4つは、データの置き場所と HTTP だけを共有する。
+
+## 横断する規則
+
+- 実行して生まれるもの（プロンプト・辞書・コーパス・声のプロファイル・レビュー）は `PAIRVOICE_DATA_ROOT` に置き、作業ツリーや同梱物には置かない。フックは実行時に `prompt.txt` を読むのでブランチの切り替えで読み上げが変わり、wheel の同梱物は更新で消える
+- フックは `plugin/` の中だけで完結させる。プラグインはインストール時に `plugin/` だけがキャッシュへ写される
+- MLX の処理は `Runner` のキューを通し、専用の1本のスレッドで実行する。別のスレッドで生成すると `There is no Stream(gpu, N)` で落ちる
+- Host / Origin のループバック判定は `studio/server/app.ts` と `server.is_local_request()` の2か所にあり、そろえておく
+- 試聴は保存済みの caption を書き換えず、`/speak` の引数で渡す（書き換えると、その最中のフックの読み上げが試行中の声で鳴る）。複数候補は seed だけ変えて1件ずつ叩く（まとめると `Runner` を占有し、フックの読み上げが待たされる）
+- 要約の改善はプラグインの `tune` スキルが利用者のエージェントで行う。pairvoice は測る道具とデータだけを持つ
+
+## studio
+
+- studio は常駐サーバーから切り離して起動するので、コードを変えたら studio も再起動する（常駐サーバーの再起動では入れ替わらない）
+- `server.ts` は Node の標準ライブラリだけで動かし、フロントの依存はすべて `devDependencies` に入れる（`shadcn add` は `dependencies` に入れるので移す）
+- 公開用の wheel はビルド済みの `web/dist` を同梱するので、`(cd studio && pnpm build) && uv build` の順で作る
+- テストで `PAIRVOICE_DATA_ROOT` を差し替えるときは、`server.ts` の import 前か別プロセスで行う（読み込み時に定数を確定する。`PAIRVOICE_URL` は呼ぶたびに読む）
+- 画面の項目は `web/src/components/nav.ts`、キーボード操作は `useHotkeys`（`web/src/lib/hotkeys.ts`）を通す
+- `web/src/components/ui/` は shadcn/ui の生成物で、`studio/` で `pnpm exec shadcn add <name>` して足す

pairvoice-0.1.0/DEVELOPMENT.md

@@ -0,0 +1,119 @@
+# pairvoice の開発
+
+使う側の説明は [README](README.md)。開発の決まりごと（不変条件と落とし穴）は [CLAUDE.md](CLAUDE.md) にある。
+
+## 構成
+
+| 部分 | 場所 | 中身 |
+| --- | --- | --- |
+| 常駐サーバー | `src/pairvoice/` | Python / FastAPI。`127.0.0.1:17495`。要約（mlx-lm）と音声合成（mlx-audio / Irodori-TTS） |
+| studio | `studio/` | `server.ts`（Node の標準ライブラリだけ、`127.0.0.1:17494`）と React 19 + Vite のフロント（`web/`） |
+| 読み上げフック | `plugin/` | Claude Code プラグイン（フックと、要約を改善する `tune` スキル）。マーケットプレイスはリポジトリ直下の `.claude-plugin/marketplace.json` |
+| メニューバー | `src/pairvoice/menubar.py` | 常駐サーバーの子として起きる |
+
+## 手元で動かす
+
+常駐は、利用者と同じ形（uv tool）で入れた wheel で動かす。
+wheel でしか起きない壊れ方（同梱物の漏れ、依存の抜け）に、ふだん使いの中で気づけるようにするためである。
+
+```bash
+uv sync
+(cd studio && pnpm install)
+rm -rf dist && (cd studio && pnpm build) && uv build --wheel
+uv tool install --reinstall dist/pairvoice-*.whl
+pairvoice install                 # 初回だけ。LaunchAgent を tool 側の Python に向ける
+```
+
+LaunchAgent は tool 側の Python を指すので、リポジトリのコードを変えても常駐サーバーには効かない。
+反映するときは、wheel のビルドと `uv tool install --reinstall` をやり直す。
+入れ直したあとの立て直し方は、変えた場所で選ぶ。
+サーバーを立て直すとモデルを読み込み直すので、要らないときは避ける。
+
+| 変えた場所 | 立て直すもの |
+| --- | --- |
+| `studio/` だけ | `pairvoice studio --restart`（studio だけ。モデルは載ったまま） |
+| `src/pairvoice/` | メニューの「再起動」（studio とサーバーの両方。`pairvoice restart` はサーバーだけで、studio は古いコードのまま残る） |
+| `prompt.txt`、辞書 | 要らない（フックが読み上げのたびに読む） |
+
+作業ツリーのコードをその場で動かしたいときは、メニューの「pairvoice を終了」で常駐を止めてから手で起動する（ポート `:17495` を取り合うので同時には動かせない）。
+
+```bash
+uv run pairvoice serve            # Ctrl-C でメニューバーごと降りる
+launchctl kickstart gui/$(id -u)/local.pairvoice   # 常駐に戻す
+
+# studio のフロントを開発する（:17493。/api は :17494 へ proxy する）
+node studio/server.ts --port 17494 &
+(cd studio && pnpm dev)
+```
+
+プラグインは、clone したディレクトリをそのままマーケットプレイスとして入れられる
+（`claude plugin marketplace add <clone のパス>`）。この場合キャッシュに写されず作業ツリーから読まれるので、
+ブランチを切り替えるとふだんの読み上げのフックも変わる。
+
+## テスト
+
+```bash
+uv run pytest                                   # 実モデルは載らない
+uv run ruff check && uv run ruff format --check && uv run ty check
+cd studio && node --test server.test.ts
+cd studio && pnpm test:web && pnpm typecheck && pnpm lint && pnpm format:check
+```
+
+studio のテストのうち1本は、`plugin/hooks/speak-summary.sh` とデータの置き場所の `dict.tsv` を読んで、
+辞書置換の bash 実装と JS 実装が一致することを確かめる（`dict.tsv` が無ければ skip）。
+
+## 公開用のビルド
+
+```bash
+(cd studio && pnpm build) && uv build
+```
+
+wheel には studio（ビルド済みの `web/dist` を含む）・`examples/` を同梱する（`pyproject.toml` の
+`force-include`）。`web/dist` は git で追跡しないので、ビルドを忘れると wheel のビルドが失敗する。
+
+## 要約の評価（`pairvoice eval`）
+
+```bash
+pairvoice eval                                      # 使用中の prompt.txt を同梱のケースで評価
+pairvoice eval --prompt 候補.txt --reviews --out 結果.jsonl
+pairvoice eval --model mlx-community/<モデル>       # 別のモデルをこのプロセスに読み込んで評価
+```
+
+`src/pairvoice/checker.py` が次の7つの規則で判定し、`evaluation.py` が集計する。同梱のケースは
+`src/pairvoice/eval_cases.tsv`。`--reviews` は studio のレビュー（アーカイブしたものを除く）をケースに加える。
+
+1. 句点・感嘆符・疑問符が1〜2個（二文まで）
+2. コード識別子（ファイル名・関数名・パスなど）を含まない
+3. 命令・急かし口調を含まない
+4. 名詞・形容詞に直接「ね」を付けて終わらない
+5. 10〜45文字程度で、絵文字を含まない
+6. 一人称（俺・僕など）を含まない
+7. です・ます調の文末を含まない（`config.toml` の `[eval] style = "casual"` のときだけ判定する）
+
+改善の作業は利用者のエージェントがプラグインの `tune` スキルに沿って行い、pairvoice は測る道具だけを持つ。
+
+## データの置き場所を変える
+
+`PAIRVOICE_DATA_ROOT` で置き場を変えられる。シェルに設定してから `pairvoice install` を実行し直す
+（launchd から起きる常駐サーバーにはシェルの環境変数が届かないので、LaunchAgent に焼き込む）。
+`config.toml` で `tts.output_dir` を明示している場合は、その親もデータの置き場所に揃える（ずれていると
+`install` が警告する。片方だけだと studio の再生が黙って失敗する）。
+
+## 詳しい状態の見方
+
+`pairvoice status` は常駐サーバーの `/health` をそのまま表示する。
+
+| 項目 | 意味 |
+| --- | --- |
+| `llm.state` / `tts.state` | `unloaded` / `downloading` / `loading` / `loaded` / `failed` / `misconfigured` |
+| `tts.profile` | 使用中の声のプロファイル（まだ一度も読み上げていなければ `null`） |
+| `mute` | ミュート中か、その理由（`manual` / `microphone` / `audio_output`）と期限 |
+| `playback` | 鳴っているか（`playing`）と、順番待ちの数（`waiting`） |
+| `dropped_recent` | 直近で後続に追い越されて捨てた要約の数。3件以上ならキューが詰まっている |
+| `config_stale` | 設定ファイルが起動後に変わった（`pairvoice restart` が要る） |
+
+ログは、常駐サーバーが `~/Library/Logs/pairvoice.log`、フックが `~/Library/Logs/speak-summary.log`。
+常駐サーバーのログは `serve --log-file` が 10MB × 3世代で回しながら書き、成功した `/health` は書かない。
+メニューバーの警告は `~/Library/Logs/pairvoice-menubar.log` に同じく回しながら書く。
+logging を通らない出力（落ちたときの Traceback、ネイティブ層の出力）は、launchd が `~/Library/Logs/pairvoice.stderr.log` に書く。
+フックのログの `SKIP (...)` の理由は [plugin/README.md](plugin/README.md) にまとめてある。

pairvoice-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 matzkoh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pairvoice-0.1.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.5
+Name: pairvoice
+Version: 0.1.0
+Summary: Claude Code の読み上げ用に、要約と音声合成を担うローカル常駐サーバー
+Project-URL: Repository, https://github.com/matzkoh/pairvoice
+Project-URL: Issues, https://github.com/matzkoh/pairvoice/issues
+Author: matzkoh
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude-code,japanese,mlx,tts
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Japanese
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.12
+Requires-Dist: fastapi<1,>=0.141
+Requires-Dist: mlx-audio==0.5.7
+Requires-Dist: mlx-lm<0.33,>=0.32.0
+Requires-Dist: pyobjc-framework-avfoundation<13,>=12
+Requires-Dist: pyobjc-framework-cocoa<13,>=12
+Requires-Dist: uvicorn<1,>=0.54
+Description-Content-Type: text/markdown
+
+# pairvoice
+
+**Claude Code の返事を、ひと言の日本語にして読み上げる。**
+
+Claude Code に長い作業を任せて別の画面を見ていると、とうに終わって入力を待っていたことに、あとから気づく。
+返事をそのまま読み上げれば済みそうに思える。
+ところが返事にはコミットのハッシュやテストの件数が混ざっていて、耳で聞いても何が起きたのか分からない。
+
+> 入力: Task 2 実装完了（`45f2238`、135 passed）。レビュアーが走っている。<br>
+> 読み上げ: 「実装が終わり、テストはすべて通っています。いまレビューを待っています。」
+
+pairvoice は、返事をこのように2文ほどの日本語に縮めてから読む。
+画面から目を離していても、いま何が終わって次に何をするのかが耳で分かる。
+
+## できること
+
+- **識別子を読まない。** ファイル名や関数名はそのまま読まず、何をしたのかに言い換える
+- **手元だけで動く。** 要約（mlx-lm）と音声合成（Irodori-TTS）を Apple Silicon の上で動かし、返事の中身を外に送らない。その分メモリを使う（下の「動作要件」を参照）
+- **会議中や動画・音楽の再生中は黙る。** マイクが使われている間と、ほかのアプリが音を出している間は自動でミュートする。メニューバーから時間を区切ってミュートもできる
+- **声を選べる。** 声の描写（「落ち着いた低い声。ゆっくり話す。」など）から声を作るか、手持ちの音声を取り込んで使う
+- **読み方を育てられる。** ブラウザの画面（studio）で、読み上げの履歴に 👍👎 を付け、要約の指示や読み替えの辞書を直せる
+
+日本語話者向けのツールで、要約の指示も読み辞書も音声合成のモデルも、日本語を前提にしている。
+
+## しくみ
+
+```
+Claude Code ──（プラグインのフック）──▶ 常駐サーバー ──▶ 要約 ──▶ 音声合成 ──▶ 再生
+                                          │
+                                          └─ studio（ブラウザ）で指示と辞書と声を育てる
+```
+
+Claude Code に入れるプラグインが返事を受け取り、手元で常駐するサーバーに要約と音声合成を頼んで再生する。
+サーバーは `127.0.0.1` にだけ待ち受ける。
+
+## はじめかた
+
+**1. 必要なものをそろえる**
+
+- Apple Silicon の Mac（ユニファイドメモリ 32GB 以上を推奨。下の「動作要件」を参照）
+- [uv](https://docs.astral.sh/uv/)、Node 24.13 以降、`jq`（`brew install jq`）
+
+**2. 入れる**
+
+```bash
+uv tool install pairvoice
+pairvoice install
+```
+
+`pairvoice install` は、常駐サーバーをログイン時に起きるよう登録し、要約の指示と読み辞書の雛形を置く。
+メニューバーにアイコンが出る。
+
+**3. Claude Code にプラグインを入れて、Claude Code を起動し直す**
+
+```
+/plugin marketplace add matzkoh/pairvoice
+/plugin install pairvoice@pairvoice
+```
+
+最初の読み上げは、モデルのダウンロード（約 15GB）と読み込みで時間がかかる。
+進み具合は `pairvoice status` で見られる。
+
+## 動作要件
+
+- macOS（Apple Silicon）
+- メモリ: 既定のモデル（要約 `gemma-4-e4b-it-8bit`、音声合成 `Irodori-TTS-v4.1-Small-8bit`）を両方載せると、常駐で約 9.5GB、生成中のピークで約 12GB を使う（48GB の機種で実測）。
+  どちらも10分使わなければ自動で解放する。
+  メモリが少ないときは、下の「設定」で要約のモデルを小さくできる
+- モデルは同梱しない。初回に Hugging Face から手元へダウンロードする。各モデルのライセンスはそれぞれの配布元に従う
+  - 要約: [Gemma 4](https://huggingface.co/google/gemma-4-E4B-it)（[Gemma Terms of Use](https://ai.google.dev/gemma/terms)）
+  - 音声合成: [Irodori-TTS](https://huggingface.co/Aratako/Irodori-TTS-v4.1-Small)（MIT）
+
+## 読み上げた内容の扱い
+
+返事の中身は外に出ないが、手元には残る。
+
+- 返事の全文と要約は、手元のデータの置き場所（`~/Library/Application Support/pairvoice/`）の `corpus.jsonl` に書きためる。
+  studio のレビューと要約の指示の改善に使う。
+  作業の中身がそのまま入るので、要らなくなったら消す
+- 外と通信するのは、モデルの初回ダウンロードだけ
+
+## 声を変える
+
+読み上げの声は**プロファイル**（参照音声と声の描写の組）で決まる。
+studio の「プロファイル」画面で、
+
+- 声の描写から候補をいくつか合成し、気に入ったものを選んで保存する
+- 手持ちの wav（数秒〜十数秒）を取り込む
+
+のどちらかで作り、「使う」で切り替える。
+何も作らなくても、最初の読み上げのときに既定の声が1つ作られる。
+切り替えは次の読み上げから効き、再起動は要らない。
+
+## 読み方を育てる
+
+要約は、いつも思いどおりに縮まるとは限らない。
+識別子を読み上げてしまったり、知りたかった結果を落としたりすることがある。
+読み上げの履歴に印を付けておくと、それを材料に要約の指示と辞書を直せる。
+
+studio はメニューの「studio を開く」か `pairvoice studio` で起動する（`127.0.0.1:17494` だけで待ち受ける）。
+
+| 画面 | できること |
+| --- | --- |
+| レビュー | 読み上げの履歴を聞き直し、👍👎 と「こう読んでほしかった」を残す |
+| プロンプト | 要約の指示（`prompt.txt`）を直す。前の版に戻せる |
+| 辞書 | 読み間違える言葉を、読み方に置き換える |
+| 声 | 声の描写とサンプラーを変えて試聴し、気に入った描写を使用中の声に当てる |
+| プロファイル | 声を作る、取り込む、切り替える |
+
+要約の指示の改善は、Claude Code で `/pairvoice:tune` を実行して頼む。
+レビューを材料に改善案を作り、`pairvoice eval` で今の指示と比べてから提案する。当てるかは人が決める。
+
+## 使い方
+
+メニューバーのアイコンから、読み上げを止める、ミュート（15分、30分、60分）、studio を開く、再起動（サーバーと studio）、終了ができる。
+同じことはコマンドでもできる。
+
+| コマンド | すること |
+| --- | --- |
+| `pairvoice status` | 状態（モデル、ミュート、声）を表示する |
+| `pairvoice mute 30m` / `unmute` | 30分ミュートする（1〜480分）／解除する |
+| `pairvoice say "テスト"` | 読み上げてみる（ミュート中でも鳴る） |
+| `pairvoice stop` | 鳴っている読み上げと、順番待ちの読み上げを止める |
+| `pairvoice warmup` | モデルを先に読み込んでおく |
+| `pairvoice restart` | 常駐サーバーを再起動する（設定を変えたら要る） |
+| `pairvoice studio` | studio を開く（`--restart` で studio だけを立て直す） |
+| `pairvoice eval` | 要約の指示やモデルを規則で採点する（`--reviews` でレビューも使う、`--model` で別のモデルを試す） |
+
+「終了」で止めたサーバーは、ログインし直すか `launchctl kickstart gui/$(id -u)/local.pairvoice` で戻る。
+
+## ミュート
+
+手動のミュート（期限付き）と、自動の条件のどちらかが当てはまれば黙る。
+自動の条件は、マイクの使用中（会議アプリを問わない）と、ほかのアプリが音を出している間（YouTube や Spotify の再生中など）。
+ほかのアプリの音は鳴らす直前まで確かめ、通知音のように5秒以内に止めば、止んだ後に読み上げる。
+読み上げている最中も見張る。ミュートやマイクが入ったらその場で止め、ほかのアプリが音を出したら音量を下げ、5秒続いたら止める。
+
+## 設定
+
+`~/.config/pairvoice/config.toml`。
+無くても既定値で動く。
+変えたら `pairvoice restart` する。
+
+| 表 | よく触る項目 |
+| --- | --- |
+| `[llm]` | `model`（要約のモデル） |
+| `[tts]` | `model`（音声合成のモデル）、`output_max_age_days`（合成した wav を消すまでの日数。既定 7、0 で消さない） |
+| `[tts.profile]` | 最初の声を作るときだけ使う。`ref_audio`（取り込む wav）、`caption`（声の描写） |
+| `[tts.sampler]` | 音声合成の細かい調整。studio の「声」画面で試して、表示される設定を写す |
+| `[mute]` | `auto_microphone`（既定 true）、`auto_audio_output`（既定 true）、`audio_output_wait_seconds`（既定 5） |
+| `[playback]` | `volume`（既定 1.0）、`duck_volume`（ほかのアプリの音が鳴っている間の音量。既定 0.3）、`max_wait_seconds`（順番待ちがこれを超えたら捨てる。既定 60） |
+| `[eval]` | `style = "casual"` で、`pairvoice eval` がです/ます調を違反にする（タメ口に育てるとき） |
+
+メモリが少ない機種では、要約のモデルを小さくすると要約側のピークが約 8GB から約 4.7GB に下がる。
+ただしコード識別子をそのまま読み上げやすく、既定のモデルより崩れやすい。
+
+```toml
+[llm]
+model = "mlx-community/gemma-4-e4b-it-4bit"
+```
+
+## うまく鳴らないとき
+
+- **何も鳴らない**: `pairvoice status` を見る
+  - `mute.active` が `true` ならミュート中（`mute.reason` が `microphone` なら会議中の自動ミュート）
+  - `state` が `downloading` / `loading` ならモデルの準備中。初回は時間がかかる
+  - `state` が `failed` / `misconfigured` なら、`~/Library/Logs/pairvoice.log` を見る
+  - サーバーが起動しては落ちるなら、落ちたときの出力が `~/Library/Logs/pairvoice.stderr.log` に残る
+  - サーバーに届かなければ、メニューの「再起動」かログインし直しで戻す
+- **サーバーは元気なのに鳴らない**: `~/Library/Logs/speak-summary.log` を見る。
+  何も書かれていなければプラグインが読まれていないので、Claude Code を起動し直す。
+  書かれていれば理由が `SKIP (...)` に出る（一覧は [plugin/README.md](https://github.com/matzkoh/pairvoice/blob/main/plugin/README.md)）
+- **設定を変えたのに効かない**: `pairvoice restart`
+- **辞書を直したのに効かない**: studio の「保存」を押すまでは書き換わらない
+
+## やめるとき
+
+Claude Code で `/plugin uninstall pairvoice@pairvoice`、続けて次を実行する。
+
+```bash
+pairvoice uninstall          # 常駐の登録を外す
+uv tool uninstall pairvoice
+```
+
+要約の指示、辞書、声、読み上げの記録は `~/Library/Application Support/pairvoice/` に残る。
+要らなければ消す。
+
+## 開発に参加する
+
+手元での動かし方、テスト、評価ハーネスは [DEVELOPMENT.md](https://github.com/matzkoh/pairvoice/blob/main/DEVELOPMENT.md) にある。
+
+## ライセンス
+
+[MIT](https://github.com/matzkoh/pairvoice/blob/main/LICENSE)

pairvoice-0.1.0/README.md

@@ -0,0 +1,194 @@
+# pairvoice
+
+**Claude Code の返事を、ひと言の日本語にして読み上げる。**
+
+Claude Code に長い作業を任せて別の画面を見ていると、とうに終わって入力を待っていたことに、あとから気づく。
+返事をそのまま読み上げれば済みそうに思える。
+ところが返事にはコミットのハッシュやテストの件数が混ざっていて、耳で聞いても何が起きたのか分からない。
+
+> 入力: Task 2 実装完了（`45f2238`、135 passed）。レビュアーが走っている。<br>
+> 読み上げ: 「実装が終わり、テストはすべて通っています。いまレビューを待っています。」
+
+pairvoice は、返事をこのように2文ほどの日本語に縮めてから読む。
+画面から目を離していても、いま何が終わって次に何をするのかが耳で分かる。
+
+## できること
+
+- **識別子を読まない。** ファイル名や関数名はそのまま読まず、何をしたのかに言い換える
+- **手元だけで動く。** 要約（mlx-lm）と音声合成（Irodori-TTS）を Apple Silicon の上で動かし、返事の中身を外に送らない。その分メモリを使う（下の「動作要件」を参照）
+- **会議中や動画・音楽の再生中は黙る。** マイクが使われている間と、ほかのアプリが音を出している間は自動でミュートする。メニューバーから時間を区切ってミュートもできる
+- **声を選べる。** 声の描写（「落ち着いた低い声。ゆっくり話す。」など）から声を作るか、手持ちの音声を取り込んで使う
+- **読み方を育てられる。** ブラウザの画面（studio）で、読み上げの履歴に 👍👎 を付け、要約の指示や読み替えの辞書を直せる
+
+日本語話者向けのツールで、要約の指示も読み辞書も音声合成のモデルも、日本語を前提にしている。
+
+## しくみ
+
+```
+Claude Code ──（プラグインのフック）──▶ 常駐サーバー ──▶ 要約 ──▶ 音声合成 ──▶ 再生
+                                          │
+                                          └─ studio（ブラウザ）で指示と辞書と声を育てる
+```
+
+Claude Code に入れるプラグインが返事を受け取り、手元で常駐するサーバーに要約と音声合成を頼んで再生する。
+サーバーは `127.0.0.1` にだけ待ち受ける。
+
+## はじめかた
+
+**1. 必要なものをそろえる**
+
+- Apple Silicon の Mac（ユニファイドメモリ 32GB 以上を推奨。下の「動作要件」を参照）
+- [uv](https://docs.astral.sh/uv/)、Node 24.13 以降、`jq`（`brew install jq`）
+
+**2. 入れる**
+
+```bash
+uv tool install pairvoice
+pairvoice install
+```
+
+`pairvoice install` は、常駐サーバーをログイン時に起きるよう登録し、要約の指示と読み辞書の雛形を置く。
+メニューバーにアイコンが出る。
+
+**3. Claude Code にプラグインを入れて、Claude Code を起動し直す**
+
+```
+/plugin marketplace add matzkoh/pairvoice
+/plugin install pairvoice@pairvoice
+```
+
+最初の読み上げは、モデルのダウンロード（約 15GB）と読み込みで時間がかかる。
+進み具合は `pairvoice status` で見られる。
+
+## 動作要件
+
+- macOS（Apple Silicon）
+- メモリ: 既定のモデル（要約 `gemma-4-e4b-it-8bit`、音声合成 `Irodori-TTS-v4.1-Small-8bit`）を両方載せると、常駐で約 9.5GB、生成中のピークで約 12GB を使う（48GB の機種で実測）。
+  どちらも10分使わなければ自動で解放する。
+  メモリが少ないときは、下の「設定」で要約のモデルを小さくできる
+- モデルは同梱しない。初回に Hugging Face から手元へダウンロードする。各モデルのライセンスはそれぞれの配布元に従う
+  - 要約: [Gemma 4](https://huggingface.co/google/gemma-4-E4B-it)（[Gemma Terms of Use](https://ai.google.dev/gemma/terms)）
+  - 音声合成: [Irodori-TTS](https://huggingface.co/Aratako/Irodori-TTS-v4.1-Small)（MIT）
+
+## 読み上げた内容の扱い
+
+返事の中身は外に出ないが、手元には残る。
+
+- 返事の全文と要約は、手元のデータの置き場所（`~/Library/Application Support/pairvoice/`）の `corpus.jsonl` に書きためる。
+  studio のレビューと要約の指示の改善に使う。
+  作業の中身がそのまま入るので、要らなくなったら消す
+- 外と通信するのは、モデルの初回ダウンロードだけ
+
+## 声を変える
+
+読み上げの声は**プロファイル**（参照音声と声の描写の組）で決まる。
+studio の「プロファイル」画面で、
+
+- 声の描写から候補をいくつか合成し、気に入ったものを選んで保存する
+- 手持ちの wav（数秒〜十数秒）を取り込む
+
+のどちらかで作り、「使う」で切り替える。
+何も作らなくても、最初の読み上げのときに既定の声が1つ作られる。
+切り替えは次の読み上げから効き、再起動は要らない。
+
+## 読み方を育てる
+
+要約は、いつも思いどおりに縮まるとは限らない。
+識別子を読み上げてしまったり、知りたかった結果を落としたりすることがある。
+読み上げの履歴に印を付けておくと、それを材料に要約の指示と辞書を直せる。
+
+studio はメニューの「studio を開く」か `pairvoice studio` で起動する（`127.0.0.1:17494` だけで待ち受ける）。
+
+| 画面 | できること |
+| --- | --- |
+| レビュー | 読み上げの履歴を聞き直し、👍👎 と「こう読んでほしかった」を残す |
+| プロンプト | 要約の指示（`prompt.txt`）を直す。前の版に戻せる |
+| 辞書 | 読み間違える言葉を、読み方に置き換える |
+| 声 | 声の描写とサンプラーを変えて試聴し、気に入った描写を使用中の声に当てる |
+| プロファイル | 声を作る、取り込む、切り替える |
+
+要約の指示の改善は、Claude Code で `/pairvoice:tune` を実行して頼む。
+レビューを材料に改善案を作り、`pairvoice eval` で今の指示と比べてから提案する。当てるかは人が決める。
+
+## 使い方
+
+メニューバーのアイコンから、読み上げを止める、ミュート（15分、30分、60分）、studio を開く、再起動（サーバーと studio）、終了ができる。
+同じことはコマンドでもできる。
+
+| コマンド | すること |
+| --- | --- |
+| `pairvoice status` | 状態（モデル、ミュート、声）を表示する |
+| `pairvoice mute 30m` / `unmute` | 30分ミュートする（1〜480分）／解除する |
+| `pairvoice say "テスト"` | 読み上げてみる（ミュート中でも鳴る） |
+| `pairvoice stop` | 鳴っている読み上げと、順番待ちの読み上げを止める |
+| `pairvoice warmup` | モデルを先に読み込んでおく |
+| `pairvoice restart` | 常駐サーバーを再起動する（設定を変えたら要る） |
+| `pairvoice studio` | studio を開く（`--restart` で studio だけを立て直す） |
+| `pairvoice eval` | 要約の指示やモデルを規則で採点する（`--reviews` でレビューも使う、`--model` で別のモデルを試す） |
+
+「終了」で止めたサーバーは、ログインし直すか `launchctl kickstart gui/$(id -u)/local.pairvoice` で戻る。
+
+## ミュート
+
+手動のミュート（期限付き）と、自動の条件のどちらかが当てはまれば黙る。
+自動の条件は、マイクの使用中（会議アプリを問わない）と、ほかのアプリが音を出している間（YouTube や Spotify の再生中など）。
+ほかのアプリの音は鳴らす直前まで確かめ、通知音のように5秒以内に止めば、止んだ後に読み上げる。
+読み上げている最中も見張る。ミュートやマイクが入ったらその場で止め、ほかのアプリが音を出したら音量を下げ、5秒続いたら止める。
+
+## 設定
+
+`~/.config/pairvoice/config.toml`。
+無くても既定値で動く。
+変えたら `pairvoice restart` する。
+
+| 表 | よく触る項目 |
+| --- | --- |
+| `[llm]` | `model`（要約のモデル） |
+| `[tts]` | `model`（音声合成のモデル）、`output_max_age_days`（合成した wav を消すまでの日数。既定 7、0 で消さない） |
+| `[tts.profile]` | 最初の声を作るときだけ使う。`ref_audio`（取り込む wav）、`caption`（声の描写） |
+| `[tts.sampler]` | 音声合成の細かい調整。studio の「声」画面で試して、表示される設定を写す |
+| `[mute]` | `auto_microphone`（既定 true）、`auto_audio_output`（既定 true）、`audio_output_wait_seconds`（既定 5） |
+| `[playback]` | `volume`（既定 1.0）、`duck_volume`（ほかのアプリの音が鳴っている間の音量。既定 0.3）、`max_wait_seconds`（順番待ちがこれを超えたら捨てる。既定 60） |
+| `[eval]` | `style = "casual"` で、`pairvoice eval` がです/ます調を違反にする（タメ口に育てるとき） |
+
+メモリが少ない機種では、要約のモデルを小さくすると要約側のピークが約 8GB から約 4.7GB に下がる。
+ただしコード識別子をそのまま読み上げやすく、既定のモデルより崩れやすい。
+
+```toml
+[llm]
+model = "mlx-community/gemma-4-e4b-it-4bit"
+```
+
+## うまく鳴らないとき
+
+- **何も鳴らない**: `pairvoice status` を見る
+  - `mute.active` が `true` ならミュート中（`mute.reason` が `microphone` なら会議中の自動ミュート）
+  - `state` が `downloading` / `loading` ならモデルの準備中。初回は時間がかかる
+  - `state` が `failed` / `misconfigured` なら、`~/Library/Logs/pairvoice.log` を見る
+  - サーバーが起動しては落ちるなら、落ちたときの出力が `~/Library/Logs/pairvoice.stderr.log` に残る
+  - サーバーに届かなければ、メニューの「再起動」かログインし直しで戻す
+- **サーバーは元気なのに鳴らない**: `~/Library/Logs/speak-summary.log` を見る。
+  何も書かれていなければプラグインが読まれていないので、Claude Code を起動し直す。
+  書かれていれば理由が `SKIP (...)` に出る（一覧は [plugin/README.md](https://github.com/matzkoh/pairvoice/blob/main/plugin/README.md)）
+- **設定を変えたのに効かない**: `pairvoice restart`
+- **辞書を直したのに効かない**: studio の「保存」を押すまでは書き換わらない
+
+## やめるとき
+
+Claude Code で `/plugin uninstall pairvoice@pairvoice`、続けて次を実行する。
+
+```bash
+pairvoice uninstall          # 常駐の登録を外す
+uv tool uninstall pairvoice
+```
+
+要約の指示、辞書、声、読み上げの記録は `~/Library/Application Support/pairvoice/` に残る。
+要らなければ消す。
+
+## 開発に参加する
+
+手元での動かし方、テスト、評価ハーネスは [DEVELOPMENT.md](https://github.com/matzkoh/pairvoice/blob/main/DEVELOPMENT.md) にある。
+
+## ライセンス
+
+[MIT](https://github.com/matzkoh/pairvoice/blob/main/LICENSE)

pairvoice-0.1.0/examples/dict.example.tsv

@@ -0,0 +1,3 @@
+通っ	とおっ	「通った」を「かよった」と読まれるのを直す
+CI	シーアイ
+PR	プルリクエスト