コンテンツにスキップ

LiveCaption マニュアル

The English version is manual.md. On the website, use the language switch at the top.

LiveCaption は、会議にリアルタイムの字幕を出すシステムです。日本語と英語の間で 翻訳します。字幕の向きは会議ごとに選びます。

  • 日本語の会議に英語字幕（日本語を話さない参加者のため）
  • 英語の会議に日本語字幕（英語で聞き取るのが負担な参加者のため）

LiveCaption は会議に無言の参加者として入り、聞こえた音を字幕にします。 自分は普段どおり同じ会議に参加して発言できます。

この文書の読み方

知りたいこと 読む場所
使い始めるまでの手順 1章と2章。Windows PC 1台と Docker Desktop で動かします
会議の当日にすること 3章
予定を入れて無人で動かす 4章
用語対訳表・会議の記録・設定・困ったとき 5章〜8章
Linux で動かす 付録A（2章との違いだけ）
Tailscale のアカウント作成と細かい設定 付録B
更新・VNC・保守のコマンド 付録C
Windows ネイティブ（Docker を使わない旧方式） 付録D
仕組みと細かい設定 付録E

動かし方は3通りあります。この文書の本文は、いちばん手軽な Windows + Docker で 書いてあります。

方法 要るもの どんなとき
Windows + Docker Windows PC 1台と Docker Desktop ノートPC 1台で足ります。 会議のたびに立ち上げる
Linux + Docker Linux 機 1台と Docker 常時起動のマシンに置いて、予定した会議に無人で入らせる（付録A）
Windows ネイティブ Windows PC をもう1台と VB-CABLE Zoom 以外の会議ソフトで字幕を出す。凍結してあり、新しい機能は入りません（付録D）

Docker では、会議ソフト（Zoom）も音声装置も画面もコンテナの中にあります。ホストに 入れるのは Docker だけです。使い方は、どの方法でも同じです。 操作画面も、予定も、 用語対訳表も、会議の記録も共通です。

1. 必要なもの

品目 補足
Windows PC 1台 Intel か AMD の CPU。Apple Silicon の Mac では動きません（Zoom の Linux 版が arm64 に無いためです）。メモリは 16 GB 以上を勧めます
Docker Desktop 2.1 で入れます。WSL2 を使います
OpenAI の APIキー 文字起こしと翻訳の両方に使います。platform.openai.com で作ります
Tailscale のアカウント 操作画面を開くのに使います。閲覧URLを前もって配る会議でも使います（3.4 C）。無料の範囲で足ります。作り方は付録B.1 にあります
Zoom の会議 LiveCaption 自身に Zoom のアカウントは要りません。サインインせずに会議に入ります（「認証済みユーザーのみ」の会議を除く。4.6）

Zoom の字幕欄に字幕を出すには、会議のホストか共同ホストの協力が要ります（3.4 A）。 それ以外の見せ方（画面共有、URL配布）に権限は要りません。

文字起こしの API 料金は $0.017/分 です。1時間の会議で約1ドル、日本円で150円ほど です。翻訳の料金は無視できるほど小さいです。無音の時間も課金されるので、長い休憩では 「停止」を押します（3.3）。

2. インストール（Windows + Docker）

一度だけ行います。所要時間は、ダウンロードの待ち時間を除いて30分ほどです。

コマンドは PowerShell で打ちます。 スタートメニューで「PowerShell」と打つと開きます。 Linux で動かす場合は、同じコマンドをシェルで打ちます（付録A）。

枠で囲った部分は3種類あります。手前の一文で見分けます。

手前の一文 枠の中身
「PowerShell で次を実行します」 打ち込むコマンド
「ファイル名 に次を書きます」 テキストエディタでそのファイルに書く中身。打ち込むコマンドではありません
それ以外 画面に出てくる表示や、ブラウザで開くURL。打ち込みません

この章では、Docker を動かす PC を「ホスト」と呼びます。 Docker の言い方に 合わせています。3章から先の「ホスト」は、Zoom の会議のホストです。

2.1 Docker Desktop のインストール

docker.com から Docker Desktop を 入れます。インストーラが WSL2 も有効にします。再起動を求められたら再起動します。

入れたあと Docker Desktop を起動し、左下の表示が「Engine running」になるのを 待ちます。PowerShell で次を実行しても確かめられます。

docker version

メモリ 16 GB のマシンでは窮屈なことがあります。 コンテナ自身は 220 MB ほどですが、 WSL2 が別にメモリを確保します。足りなければ、%USERPROFILE%\.wslconfig に次を書きます （無ければ作ります）。

[wsl2]
memory=8GB

2.2 LiveCaption のダウンロード

GitHub から ZIP をダウンロードして展開します。

  1. github.com/asoy01/LiveCaption を開き、 緑の Code ボタン → Download ZIP を押します。直接のリンクは main.zip です
  2. ZIP を展開します。LiveCaption-main というフォルダができます。compose.yml が 直下にあるフォルダが LiveCaption のフォルダです（展開の仕方によっては、同じ名前の フォルダが二重にできます）
  3. そのフォルダを、日本語やスペースを含まない場所に置きます。例: C:\LiveCaption。 フォルダの名前は変えて構いません

以降のコマンドは、すべて LiveCaption のフォルダの中で実行します。PowerShell で次を 実行して、そこへ移動します。

cd C:\LiveCaption

Git で取ってきたい場合（git pull で更新したい人向け）は、付録C.1 を見てください。

2.3 .env の作成（APIキー）

設定はすべて .env という1つのファイルに書きます。PowerShell で次を実行すると、見本が コピーされ、メモ帳が開きます。

copy .env.example .env
notepad .env

開いたメモ帳で、.env に次を書きます。sk-... のところは自分のキーに置き換えて、 保存します。

OPENAI_API_KEY=sk-...

会議のときだけ立ち上げるノートPCなら、.env に次の1行を足します。

LIVECAPTION_RESTART=no

書かないと、Docker Desktop を立ち上げるたびに LiveCaption が自動で起動し、予定を 入れてあれば Zoom にまで入ります。常時つけておくマシンに置くなら、この行は書きません。

ファイル名は .env です。.env.txt ではありません。 上の copy を使えば .txt は 付きません。他の項目は、いまは触らなくて構いません（7章）。

2.4 起動

PowerShell で次を実行します。

docker compose up -d --build

初回はイメージを作るので、10分ほどかかります。2回目からは数秒です。

起動の様子はログで見ます。PowerShell で次を実行します。

docker compose logs -f

初回は、次のように Tailscale のURLが出て止まります。次の 2.5 に進んでください。

Tailscale:  TS_AUTHKEY is not set. Open the URL below to connect by hand.

To authenticate, visit:

    https://login.tailscale.com/a/110e718b012a76

Tailscale:  No address yet. LiveCaption keeps trying in the background.

ログの表示を抜けるには Ctrl+C を押します。LiveCaption は止まりません。

2.5 Tailscale の承認

LiveCaption のコンテナは、Tailscale のネットワーク（tailnet）の1台として動きます。 操作画面は、この tailnet の中からだけ開けます。閲覧URLを前もって配る会議では、 Tailscale の Funnel という機能で配信します（3.4 C）。

2 を 3 より先に済ませてください。 順番が逆だと、操作画面の https のURLが出ません （出なかったときは docker compose restart で出ます）。

  1. Tailscale の管理画面（login.tailscale.com/admin） を開きます。アカウントが無ければ、先に付録B.1 で作ってください。 どのアカウントで 作るかを、あとから変えるのは面倒です
  2. 管理画面の DNS → HTTPS Certificates → Enable HTTPS を有効にします。 操作画面を https で開くのと、Tailscale 経路の配信の両方に要ります。tailnet ごとに 1回です
  3. 2.4 のログに出たURLをブラウザで開き、自分の Tailscale アカウントで承認します。 承認は一度だけです。 状態はコンテナのボリュームに残ります
  4. 管理画面の Machines に livecaption が現れます。右端の「…」→ Disable key expiry を選びます。これをしないと、180日後にコンテナが tailnet から 外れ、操作画面が開けなくなります。Tailscale 経路で前もって配った閲覧URLも 使えなくなります

操作画面を開く端末にも Tailscale を入れて、同じアカウントでログインしておきます。 端末は、ホストの PC 自身で構いません（tailscale.com/download）。

承認が済むと、ログにアドレスと操作画面のURLが出ます。承認の前から LiveCaption は 動いているので、起動し直す必要はありません。

Tailscale:  100.x.x.x  (livecaption.tail1234.ts.net)
[10:24:31] control     also open over https: https://livecaption.tail1234.ts.net:8443

2台以上で使う、auth key で無人登録する、Tailnet Lock を使っている、tailnet に他の人を 招いている、という場合は付録Bを見てください。

2.6 操作画面のURL

操作画面は、tailnet に入っている端末のブラウザで開きます。

https://livecaption.<tailnet名>.ts.net:8443

<tailnet名> は 2.5 のログに出た名前です（tail1234 のような形）。ログに出た完全な 名前で開いてください。 短い名前やIPアドレスでは、証明書が合いません。

操作画面は、会議で画面共有しないでください。 Zoom の字幕トークンが映ります。 共有するのは閲覧画面（3.4 B）です。

2.7 用語対訳表のアップロード

専門用語を正しく出すには、用語対訳表が要ります。ZIP には表が入っていません。 表には人名や組織名が入るので、配布物には含めていません（5章）。

  1. 見本 docs/glossary-example.tsv をテキストエディタで開き、自分の会議に出る語に 書き換えて、別の名前（例: MyProject.tsv）で保存します。書式は5章にあります
  2. 操作画面の設定タブ →「用語集」→ アップロードで、そのファイルを送ります

表はコンテナのボリュームに残るので、コンテナを作り直しても消えません。 まずは見本のまま入れて動かし、あとから育てても構いません。

