Zoom字幕APIを使う

作成:2021年6月15日 　最終更新:2021年6月15日

Zoomには字幕APIが用意されており、外部ツールから字幕を送り込むことができます。
ここでは、字幕APIを使う流れについて簡単にまとめます。

■公式情報

Integrating a third-party closed captioning service
https://support.zoom.us/hc/en-us/articles/115002212983

基本的にこれだけで情報としては完結しています。

■使ってみる／1.準備

Zoomのサイト（zoom.us）でログイン（無料アカウントでOK）して、字幕を有効化してあるか確認します。

この記事を書いている時点（2021-06-15）のZoomの場合、ブラウザでログインした状態で「設定」→「字幕機能」を有効にして、さらに直下のチェックボックス（なぜか英語のまま）にチェックを入れます。特に最初の項目は有効にしないと字幕APIが使えないのでご注意を。


Zoom字幕有効化設定


■使ってみる／2.会議開始～字幕表示設定

字幕有効化ができたら、会議を始めます。
カメラはオフでいいし、音声も会議開始後はミュートで構いません。

次にZoomで字幕を表示できる状態にするために、Zoom下側の「字幕」ボタンを押して、「私が入力します」をクリックします。Zoomは、最初にホストがこの手続きを行わないと、ホスト自身にも字幕が表示されないし、ゲストの画面には字幕ボタンすら表示されません。字幕ボタンはデフォルトで全員に出るべきだと思うのですが。

Zoom字幕ボタン押下状態（初期時）


これでZoomの字幕ボタンの右上に「ˆ」が出ます。この部分は小さなボタンになっており、クリックすると「サブタイトルを表示」という選択肢が出てくるので選びます。これで字幕がホスト自身に表示される状態になりました。なお、デフォルトの字幕サイズが小さい場合は「サブタイトルの設定」で、ある程度まで大きくできます。

Zoom字幕ボタン押下状態（字幕有効状態）


■使ってみる／3.字幕APIの利用

改めて、字幕ボタン（「ˆ」以外の部分）を押して、「APIトークンをコピー」をクリックします。これで字幕APIトークンがクリップボードに入ります。

次に、何らかの方法でHTTP POSTを送ります。とりあえず使うだけなら、curlでしょうか。今はWindowsでも（Windows 10 1803以降なら）curlコマンドが標準搭載されています。ここではWindowsでcurlを使う前提で説明します。

とりあえずPowershellを開き、次のコマンドを入力します（cmd.exeやwindows terminalでも可能だと思います）。Zoomの字幕APIトークンは字幕APIにアクセスするためのURLなので、次のようにcurlのURL部分に貼り付けて、後に「&lang=jp-JP&seq=1」と続けてください。なお、下記の例では表示する字幕を「Hello, Zoom!」としていますが、日本語の送信はWindowsのコマンドラインだと厄介なので、ASCII文字列がおすすめです。

curl.exe -X POST -H "Content-Type:text/plain" -d "Hello, Zoom!" "（字幕APIトークン）&lang=jp-JP&seq=1"


※1:curl.exeと拡張子つきにしているのは、拡張子のつかない"curl"をPowershellが別の意味として扱うためです。
※2:「-H "Content-Type:text/plain"」はヘッダ追加情報ですが、これを省くとHTTP上では正常な応答が返るもののZoomの字幕には反映されません。

正しくコマンドが打てていれば、コマンドライン上では日時が表示されるはずです。これはZoomのサーバがPOSTを処理したタイムスタンプです（公式文書の"HTTP POST returns timestamp"）。

Powershellからの字幕が表示されたZoom


この後も、seqの数字を増やしながら字幕を送ることが可能です。

■シーケンス番号の設定

Zoom字幕APIでは、シーケンス番号（URLのクエリパラメータにつける"seq"の値）が重要です。新しい字幕データでは、最後のシーケンス番号に1を加えた値を設定しなければなりません。なお、送信が失敗した場合、再送データにつけるシーケンス番号は増やしません。

なお、字幕未送信状態でのZoom内部の最終シーケンス番号はゼロに設定されているようです。このため、最初の字幕のシーケンス番号は1です。

ところで、正しくないシーケンス番号を送った場合ですが、試した結果は次の通りです。


本来より大きな値を送信してしまった場合が問題で、HTTP上では正常に見えるので異常が検出できない上に内部のシーケンス番号が上書きされてしまいます。

なお、Zoom自体で字幕を送った場合は、Zoom内部のシーケンス番号には影響しないようです。シーケンス番号はあくまでAPI利用時のためのものということですね。

■シーケンス番号の取得

ツールが、字幕APIを「既にAPI経由で字幕が送信された後から」使うケースがありえます。この場合、正しいシーケンス番号から開始しないと、うまく字幕が送信できません。

幸い、Zoomは現在の内部シーケンス番号を返すAPIをもっています。具体的にはAPIトークンにある「/closedcaption」を「/closedcaption/seq」に書き換えて（langやseqはつけずに）HTTP GETします。正常なら「0」など内部シーケンス番号だけが返ってきます。

内部シーケンス番号がとれたら、それに1を加えた値を字幕送信時のURLに使います。

補足ですが、wayback machineで確認した範囲では、このAPIについての記述は2021年3月5日と3月19日の間のどこかで追加されたようです。

（2021-03-05時点ではGET APIの記載はない）
https://web.archive.org/web/20210305002801/https://support.zoom.us/hc/en-us/articles/115002212983

（2021-03-19時点ではGET APIの記載が加わっている）
https://web.archive.org/web/20210319000756/https://support.zoom.us/hc/en-us/articles/115002212983

■シーケンス番号の扱い

理想的には、字幕ツール側で初期値ゼロとしてシーケンス番号を保持しておき、字幕を送信するたびにシーケンス番号をインクリメントすれば事足ります。

一方、毎回シーケンス番号を取得してから送信する、という考え方もあります。この方法はおそらく堅実ですが、シーケンス番号の取得にも時間がかかります（1秒程度はかかっているようです）。

字幕送信の結果（HTTP応答）については、403の場合はシーケンス番号を取得して再送信する必要があります。400なら会議が始まっていないようなので、何らかの警告を出せるといいでしょうし、404ならAPIトークンが間違っている可能性があります。500番台なら字幕ツールではない（Zoomやネットワーク）の要因のため、（シーケンス番号を取得するかはともかく）再送するのが基本的な対策となります。

字幕ツールの開発者は、これらを前提にシーケンス番号の管理を考える必要があるようです。


◀（前記事）Windows 10のMS-IMEの注意点：単語登録
▶（次記事）オフラインでファイルが消える問題と対策

（一覧）[2.技術情報 (tech)]

(c) mekiku.com