Twilio Videoアプリのトラブルシューティング

読む所要時間: 1 分

April 28, 2021
執筆者
Alberto Gonzalez Trastoy
寄稿者
Twilio の寄稿者によって表明された意見は彼ら自身のものです
Daizen Ikehara
Twilion
レビュー担当者
Mia Adjei
Twilion

troubleshooting twilio video app jp

This article is for reference only. We're not onboarding new customers to Programmable Video. Existing customers can continue to use the product until December 5, 2024.


We recommend migrating your application to the API provided by our preferred video partner, Zoom. We've prepared this migration guide to assist you in minimizing any service disruption.

このBlogはAlberto Gonzalez Trastoyがこちらで公開した記事を日本語化したものです。

ミリ秒単位の処理が重要ないま、リアルタイムコミュニケーションの主力プロトコルは低レイテンシーのWebRTCです。ビデオやライブコンテンツの配信、遠隔操作車両やさまざまなオブジェクトの制御など、無数のユーザーにWebRTCは利用されています。World Wide Web Consortium（W3C）とInternet Engineering Task Force（IETF）は、今年ようやくWebRTCの正式な標準規格入りを発表しました。しかし、WebRTCはまだ進化の途上にあります。

WebRTCは継続的に改善されています。ブラウザとデバイスの統合（コンバージェンス）などに関する問題が解決され、さまざまなブラウザやデバイスのどちらからでも、同様のタスクを実行したり、同じ種類のコンテンツを利用してやり取りしたりすることが可能になる見込みです。開発者がTwilio Programmable Videoを好んで使用するのは、WebRTCの利用が簡単だからです。それでも、ブラウザとオペレーティングシステム間の違いが依然として問題になることがあります。

その他さまざまな理由から、本番環境でWebRTCアプリケーションを構築する際はテストとトラブルシューティングを繰り返すことになります。この記事ではトラブルシューティングを中心に取り上げます。どのビデオアプリケーションのトラブルシューティングにも役立つ方法やツールを紹介するほか、Twilio Video APIを使用したリリース版アプリケーションのトラブルシューティングに際し理解しておくべき重要なコンセプトも説明します。

アプリケーションのトラブルシューティングにおける最初のステップは、問題を特定することです。

Twilio Videoアプリの問題を特定する方法

下図は、Twilioを使用した基本的なメディアパブリッシングの初期化を示しています。

twilio media connection - initialization

                                         Twilioによるメディア接続の初期化の主な流れを示した図

ネットワーク接続の問題、コード不備、負荷分散の欠如などの一般的な問題は、多くのアプリケーションに影響を与える可能性があります。しかし、Twilio Videoを使用したアプリには追加サービスがあり、値を返すだけでなく、ユーザー間でメディアのキャプチャ、処理、配信を行えます。そのため、Twilioサーバーの動作確認だけでは不十分です。ユーザーのハードウェアが正常に動作しているか、サポート対象ブラウザを使用しているか、ユーザーのネットワークが必要なプロトコルに対応しているか、ユーザーとTwilioサーバーとの間に必要最低限の帯域幅をサポートしているかという点も確認する必要があります。

本番環境にあるアプリケーションの場合、問題の診断に使用できる第1のツールは、Video Log Analyzerツールです。Twilio Consoleにあります。問題とされているビデオ通話のRoom SIDがわかれば、通話内で起きた問題について多くのデータを取得できます。下の画像は、最新のビデオルーム一覧です。

twilio console video log analyzer

                                                        最近作成されたルーム一覧を表示するVideo Log Analyzer

特定のビデオルームのRoom SIDをクリックすると、下の画像のように、詳細が記載されたページに移動します。

video log analyzer - details

Video Log Analyzerに表示されたビデオルームの詳細。ルーム作成日時、参加者、公開されたストリーム、参加者の接続が終了した理由、使用されたコーデック、メディアのリージョンなどの情報を確認できます。

これは、さらに調査を進めるために必要な情報を確認できる優れたツールです。特定のオペレーティングシステムを使用しているユーザーに同じタイプのエラーコードが発生している、特定地域の参加者が他地域よりも頻繁に切断されるなど、さまざまなパターンを発見できる場合があります。起きている事象の手がかりが得られれば、解決策を考えることができます。