2.8 動作の確認

会議に入らずに、録音した音で一通り試せます。24 kHz モノラルの WAV が要ります （過去の会議の録音を、その形式に変換したものなど）。日本語やスペースを含まない フォルダ（例: C:\samples）に置きます。以下では、そのファイルを C:\samples\test.wav として書きます。

動いている LiveCaption をいったん止めてから、PowerShell で次を実行します。2行目の コマンドは、折り返さずに1行で打ちます。

docker compose stop
docker compose run --rm -v "C:\samples:/samples:ro" engine --from-file /samples/test.wav --dry-run
docker compose start

文字起こしと翻訳が流れれば、APIキーと環境は正しく入っています。--dry-run なので、 Zoom へは何も送りません。

録音が手元に無ければ、この確認は飛ばして構いません。3章の手順で、自分だけの Zoom 会議に 入れて確かめます。

これでインストールは終わりです。

3. 会議での使い方

3.1 操作画面の表示

常駐させている場合、起動は要りません。 ブラウザで操作画面を開くだけです。

LIVECAPTION_RESTART=no にしてある場合は、先に立ち上げます。 Docker Desktop を 起動してから、下のAとBのどちらか一方を行います。両方やる必要はありません。

A. Docker Desktop の画面から（2回目以降はこれが最短）

左の Containers を開き、livecaption の行の Start（▶）を押します。 これで立ち上がるので、このあと PowerShell で打つことはありません。

livecaption が一覧に無いときは、まだ作られていません。 2章のインストールを 済ませてください。

B. PowerShell から

LiveCaption のフォルダへ移動して、PowerShell で次を実行します。

docker compose up -d

立ち上げたあと

AとBのどちらで立ち上げても、ここから先は同じです。 操作画面を開きます。

https://livecaption.<tailnet名>.ts.net:8443

LiveCaption は、字幕の生成を止めた状態で始まります。 開始するまで、音は取り込まれず、 API も呼ばれません。会議に入る前に立ち上げておけます。

操作画面の見方

左が字幕、右が操作です。境目をドラッグすると幅が変わり、ダブルクリックで元に戻ります。 右は3枚のタブに分かれています。

タブ 中身 いつ見るか
この会議 いまの状態・配信する会議・見せ方・会議の記録 会議のたび
会議の管理 予定の追加・入力・削除 会議の前に
設定 音声の入力・用語集・遅延の調整・VNC・アプリの再起動 据え付けるとき
  • 当日触るものは、すべて「この会議」の側にあります
  • 設定タブの「音声の入力」は、Docker では pulse です。 コンテナの中の 仮想の音声装置なので、触りません
  • 「この会議」に赤い丸が付いたら、そのタブの中で何かが失敗しています
  • 「見せ方」の3つは畳んであります。畳んだままでも、見出しの右に 配信中 や 送信中 と 出ます
  • 操作画面は日本語と英語を切り替えられます（ヘッダの 日本語 / English）。 切り替わるのは操作画面だけで、字幕や記録は訳しません。閲覧画面は英語です

3.2 会議への参加

LiveCaption が自分で Zoom に入ります。

  1. 会議の管理タブで会議を1行足し、名前と Zoom の招待URL（https://zoom.us/j/...）を 入れます。個人リンク（/my/...）は使えません。 会議番号の入ったURLが要ります
  2. この会議タブで、その会議を選びます（左の丸印）
  3. この会議をいま始めるを押します。ボタンの下に、何が起きるかが出ます
配信 → Zoomに入る → 字幕の生成 → チャットに投げる

「いま始める」は、配信（閲覧URL）と Zoom への参加と字幕の生成をまとめて始めます。 始まるまで数十秒かかります。進み具合は「いまの状態」に出ます。止めるときは いま止めるです。

会議に入れたかどうかは、3.3 の音量メーターで分かります。入れないときは、設定タブから VNC を起動すると、Zoom の窓が何で止まっているか（待機室、パスコード、サインイン）が 見えます（付録C.3）。

ホストが AI Companion を使っている会議では、入ったときにダイアログが出ます。 放っておいて構いません。 誰も押さなくても字幕は出ます。

3.3 字幕の向きと開始

この会議タブの「字幕の向き」を、会議ごとに選びます。

選ぶもの どんな会議か 出る字幕
日本語 → 英語 日本語で行う会議 英語
英語 → 日本語 英語で行う会議 日本語

選んだ時点で切り替わります。会議の途中で変えても構いません。逆の言語が混ざったときは、 訳さずにそのまま出します。 前半が英語で後半が日本語といった会議でも、片方を選んで おけば足ります。次の起動もこの向きで始まります。

「いま始める」を使った場合、字幕の生成は既に始まっています。手で Zoom に入れた場合や、 止めたあとに再開する場合は、いちばん上の「いまの状態」の開始を押します。

音量メーターを見てください。 誰かが喋っているのにメーターが振れないなら、音が 届いていません。Zoom に入れていないか、Zoom 側で音声に参加できていません（8章）。

「停止」は3つとも止めます。 字幕の生成だけでなく、参加者への配信（閲覧URL）と Zoom字幕への送信も一緒に閉じます。止めたつもりで字幕が流れ続けるのを防ぐためです。 閲覧URLも使えなくなるので、休憩のたびに押すものではありません。

音量メーターは振れているのに字幕が止まったときは、「文字起こしを繋ぎ直す」を 押します。 配信と Zoom字幕はそのまま続きます。押さなくても、約15秒で自動的に 繋ぎ直します（8章）。

3.4 字幕の見せ方

見せ方は3つあり、同時に使えます。

方法 ホスト権限 読み手がすること 外に出るか
A. Zoom字幕 要る 各自が手動字幕をオンにする Zoom経由
B. 画面共有 要らない 閲覧画面を全画面にして共有する 出ない
C. URL配布 要らない 各自の端末でURLを開く Cloudflare 経由（経路を Tailscale にした会議は Tailscale 経由）

A. Zoom字幕（ホストまたは共同ホストの協力が必要）

Zoom の字幕欄に出す方法です。トークンは会議中にしか作れず、作れるのはホストと 共同ホストだけです。

  1. ホストがツールバーの「字幕」の横の矢印を押し、「手動字幕の設定」で手動字幕を 有効にします。これを先にしないと「APIトークンをコピー」は出てきません
  2. 同じ場所から「APIトークンをコピー」を選びます
  3. そのトークンを、会議のチャットなどでホストから受け取ります
  4. 操作画面の「見せ方」→ Zoomの字幕に流す を開き、トークンを貼って登録を 押します。入力欄は伏せ字で、登録すると空になります
  5. 同じ枠の開始を押します。Zoom への送信の開始で、いちばん上の「開始」とは 別のボタンです。まず捨て字幕が3つ流れます。受信側は、字幕が流れ始めるまで 手動字幕をオンにできません

自分がホストでない会議で、トークンの貼り付けをホストに任せるには「ホスト用URL」が 使えます（4.5）。

Zoom の自動字幕はオフにしてもらってください。 オンのままだと、LiveCaption の字幕が 押し出されて読めなくなります。

右上に Zoom: 送信中（失敗 3） のように失敗の数が出たら、トークンが切れたか会議が 変わっています。トークンを取り直して登録し直します。

B. 画面共有

ホスト権限が要らず、字幕が外に出ません。

  1. 操作画面の「見せ方」→ 閲覧画面を自分で開く → 閲覧画面を開くを押します
  2. F11 で閲覧画面を全画面にします
  3. 自分が会議に出ている PC から、閲覧画面を開いたブラウザの窓を共有します

閲覧画面は tailnet の名前で開くので、共有する PC が tailnet に入っている必要があります。 画面共有の映像は圧縮されるので、小さい字は潰れます。 2台目の端末から読めるか 確かめてください。

C. URL配布

ホスト権限が要りません。閲覧URLとQRコードを配り、各自が自分のスマホやノートで開きます。

  1. この会議タブで会議を選び、「見せ方」→ ブラウザで見てもらう を開きます
  2. 配信を開始を押します（「いま始める」を使った場合は、既に始まっています）。 表示が 配信: 中 になります
  3. URL をコピーするか、QRコードを保存で PNG にして、チャットに載せます。 会議の管理で印を付けてあれば、Zoom のチャットへ自動で投げます（4.4）

配信の経路は2つあり、会議ごとに選びます。 会議の管理で、会議ごとの 「配信の経路」を選びます。通常は Cloudflare のままで構いません。

Cloudflare（通常） Tailscale
準備 要りません tailnet の設定が1回要ります（付録B.6）
閲覧URL 配信を始めるたびに変わります 会議ごとに決まっていて、変わりません
前もって配れるか 配れません。配信を始めてから配ります 配れます。会議の管理に、配信の前から URL と QR が出ます
字幕が通る中継サーバ Cloudflare Tailscale

URLはその場で配れば足ります。 4.4 の自動投稿を使えば、配信を始めたあとで Zoom のチャットへ URL と QR が届きます。

Tailscale にするのは、閲覧URLを前もって配りたい会議だけです。 Zoom の招待や 案内のメールに閲覧URLや QR を載せる場合です。Tailscale 経路では、つながらない人が 出ることがあります（付録B.7）。

  • 配信するのは選んである1つだけです。 選んでいない会議の閲覧URLは開けません。 別の会議を選び直せば、そちらに切り替わります。配信の経路も、その会議の経路に 切り替わります
  • 配信中は、その会議の経路を変えられません。 先に配信を停止してください
  • 「見せ方」の「経路」を変えても、その会議の経路として保存されます。会議の管理で 選ぶのと同じです
  • Tailscale 経路の閲覧URLは、配信していない間も開けます。 そのあいだは 「いまは配信していません」という画面が出て、10秒ごとに読み直します。配信を 始めると、そのまま字幕に切り替わります。早めに QR を開いた人は、そのまま待てます。 字幕も会議名も、配信を始めるまでは見えません
  • Tailscale 経路の URL は固定なので、漏れたら使われ続けます。 漏れたら会議を消して 作り直してください
  • 外に出せない内容を扱う会議では、URL配布を使わないでください。 どちらの経路でも、 字幕は中継サーバを通ります。画面共有を使います
  • Tailscale 経路で初めて配信を開始するときに失敗したら、Funnel がまだ有効になって いません。付録B.6 を見てください

