インスタントメッセンジャーの規制を検討している人もいれば、分散型インスタントメッセンジャーを開発している人もいます。以前の出版物では、単純なエコーボットを作成する例を使用して、ToxメッセンジャーカーネルAPIの使用が検討されました。 Toxの開発はまだ止まっておらず、11月3日にToxコアはオーディオおよびビデオコールの新しいサブシステムであるToxAVで強化されました。これについては、この出版物で説明します。

はじめに

ToxAVは、オーディオ用のOpusコーデックとビデオ用のVP8 、およびそれぞれlibopus ライブラリとlibvpxライブラリでの実装に基づいています。

ToxAV APIは、オーディオの入力および出力形式として、16ビットサンプリング、1または2チャネルのサポート、8、12、16、24、48 KHzのサンプリング周波数を備えたPCM形式を使用します。 1つのデータフレームの期間は、2.5、5、10、20、40、または60ミリ秒である必要があります（opusコーデックの要件）。

ToxAV APIは、ビデオの入力および出力形式として、YUV420形式（IYUVおよびI420とも呼ばれます）のフレームを使用します。これは、より使い慣れたRGB色空間に比較的簡単に変換できます。

ToxAVは、オーディオデバイスやビデオデバイスからデータをキャプチャしたり、再生したりする方法を提供しません。これらはすべて、アプリケーション開発者の裁量に任されています。したがって、たとえば、 µToxクライアントは、オーディオの操作にOpenALを使用し、ビデオデバイスの操作にv4l （video4Linux）を使用します。 QToxクライアントは、 FFmpegを使用してビデオを処理します。 Python（以下で間接的に説明します）では、オーディオにPyAudioを、ビデオにOpenCVを使用できます。

ToxAVの一般的な作業サイクルは、次の形式で順番に表すことができます。

ToxCoreカーネルの初期化（以前の出版物で詳細に説明されています）。
ToxAVサブシステムの初期化（ toxav_new ）。
イベント処理のためのコールバック関数の設定（ toxav_callback_ * ）-イベントハンドラーはメインループから呼び出され（4）、アプリケーションのメインロジックは通常それらに集中します。
メインデューティサイクル（ toxav_iterate ）およびイベント処理。
toxav_iteration_intervalを一時停止し、前の手順に戻ります。

なぜなら Tox APIの知識を得るための主な方法は、ソースコード（Cで記述）を読むことです。さらにプレゼンテーションを単純化するために、Python言語のラッパー（ githubのpytoxcore ）を使用します。ソースからライブラリの自己アセンブリを行いたくない人のために、一般的なディストリビューション用の既製のバイナリパッケージへのリンクもあります。

Pythonラッパーを使用する場合、次の方法でライブラリのヘルプを取得できます。

$ python >>> from pytoxcore import ToxAV >>> help(ToxAV) class ToxAV(object) | ToxAV object ... | toxav_answer(...) | toxav_answer(friend_number, audio_bit_rate, video_bit_rate) | Accept an incoming call. | If answering fails for any reason, the call will still be pending and it is possible to try and answer it later. Audio and video receiving are both enabled by default. | | toxav_audio_receive_frame_cb(...) | toxav_audio_receive_frame_cb(friend_number, pcm, sample_count, channels, sampling_rate) | This event is triggered when a audio data received. ...

以下では、APIを操作する各ステップについてもう少し詳しく説明します。

ToxAVの初期化

ToxAVサブシステムを初期化するために、以前に初期化されたToxCoreカーネルのインスタンスが呼び出しパラメーターtoxav_newとして使用されます。単一のToxCoreインスタンスに対して作成できるToxAVインスタンスは1つだけです。 Pythonラッパーでは、toxav_new呼び出しはコンストラクター内に隠されており、初期化は次のようになります。

 from pytoxcore import ToxCore, ToxAV class EchoBot(ToxCore): ... class EchoAVBot(ToxAV): def __init__(self, core): super(EchoAVBot, self).__init__(core) ... bot = EchoBot(options) botav = EchoAVBot(bot)

ToxAVインスタンスを破棄するには、 toxav_kill呼び出しを使用するか、Pythonラッパーのクラスインスタンスを破棄します。この場合、toxav_kill呼び出しはデストラクタに隠されています。

コールバック関数を設定する

