sarari 説明書

録音キーを押して喋り、もう一度押すと、いま書いていた場所に文字が入る。 それが全部です。 録音キーは最初は**右 ⌥**です。好きなキーや組み合わせに変えられます（一般 › ホットキー）。 設定は「もっと速く／もっとキレイに／挿入が効かない」のどれかを直すためのもので、最初は何も触らなくて動きます。

---

1. 全体の流れ

録音キー ─▶ 録音 ─▶ 音声認識 ─▶ 辞書置換 ─▶ フィラー除去 ─▶ ？補完 ─▶ カーソル位置へ挿入
                       │            │              │              │
                       │            │              │              └ 「〜ですか」「〜ますか」の文末に？を付ける
                       │            │              └ 「えーと」「あの」を落とす。既定 ON
                       │            └ 「アットマーク」→「@」のような機械置換。必ず同じ結果
                       └ 既定は Apple 音声認識（DL 0）。WhisperKit に替えられる

設定画面の3つのタブは、この流れのどこを触るかで分かれています。

タブ	触る場所	ひとことで
一般	録音 と 挿入	音・HUD・ホットキー・挿入方式・履歴
辞書置換	認識のあと	毎回同じ間違いを機械的に直す
候補	認識のあと	履歴から、辞書に入れるとよさそうな聞き違いを出す

---

2. 最初の3分

1. Releases の zip を展開して「アプリケーション」に移し、開きます。最初の 1 回は Mac に止められるので、システム設定 › プライバシーとセキュリティ の「このまま開く」を押します（README のインストール） — 起動するとメニューバーにマイクのアイコンが出ます（Dock には出ません）
2. アクセシビリティを許可します。メニューの「アクセシビリティ設定を開く」から sarari を ON — これを忘れると録音キーを押しても何も起きません
3. 文字を入れたい場所にカーソルを置く → 録音キー（最初は右 ⌥）→ 喋る → もう一度録音キー
4. 初回だけマイクの許可ダイアログが出るので「許可」

ダウンロードは要りません。数 GB のモデルが要るのは、あとで自分で「WhisperKit」を選んだときだけです。

状態はアイコンの色で分かる

アイコン	状態
マイク（無色）	待機中。録音キーで録音開始
すみれ色のマイク	録音中。録音キーで停止。マウスのある画面の縁もすみれ色に光る（設定でオフにできる）
水色の波形	文字起こし中
緑のチェック	挿入できた
黄の「!」	挿入したが、注意あり（録音中に入力デバイスが変わった等）。メニューを開くと理由が読める
橙の警告	失敗。メニューを開くと原因が読める
黄の砂時計	モデル読み込み中（WhisperKit を選んだときだけ）

録音中の HUD

画面下に細いパネルが出ます。棒の動きと色で、いまの状態が分かります。

HUD	状態
	録音中。棒が声の大きさで伸び縮みします（すみれ色）
	マウスを乗せると、停止（■）とキャンセル（×）が出ます
	文字起こし中。棒が水色の波形の形で止まります
	挿入できた。棒が緑の点に畳まれて消えます
	録音を始めて 2 秒たっても一度も音を拾えていない。マイクの権限と入力デバイスを確かめます

30 秒を超えた録音をキャンセルするときは確認が入ります。

---

3. やりたいこと → どこを触る

設定項目を全部読む必要はありません。困ったことから引いてください。