3.5 参加者への案内

会議の冒頭で、字幕を読む人に次を伝えます。

  • 各自が手動字幕をオンにすること（A の場合）。オンにした人にしか字幕は見えません
  • 字幕の表示領域をドラッグして広げること。 既定は4行です。4行では翻訳を読む余裕が ありません

3.6 終了

会議ごとにアプリを終わらせる必要はありません。 「いま止める」か「停止」を押せば、 API も呼ばれず、課金も止まります。次の会議までそのままにしておけます。

LIVECAPTION_RESTART=no のノートPCでは、終わったら止めます。止め方は2通りあり、 次に立ち上げるときの手間が変わります。

止め方 コンテナ 次に立ち上げるとき
Docker Desktop の Stop（■）、または docker compose stop 残る Docker Desktop の Start を押すだけ
docker compose down 消える PowerShell で docker compose up -d

普段は Stop で足ります。 設定・会議の一覧・記録・Tailscale の登録はボリュームに あるので、どちらで止めても残ります。down -v は使わないでください。 ボリュームまで消えます。

4. 予定した会議の自動処理

予定を入れておけば、時刻が来たときに自動で動きます。 常時起動のマシンに置く 使い方（付録A）を想定していますが、会議の前に立ち上げてあれば、ノートPCでも同じように 動きます。

自動で行うのは次の4つです。3.2 の「いま始める」と同じ動きを、時刻で始めます。

  1. 会議を選び、配信を開始する
  2. Zoom に参加する
  3. 字幕の生成を開始する
  4. 会議が終わったら、離脱して停止する

字幕APIトークンだけは自動で取れません。 会議中にホストしか作れないためです。 受け取り方は 4.5 にあります。

4.1 予定の入力

会議の管理タブで、会議の行に入力します。

欄 意味
開始 会議の開始時刻
毎週 同じ曜日・同じ時刻で繰り返す
Zoom 招待URL（https://zoom.us/j/...）か会議番号。空なら自分では参加しません
配信の経路 Cloudflare（通常）か Tailscale。閲覧URLを前もって配るなら Tailscale（3.4 C）
何分前から 指定した分だけ前に、配信と Zoom 参加を始めます。既定は2分
無音で終了（分） 文字起こしが指定した分だけ出なければ、会議が終わったとみなします。既定は10分
安全上限（分） 無音でなくても、指定した時間で必ず止めます。既定は180分
この会議を自動で開始する この印が付いた会議だけが自動で動きます

「自動で開始する」の既定は切りです。 自動で開始すると、人が見ていなくても字幕が 外に出ます。外に出せない内容を扱う会議には、印を付けないでください。

繰り返しは「毎週」だけです。

4.2 動作の確認

予定の状態は、この会議タブのいちばん上、「いまの状態」に出ます。

いまの状態
[開始] [停止] [文字起こしを繋ぎ直す]  止まっている
待機中
2026-09-25 10:00  定例会議           あと 23 分
2026-09-27 13:00  共同研究者会議     あと 2 日 3 時間
[いま止める] [次の予定を飛ばす]

動いている間は、無音で終了するまでの残り時間と、安全上限までの残り時間が出ます。

  • 失敗は、押して消すまで残ります。 内容を確かめたら「了解」で消してください
  • 「次の予定を飛ばす」は、その回だけ休むときに使います。予定そのものは残ります
  • 会議が重なったときは、動いているほうを続け、あとの会議を飛ばします

4.3 予定を待たない開始

3.2 のこの会議をいま始めるです。予定の入っていない会議や、予定より早く始まった会議に 使います。予定の回と同じ動きをします。

4.4 Zoom のチャットへの投稿

字幕が出たら、会議のチャットに閲覧URLとQRコードを投げられます。 会議の管理で 「字幕が出たら、ZoomのチャットにURLとQRを投げる」に印を付けてください。既定は 切りです。

投げる文面は英語で固定です。括弧の中だけは、字幕の向きに合わせて Japanese to English か English to Japanese になります。

Live captions for this meeting (Japanese to English):
https://xxxx-xxxx-xxxx.trycloudflare.com/v/xxxxxxxx
Open the link in any browser. No app or sign-in needed.

URL は配信の経路で変わります。上は Cloudflare の例です。Tailscale 経路の会議では https://livecaption.<tailnet名>.ts.net/v/xxxxxxxx になります。

2回投げます。予定の開始時刻と、その3分後です（「いま始める」では、押した時と 3分後）。Zoom のチャットは、自分が入る前の発言が見えません。 定刻に入ってきた人と、 少し遅れて入ってきた人の両方に届かせるための2回です。

3分より後に入ってきた人には届きません。 遅れて入る人が多い会議では、会議の途中で 「見せ方」→ ブラウザで見てもらう の中の Zoomのチャットに投げるを手で押して ください。または、その会議の経路を Tailscale にして、Zoom の招待に閲覧URLを書いて おきます（3.4 C）。

投稿は Zoom の窓を画面操作で動かすので、届いたかどうかは確かめられません。 仕組みと弱さは付録E.3 にあります。

4.5 ホスト用URL

自分がホストでない会議でも、ホストに協力してもらえば Zoom字幕を出せます。

会議ごとに、閲覧URLとは別の秘密のURLを作れます。会議の管理のホスト用URLを 出すを押すと表示されます。

ホスト用URLは、配信の経路を Tailscale にした会議にしか出ません。 Cloudflare では、 Zoom のトークンが Cloudflare の中継サーバを通ってしまうためです。Cloudflare 経路の 会議では、トークンを受け取って自分で操作画面に貼ります（3.4 A）。

ホスト用URLはホストにだけ渡してください。 閲覧URLと取り違えないでください。 ホスト用URLを持つ人は、その会議の字幕を Zoom へ流し込めます。

ホストがホスト用URLをブラウザで開くと、トークンを貼る画面が出ます。貼って送ると、 LiveCaption が Zoom へ字幕を送り始めます。

受け付けるのは次の場合だけです。

  • いま配信している会議であること
  • 配信の経路が Tailscale であること
  • 予定の前後30分か、その会議を動かしている間であること
  • 1回だけ（2回目からは断ります。操作画面の「もう一度受け付ける」で開き直せます）

URLが漏れたら、その会議を消して作り直してください。

4.6 Zoom 側の注意

  • 「認証済みユーザーのみ」の会議には、サインインしないと入れません。 その場合だけ、 VNC で Zoom の窓を開いてサインインします（付録C.3）。一度サインインすれば、状態は ボリュームに残ります
  • 会議に入れたのに音が来ない状態が5分続くと、操作画面に「Zoomから音が来ない」と 出ます。待機室で止まっている、パスコードが違う、更新のダイアログが出ている、の いずれかです。VNC で画面を見てください
  • Zoom から出る手段は、Zoom を終了させることだけです。 人が手で入れた会議は 終了させません。LiveCaption が参加させたときだけ終了させます

5. 用語対訳表

専門用語をどれだけ正しく出せるかは、用語対訳表で決まります。LiveCaption で主に 保守するのは、用語対訳表です。

表の作成

分野ごとに1ファイル作ります。 拡張子は .tsv です。見本が glossary-example.tsv にあります。見本を自分の会議に出る語に 置き換えて、操作画面からアップロードします（2.7）。

ZIP には表が入っていません。 人名や組織名を入れると表はよく効きますが、そうした語を 配布物に入れたくないためです。表は各自の手元に残ります。

分野ごとに分ける理由は2つあります。1つは、会議に要らない語を外せることです。もう1つは、 文字起こしに渡せる語数に上限（既定 200）があることです。1つの大きな表を全部の会議で 使うと、関係の無い語が上限を占めて、本当に要る語が渡らなくなります。

書式

1行に1語、3列をタブで区切ります。

日本語（正しい表記）  <TAB>  English  <TAB>  よくある誤認識（カンマ区切り）

用語対訳表は2か所で使います。

  1. 文字起こし。 日本語と英語の表記を、キーワードとして文字起こしのモデルに渡します。 用語を正しく聞き取る確率が上がります
  2. 翻訳。 表全体を翻訳のプロンプトに入れ、第3列から置換規則を組み立てます

効くのは第3列です。 文字起こしはそれでも間違えます。実際に出た誤りを書いておくと、 翻訳側がそこから正しい用語を復元できます。

列の区切りはタブです。スペースにすると、行全体が1つの日本語の語として読まれ、英語も 誤認識も登録されません。 見た目では分かりません。

会議ごとの表の選択

操作画面の設定タブにある「用語集」の行は畳んであります。いまどの表を使っているかは、 畳んだままでも見えます（表の名前と合計の語数）。行を押すと一覧が開くので、使う表に チェックを入れてください。チェックした時点で切り替わります。

チェックの下の行に、合計の語数と、文字起こしに渡す語の数が出ます。上限を超えると語数が 赤くなるので、表を減らしてください。 超えた分は文字起こしに届きません。

  • 表が8個以上になると、一覧の上に絞り込みの欄が出ます。チェックを入れた表は、絞り込みで 他が消えても残ります
  • 「全部選ぶ」「全部外す」は、絞り込みで隠れている表にも効きます
  • LiveCaption は表の選択を覚えています。次の起動も同じ組み合わせで始まります
  • 同じ日本語が複数の表にあるときは、1つにまとめます。英語は最初に見つけた表のものを 使い、第3列の誤認識は全部の表から集めます。英語が食い違ったときは、画面に出します