Pythonラッパーでは、サポートされているコールバック関数への接続が自動的に行われます。ハンドラー自体はToxAVの子孫のメソッドであり、サフィックス* _cbを持つことができます。すべてのハンドラーで、パラメーターの1つはfriend_number-同様のToxCoreメソッドからの友人の整数識別子です。

toxav_call_cb（friend_number、audio_enabled、video_enabled） -着信コール。引数として、コンタクト側からのオーディオとビデオをサポートするためのフラグが追加で渡されます。将来、ミュートされたオーディオまたはビデオストリームとの接触により、それらがオンになり、イベントによってコールステータスが変更される可能性があります。呼び出しは、呼び出しtoxav_answerで受信するか、呼び出しtoxav_call_controlで拒否できます。

toxav_call_state_cb（friend_number、state） -通話状態を変更します。状態は、定数のビットマスクであり、引数として渡されます。

TOXAV_FRIEND_CALL_STATE_ERROR-連絡先へのデータ転送のタイムアウト。この状態は、コールの最後の状態であり（この時点でコールは完了しています）、他の条件と組み合わせることができません。
TOXAV_FRIEND_CALL_STATE_FINISHED-正常な通話終了。この状態は、コールの最後の状態であり（この時点でコールは完了しています）、他の条件と組み合わせることができません。
TOXAV_FRIEND_CALL_STATE_SENDING_A-連絡先は音声ストリームの送信を開始しました。
TOXAV_FRIEND_CALL_STATE_SENDING_V-連絡先はビデオストリームの送信を開始しました。
TOXAV_FRIEND_CALL_STATE_ACCEPTING_A-連絡先はオーディオストリームの受信を開始しました。
TOXAV_FRIEND_CALL_STATE_ACCEPTING_V-連絡先はビデオストリームの受信を開始しました

toxav_bit_rate_status_cb（friend_number、audio_bit_rate、video_bit_rate） -カーネルが必要なビットレートでデータを送信できない場合のネットワーク輻輳イベント。パラメータとして、カーネルはオーディオおよびビデオストリームの新しいビットレートを提供します。さらに、カーネルは最初にメインレーンを占有するため、ビデオストリームのビットレートを低下させようとします。ビデオストリームを切断した後にのみ、オーディオのビットレートを低下させようとします。アプリケーションはこれらの推奨事項を無視するか、 xav_bit_rate_set（friend_number、audio_bit_rate、video_bit_rate）の呼び出しを使用して新しいビットレートを設定できます。ビットレートはKb / s（キロビット/秒）で設定され、値0は対応するデータストリームのシャットダウンを示し、値-1は以前の設定ビットレートを変更しません。

opusオーディオコーデックの場合、最小ビットレートは6で、私の耳の16〜32を超える値は、Webカメラからの音で区別できなくなりました。

V8ビデオコーデックの場合、フレームサイズとFPSによっては推奨帯域幅値が見つかりませんでした。一般に、さまざまなビデオ解像度に対して次の基本ビットレートが推奨されます。

フレームサイズ、px	ビットレート、Kb / s
320x240	400
480x270	700
1024x576	1500
1280x720	2500
1920x1080	4000

toxav_audio_receive_frame_cb（friend_number、pcm、sample_count、channels、sampling_rate） -オーディオデータのフレームを受信します。データバッファ、サンプル数、チャネル数、サンプリング周波数（Hz）がパラメーターとして送信されます。ステレオサウンドの場合、16ビットのサンプルは、左右のチャンネルで次々に順番に送信されます。バイト単位のバッファーのサイズは、 sample_count * channels * 2バイトとして定義され、ミリ秒単位のバッファーの持続時間は、 sampling_rate / sample_countとして定義されます。

PCMは従来のパルスコード変調形式であるため、バッファーデータは、DACに変換せずに実質的に転送するか、形式の説明を含む適切なヘッダーを追加することでWAVファイルに保存できますが、会話中にオーディオストリームパラメーターを準備する必要があります呼び出し元によって変更されます。

toxav_video_receive_frame_cb（friend_number、幅、高さ、y、u、v、ystride、ustride、vstride） -YUV420形式のビデオデータのフレームを受信します。これはToxAVからの元のコールバックです。 YUV420からBGRへの変換の実装例は、たとえばμToxソースコード（ yuv420tobgr ）にあります。