Video Log Analyzerの詳細は、こちらのドキュメントをご覧ください。

また、RTC Diagnostics SDKを使用し、音声/ビデオの入出力の問題やメディア接続状態を検出することもできます。これはTwilio Video SDKに組み込まれていませんが、使い方は簡単です。キャプチャしたい情報を決め、対応するイベントを処理するだけです。

例えば、受信する最大ビットレートをキャプチャするには、以下のコードを使用します。

import { testMediaConnectionBitrate } from '@twilio/rtc-diagnostics';

const mediaConnectionBitrateTest = testMediaConnectionBitrate({
 iceServers: [{
   credential: 'bar',
   username: 'foo',
   urls: 'turn:global.turn.twilio.com:3478?transport=udp',
 }],
});

mediaConnectionBitrateTest.on('bitrate', (bitrate) => {
 console.log(bitrate);
});

もう1つ、Twilio Video Roomのトラブルシューティングに便利なツールが、Preflight APIです（現在はベータ版）。

日本版作成者によるメモ（2021/08/17更新）: この機能はtwilio-video.jsバージョン2.16.0においてパブリックベータAPIとなり、runPreflightと変更されました。機能を試す場合はこちらをご確認ください。

この診断用APIは、ビデオルームに入室する前、またはトラブルシューティングページの一部として、接続やメディア品質に関する問題を検出する目的で使用できます。最初にTwilioクラウドへのWebSocket接続を点検し、次にメディアパスを確認します。このAPIは、メディアを自動パブリッシュし、ループのなかでそれ自体をサブスクライブし、テスト終了時にレポートを生成します。この情報には、ジッターやパケットロス、ネットワーク品質、ラウンドトリップタイム（RTT）などが含まれます。Preflight APIの使い方を理解するため、以下の例を見てみましょう。

const Video = require('twilio-video');
const tempRoomName = 'test-room-' + Date.now();
const publisherToken = getAccessToken('alice', tempRoomName);
const subscriberToken = getAccessToken('bob', tempRoomName);

上記のこの部分では、テストルームを作成し、パブリッシャーとサブスクライバーを1人ずつ指定しています。次に、下のコードにて、testPreflight()メソッドを呼び出します。そこから、completedイベントをリッスンし、レポートオブジェクトを渡すことができます。

const preflightTest = Video.testPreflight(publisherToken, subscriberToken);

preflightTest.on('completed', function(report) {
  console.log("Test completed in " + report.testTiming.duration + " milliseconds.");
  console.log(" It took " + report.networkTiming.connect.duration + " milliseconds to connect");
  console.log(" It took " + report.networkTiming.media.duration + " milliseconds to receive media");
  // network score is available only for group rooms.
  console.log(" Your network score was: " + report.stats.networkQuality);
});

さらに、問題をローカルで再現でき、Chromeブラウザを使用している場合は、検索バーにchrome://webrtc-internalsと入力してください。各通話のステージ、コーデック、ビットレート、その他の進行中のコールに関する有益なWebRTC情報が表示されます。Firefoxを使用している場合、about:webrtcにアクセスすると同等の情報が得られます。

トラブルシューティングのためのデータ収集ツール

Twilio Video Log Analyzerにて情報を視覚化することや、コンソールに情報を表示するだけということも可能ですが、ほかのユーザーのログにはアクセスできない場合もあります。あるいは、問題のトラブルシューティングや監視に役立つ、さらに詳細な情報が必要になる可能性もあります。このような場合は、情報をキャプチャし、それをいずれかの場所に保存する必要があります。

twilio-video.js v2.10.0以降では、loglevelモジュールを使用することにより、ログをインターセプトできます。これにより、ログのリアルタイム処理が可能になります。処理には、ログデータの検証や自社サーバーへのログ送信などがありますが、これらに限定されてはいません。例えば、以下のように、ロガーのメッセージをインターセプトし、signalingイベントをリッスンできます。

const { Logger, connect } = require('twilio-video');
const token = getAccessToken();

const logger = Logger.getLogger('twilio-video');