会議後の表の更新

  1. 会議の記録の .md を開きます（操作画面の「会議の記録」からダウンロードできます）。冒頭に、 その会議で使った表の名前が書いてあります
  2. 訳が誤っている用語を探します
  3. 元の誤った文字起こしを、その用語が載っている表の第3列に足します
  4. 表をアップロードし直します

第3列に入れるものは3種類あります。

  • 同音の誤変換。 例:「光軸」が「校則」になる
  • 英語の誤認識。 略語が普通の英単語に化ける。例: PID が「peed」になる
  • 前の語の末尾が食い込んだ形。 文字起こしは音の切れ目を誤ります。「この回折」が 「子の解析」になったなら、回折 の行の第3列に「子の解析」を入れます。前の語ごと 入れてください。 文字起こしがそう書き起こすからです

推測で入れないでください。 意味の通らない語が残ったら、話していた人に聞きます。 音声だけから正解を当てられないことがあります。

足した語は、会議の前に実際に試してください。 その語を含む文を話して、字幕に正しい 英語が出るかを見ます。表に書いただけでは、効いている証拠になりません。

6. 会議の記録

LiveCaption は既定で会議の記録を残します。 文字起こしと、それを訳した字幕が対に なっています。用語対訳表を育てる材料になります。

記録のダウンロード

記録はコンテナの中に溜まります。操作画面からダウンロードしてください。

操作画面のこの会議タブ、「会議の記録」にボタンが2つあります。

ボタン 中身
読める形 (.md) 人が読む形。文字起こしと字幕が対になっています
原本 (.jsonl) 1行が1文。遅延の実測も入っています。落ちたあとに .md を作り直すときと、遅延を見るときに使います

保存先は、操作画面を開いている端末のダウンロードフォルダです。

  • ダウンロードできるのは最新の1本だけです。 どれが対象かは、ボタンの下に出ています。 古い記録が要るときは付録C.4 を見てください
  • 会議の最中でもダウンロードできます。 そのときの .md には「会議はまだ続いている」 と書きます
  • 「停止」を押すと、記録はそこで区切られます（3秒ほど後）。停止のあとにダウンロードすると、 終わった会議の記録が手に入ります。休憩で止めてすぐ再開したときは区切りません
  • 1文も出なかったときは、ファイルを残しません

記録を残したくない会議では、その会議の間だけ記録を切る手段はありません。会議の後に 付録C.4 の手順で消してください。

7. 設定

設定は .env に書きます。 APIキーも、マシンごとの違いも、遅延の調整も、すべて 同じファイルです。書き方の見本は .env.example にあります。

.env の名前 何を決めるか 説明のある場所
OPENAI_API_KEY APIキー。これだけは必須です 2.3
LIVECAPTION_MEETING_CONTEXT 会議の分野。専門用語の精度が上がります 下の節
LIVECAPTION_RESTART 常駐させるか。no で会議のときだけ立ち上げる 2.3
TS_HOSTNAME tailnet でのコンテナの名前。2台以上で使うなら変える 付録B.2
TS_AUTHKEY Tailscale の auth key。手で承認するなら要りません 付録B.3
LIVECAPTION_VNC 起動した時点から VNC を動かすか 付録C.3
LIVECAPTION_SAVE_DIR 会議の記録の置き場 付録C.4
LIVECAPTION_GLOSSARY_DIR 用語対訳表の置き場 付録E.4
LIVECAPTION_IDLE_FLUSH_SEC ほか4つ 遅延の調整 付録E.4

会議の分野の指定

用語対訳表の次に効く設定です。 会議がどの分野のものかを1文で書くと、文字起こしと 翻訳の両方のプロンプトに入り、専門用語をその分野の語として解釈させられます。

LIVECAPTION_MEETING_CONTEXT=電波天文学の定例会議。受信機、較正、観測スケジュールの話題。

既定は分野を書いていない文面なので、動きますが専門用語を外しやすくなります。 会議で主に話される言語で書いてください。

用語対訳表とは役割が違います。 表は「この語はこう訳す」と個々の語を決めるもので、 この設定は「どの分野の語として読むか」をモデルに伝えるものです。両方を使います。

.env の直し方

.env を直したら、コンテナを作り直します。 .env を読むのは起動のときだけです。 PowerShell で次を実行します。

docker compose up -d

docker compose restart では読み直しません。

遅延に関わる4つは、操作画面からも変えられます。 設定タブの「遅延の調整」の行を 押すと、入力欄が開きます。数字を直して欄から離れると、その場で効きます。.env に 保存を押すと、次の起動でも同じ値で始まります。既定に戻すで元に戻ります。 意味は付録E.4 にあります。

書き間違えても会議は止まりません。 数字として読めない値は、警告を出して既定値のまま 動きます。

8. 困ったとき

症状 見るところ
何も起きない。字幕が流れない 「いまの状態」の開始を押しましたか。 起動しただけでは動きません
操作画面が開かない docker compose ps でコンテナが動いていますか。docker compose logs に Tailscale のアドレスが出ていますか。開いている端末は tailnet に入っていますか。https:// は完全な名前で開いてください（短い名前やIPでは証明書が合いません）
ログに https では出せなかった と出る Tailscale の管理画面で HTTPS を有効にしましたか（2.5）。有効にしたあと docker compose restart
ログに認証のURLが出たまま URLをブラウザで開いて承認してください（2.5）
Zoom に入れない VNC を起動して Zoom の窓を見てください（付録C.3）。待機室で止まっている、パスコードが違う、「認証済みユーザーのみ」の会議でサインインを求められている、のいずれかです
Zoom に入ったのに音量メーターが振れない 待機室で止まっている、パスコードが違う、Zoom 側で音声に参加できていない、のいずれかです。VNC で画面を見てください。5分続くと操作画面にも出ます
会議に入ると AI Companion のダイアログが出る 放っておいて構いません。 誰も押さなくても字幕は出ます。Zoom 側の設定では消せません
文字起こしの行が出ない .env の OPENAI_API_KEY。.env は compose.yml と同じフォルダにありますか。名前が .env.txt になっていませんか。 直したら docker compose up -d
文字起こしは出るが字幕が出ない 翻訳のエラーが画面に出ているはずです
会議の途中で字幕が止まる。音量メーターは振れている 文字起こしの接続が、切れないまま黙ることがあります。約15秒で自動的に繋ぎ直します。 待てなければ「いまの状態」の「文字起こしを繋ぎ直す」を押してください。「停止」は押さないでください（配信と Zoom字幕も止まります）
Zoom の字幕欄に出ない ホストの画面を見ていませんか（ホストには出ません）。相手が手動字幕をオンにしたか。トークンが今の会議のものか。右上の失敗の数
喋ると別の字幕が出る Zoom の自動字幕が動いています。 オフにしてもらってください
配信を開始できない（Cloudflare） cloudflared was not found と出たら、古いイメージのままです。イメージを作り直してください（付録C.1）
配信を開始できない（Tailscale） Funnel が有効になっていません（付録B.6）
閲覧URLが開ける人と開けない人がいる（Tailscale） Tailscale の中継サーバ側の問題です。その会議の経路を Cloudflare に変えて配信し直してください（付録B.7）
会議の管理に閲覧URLや QR が出ない その会議の経路が Cloudflare です。Cloudflare の URL は配信を始めるまで決まりません。前もって配るなら経路を Tailscale にします（3.4 C）
ホスト用URLが出ない その会議の経路が Cloudflare です。ホスト用URLは Tailscale 経路の会議にしか出ません（4.5）
表にあるのに用語を外す 文字起こしに渡す語数が上限を超えていませんか（5章）。その分野の表にチェックが入っていますか
字幕が速すぎて読めない 受信側に表示領域を広げてもらいます。LIVECAPTION_FORCE_CUT_CHARS を下げます（付録E.4）
予定の時刻になっても始まらない 「この会議を自動で開始する」に印が付いていますか。 既定は切りです。「いまの状態」に予定が並んでいるかも確認してください
会議が終わっても離脱しない 無音で終了するまでの分を確認してください。安全上限に達すれば必ず止まります
会議が早く終わったのに動き続ける 誰かのマイクが開いたままだと、無音になりません。「いま止める」を押してください
「アプリの再起動」を押したのに止まらない 常駐の設定（unless-stopped）の動きです。本当に止めるなら docker compose stop（付録C.5）
用語集が空のまま ZIP に表は入っていません（2.7）。操作画面からアップロードしてください
会議の記録が見当たらない コンテナのボリュームの中にあります。操作画面からダウンロードするのが早いです
コンテナを動かすとホストの通信が切れる（Linux） ConnMan です（付録A.2）。数十秒遅れて壊れるので、起動直後に確かめても分かりません

受信側を先に確かめてください。 送信が成功しても、受信側に字幕が表示されているとは 限りません。原因は受信側にあることが多いです。

字幕は時間では消えません。 新しい行に押し出されるまで残っています。見逃しても、 もう一度見れば済みます。

Windows ネイティブで動かしている場合の症状は、付録D.12 にあります。

付録A. Linux + Docker での違い

常時起動の Linux 機に置く場合です。 予定した会議に無人で入らせるなら、この形が 向いています。ホストがスリープしていると予定の時刻に動けないので、サスペンドしない 設定にしておいてください。

コマンドはシェルで打ちます。 2章の「PowerShell で次を実行します」は、すべて シェルに読み替えてください。.env などのファイルに書く中身は、2章と同じです。

手順も2章と同じです。違うのは、次の A.1 から A.3 の3つだけです。

A.1 Docker のインストール（2.1 の読み替え）

Docker Desktop ではなく、Docker Engine と Compose を入れます。入れ方は docs.docker.com にあります。Compose は v2 以降が要ります。

自分を docker グループに入れておくと、sudo が要らなくなります。シェルで次を 実行します。