toxav_video_receive_frame_cb（friend_number、width、height、rgb）-RGBまたはBGR形式でフレームを受信することは、ToxAVでは利用できない追加のPythonラッパーコールバックです。このオプションは、pyhonに変換するのではなく、ライブラリ内で必要な変換を高速化するために使用されます（実際、µToxコードのyuv420tobgrが使用されます）。 RGBまたはBGR形式を設定するには、パラメーターを指定してtoxav_video_frame_format_setを呼び出します。

TOXAV_VIDEO_FRAME_FORMAT_BGR -BGR形式（OpenCVで使用）。
TOXAV_VIDEO_FRAME_FORMAT_RGB -RGB形式。
TOXAV_VIDEO_FRAME_FORMAT_YUV420は、YUV420形式のToxAVからの元のコールバックです。

以下、RGB / BGRは、アルファチャネルのない24ビット形式を指し、赤、緑、青の各コンポーネントには8ビットが割り当てられます。この形式は、赤と青の色成分の順序に応じて、RGB24 / BGR24と呼ばれることもあります。

オーディオストリームと同様に、ビデオストリームの形式は、発信者がいつでも変更できます（たとえば、フレームサイズが変更されます）。

イベント処理

Toxavイベントは、 toxav_iteration_interval呼び出しを返す値と等しい呼び出し間の推奨間隔（ tox_iteration_intervalカーネルの呼び出しに類似）でtoxav_iterateメソッドを定期的に呼び出して（ tox_iterateカーネルメソッドの呼び出しに類似）処理されます。

ToxAVのデューティサイクルは、次のように別のスレッドで提供することをお勧めします。オーディオ/ビデオコールがない場合、 toxav_iteration_intervalの値は200ミリ秒になり、ストリームはほとんどの時間スリープします。

 import threading class EchoAVBot(ToxAV): def __init__(self, core): ... self.running = True self.iterate_thread = threading.Thread(target = self.iterate_cb) self.iterate_thread.start() def iterate_cb(self): while self.running: self.toxav_iterate() interval = self.toxav_iteration_interval() time.sleep(float(interval) / 1000.0) def stop(self): self.running = False self.iterate_thread.join() self.toxav_kill();

GIL（Global Interpreter Lock）はPythonに存在するため、スレッド間の同期の必要性について心配する必要はありませんが、他の言語ではtox av _ * _ cbイベントがtox_iterateを提供するスレッドから呼び出されると「予期しない」驚きがありますフローサービングトックスav _iterate。たとえば、このようなイベントはtoxav_call_state_cb呼び出し完了イベントです。Toxカーネル内でのデッドロックの可能性を考慮して、適切な同期プリミティブを使用します。

通話管理

発信コールを作成するには、 toxav_callメソッド（friend_number、audio_bit_rate、video_bit_rate）を使用します 。ここで、連絡先リストの連絡先識別子と発信オーディオおよびビデオビットレート（Kb / s）が引数として指定されます。ビットレート値0は、対応するストリームの送信をブロックします。これは、 toxav_bit_rate_setを呼び出すことで後で有効にできます。

ToxAVには通常の呼び出し制御がありません-受け入れられない発信呼び出しは、アプリケーション自体の内部タイムアウトによって呼び出しがキャンセルされる（アプリケーションがハングアップする）か、連絡先がオフラインになりません（ネットワーク切断とtoxav_call_state_cbイベント）パラメータTOXAV_FRIEND_CALL_STATE_FINISHED ）。デフォルトでは、連絡先からのオーディオおよびビデオデータの受信は有効になっており、 toxav_call_controlを呼び出すことで変更できます。

着信呼び出しはtoxav_call_cbイベントによって決定され、その後、呼び出しは完全に無視されるか、呼び出しに応答するか、 toxav_call_controlを介してその状態を変更することによって処理されます。

呼び出しに応答するには、 toxav_answer呼び出し（friend_number、audio_bit_rate、video_bit_rate）を使用します 。ここでは、着信呼び出しを行う連絡先リストの連絡先識別子と、発信オーディオおよびビデオビットレート（Kb / s）が引数として指定されます。ビットレート値0は、対応するストリームの送信をブロックします。これは、 toxav_bit_rate_setを呼び出すことで後で有効にできます。