やりたいこと	触る場所
録音キーを右 ⌥ から変えたい	一般 › ホットキー › 「変更」を押して使いたい修飾キー（複数可）を押す。押したまま別のキーを押せば「右⌥ + S」「左⇧ + 左⌘ + 0」のような組み合わせになる
ゲームコントローラーやキーマッパーから録音したい	JoyKeyMapper などは修飾キーを左側として送るが、sarari は他アプリが合成したキーイベントは左右を問わず受ける。右⌥ 設定のままでよい。実キーボードでは従来どおり左右を区別する
開始音・停止音を消したい／変えたい	一般 › サウンド（「なし」も選べる）
録音中のパネルが邪魔	一般 › 録音HUD › 表示サイズを「非表示」に
パネルを画面の上に出したい	一般 › 録音HUD › 表示位置
「アットマーク」が「@」にならない	辞書置換 › 「記号の初期ルールを追加」
固有名詞がいつも同じ誤変換になる	辞書置換 › 「ルールを追加」で 読み→正しい表記 を登録。まとめて拾うなら「履歴から辞書を育てる」
英数字・URL・メールアドレスの認識が壊れる	辞書置換で直すか、一般 › 音声認識 を WhisperKit に（約 630MB）
「えーと」「あの」を落として欲しい	一般 › フィラー除去（既定 ON）。語彙は ~/sarari/fillers.json
挿入に失敗したときの文章を拾いたい	履歴（メニュー › 履歴…）→ コピー／再挿入。残し先は 一般 › 挿入 の「挿入できなかった結果」で選ぶ（どれでも履歴には残る）
喋った内容を残したくない	一般 › 履歴 › 保存期間を短く（7日〜無期限）

---

4. 設定項目の一覧

各項目「何をするか／既定／いつ変えるか」を1行ずつ。

一般

一般タブの画面を見る

サウンド

項目	既定	いつ変えるか
録音開始音	Glass	音が要らないなら「なし」。HUD を非表示にしても音で状態が分かる
録音停止音	Basso	同上

音声認識

項目	既定	いつ変えるか
エンジン	Apple 音声認識	英数字・URL の精度が欲しいとき WhisperKit へ。初回 約 630MB、以後は常駐。認識は Apple より数百 ms 遅い。macOS 26 未満では自動的に WhisperKit

録音HUD

項目	既定	いつ変えるか
表示サイズ	最小	「最小」は声の大きさと経過時間だけの細いバー（マウスを乗せると停止・キャンセル）。「非表示」は音だけで状態を知らせる
表示位置	画面下部中央	下に他の UI があるなら「画面上部中央」

挿入

項目	既定	いつ変えるか
挿入できなかった結果	HUD に残す	「HUD に残す」はパネルからコピー／再挿入できる。「クリップボードに残す」はそのまま ⌘V で貼れる（はっきり挿入できなかったときだけで、ターミナルのように確かめられないアプリでは元に戻す）。「履歴だけに残す」はどちらにも出さない。どれを選んでも履歴には残る

ホットキー

項目	既定	いつ変えるか
録音トリガー（この説明書でいう録音キー）	右 ⌥	「変更」→ 使いたい修飾キーを押す（複数可。右⌥／左⌥／右⌘／左⌘／右⌃／左⌃／右⇧／左⇧／fn。左右は区別）。押したまま別のキー（S や 0 など）を押すと組み合わせ（例: 右⌥ + S、左⇧ + 左⌘ + 0）になり、そのキー入力は前面アプリに届かない。押さずに離すと修飾キーだけ（⇧ を含む・複数の修飾キーは通常キー必須。fn は矢印・F キーと組み合わせ不可）。Esc で中止

履歴

項目	既定	いつ変えるか
保存期間	30日	7日／30日／90日／1年／無期限。期限切れは自動削除
保存先	~/sarari/history/	「フォルダを開く」で中身を見られる。生テキスト・置換後が1発話ごとに残る（音声は残さない）

辞書置換

文字起こしの直後に機械的に置換します。LLM を通さないので同じ入力から必ず同じ結果になります。大文字小文字は区別しません。

操作	内容
ルールを追加	「読み（発話される語）」と「置換後」を登録
記号の初期ルールを追加	アットマーク→@、ドットコム→.com、スラッシュ→/、シャープ→#、アンダースコア→_ を足す
ファイルから読み込む…	同じ形式の JSON をまとめて足す。同じ読みのルールは飛ばす。開発の話が多いなら presets/engineer.json（プルリク→PR、ギットハブ→GitHub など）

ルールを編集している行には、直近の履歴でその読みが何回出てきたか、何件の文が変わるかと、変わる箇所の例が出ます。「ライナー → Linear」で「ライナーノーツ」まで変わる、といった巻き添えを登録前に見られます。