sudo usermod -aG docker $USER

実行したあとは、ログインし直してください。 グループの変更は、ログインし直すまで 効きません。

2.2 と 2.3 にあたる部分では、シェルで次を実行します（copy が cp になるだけです）。

unzip main.zip
cd LiveCaption-main
cp .env.example .env

A.2 ConnMan を使っているホストの設定（2章には無い手順）

ネットワーク管理が ConnMan の場合は、先に ConnMan の設定を直してください。 ConnMan は Debian の一部の構成や、組み込み向けのマシンで使われています。使っているか どうかは、シェルで次を実行すると分かります。使っていなければ、この節は飛ばして 構いません。

systemctl is-active connman

ConnMan は見つけた機器を全部管理しようとしますが、既定の除外一覧に docker・ veth・br-・tailscale が入っていません。 そのため Docker の作る仮想の線を掴み、 DHCP に失敗し、リンクローカルのアドレスを振り、ホストの既定経路までその線へ向けます。 ホストの外向き通信が、コンテナの中へ吸い込まれて消えます。

症状が分かりにくいので注意してください。 DHCP の待ち時間があるので、コンテナの 起動から数十秒遅れてホストの通信が壊れます。Zoom から見ると「入室はできるが、 30〜40秒後に音声を失って切断」という形になります。

/etc/connman/main.conf に次を書きます。

NetworkInterfaceBlacklist = vmnet,vboxnet,virbr,ifb,ve-,vb-,docker,veth,br-,tailscale

書いたら、ConnMan と tailscaled を再起動します。シェルで次を実行します。

sudo systemctl restart connman
sudo systemctl restart tailscaled

tailscale も忘れずに除外一覧へ入れてください。 docker だけを除外すると、今度は ConnMan が tailscale0 を掴んで落とします。このとき tailscale status は 「Online: True」と表示します。 壊れているのはデータの通り道だけなので、状態表示では 気づけません。確かめるには、シェルで次を実行します。

ip addr show tailscale0

A.3 常駐（2.3 の読み替え）

LIVECAPTION_RESTART=no は書きません。既定（unless-stopped）のままにすると、ホストを 再起動してもコンテナが自分で戻ってきます。予定した会議に備えるには、この常駐が要ります。

付録B. Tailscale のアカウントと細かい設定

アカウントをまだ持っていない場合は、B.1 を先に読んでください。

B.2 から先は、2.5 では足りない場合のものです。2.5 の手順は、自分ひとりの tailnet に 1台だけ置く場合を想定しています。Funnel に関わる節（B.3 と B.5 の nodeAttrs、 B.6、B.7）は、配信の経路を Tailscale にする会議があるときだけ要ります。

B.1 アカウントの作成

Tailscale 独自のアカウントは作れません。 メールアドレスとパスワードで登録する方法が 無く、Tailscale のパスワードというものが存在しません。 既に持っている Google・Microsoft・GitHub・Apple のどれかでサインインします（勤務先が Okta や OneLogin を使っているなら、それも選べます）。

  1. login.tailscale.com/start を開きます
  2. サインインに使うアカウントを選び、サインインします
  3. tailnet が1つできます。名前は tail1234.ts.net のような形で、自動で決まります。 この名前が、操作画面と閲覧URLの一部になります（2.6）

どのアカウントで作るかを、先に決めてください。

  • 勤務先や大学のアカウントで作ると、同じドメインの人と同じ tailnet に入ることが あります。 その組織の誰かが既に tailnet を作っていれば、そこへ参加します。 自分だけで使うなら、個人のアカウントで作ってください
  • GitHub と Apple で作った tailnet は、あとからサインインの方法を変えられません。 他の方法（Google・Microsoft など）どうしなら変えられます。迷うなら Google か Microsoft にしてください
  • 操作画面を開く端末も、同じアカウントでログインします。 別のアカウントの端末からは 操作画面に届きません

無料の Personal プランで足ります。 利用者6人までで、機器の台数に制限はありません。 LiveCaption が使うのは、コンテナ1台と、操作画面を開く自分の端末だけです。最新の条件は tailscale.com/pricing にあります。

アカウントができたら、2.5 に戻ってください。

B.2 2台以上での使用

承認したノードには名前が付きます。既定は livecaption です。2台目からは、起動する前に .env に次を書いて、名前を変えてください。

TS_HOSTNAME=livecaption-note

同じ名前を2台が名乗っても、共有はされません。あとから来たほうが livecaption-1 に 付け替えられ、前もって配った閲覧URLが使えなくなります。

.env はマシンごとに1つです。別のマシンへ移るときは、手で持っていきます。

B.3 auth key での登録

2.5 の手での承認の代わりに、auth key を .env に書いて無人で登録できます。 Tailscale の管理画面（Settings → Keys → Generate auth key）で作ります。

項目 値 理由
Reusable on ボリュームを作り直すたびに要ります
Ephemeral off ephemeral のノードは名前が毎回変わり、閲覧URLが使えなくなります
Tags tag:livecaption タグ付きのデバイスには鍵の期限が適用されません。Disable key expiry が要らなくなります

タグを使うには、先に ACL に書いておきます（B.5）。Funnel を使うので、nodeAttrs も 要ります。管理画面の Access Controls にある JSON に、次を足します。

"tagOwners": { "tag:livecaption": ["autogroup:admin"] },
"nodeAttrs": [ { "target": ["tag:livecaption"], "attr": ["funnel"] } ]

nodeAttrs の行を忘れないでください。 タグを付けたデバイスは autogroup:member から 外れるので、nodeAttrs が無いと Funnel を失います。タグを付けない場合は、2.5 と同じく Disable key expiry を有効にします。

できた鍵を .env に次のように書きます。

TS_AUTHKEY=tskey-auth-xxxxxxxx

書いたら docker compose up -d でコンテナを作り直します。

B.4 Tailnet Lock を使っている場合

手での承認でも auth key でも、署名が要ります。 コンテナは新しいノードで、署名鍵を 持ちません。署名の無いノードは、登録はされますが他のノードと通信できません。

Tailnet Lock を使っているかどうかは、署名鍵を持っているマシンで次を実行すると 分かります。

tailscale lock status

Tailnet Lock is NOT enabled. と出たなら、この節は読み飛ばしてください。

auth key を使う場合は、鍵に署名します。 署名鍵を持っているマシンで次を実行し、 出てきた署名済みの鍵を .env の TS_AUTHKEY に書きます。

sudo tailscale lock sign tskey-auth-xxxxxxxx

署名済みの鍵で登録したノードには、登録の時点で署名が付きます。auth key は reusable なので、 1本で何台でも署名済みのノードを立てられます。

手で承認する場合は、ノード鍵に署名します。 承認したあと、コンテナの中で次を実行すると ノード鍵が出ます。

docker compose exec engine tailscale lock status

そのノード鍵に、署名鍵を持っているマシンで署名します。

sudo tailscale lock sign nodekey:xxxxxxxx

署名は一度きりです。 状態は tailscale ボリュームに残ります。

署名済みの auth key は、扱いに気をつけてください。 その鍵自体が「信頼された 署名鍵」として tailnet に登録されるので、鍵を持っている人は、署名済みで信頼された ノードを好きなだけ足せます。 Tailnet Lock の保護をそのまま迂回できてしまいます。 この点でも、手での承認のほうが安全です。

B.5 ACL — 誰がどこへ届くかの設定

ACL は、tailnet の中で「誰がどのノードへ繋げるか」を決める規則です。 Tailscale の 管理画面（Access Controls）で、JSON を1つ書きます。tailnet 全体で1つなので、 書き換えると他のノードにも効きます。

自分ひとりの tailnet なら、既定のままで動きます。 既定は「全員が全部へ繋げる」 なので、この節を読み飛ばしても LiveCaption は使えます。読む必要があるのは次の2つの 場合です。

(1) tailnet に他の人を招いている場合。 絞らないと、その人たちも操作画面を開けます。 開ければ、終了も、配信の開始も、会議の文字起こしの閲覧もできます。操作画面には 認証がありません。 守っているのは「どこから届くか」だけなので、ACL で絞らないと 守るものがありません。

自分の端末だけに絞る例です。autogroup:member を使わず、自分のユーザー名で書きます。

{
  "acls": [
    {"action": "accept", "src": ["your-name@example.com"],
     "dst": ["tag:livecaption:8081,8443,6080,6443"]}
  ]
}

(2) タグを付けたノードで Funnel を使う場合。 既定の ACL では autogroup:member に funnel が付いていますが、タグを付けたデバイスは autogroup:member から外れます。 下の nodeAttrs を足さないと、配信を開始できません。

{
  "tagOwners": {"tag:livecaption": ["your-name@example.com"]},
  "nodeAttrs": [{"target": ["tag:livecaption"], "attr": ["funnel"]}]
}

変更はすぐ効きます。 ノードを起動し直す必要はありません。書き方の詳細は tailscale.com/kb/1018/acls にあります。

B.6 Funnel が有効にならないとき

Tailscale 経路の会議で「配信を開始」が失敗したときは、tailnet 側で次のどちらかが 有効になっていません。失敗の理由は、ボタンの下に出ます。

  1. HTTPS 証明書。 管理画面の DNS → HTTPS Certificates → Enable HTTPS（2.5）
  2. funnel のノード属性。 既定の ACL では autogroup:member に付いていますが、 ACL を書き換えている tailnet や、タグを付けたノードでは外れていることがあります （B.5 の nodeAttrs）

B.7 Funnel で閲覧URLが開けない人がいるとき

Tailscale 経路では、同じ閲覧URLでも、開ける人と開けない人が出ることがあります。 開けない人の画面には、接続や証明書のエラーが出ます。

