本日本語訳はPJSIP Video User's Guideをよりよく理解をする支援を行う目的で作成されたものであり、非公式なドキュメントです。

原文: PJSIP Video User's Guide

バージョン2.0以降のPJSIPではビデオ通話が可能です。ただしビデオ通話はデスクトップのみで有効です。iOSを含むモバイルデバイスはまだサポートされません（訳者注：2.3でiOSのビデオ通話がサポートされています）。
このドキュメントではPJSIPでビデオ通話をする為の方法を説明します。

ビデオサポート付きのビルド

あなたのプラットフォームにおいて、pjsipをビデオ通話対応でビルドする為にGettting Startedに従ってビルドしてください。

GUIサンプルアプリケーションをビルドする

GNUビルド・システム(Mac OSX, Linux等)

以下のステップに従ってvidguiサンプルをビルドしてください。

vidguiのソースディレクトリに移動する。
- $ cd pjsip-apps/src/vidgui
Linux用にMakefileを生成します。
- $ qmake
Mac OSXの場合
- $ qmake -spec macx-g++
アプリケーションをビルドします。
- $ make

Visual Studio

Visual Studioでvidguiサンプルをビルドする為に下記の手順に従ってください。

コマンドプロンプトを起動し、以下を実行します。
- cd pjsip-apps\src\vidgui
プロジェクトファイルを生成する。
- qmake -tp vc
vidgui.vcprojを起動します。
保存し、プロジェクトをビルドします。

ビデオAPIを使う（pjsua-lib）

この章では、あなたのアプリケーションでビデオを使う幾つかのパターンをお見せします。
ビデオAPIについてのより詳しい情報が必要な場合はVideo API Referenceを参照してください。

ビデオの有効化

初期状態で、pjsua_call_setting内のvid_cnt設定によってビデオ設定は有効になっています。

ビデオコールの受信

ビデオ受信の許可/拒否はビデオ設定が有効かどうかによって決まります（一つ前の章を見てください）。
あなたはAPI(pjsua_call_answer2())を使う事でcall設定を反映する事ができます（例：ビデオを拒否するには、vid_cntを0に設定して pjsua_call_answer2()を呼びます）。
もしビデオが有効であれば、お互いのビデオコーデックがマッチしていればビデオ受信はは許可されるでしょう。しかしながら、この事はビデオが自動的に画面上に表示される事を必ずしも意味しません。また、ビデオ送信データが自動的に送信される事も意味しません。これらの設定はそれぞれ別個のものとして別れています。
ビデオデータの送信については次の章で説明します。

受信ビデオデータの自動表示

初期状態ではビデオ受信データは自動的には画面に表示されません。これはアプリがユーザーによる承認を最初に求めたいかもしれない為です。
この振る舞いはアカウント毎に以下のコードで変更できます。

pjsua_acc_config cfg;

pjsua_acc_config_default(&cfg);
cfg.vid_in_auto_show = PJ_TRUE;

受信ビデオの表示・非表示

上のように設定した場合でも、次の手順を行う事でビデオの表示・非表示を切り替える事ができます。

デフォルトで使用するビデオのメディアインデックスを見つける為に、pjsua_call_get_vid_stream_idx()を呼ぶか、呼ばれたメディアストリームを列挙してください。もしも１つの通話で複数のビデオストリームが存在した場合、デフォルトのビデオは、その通話の中で最初にアクティブになったビデオストリームです。

pjsua_call_info に、指定されたストリームインデックスのメディア情報を与えます。そして通話相手のビデオと関連付いているウインドウのIDを得ます。以下はそのサンプルコードです。

int vid_idx;
pjsua_vid_win_id wid;

vid_idx = pjsua_call_get_vid_stream_idx(call_id);

if (vid_idx >= 0) {
    pjsua_call_info ci;

    pjsua_call_get_info(call_id, &ci);
    wid = ci.media[vid_idx].stream.vid.win_in;
}

