sync: update from private repo (2336949a)

docs/tools/speak.md

@@ -0,0 +1,80 @@
+# Speak
+
+文章を読み上げて音声ファイルにする。外部の読み上げサーバー（OpenAI 互換の `/audio/speech`）に文字を送り、返ってきた音声を workspace の `output/` に保存する。
+
+## 基本
+
+```js
+Speak({
+  text: "おはようございます。今日の予定は 3 件です。",
+  file_name: "morning-brief",   // 省略時 speak-{日時}.{形式}
+  voice: "jf_alpha"             // 省略時 config の speak_voice
+})
+```
+
+返り値は保存したパス。そのまま利用者に示せる。
+
+```
+音声を保存しました -> output/morning-brief.mp3 (mp3, 48213 bytes, 24 文字, voice: jf_alpha)
+```
+
+## サーバー設定（必須）
+
+設定 → ツール → Speech の「読み上げ」の欄で設定する。**文字起こし（TranscribeAudio）とは別の接続先**で、片方だけ設定しても構わない。
+
+| 欄 | 設定キー | 既定 |
+|---|---|---|
+| 読み上げの接続先 | `speak_server_url` | なし（未設定なら使えない） |
+| 読み上げモデル | `speak_model` | なし（送らない） |
+| 声 | `speak_voice` | なし（送らない） |
+| 出力の形式 | `speak_format` | `mp3` |
+| 読み上げのタイムアウト | `speak_timeout` | 120 秒 |
+| 文字数の上限 | `speak_max_chars` | 4096 文字 |
+
+接続先が未設定のときは、送信せずに断る。
+
+## ツールの入り切り
+
+読み上げは分類 `speak` として、ワークスペースごとに入り切りを決める（設定 → ツール）。**既定は切**。接続先を設定していない状態では動かないため。
+
+## 声の名前について
+
+声の名前は**自由入力**で、こちらは選択肢を持たない。OpenAI 互換の仕様が声の語彙を定めておらず、サーバーの実装ごとに違うため。決め打ちすると、接続先を替えた瞬間に通らなくなる。
+
+名前が通らなかったときは、サーバーが返した文をそのまま返す。
+
+```
+読み上げサーバーエラー (400): {"error":{"message":"voice 'alloy' is not available"}}
+```
+
+この文が「声の名前が違う」と気づける唯一の手がかりなので、加工しない。
+
+## 出力の形式
+
+仕様上は `mp3` / `opus` / `aac` / `flac` / `wav` / `pcm` があるが、**全部を持つサーバーとは限らない**。既定の `mp3` がいちばん通りやすい。指定した形式がそのまま拡張子になる。
+
+`pcm` は画面のプレビューでは再生できない（ダウンロードはできる）。アプリの中で聴くなら `mp3` などにする。
+
+## 文字数の上限
+
+上限を超える文章は**断る。黙って切り詰めることはしない**。切ると、途中で終わった音声が「できた」として返り、最後まで聴いて初めて気づくことになる。
+
+```
+文字数が上限を超えています（5200 文字 / 上限 4096 文字）。切り詰めてはいません。…
+```
+
+長い文章は段落ごとに分けて複数回呼ぶか、設定で上限を上げる。
+
+## 立てられるサーバーの例
+
+OpenAI 互換の `/audio/speech` を持つ実装であれば何でもよい。
+
+- [openedai-speech](https://github.com/matatonic/openedai-speech)
+- [openai-edge-tts](https://github.com/travisvn/openai-edge-tts)
+
+音の品質・話速・言語の対応はサーバー側の責務で、このアプリでは扱わない。
+
+## 関連
+
+- 文字起こしは [TranscribeAudio](transcribeaudio.md)（逆向き。音声 → 文字）
+- 保存した音声はファイル窓のプレビューでそのまま再生できる