Funnel で配信すると、閲覧URLの名前は Tailscale の中継サーバを指します。中継サーバは 2台あり、閲覧者がどちらに繋がるかは選べません。片方の中継サーバだけが LiveCaption に届かない状態になることがあり、そちらに当たった人だけが開けません。 中継サーバは Tailscale が運用しているので、こちらの設定では直せません。

いちばん起きやすいのは、Funnel を張った直後です。 実測では、張ってから 中継サーバが応答するまでに、初回で約1.5分、張り直しで16〜30秒かかりました。 そこで LiveCaption は、Tailscale 経路の会議が1つでもあれば、起動した時点で Funnel を張り、そのまま張っておきます。 「配信を停止」を押しても Funnel は 外さず、閲覧URLには「いまは配信していません」の画面を出します（3.4 C）。 会議が始まる頃には、中継サーバの準備が済んでいます。

コンテナを起動した直後の1〜2分は、開けない人が出ることがあります。 会議の 直前にコンテナを起こす使い方では、会議の数分前に起こしてください。

会議中に起きたら、その会議の経路を Cloudflare に変えて配信し直します。閲覧URLが 変わるので、チャットに投げ直します（4.4）。配信の停止と開始を押し直しても、 Funnel は張り直されないので効きません。

閲覧URLを前もって配る必要が無い会議は、Cloudflare 経路にしてください。

付録C. 更新・VNC・保守

C.1 更新

ZIP で入れた場合。 新しい ZIP をダウンロードして展開し、LiveCaption のフォルダに上書き します。.env は新しい ZIP に入っていないので、上書きしても消えません。用語対訳表・ 会議の一覧・記録・Tailscale の登録は Docker のボリュームにあるので、フォルダを丸ごと 入れ替えても消えません。

そのあと、イメージを作り直します。フォルダを更新しただけでは、動いている中身は 変わりません。 PowerShell で次を実行します。

docker compose up -d --build

Git で入れる場合。 2.2 の代わりに、PowerShell で次を実行します。

git clone https://github.com/asoy01/LiveCaption.git
cd LiveCaption

更新は git pull のあと、同じく docker compose up -d --build です。.env は Git に 入らないので、git pull で消えません。

C.2 Docker のコマンド一覧

会議のために打つコマンドはありません。以下は据え付けと保守で使うものです。 LiveCaption のフォルダの中で、PowerShell で実行します（Linux ではシェルで、同じものを 実行します）。

docker compose up -d --build     # 作って起動する。最初の1回と、更新したあと
docker compose up -d             # .env を直したあと（作り直す）
docker compose logs -f           # 起動の様子と、動いている間のログ
docker compose ps                # 動いているか
docker compose restart           # 入れ替えずに立ち上げ直す
docker compose stop              # 止める。ホストを再起動しても上がってこない
docker compose start             # 止めたものを戻す
docker compose down              # コンテナを消す。ボリュームは残る

docker compose exec engine bash  # 中に入る
docker compose cp engine:/app/local/transcripts ./transcripts   # 記録を全部取り出す

docker compose down -v は使わないでください。 ボリュームまで消えるので、会議の 一覧も、閲覧URLも、Tailscale の登録も、Zoom のサインインも失われます。

C.3 VNC — コンテナの中の画面

普段は要りません。 コンテナの中の Zoom はサインインせずに会議に入ります。 使うのは次の2つの場面です。

  • 自動参加が詰まったとき。 待機室で待たされている、パスコードが違う、更新の ダイアログが出ている、といった理由は画面を見れば分かります
  • サインインが要る会議のとき。 主催者が「認証済みユーザーのみ」にしている会議には、 サインインしないと入れません。その場合だけ、VNC で Zoom の窓を開いてサインインします。 状態はボリュームに残るので、一度で済みます

操作画面の設定タブ →「VNC」→「起動」を押すと、次のURLで中の画面が見えます。

https://livecaption.<tailnet名>.ts.net:6443/vnc.html

VNC にはパスワードがありません。 守っているのは tailnet の境目だけです。使うときだけ 起動して、終わったら止めてください。 会議の最中でも起動・停止できます。

コンテナの中で端末も開けます。何も無い所で右クリック → Terminal emulator。

クリップボードを手元の PC と同期したいときは、ブラウザではなく VNC クライアントで livecaption.<tailnet名>.ts.net:5900 に繋ぎます。起動と同時に VNC を動かしたいときは、 .env に LIVECAPTION_VNC=1 を書きます（常用しないでください）。

C.4 会議の記録の取り出しと削除

記録はコンテナの state ボリュームの local/transcripts/ にあります。操作画面から ダウンロードできるのは最新の1本だけなので、古い記録はホストから取り出します。 PowerShell で次を実行します。

docker compose cp engine:/app/local/transcripts ./transcripts

記録は溜まっていきます。消すのは手作業です。 PowerShell で次を実行します。

docker compose exec engine ls /app/local/transcripts
docker compose exec engine rm /app/local/transcripts/live-caption_2026-09-01_*

ホストのフォルダに直接書かせたいときは、compose.yml の volumes: にホストの フォルダを足してください。 .env の LIVECAPTION_SAVE_DIR はコンテナの中のパス なので、そこに書いてもホストのフォルダにはなりません。

C.5 常駐の仕組み

コンテナは restart: unless-stopped で動いています。落ちても、ホストを再起動しても、 自分で戻ってきます。そのため、操作画面の「アプリの再起動」は、止めるのではなく 再起動になります。 本当に止めるときは、ホストで docker compose stop を実行します。 止めると操作画面も消えるので、外からは戻せません。

.env の LIVECAPTION_RESTART で、常駐と操作画面のボタンの両方が変わります。

LIVECAPTION_RESTART 常駐 ボタン 押すと
unless-stopped（既定） する アプリの再起動 落ちて、数秒で戻ってきます
no しない アプリの終了 止まったままになります。戻すのは docker compose up -d

付録D. Windows ネイティブ（凍結）

この方法は凍結してあります。 動いているものはそのまま残してありますが、新しい機能は 入りません。この付録は、既に Windows ネイティブで動かしている人のためのものです。 これから据え付けるなら、2章の Docker を使ってください。

この方法では、字幕のための Windows PC を1台用意します。 以下ではこの PC を 「字幕PC」と呼びます。字幕PC は会議に無言の参加者として入るので、自分が発言に使う PC とは別に要ります。

欠点

  • PC が2台要ります。 字幕PC のサウンド出力は CABLE Input に向けたままにするので、 同じ PC で自分が会議参加者として入ることはできません
  • サウンドデバイスの取り合いが起きます。 他のアプリが出力先を変えると、字幕が黙って 止まります
  • 凍結してあります。 新しい機能は入りません

利点

  • Zoom 以外の会議ソフトでも字幕を出せます。 音は CABLE Output から取るので、 出力先に CABLE Input を選べる会議ソフトなら何でも使えます（Teams、Google Meet、 Webex など）。ただし自動参加とチャットへの投稿は Zoom 専用です。他の会議ソフトでは、 人が手で会議に入れてください
  • Docker が要りません。 WSL2 もイメージのビルドも要りません

インストールは字幕PCで一度だけ済ませます。

D.1 VB-CABLE のインストール

vb-audio.com/Cable/ からダウンロードします。 インストーラは管理者権限で実行し、終わったら PC を再起動してください。

D.2 CABLE の周波数設定（48000 Hz）

再起動後、Windows のサウンド設定で次の2つを確認します。

デバイス 形式
CABLE Input（再生） 48000 Hz、16ビット
CABLE Output（録音） 48000 Hz、16ビット

両方を 48000 Hz に揃えてください。 食い違うと Windows が再サンプリングし、音が 乱れます。

D.3 pixi のインストール

pixi は Python の環境を作るソフトです。Python を別に入れる必要はありません。

PowerShell で、次のどちらかを実行します。

winget install prefix-dev.pixi

powershell -ExecutionPolicy ByPass -c "irm -useb https://pixi.sh/install.ps1 | iex"

pixi を入れたあとは、PowerShell を開き直してください。 開き直さないと、PATH の 変更が反映されません。開き直したら、PowerShell で次を実行して確かめます。

pixi --version

D.4 LiveCaption の取得

2.2 と同じです。ZIP を展開して、日本語やスペースを含まない場所（例: C:\LiveCaption）に 置きます。Git を使うなら git clone https://github.com/asoy01/LiveCaption.git です。

D.5 Python 環境の構築

LiveCaption のフォルダの中で、PowerShell で次を実行します。

pixi install

必要なパッケージが .pixi フォルダの中に入ります。pixi はシステムの Python を 変更しません。初回は数分かかります。

D.6 APIキーの設定

2.3 と同じです。.env を作り、OPENAI_API_KEY を書きます。LIVECAPTION_RESTART は Docker 用なので書きません。

D.7 音声経路の確認

この確認に会議も APIキーも要りません。CABLE Input にサイン波を流しながら、 CABLE Output から読み返します。PowerShell で次を実行します。

pixi run python scripts/cable_loopback.py

送った振幅が返ってくれば、VB-CABLE は正常です。

--- 本体が既定で選ぶもの: 2 'CABLE Output (VB-Audio Virtual ' [MME] ---
  区間 39、音あり 39（100%）  最大 peak 0.299  取りこぼし 0
  => 通っている

D.8 スタートメニューへの登録（任意）

InstallToStartMenu.bat をダブルクリックします。スタートメニューに LiveCaption の 項目が入ります。

Windowsキー  ->  「livecaption」と打つ  ->  Enter

この項目はウィンドウを開きません。 タスクトレイに常駐し、アイコンを右クリックして 操作画面・ログ・終了を選びます（D.11）。起動の様子を見たいときは、StartLiveCaption.bat を手で実行してください。

フォルダを移動・改名したら、InstallToStartMenu.bat をもう一度実行してください。 登録を消すときは、PowerShell から InstallToStartMenu.bat -Remove を実行します。

D.9 用語対訳表の置き場

