開発者・AI向けドキュメント

MACARON API — v1.1.18 以降の macOS 版に対応

使い方はかんたん。 Claude や ChatGPT などの AI アシスタントに「https://macaronkey.com/developers を読んで、MACARON を◯◯して」と伝えるだけ。状態の診断も、設定の変更も、AI がこのページを読んでそのまま実行できます。もちろん人間が読んでスクリプトから使っても構いません。

2つの入口

読む — ~/Library/Application Support/VoiceRush/status.json。権限・ライセンス・設定・サーバー疎通の現在地を、アプリが常時ここへ書き出しています。「なぜ動かないか」と「どう直すか」も入っています
書く — defaults write jp.tn.voiceos キー値。アプリの再起動は不要、1〜2秒で反映されます。決まりに合わない値は反映されず元に戻り、理由が status.json の lastConfigError に残ります

まず状態を見る

# いまの状態をぜんぶ見る
cat ~/Library/Application\ Support/VoiceRush/status.json

# 動かない理由だけ見る（jq があれば）
jq '.ready, .issues' ~/Library/Application\ Support/VoiceRush/status.json

# アプリが動いているか
pgrep -x VoiceOS >/dev/null && echo 起動中 || echo 停止中

# 動きの記録
tail -20 ~/Library/Logs/VoiceOS.log

status.json の中身

フィールド	意味
`ready`	3つの権限が揃い、ライセンスが無効でない＝使える状態か（真偽）
`issues[]`	足りないもの。`code` / `message`（なぜ動かないか）/ `fix`（直しかた）/ `command`（そのまま打てるコマンド）
`permissions`	`microphone` / `accessibility` / `inputMonitoring`。値は `granted` / `denied` / `restricted` / `notDetermined`
`license.state`	`active`（照合済み。トライアル中もこれ）/ `unverified`（キーはあるが未照合）/ `invalid` / `unset`。キー本体は書かれず、末尾4桁（`keyTail`）だけ
`settings`	モード・職種・起動キー・品質・効果音など現在の設定。「よく使う言葉」と口調メモは中身ではなく文字数だけ入ります（固有名詞は個人情報になりうるため）
`api`	直近の書き起こしの疎通（`lastSuccessAt` / `lastError`）
`lastConfigChange` / `lastConfigError`	外から受け付けた最後の変更と、弾いた最後の値（理由つき）
`version` / `pid` / `startedAt` / `updatedAt`	アプリのバージョン・プロセスID・起動時刻・中身が最後に変わった時刻
`paths`	status.json 自身・ログ・defaults ドメイン・このページのURL

設定を変える（defaults キー一覧）

宛先ドメインは jp.tn.voiceos。型指定（-bool / -int / -float）を付け忘れて文字列で書いても、正しい型に直して受け取ります。キーを defaults delete で消すと、その項目はアプリの既定値に戻ります。