呼び出し状態を制御するには、 toxav_call_control（friend_number、control）呼び出しを使用します。ここで、以下の定数を制御パラメーターとして使用できます。

TOXAV_CALL_CONTROL_RESUME-呼び出しが応答されるまで、以前に一時停止された呼び出しを再開することはできません。
TOXAV_CALL_CONTROL_PAUSE-通話を一時停止に設定する（通話を保留、保留）。通話に応答するまで使用できません。
TOXAV_CALL_CONTROL_CANCEL-着信コールをリセットするか、アクティブなコールを終了します。
TOXAV_CALL_CONTROL_MUTE_AUDIO-音声データの送信を停止する要求を応答者に送信します（応答者はこの要求を無視できます）。
TOXAV_CALL_CONTROL_UNMUTE_AUDIO-音声データの送信を再開する要求を回答者に送信します。
TOXAV_CALL_CONTROL_HIDE_VIDEO-ビデオデータの送信を停止する要求を回答者に送信します（回答者はこの要求を無視できます）。
TOXAV_CALL_CONTROL_SHOW_VIDEO-回答者にビデオデータの送信を再開する要求を送信します。

オーディオとビデオのストリーミング

オーディオストリームを送信するには、呼び出しtoxav_audio_send_frame（friend_number、pcm、sample_count、channels、sampling_rate）が使用されます 。ここでは、連絡先リストからの連絡先の識別子、PCMデータバッファー、サンプル数、サンプル数、およびサンプリング周波数が指定されます。ステレオストリームのtoxav_audio_receive_frame_cbとの類推により、左右のチャネルの16ビットサンプルは次々と順番に進むはずです。

チャネルの最大数は2（ステレオ）であり、サンプリング周波数は8、12、16、24、および48 KHzの値を取ることができ、opusコーデックの機能により、サンプル数は2.5、5、10、20のフレーム期間に対応する必要があることを思い出してください40または60ミリ秒。

ビデオストリームのフレームを転送するには、呼び出しtoxav_video_send_frameを使用します。これは、Pythonラッパーでtoxav_video_send_yuv420_frame（friend_number、width、height、y、u、v）に名前が変更されます。 Y（輝度）および色差UV。

BGRからYUV420への変換の実装例は、たとえばμToxソースコード（ bgrtoyuv420 ）にあります。 Pythonラッパーでは、便宜上、メソッドtoxav_video_send_bgr_frame（friend_number、width、height、 bgr ）およびtoxav_video_send_rgb_frame（friend_number、width、height、rgb）が実装されており、これらの変換を個別に実行します（実際、µToxコードからbgrtoyuv420が使用されます）。

例

Pythonは、プロトタイピングと動作方法の学習に非常に便利な言語です。上記のすべてを明確に示すために、いくつかの例を作成しました。

echobot.pyは、送信されたテキストで応答する通常のテキストエコーボットです。さらに、連絡先、ステータス、アバター、ファイルの管理を示します。これは、残りの例の実装の基礎です。

echoavbot.py-発信者に送り返されたオーディオおよびビデオストリームを送信するオーディオおよびビデオエコーボット。データ転送の品質、発生する遅延に対するネットワークの影響を調査し、自分の機器をテストするのに便利です。

avbot.py-回答者をシミュレートし、自身のデバイスからオーディオおよびビデオデータを送信するボット。不在中にペットを観察するのに便利です:)

おわりに

Toxプロジェクトは現在も活発に開発されています。 Tox Foundationとの関係が断たれても、プロジェクトの開発はまったく妨げられず、2番目の風が吹き込まれたようです.PRが受け入れられ始め、チケットが整理され、新しいサイトが活発に埋められ、ドキュメントの作業が進行中です。グループチャットで作業するためのブランチがすぐにカーネルに注ぎ込まれ、カーネルが完全なプレリリースの外観になることを願っています。

参照資料

tox.chat -Toxプロジェクトの公式サイト。
githubのtoxcoreカーネルプロジェクト。
githubのPytoxcore pythonラッパープロジェクト。
「公式」クライアントビルドが開始されないDebian Wheezy、Ubuntu Precise、CentOS 6などの旧安定版ディストリビューションを含む、githubでtox.pkgクライアントとライブラリのバイナリバージョンをビルドするプロジェクト。

Toxメッセンジャーのオーディオとビデオ