Windows ネイティブでは、表を etc/glossary/ に直接置きます。PowerShell で次を実行すると、 見本をそこへコピーできます。

copy docs\glossary-example.tsv etc\glossary\MyProject.tsv

書式と選び方は5章と同じです。起動時に使う表を決めることもできます。

pixi run caption --web --glossary 表の名前1 表の名前2

D.10 会議での使い方の違い

起動。 StartLiveCaption.bat をダブルクリックします。操作画面がブラウザで開きます。

http://localhost:8081              操作画面   <- この画面は共有しないこと
http://localhost:8080/v/<ランダム>  閲覧画面   <- 共有するのはこちら

会議への参加。 字幕PC の会議ソフトで、次の3つを確かめてから会議に入ります。

  • 音声の出力先: CABLE Input。 出力先が違うと、音が LiveCaption に届きません
  • マイク: ミュート。 この PC は発言しません
  • 表示名: Live Captions など。 参加者一覧に出るので、何をしているか分かるようにします

自動参加（4章）を使う場合は、Zoom クライアント側で1回だけ次を設定します。

  • 参加時にマイクをミュート、参加時にビデオをオフ
  • 「コンピューターオーディオに参加」の確認を出さない。 この確認が出たままだと、 参加はできても音が繋がりません。無人では誰も押せないので、原因の分かりにくい失敗に なります

入力デバイス。 操作画面の設定タブ →「音声の入力」が CABLE Output になっている ことを確かめます。違っていたら一覧から選びます。選んだ時点で切り替わります。一覧には 名前だけでなくホストAPIも出ます（CABLE Output が MME・DirectSound・WASAPI の3つに 現れるためです）。3つのどれでも動きます。

画面共有。 閲覧画面は http://localhost:8080/v/... です。字幕PC の画面ではなく、 自分が会議に出ている PC のブラウザで開くには、D.13 の --control-bind か、 下の URL配布を使います。

URL配布。 経路は2つあり、Docker と同じく会議ごとに選びます（3.4 C）。 Windows ネイティブでは、Cloudflare に cloudflared の準備が要ります。

Cloudflare Tailscale
準備 字幕PC に cloudflared を入れます 字幕PC に Tailscale を入れ、tailscale funnel 8080 を1回実行して同意します
URL 配信のたびに変わります 変わりません
前もって配れるか 配れません 配れます

Cloudflare を使うには、先に cloudflared を入れます。PowerShell で次を実行します。

winget install --id Cloudflare.cloudflared

または cloudflared-windows-amd64.exe をダウンロードして、LiveCaption のフォルダの local/bin/cloudflared.exe に置きます。

Cloudflare では、字幕が Cloudflare の中継サーバを通ります。 外に出せない内容を扱う 会議では、画面共有を使ってください。

Zoom のチャットへの投稿（4.4）は、字幕PC の画面で Zoom のチャット窓を操作します。 字幕PC の画面を共有している場合は、一瞬チャット窓が映ります。クリップボードも字幕PC のものを 使い、文字は退避して戻しますが、画像やファイルは失われます。

終了。 操作画面の設定タブの「アプリの終了」を押します。ブラウザのタブも ターミナルのウィンドウも閉じます。タスクトレイから起動した場合は、アイコンを 右クリックして終了でも同じです。

D.11 常駐と自動起動

StartLiveCaptionTray.vbs をダブルクリックすると、ウィンドウを出さずにタスクトレイへ 常駐します。

アイコンの色 状態
青 待機中
緑 字幕を出している
赤 失敗が残っている

アイコンにマウスを乗せると、次の会議か、いま出している会議が出ます。右クリックすると、 操作画面・ログ・終了を選べます。ウィンドウが無いので、ログは local/log/ に残ります。

StartLiveCaptionTray.vbs を編集するときは、ASCII だけで書いてください。 日本語のコメントを入れると、ダブルクリックしても何も起きません。エラーも出ません。

Windows のログオン時に自動で起動させるには、PowerShell で次を実行します。管理者権限は 要りません。

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install_autostart.ps1

外すときは -Remove を付けます。

字幕PC はログオンしたままにしてください。 画面のロックは構いません。ログオフすると LiveCaption は動けません。

D.12 困ったとき

症状 見るところ
CABLE Output が一覧に無い VB-CABLE を入れましたか。PC を再起動しましたか
音量メーターが振れない 会議ソフトの出力先が CABLE Input か。両方 48000 Hz か。設定タブの「音声の入力」が CABLE Output か
「入力を開けない」と出る 別のアプリが専有していないか。48000 Hz を受け付けるデバイスか。別の入力を選んでください
文字起こしの行が出ない .env の OPENAI_API_KEY。.env は pixi.toml と同じ場所にありますか。名前が .env.txt になっていませんか
遠隔操作したら字幕が止まった RDP で入っていませんか。 音声経路が切れます（D.13）
Zoom に入ったのに音が来ない 「コンピューターオーディオに参加」の確認が出たままになっていませんか（D.10）
自動起動しない ログオンしていますか。タスクスケジューラで LiveCaption の状態を見てください
トレイのアイコンが出ない ログ（local/log/）を見てください
tailnet から操作画面が開けない --control-bind を付けて起動しましたか（D.13）。Tailscale が上がっていますか
字幕が途中で止まった seq が巻き戻りました。アプリを再起動したなら local/seq_state.json を確認してください
文字起こしの再接続が増える 回線です。字幕PC の会議ソフトで受信ビデオを止め、別回線を試してください

D.13 遠隔操作

字幕PC を別の部屋に置いて遠隔操作しても構いません。ただし RDP（リモートデスクトップ） は使えません。 RDP は音声を「リモートオーディオ」へ振り替えるので、会議ソフトが選んで いた CABLE Input への経路が切れて、字幕が止まります。VNC 系のように、コンソール セッションをそのまま操作するソフトを使ってください。

操作画面は Web ページなので、別の端末のブラウザから直接開くほうが速くて確実です。 Tailscale を使っている場合、PowerShell で次のように起動すると、操作画面が tailnet の アドレスでも開けます。

pixi run caption --web --control-bind

Control page: http://localhost:8081  (for you only. Do not share it)
              http://100.x.x.x:8081  (from inside the tailnet. **Narrow it with an ACL**)
  • 127.0.0.1 は必ず残ります。 Tailscale が落ちていても、そのマシンの前からは操作 できます
  • 操作画面には認証がありません。 Tailscale の範囲以外のアドレスは受け付けない作りに してあります。tailnet に他の人を招いている場合は、ACL で絞ってください（付録B.5）
  • 平文の HTTP になるので、「URLをコピー」のボタンは効きません。URLは選択された状態に なるので、Ctrl+C でコピーしてください

D.14 コマンドとオプション

はじめの3つはダブルクリックで動きます。それ以外は、LiveCaption のフォルダの中で、 PowerShell で実行します。

StartLiveCaption.bat                             # 会議で使うのはこれ
StartLiveCaptionTray.vbs                         # 窓を出さずにタスクトレイへ常駐する
InstallToStartMenu.bat                           # スタートメニューに登録する（最初に1回）

pixi run web                                     # 同じもの。PowerShell から起動する場合
pixi run caption --web                           # 同上
pixi run caption --token "<URL>" --web           # Zoom字幕とブラウザ字幕の両方
pixi run caption --web --no-save                 # 記録を残さない
pixi run caption --check-audio 20                # 音量だけ見る（API不要）
pixi run devices                                 # 入力デバイスの一覧
pixi run caption --from-file recording.wav --dry-run   # WAVを実時間で流す
pixi run python scripts/transcript_to_md.py      # 落ちたあとに .md を作り直す
pixi run python scripts/cable_loopback.py        # VB-CABLE の経路を試す
オプション 意味
--token <URL> Zoom字幕APIのトークン。あとから操作画面に貼っても構いません
--direction <向き> 字幕の向き。ja2en か en2ja。既定は前回の選択
--glossary <名前> ... 使う用語集（etc/glossary/ の .tsv の名前）。既定は前回の組み合わせ
--device <名前> 入力デバイス名の一部。既定: CABLE Output
--web [ポート] ブラウザに字幕を出します。閲覧側のポート、既定 8080
--control-port <ポート> 操作画面のポート、既定 8081
--control-bind [アドレス] 操作画面を tailnet からも開けるようにします（D.13）
--web-bind <アドレス> 閲覧画面が待ち受けるアドレス、既定 127.0.0.1。同じLANの端末から直接見せるなら 0.0.0.0
--tray タスクトレイに常駐します。ログは local/log/ にも残ります
--tunnel 起動時からトンネルを張ります。既定では張りません
--no-browser ブラウザを自動で開きません
--no-save 会議の記録を残しません
--save-dir <フォルダ> 記録の置き場。.env の LIVECAPTION_SAVE_DIR より優先します
--dry-run Zoom には送らず、画面に出すだけ
--from-file <wav> デバイスの代わりに WAV を実時間で流します。24 kHz モノラル
--loop --from-file のファイルを繰り返します
--delay <段階> 文字起こしの遅延と精度。minimal・low・medium・high・xhigh。既定 low
--model <名前> 翻訳のモデル。既定 gpt-4.1-mini
--check-audio [秒] 音量を表示して終わります。API を呼びません
--list-devices 入力デバイスの一覧を出します
--cloudflared <パス> cloudflared の場所。PATH か local/bin にあれば要りません

ポートが埋まっているときは、両方の番号を変えてください。 閲覧側に 8081 を指定しては いけません。

pixi run caption --web 8090 --control-port 8091

記録の置き場を変えるときは、.env に次を書きます。同期フォルダの中に LiveCaption を 置いている場合に使います。

LIVECAPTION_SAVE_DIR=%LOCALAPPDATA%\LiveCaption\transcripts

付録E. 仕組みと細かい設定

この付録は、LiveCaption を使うだけなら読まなくて構いません。