// Listen for logs
let originalFactory = logger.methodFactory;
logger.methodFactory = function (methodName, level, loggerName) {
  let method = originalFactory(methodName, level, loggerName);

  return function (datetime, logLevel, component, message, data) {
    method(datetime, logLevel, component, message, data);
    if (message === 'event' && data.group === 'signaling') {
      if (data.name === 'waiting') {
        console.warn('Twilio\'s signaling server is busy, so we wait a little while before trying again.');
      } else if (data.name === 'open') {
        console.log('Connected to Twilio\'s signaling server, joining the Room now.');
      } else if (data.name === 'closed') {
        if (data.level === 'error') {
          const { payload: { reason } } = data;
          console.error('Connection to Twilio\'s signaling server abruptly closed:', data.reason);
        } else {
          console.log('Connection to Twilio\'s signaling server closed.');
        }
      }
    }
  };
};

上のコードにあるとおり、signalingグループ（data.group === 'signaling'）から受信するeventメッセージをフィルタリングしています。この後、signalingイベントをインターセプトするために、info（debug）にログレベルを設定する必要があります。

logger.setLevel('info');
connect(token, {
  name: 'aroom'
}).then(function(room) {
  room.on('participantConnected', function(participant) {
    console.log(participant.identity + ' has connected');
  });
}).catch(error => {
  console.log('Could not connect to the Room:', error.message);
});

他にも、データ収集に役立つツールとして、Network Quality APIがあります。このAPIは、ビデオルーム参加者のネットワーク接続を監視し、アルゴリズムを用いて接続品質を「0（ネットワーク障害）」から「5（非常に良好）」の間で評価します。

例えば、Network Quality APIを使用して通話品質を追跡するために、network quality verbosityを定義し、networkQualityLevelChangedイベントを処理するという方法があります。この方法を以下のコードに示します。printNetworkQualityStatsは、これらの統計を、定期的にまたは必要に応じ、てログシステムに投稿する関数です。

const Video = require('twilio-video');
const token = getAccessToken();

Video.connect(token, {
  name: 'my-room',
  audio: { name: 'microphone' },
  video: { name: 'camera' },
  networkQuality: {
    local: 1, // LocalParticipant's Network Quality verbosity [1 - 3]
    remote: 2 // RemoteParticipants' Network Quality verbosity [0 - 3]
  }
}).then(function(room) {
  // Print changes to Network Quality Level and statistics
  room.localparticipant.on('networkQualityLevelChanged', printNetworkQualityStats);
});

データの視覚化と保存

ここまで紹介したデバッグツールやAPIは、イベントのログ/視覚化システムと組み合わせて使用する必要があります。データはJSONやテキストファイルに直接送信できますが、イベントデバッグWebhookの設定や、ELKスタックシステム（オープンソース）その他のサードパーティサービスへのログ送信もできます。

最終的にどのサービスを選択したとしても、Twilio Videoアプリケーションのトラブルシューティングに最も役立つ情報をログとして記録し保存するようにしてください。

まず保存すべき情報は、Twilioからのエラーや警告です。一般に、参加者が最初に通話に接続したときや通話を開始したとき、あるいは新しい参加者が参加したときに発生する問題が含まれていると考えられます。また、RTC Diagnostics SDK、Video SDK Preflight API、Network Quality APIからもたらされる関連データは、参加者エクスペリエンスを監視する場合や、品質メトリックスを保存してあとで確認する場合に有効です。

ユーザーのブラウザ、ブラウザバージョン、オペレーティングシステム、ロケーションをログとして記録し、保存することもお勧めします。この情報が、特定のTwilioエラー、警告、その他の品質メトリックスと関連している場合、バグの追跡や再現に役立ちます。

ネットワークと帯域幅に関する要件

ビデオアプリケーションではリアルタイムでメディアをやり取りしているため、他の種類のアプリよりもネットワークに大きく依存します。下の図1は、Twilioが音声とビデオ向けに提供している公式の帯域幅要件表です。

帯域幅（アップリンク/ダウンリンク）

32～100kbps（音声のみ）

> 150kbps（ビデオのみ）

レイテンシー（RTT）

< 200ms

ジッター

< 30ms

パケットロス

