設定
文字起こしと費用
端末内の whisper（無料）、自分の OpenAI キー、または自前の GPU マシンなど OpenAI 互換のエンドポイントから選べます。音声は自分の PC から、選んだサービスへ直接送られます。
#誰が払い、通信はどこへ行くか
費用と通信の仕組み
- 開発元（Japan Marketing LLC）は、文字起こしや AI の利用料を負担せず、中継も請求もしません。
- リクエストは自分の PC から OpenAI か自分のエンドポイントへ直接送られ、開発元のサーバーは通りません。
- OpenAI の利用料は、自分の OpenAI アカウントに請求されます。
- 整理 は、すでにサインインしている Claude Code / Codex の CLI を使います。API で動かす設定（
organizer.runner: "api:<provider>"。settings.json で設定するを参照）をはっきり選んだときだけは別です。勝手に API キーへ切り替えることはありません。
#方式
設定 → 文字起こし → 処理 で選びます。フッターの マイクと文字起こし のポップオーバーに、いまの選択が出ます。
| 処理 | 音声の送り先 | 費用 |
|---|---|---|
| この端末（無料）（最初の設定） | どこにも送らない | 無料 |
| OpenAI（自分のキー） | OpenAI | 自分の OpenAI の請求: gpt-transcribe は1分 $0.0045（1時間で約 $0.27） |
| OpenAI互換（自前のGPU・Groqなど） | 指定した 接続先の Base URL | エンドポイントによる |
設定 → 文字起こし → 言語: 自動、日本語、英語。これは話す言葉の言語で、画面の言語とは別です。
#端末内の whisper（無料）
端末内の文字起こしには whisper.cpp （新しいタブで開きます） を使います。whisper-cli の実行ファイルと GGML モデルの組み合わせです。
1. whisper-cli を入れる。Ferret は同梱のもの（resources/whisper/<platform>-<arch>/）、PATH、Homebrew などのよくある場所の順に探します。
# macOS
brew install whisper-cpp
# Linux: build from source, then add build/bin to PATH
git clone https://github.com/ggml-org/whisper.cpp && cd whisper.cpp
cmake -B build && cmake --build build -j --config Release
# Windows: download the zip from github.com/ggml-org/whisper.cpp/releases
# and add the folder containing whisper-cli.exe to PATH2. モデルを入れる。この端末（無料） を選んだ状態で モデル を選び、モデルをダウンロード を押します。ファイルは Hugging Face（ggerganov/whisper.cpp）から直接取り、アプリに固定した sha256 と照らし合わせ（合わなければファイルを消します）、<userData>/models/ に保存します。ダウンロードしたモデルは自動で選ばれます。中止 しても途中までのファイルは残り、続きからダウンロード でそこから続けます。
| モデル | サイズ | メモ |
|---|---|---|
large-v3-turbo | 1.6 GB | おすすめの既定。Metal / GPU で速い |
large-v3-turbo-q5_0 | 574 MB | 量子化版。ディスクとメモリを節約 |
small | 488 MB | CPU だけのマシン向け |
base | 148 MB | 軽い。日本語では誤りが多い |
tiny | 78 MB | 最も速い。日本語には精度が足りない |
モデルをすでに持っているなら、ファイルを選ぶ… で任意の ggml-*.bin を指定できます。モデルが無いと、設定にモデルが未設定と出ます。それでも録画はでき、音声は保存されますが、できる指摘はペンのものだけです。
whisper-cli はアプリに同梱していません。上のとおり自分で入れてください。見つからないときは、設定に whisper.cpp（whisper-cli）が見つかりません。入れてから設定を開き直してください。
と、同じ手順が出ます。
#自分の OpenAI キー
- 処理 を OpenAI（自分のキー） にします。
sk-で始まるキーを OpenAIのAPIキー に貼り、保存 を押します。- 接続を確認 を押します。1秒の無音を送ります（約 $0.0001）。
モデルは gpt-transcribe に固定です。開発時（pnpm dev）に限り、git で無視される .env ファイルの OPENAI_API_KEY も読みます。配布用のビルドは .env を読みません。
#OpenAI 互換のエンドポイント
Ferret は POST <base>/v1/audio/transcriptions（multipart: file、model、response_format=json、language、prompt）を送ります。OpenAI の文字起こしのルートを実装したサーバー向けの作りです。
- 処理 を OpenAI互換（自前のGPU・Groqなど） にします。
- 接続先の Base URL と モデル（エンドポイント側のモデル名）を入れます。
- サーバーがキーを求めるなら、接続先のAPIキー（省略可） を入れて 保存 を押します。
- 接続を確認 を押します。エラーには原因が出ます。たとえば Base URL の誤り（
/v1/audio/transcriptionsが無い）、キーの拒否、知らないモデル名などです。
| サーバー | Base URL | モデル（例） |
|---|---|---|
| speaches （新しいタブで開きます）（旧 faster-whisper-server） | http://localhost:8000/v1 | Systran/faster-whisper-small |
vLLM （新しいタブで開きます）（vllm serve openai/whisper-large-v3） | http://localhost:8000/v1 | openai/whisper-large-v3 |
| Groq （新しいタブで開きます） | https://api.groq.com/openai/v1 | whisper-large-v3-turbo |
Ferret はこうした OpenAI 互換のサーバー向けに作っていますが、まだ Ferret との組み合わせでは試していません。URL とモデル名は、各サーバーのドキュメントにある既定値です。
- 末尾の
/v1や、貼り付けた/v1/audio/transcriptionsは保存時に取り除くので、どちらの形でも動きます。 - ユーザー名やパスワードを含む URL は受け付けません。キーが
settings.jsonに入ることはありません。 - LAN や tailnet 上の GPU マシンなら、そのアドレスを使います。たとえば
http://100.x.y.z:8000/v1。
#費用の上限
OpenAI と互換のエンドポイントでは 費用の上限 を決めます。なし か、1回 $0.10 まで から $0.50、$1（最初の設定）、$5、$20 までです。自前の GPU なら なし でよいでしょう。設定は capture.costLimitUsd に保存します（最大 1000、null は上限なし）。互換のエンドポイントは1分 $0.006 として見積もります。
次のまとまりを送ると上限を超えるときは、Ferret は送るのをやめて音声を残します。失敗した API の呼び出しは自動では再試行しません。
#キーの保存場所
設定 で入れたキーは Electron の safeStorage で暗号化し、<userData>/stt-keys.bin に書きます。アプリが settings.json にキーを書くことはありません。代わりに settings.json からキーを指したいとき（環境変数や .env の項目）は、API キーを見てください。
- macOS: キーチェーン
- Windows: DPAPI
- Linux: libsecret か KWallet。
basic_textのバックエンドしか使えないときは、キーはいまの起動の間だけメモリに置きます（ボタンが この起動に設定 になります）。
キーを削除 で消せます。<userData> のパスはファイルと環境変数を見てください。