キー	許容値	既定	意味
`cleanupMode`	`off` / `standard` / `formal` / `junior` / `friend` / `lover`	`standard`	整えモード。⚡オフ / ✨整える / 💼上司 / 🫡部下 / 🤝友達 / ❤️恋人
`styleNote.<style>`	2000字まで。`<style>` は `standard`〜`lover`	空	モードごとの口調メモ（例:「語尾はですます。絵文字は使わない」）
`loverHeartLevel`	`few` / `normal` / `lots`	`lots`	恋人モードのハートの量
`field`	`""` / `engineer` / `marketing` / `sales` / `accounting` / `legal` / `medical` / `construction` / `manufacturing` / `realestate`	`""`	あなたの職種。分野の専門用語と聞き間違い補正が効く
`vocabulary`	2000字まで（カンマ区切り。送信は先頭300字）	初期セット	よく使う言葉（社名・商品名など固有名詞）
`triggerKeyCode`	JIS 左→右: `63` fn / `58` 左⌥ / `55` 左⌘ / `102` 英数 / `104` かな / `54` 右⌘ / `61` 右⌥ / `60` 右⇧ / `57` caps US 左→右: `63` fn / `58` 左⌥ / `55` 左⌘ / `54` 右⌘ / `61` 右⌥ / `60` 右⇧ / `57` caps （スペースは起動キー候補に含めない）	未設定時: US=`61` / 日本語配列=`63`	起動キー（候補の並び＝キーボード下段の左→右）
`holdToTalk`	`true` / `false`	`true`	true=押しっぱなしで録音、false=押すたび開始・停止
`holdThreshold`	`0.05`〜`1.5`（秒）	`0.25`	これより短い押下は押し間違いとみなして録音を捨てる（録音自体は押した瞬間に始まる）
`qualityLevel`	`low`(Low) / `high`(Max・高精度)	`low`	聞き取りの品質。Max は消費が3倍
`speedRate`	`1.0`〜`2.0`	Low は `1.0` / それ以外は `1.25`	送信前に音声を速める倍率（内部の調整用。通常は触らなくてよい）
`soundEnabled`	`true` / `false`	`true`	効果音の総スイッチ
`gestureSelect`	`true` / `false`	`true`	長押し中のマウス移動でその1回だけのモードを選ぶ（上=上司/左=部下/下=友達/右=恋人）
`soundStart` / `soundStop` / `soundSuccess` / `soundFailure`	`なし` / `Tink` / `Pop` / `Purr` / `Morse` / `Ping` / `Bottle` / `Blow` / `Frog` / `Funk` / `Glass` / `Hero` / `Sosumi` / `Submarine` / `Basso`	`Tink`/`Pop`/`Morse`/`Basso`	場面ごとの効果音
`iconName`	`窓と波形` / `波形` / `吹き出し` / `マイク`	`窓と波形`	メニューバーのアイコン
`launchAtLogin`	`true` / `false`	`true`	ログイン時に自動起動

コピペで動く例

# 設定を変える（どれも再起動不要。1〜2秒で効く）
defaults write jp.tn.voiceos cleanupMode formal            # 上司モード（敬語）
defaults write jp.tn.voiceos field engineer                # IT用語に強くする
defaults write jp.tn.voiceos triggerKeyCode -int 61        # 起動キーを右オプションへ
defaults write jp.tn.voiceos qualityLevel -string high     # 品質 Max（高精度・消費3倍）
defaults write jp.tn.voiceos soundEnabled -bool false      # 効果音を止める
defaults write jp.tn.voiceos vocabulary "社名, 商品名, 専門用語"
defaults write jp.tn.voiceos "styleNote.formal" "語尾はですます。絵文字は使わない"

# 変わったか確かめる
defaults read jp.tn.voiceos cleanupMode
jq '.settings, .lastConfigChange, .lastConfigError' \
  ~/Library/Application\ Support/VoiceRush/status.json

# 元に戻す（キーを消すとアプリの既定値に戻る）
defaults delete jp.tn.voiceos field

決めごと

licenseKey / serverURL / deviceID は外からの書き換え対象ではありません（誤爆の被害が大きいため）。ライセンスの設定は購入完了ページの「アプリに設定」か、設定ウィンドウから行ってください
status. で始まるキーは記録専用。書き換えても設定には影響しません
status.json にはライセンスキー本体・語彙の中身・口調メモの中身は書かれません
不正な値は反映されず元の値に復元されます。理由は lastConfigError の reason に、許容値の一覧つきで入ります

典型的な使いみち

トラブル解決の丸投げ — 「MACARON が動かない、直して」と AI に言う。 AI が issues[] を読み、command をそのまま実行して案内できます
環境の一発セットアップ — 「法律事務所向けの設定にして」→ field legal + 語彙 + 上司モード、を AI がまとめて設定
法人の一括配布 — Jamf などの MDM から defaults で全端末へ設定配布。status.json で権限漏れ・ライセンス切れの棚卸しも機械的にできます

提供元・お問い合わせ

開発・販売	株式会社ゲットラッキー（GETLUCKY Inc.）
お問い合わせ	info@voicerush.app
各種規約	利用規約／プライバシーポリシー