< 3%

                                           図1.Twilioの帯域幅要件表

帯域幅がこの要件を下回る場合は、ユーザーに通知する必要があります。例えば、ページの最上部にモーダルを表示し、低帯域幅によりカメラがオフであることをユーザーに警告したり、電話でダイヤルインするオプションを提示したりできます。

図2は、ビデオ通話を成立させる最低限のユーザー要件です。

ビデオルームの種類

最低限の必須帯域幅（クライアントサイド）

参加者9人まで、低解像度VP8ビデオ（240x180）+HD音声

～2 Mbps

参加者9人まで、SD VP8ビデオ（640x480）+HD音声

～4 Mbps

参加者9人まで、HD VP8ビデオ（1280x720）+HD音声

～6 Mbps

図2.ビデオの帯域幅要件は、ユーザーが参加者全員の音声とビデオ（自分自身を除く）を30fpsで受信しているという想定。この帯域幅要件は、コーデック、解像度、フレームレートにより異なります。

WebRTCのおかげでビデオ通話はネットワークの状態に適応できるため、最低限の低解像度ビデオ品質に達しているか確認するだけで済みます。ユーザーが最低限のビデオ要件を満たせない場合は、音声のみのモードに切り替える必要があります。

WebRTCは、HTTPリクエストによく利用される80番ポートと443番ポートでの標準的なTCP通信以外に、さまざまなポートやプロトコルを使用します。そのため、ネットワークインフラストラクチャを確認し、サーバーがTCPとUDPの発信トラフィックを公衆インターネットに送信し、クライアントからの受信リクエストを受信できるか確認することをお勧めします。アプリケーションは、Twilioのメディアサーバーやシグナリングサーバーに対してリクエストを開始し、これらのサーバーからトラフィックを受信する必要があります。

Twilio Videoアプリのトラブルシューティングに関する詳細情報

優れたトラブルシューティングツールについて知識を得たところで、自社のビデオアプリケーションに早速使用してみましょう。

ここに、トラブルシューティングに最低限必要なチェック項目をまとめました。

  1. 上記で紹介した診断ツールを用いて、接続をテストし、その他の問題を特定する
  2. 監視目的や今後の参考のために、ログを収集し、保存する
  3. 帯域幅要件を満たしていることを確認する
  4. アプリケーションとTwilioのメディアサーバー/シグナリングサーバーとの接続を許可する
  5. ユーザーに最高のエクスペリエンスを提供するための、Twilio Videoの推奨事項とベストプラクティスを確認する

Twilio Programmable Videoのテクノロジーは常に改良されているため、開発者は、新しい方法でビデオ通話の分析やトラブルシューティングを行うことができます。トラブルシューティングについてさらに詳しく知りたい方は、Video Log Analyser REST APIを確認してください。デバッグ全般に関心のある方は、Twilioアプリケーションのデバッグに関する一般的な推奨事項をご覧ください。Programmable Videoのベストプラクティスについては、Twilio Programmable Videoに関するこちらのドキュメントで確認できます。

Alberto Gonzalez Trastoyは、WebRTC.venturesのシニアエンジニアです。通信工学の分野で活躍し、技術に対する関心が高く、大企業や中小企業向けのVoIP/WebRTCベースのプロジェクトに多数参加しています。これまで関与したプロジェクトには、テレプレゼンスリモートコントロール、ライブ配信ゲーム、ビデオ通話センター、音声分析、その他さまざまなリアルタイムアプリケーションがあります。

AlbertoのTwitterアカウントは@lbertogonです。

関連投稿

関連リソース

A newspaper article

Twilio Docs

APIからSDK、サンプルアプリまで

言語とプラットフォームの API リファレンス ドキュメント、SDK、ヘルパー ライブラリ、クイックスタート、チュートリアル。
An Open book

リソース・センター

最新の電子ブック、業界レポート、ウェビナー

顧客エンゲージメントの専門家から学び、自社のコミュニケーションを改善しましょう。
User group reactions

Ahoy

Twilio の開発者コミュニティ ハブ

コミュニケーションとデジタル エンゲージメント エクスペリエンスを構築するためのベスト プラクティス、コード サンプル、インスピレーション。