E.1 別の参加者として入る理由

Docker の場合:

[ホストPC]        通常どおり会議を進める
     |
[コンテナ]
  Zoom ---------- 無言の参加者として参加、マイクはミュート
   |
   +-- 出力 --> meeting（PulseAudio の仮想の出口）
                    |
                 meeting.monitor --> LiveCaption
                                       |-- 文字起こし
                                       |-- 翻訳
                                       +-- 出力

Windows ネイティブの場合:

[ホストPC]        通常どおり会議を進める
     |
[字幕PC]
  会議ソフト ----- 無言の参加者として参加、マイクはミュート
   |
   +-- スピーカー出力 --> CABLE Input
                             |   (VB-CABLE、仮想オーディオケーブル)
                          CABLE Output --> LiveCaption
                                             |-- 文字起こし
                                             |-- 翻訳
                                             +-- 出力

LiveCaption を、Zoom のホストの PC で動かしてはいけません。 会議ソフトは自分の マイク音声を自分のスピーカーに流しません。その PC でスピーカー出力を録ると、ホスト自身の 声が入りません。 別の参加者として入れば、会議ソフトからミックス音声を受け取るので、 その中に全参加者の声が入っています。

音は仮想の音声装置を通します。 ループバックの API を使わないので、音量やミュートの 影響を受けません。Docker では PulseAudio の null sink が、Windows では VB-CABLE がその 役です。Docker のほうは、ホストの音声装置をまったく使いません。 ホストで音楽を 鳴らしても字幕には入りませんし、ホストに音声装置が無くても動きます。

E.2 処理の流れと遅延

会議の音
  ↓
音声取得（24 kHz mono PCM、100 ms ずつ）
  ↓
文字起こし: gpt-live-transcribe（WebSocket、用語表をキーワードとして渡す、日英の自動判定）
  ↓
文の切り出し（句点で切る。日本語70字で強制分割）
  ↓
翻訳: gpt-4.1-mini（用語対訳表＋置換規則＋直前3文の文脈）
  ↓ 3つへ同時に
  ├→ Zoom 字幕API
  ├→ 閲覧画面
  └→ 会議の記録

用語対応は2段構成です。 文字起こし側では、用語対訳表の語をキーワードとして渡し、 固有名詞の音を拾わせます。翻訳側では、用語対訳表と、実際に出た誤認識からの置換規則と、 直前3文の文脈をモデルに渡します。本命は翻訳側です。 文字起こし側が音の近い誤りを しても、文脈と用語対訳表があれば翻訳側で復元できます。ただし全部は直せません。誤認識が 別の妥当な専門用語になると、流暢な誤訳が出ます。

確定した文だけを送ります。 途中経過を出して後から書き換えると、読み手は追えません。 Zoom の字幕は蓄積されて置き換わらないので、途中経過を送ると、その途中経過が1行として 残り、訂正した完成版がその下に並びます。閲覧画面には、確定前の文字起こしも途中経過として出します （末尾に … が付きます。閲覧画面は書き換えられるためです）。

遅延は文の終わり方で変わります（実測）。

文字起こし 確定待ち 翻訳 送信 合計
文末記号で終わった文（約74%） 0.2〜1秒 0秒 0.9秒 0.3秒 約1.5〜2秒
無音で終わった文（約9%） 同上 2.5秒 0.9秒 0.3秒 約4秒
長すぎて強制的に切った文（約17%） 同上 0秒 0.9秒 0.3秒 約1.5〜2秒

無音で終わった文は、確定を待つ間に先回りで訳しておきます（SPECULATE_AFTER_SEC）。 当たれば翻訳の 0.9秒 が消えます。確定待ち（IDLE_FLUSH_SEC）は下げられません。 話し続けている最中でも文字起こしの出力が 2.5秒 近く空くことがあり、閾値を下げると、 喋っている途中で文を切る回数が増えます。

E.3 Zoom のチャットへの投稿の仕組みと弱さ

Zoom に「会議中のチャットへ投稿する」API はありません。 LiveCaption は Zoom の窓を 画面操作で動かしています。したがって次の弱さがあります。

  • Zoom の作りが変われば、黙って効かなくなります。 窓の名前で見分けているためです
  • 届いたかどうかは、こちらから確かめられません。 送ったところまでしか分かりません
  • 投げるあいだ、Zoom のチャット窓が前面に出ます（Docker ではコンテナの中なので、誰にも 見えません）

URLを先に、QRコードを後に投げます。 ホストがファイル送信を切っている会議では QRコードが弾かれますが、URLは先に届いています。

Zoom が会議に入り終えるのを待ってから投げます。 会議の窓が出るまで10秒ごとに見に行き、 10分待って出てこなければ、諦めたことをログに残します。Zoom への参加が遅れて1回目の 投稿が定刻より後になったときは、2回目まで1分以上あけます。

失敗しても字幕は止まりません。結果はログに残ります。投げる時刻を変えるには、 src/live_caption/config.py の SCHEDULE_CHAT_AT_MIN を直します。

E.4 細かい設定

既定値は src/live_caption/config.py にあります。実測で決めたものなので、理由がある ときだけ .env で上書きしてください。

遅延に関わる4つは .env に書けます（操作画面の「遅延の調整」からも同じものを 変えられます。7章）。

.env の名前 対応する設定
LIVECAPTION_IDLE_FLUSH_SEC IDLE_FLUSH_SEC
LIVECAPTION_SPECULATE_AFTER_SEC SPECULATE_AFTER_SEC
LIVECAPTION_FORCE_CUT_CHARS FORCE_CUT_CHARS
LIVECAPTION_LINE_INTERVAL_SEC LINE_INTERVAL_SEC

差し替えると、起動時に [設定] .env で差し替えた: … と出ます。IDLE_FLUSH_SEC だけを 変えると、SPECULATE_AFTER_SEC も自動で追随します（IDLE_FLUSH_SEC − 1.1 秒）。

設定 既定 意味
ASR_MODEL gpt-live-transcribe 文字起こしのモデル
ASR_DELAY low minimal と high はどちらも専門用語を取り違えました
ASR_LANGUAGES ("ja", "en") 言語を1つに固定してはいけません。 会議の途中で言語が切り替わることがあります
ASR_KEYWORD_LIMIT 200 文字起こしに渡す用語の数の上限。切り捨てが起きたら画面に出ます
TRANSLATE_MODEL gpt-4.1-mini 翻訳のモデル
CONTEXT_SENTENCES 3 翻訳に文脈として渡す直前の文の数
MAX_CAPTION_CHARS 80 / 40 字幕1行の最大文字数。向きで変わります（英語80、日本語40）
FORCE_CUT_CHARS 70 / 140 これより長い文は強制的に切ります。字幕が速すぎるなら下げてください
IDLE_FLUSH_SEC 2.5 発話が途切れてから、文末記号が無くても確定させるまでの秒数
SPECULATE_AFTER_SEC 1.4 無音がこれだけ続いたら、確定を待たずに翻訳を投げます。0 で止めます
LINE_INTERVAL_SEC 0.6 Zoom へ1行ずつ送る間隔。閲覧画面には効きません
WEB_LINES 8 閲覧画面に出す行数
WEB_PORT / CONTROL_PORT 8080 / 8081 閲覧画面と操作画面のポート

.env のその他の注意:

  • .env の値が、同じ名前の環境変数より優先されます。 値が空の行は上書きしません
  • Docker では、compose.yml の environment: に直書きした値が .env より強い という点に気をつけてください。compose.yml を直すときは、.env から取る形 （${名前:-既定}）を保ってください
  • LIVECAPTION_GLOSSARY_DIR は用語対訳表の置き場です。Docker では compose.yml が ボリュームの中を指しているので、触りません

E.5 会議の記録の中身

置き場は local/transcripts/ です。Docker ではコンテナの中の state ボリュームにあります。

local/transcripts/live-caption_2026-09-08_143012.jsonl   1文ごとに追記する
local/transcripts/live-caption_2026-09-08_143012.md      読める形。停止か終了のときに書く

文字起こしと字幕が対になっています。時刻は文字起こしが確定した時刻です。.jsonl には遅延の実測も入ります。

項目 意味
cut 文が確定した理由。punct（文末記号）/ force（長さ）/ idle（無音）/ flush（終了時）
waited 無音で確定したときに、実際に待った秒数
took 翻訳にかかった秒数
total 確定から最初の字幕までの秒数。 total − took が待ち行列
spec 先回りの翻訳が当たった文に付く。このとき total は took より小さくなる
dir そのときの字幕の向き

.md が書かれるのは、「停止」を押したときと、アプリを終了したときです。操作画面から ダウンロードするときは、そのつど .jsonl から組み立てます。電源ごと落ちたときは scripts/transcript_to_md.py で作り直せます。

E.6 閲覧と操作のポート

閲覧画面（8080）と操作画面（8081）は、パスではなくポートで分けてあります。安全の ための決定です。 トンネルは閲覧側のポートにしか繋がないので、URLを知った人が字幕アプリを 止めることはできません。閲覧画面には推測できない経路（/v/<ランダム>）が付き、閲覧 ポートの / は 404 です。

Docker では、操作画面はコンテナの中の 127.0.0.1 と tailnet のアドレスにだけ出ます。 tailnet の中には tailscale serve で https（8443）でも出します。ホストの 127.0.0.1:8080 には閲覧画面だけを出しています（compose.yml の ports:）。

関連文書

  • glossary-example.tsv — 用語対訳表の見本
  • .env.example — 設定できる項目の一覧。説明が付いています
  • compose.yml — Docker の設定。ボリュームと環境変数の意味を書いてあります
  • test-procedure.md — 段階を分けた立ち上げ試験と、本番当日の 確認手順（英語）。段階1と2は Windows ネイティブ向けで、Docker では 2.8 が同じ役割です