ルールは ~/sarari/replacements.json に保存されます。設定画面のパスをクリックするとエディタに出せて（右クリックで Finder に表示・パスをコピー）、保存すれば再起動せずに次の口述から効きます（Claude Code などでまとめて直す使い方を想定しています。フィラー語の ~/sarari/fillers.json も同じ）。 JSON が壊れた状態で保存しても、直前のルールのまま動き続け、設定画面に理由が出ます。外で編集した直後に設定画面で変更すると、外の編集を優先して読み直します。 各位置で最も長く一致するルールが1つだけ効き、置換結果が別のルールに連鎖することはありません。

候補

履歴の中で、よく出る語と音がほぼ同じなのに少ししか出てこない語を、聞き違いの候補として並べます（例: HitHub（1 回）→ GitHub（13 回）、プランチ → ブランチ）。

• 置換後を直して「追加」すると辞書に入る。行を選ぶと、辞書タブと同じく変わる文の例が出る
• 別の語だったら「無視」。次から出ない（「無視した N 件を戻す」で戻せる）
• エンジンが毎回同じ聞き違いをしていると、多い方が間違いのことがある（プロレクエスト が多く プルリクエスト が少ない、など）。そのときは無視して、辞書タブで逆向きに登録する

履歴から辞書を育てる（Claude Code）

候補タブは回数の偏りで拾うので、スライプ → Stripe のように文脈で分かる誤変換は出てきません。これは Claude Code に履歴を読ませて拾います。

1. リポジトリを開いた Claude Code で「辞書を育てて」と頼む（手順は .claude/skills/grow-dictionary/SKILL.md）
2. 候補が、履歴全体でどの文に当たるかと一緒に出る。狙っていない文を壊すもの（一周 → Issue など、化けた形が普通の語のもの）は外される
3. 了承すると ~/sarari/replacements.json にバックアップを取ってから足される。次の口述から効く

LLM は口述のたびには使いません。使うのは辞書を育てるときだけで、口述は決定的なまま速く動きます。

WARNING

この手順では、履歴のテキストが Claude（Anthropic）に送られます。アプリ自体は何も送りません。送りたくない期間の履歴は、--since で範囲を絞るか、先に履歴から消してください。

---

5. 履歴

メニュー › 履歴…。直前の発話が一番上です。

• コピー／再挿入 — 挿入に失敗したときはここから拾う
• 生／置換後の比較 — 辞書置換とフィラー除去が何を変えたか並べて見られる

---

6. 困ったとき

症状	見るところ
録音キーを押しても何も起きない	アクセシビリティ権限。新しい版に入れ替えた後・ビルドし直した後は、一覧の sarari を「−」で消してからもう一度 ON
録音は始まるが文字が出ない	マイク権限。HUD の棒がオレンジのマイク斜線になっていたら、音を一度も拾えていない
文字は出たがカーソル位置に入らない	挿入先が ⌘V を受け付けていない。文章は履歴と HUD に残っているので、そこからコピーする
「パスワード欄には入力しません」と出る	仕様。パスワード欄と Secure Keyboard Entry 中は送っても届かないうえ、届くと口述文がパスワード欄に入るので手前で止めている。文章は履歴に残る
「Secure Keyboard Entry が有効なため…」と出る	どこかのアプリが Secure Keyboard Entry を掴んでいる（Terminal の「セキュリティ保護されたキー入力」など）。そのアプリでオフにする
起動後ずっと黄の砂時計	WhisperKit モデルの DL 中。一般 › 音声認識 を Apple に戻せば即座に待機になる
挿入後に黄の「!」	録音中に入力デバイスが変わり、切り替え前までの音声で処理した。メニューを開くと理由が読める

挿入できなかったときは、HUD に文章が残ります。「コピー」でクリップボードに入れるか、入れたい場所をクリックしてから「もう一度挿入」を押します。

---

7. ファイルの場所

すべて端末の中にあります。ネットワークに出るのはモデルの DL だけで、音声もテキストも送信しません。

内容	場所
辞書置換ルール	~/sarari/replacements.json
フィラー語	~/sarari/fillers.json
取り込んだ開始音・停止音	~/sarari/sounds/
履歴（テキスト）	~/sarari/history/
設定値	UserDefaults（com.kenta3578.koebun）
WhisperKit モデル	~/Library/Application Support/com.kenta3578.koebun/huggingface/models/argmaxinc/whisperkit-coreml/