ビデオウインドウIDを使う事で、pjsua_vid_win_get_info()により関連付けられたネイティブビデオの操作ハンドルを得られます。そしてビデオウインドウの表示・非表示をネイティブAPI、またはPJSUAのAPIであるpjsua_vid_win_set_show()で切り替える事が出来ます。ビデオウインドウの操作についての情報はWorking with Windowの章を参照してください。

受信ビデオデータの制御

上で説明したビデオ・ウインドウの制御はre-INVITEもUPDATEも相手側に送る事はありません。なぜなら上記操作はローカルでのものに限られるからです。
しかしながら、pjsua_call_set_vid_strm()APIを使用して受信ビデオストリームになんらかの変更を行いたい場合は、あたらしいSDPを取り決めるためにre-INVITEまたはUPDATEを送る必要が有ります。
pjsua_call_set_vid_strm()を使ったビデオ受信の制御に関係する操作は以下です。

PJSUA_CALL_VID_STRM_CHANGE_DIR: メディアのディレクションを変更する。
- 例 "sendonly(受信のみ)", あるいは "inactive（動作していない）"
PJSUA_CALL_VID_STRM_REMOVE: portを0に設定する事で、全てのメディアストリームを削除する。
PJSUA_CALL_VID_STRM_ADD: 新しいメディアストリームを追加する

Incoming Re-offer

(後回し)
If the re-offer contains video, incoming re-offer will be automatically answered with current video setting in the call setting. Currently there is no callback for this, however application can always watch for media update via on_call_media_state() callback.

ビデオデータの送信

ビデオデータの送信は、受信とは別に扱われます。其々は別個に制御できます。そしてビデオデータの送信は初期設定では開始されない事に注意してください。ビデオ通話を受信した際に、相手側がビデオのサポートを含んでいたとしてもです。この振る舞いはpjsua_acc_config.vid_out_auto_transit設定によって制御できます。この設定は初期設定ではPJ_FALSEです。この設定をPJ_TRUEにする事で、全ての電話の発信・受信で、相手側でビデオが有効だった場合にビデオデータの送信を開始します。
しかしながら、この設定はPJ_FLASEのままにしておき、後から通話中にAPIのpjsua_call_set_vid_strm()を呼ぶほうが柔軟で適切です。これについてはこのすぐ後で説明します。

デフォルトのキャプチャデバイス

(後回し)
The default capture device that is used by an account is configured in pjsua_acc_config.vid_cap_dev setting. It is more convenient to set the "correct" device here rather than having to set it in every other API calls later.

ビデオストリームの制御

アプリケーションはpjsua_call_set_vid_strm()APIを使って通話におけるビデオストリームを制御します。以下のop_codeはAPIを通じてビデオメディアを制御するのに使用する事が出来ます。

PJSUA_CALL_VID_STRM_ADD: 新しいビデオストリームを追加する。
PJSUA_CALL_VID_STRM_REMOVE: ビデオストリームの削除（portをゼロに設定）
PJSUA_CALL_VID_STRM_CHANGE_DIR:ディレクションの変更または非アクティブ化
PJSUA_CALL_VID_STRM_CHANGE_CAP_DEV: キャプチャするデバイスの変更
PJSUA_CALL_VID_STRM_START_TRANSMIT: 止められていた送信の再開
PJSUA_CALL_VID_STRM_STOP_TRANSMIT: 送信の停止

上記操作のうち、幾つかはre-INVITEかUPDATEを送らなければなりません。それ故に結果はすぐには反映されません。この場合、アプリケーションはon_call_media_state()コールバックを実装し、pjsua_call_infoの戻り値を見る事で結果のチェックを行う事ができます。
上記操作についてのより詳しい情報は、APIリファレンス中のVideo Call Manipulationの章を参照してください。

ビデオの追加と削除

pjsua_call_settingのvid_cntフィールドにビデオの数を設定しreinvite/updateする事でビデオの追加/削除を行えます。
あるいはpjsua_call_set_vid_strm()APIを使って通話回線上のビデオストリームを制御できます（上記受信ビデオデータの制御 または ビデオストリームの制御を参照してください）。