通話モードのクイックスタート(Windows)

最終更新日:2021-10-12 14:14:54

    ドキュメントガイド

    このドキュメントでは、主にTRTC SDKをベースに簡単なビデオ通話機能を実現する方法を紹介します。ここでは最もよく使われるインターフェースを幾つかリストアップしただけですので、より多くのインターフェース関数を理解したい場合は、API ドキュメントをご参照ください。

    サンプルコード

    属するプラットフォーム サンプルコード
    Windows(MFC) TRTCMainViewController.cpp
    Windows(Duilib) TRTCMainViewController.cpp
    Windows(C#) TRTCMainForm.cs

    ビデオ通話

    1. SDKの初期化

    TRTC SDKを使用する第1ステップは、getTRTCShareInstanceエクスポートインターフェースによって、 TRTCCloudシングルインスタンスのオブジェクトポインタ ITRTCCloud*を取得し、SDKのイベントをモニタリングするコールバックを登録することです。

    • ITRTCCloudCallbackのイベントコールバックインターフェースクラスを継承し、キーとなるイベントのコールバックインターフェースをリライトします。これには、ローカルユーザーの入室/退室イベント、リモートユーザーの参加/退出イベント、エラーイベント、アラームイベントなどが含まれます。
    • addCallbackインターフェースを呼び出して、SDKのイベントの監視を登録します。
    注意:

    addCallbackでN回登録すると、同一イベントに対して、SDKがN回コールバックします、addCallbackを1回のみ呼び出すことをお勧めします。

    // TRTCMainViewController.h

    // ITRTCCloudCallbackのイベントコールバックインターフェースクラスを継承します
    class TRTCMainViewController : public ITRTCCloudCallback
    {
    public:
    TRTCMainViewController()
    ;
    virtual ~TRTCMainViewController();

    virtual void onError(TXLiteAVError errCode, const char* errMsg, void* arg)
    ;
    virtual void onWarning(TXLiteAVWarning warningCode, const char* warningMsg, void* arg)
    ;
    virtual void onEnterRoom(int result)
    ;
    virtual void onExitRoom(int reason)
    ;
    virtual void onRemoteUserEnterRoom(const char* userId)
    ;
    virtual void onRemoteUserLeaveRoom(const char* userId, int reason)
    ;
    virtual void onUserVideoAvailable(const char* userId, bool available)
    ;
    virtual void onUserAudioAvailable(const char* userId, bool available)
    ;
    ...
    private:
    ITRTCCloud * m_pTRTCSDK = NULL
    ...
    }

    // TRTCMainViewController.cpp

    TRTCMainViewController::TRTCMainViewController()
    {
    // TRTCCloud インスタンスの作成
    m_pTRTCSDK = getTRTCShareInstance();

    // SDK イベントコールバックの登録
    m_pTRTCSDK->addCallback(this);
    }

    TRTCMainViewController::~TRTCMainViewController()
    {
    // SDK イベントのモニタリング のキャンセル
    if(m_pTRTCSDK) {
    m_pTRTCSDK->removeCallback(this);
    }

    // TRTCCloud インスタンスのリリース
    if(m_pTRTCSDK != NULL) {
    destroyTRTCShareInstance()
    ;
    m_pTRTCSDK = null;
    }
    }

    // エラー通知はモニタリングする必要があります。エラー通知は、SDKの実行を継続できないことを意味します
    virtual void TRTCMainViewController::onError(TXLiteAVError errCode, const char* errMsg, void* arg)
    {
    if (errCode == ERR_ROOM_ENTER_FAIL)
    {
    LOGE(L"onError errorCode[%d], errorInfo[%s]", errCode, UTF82Wide(errMsg).c_str())
    ;
    exitRoom()
    ;
    }
    }

    2. TRTCParamsの組み立て

    TRTCParams は SDK で最も重要なパラメータであり、SDKAppID、userId、userSig 、roomIdの4つの記入必須のフィールドがあります。

    • SDKAppID
      Tencent CloudのTencent Real-Time Communicationコンソールにアクセスします。まだアプリケーションをお持ちでない場合、作成してください。SDKAppIDが表示されます。

    • userId
      自由に指定することができ、文字列タイプのため、お客様の既存のアカウント体系と同じのものにすることが可能です。但し、同じ音声/ビデオルームには2つの同名の userIdが存在できませんので、ご注意ください。

    • userSig
      SDKAppIDとuserIdを基に、userSigを計算できます。計算方法については、UserSigの計算方法をご参照ください。

    • roomId
      ルームナンバーは数字タイプとなり、自由に指定できます。但し、同じアプリケーション内の2つの音声/ビデオルームに、同じroomIdをアサインすることはできませんので、ご注意ください。

    3. ルームへの入室(または作成)

    enterRoom を呼び出し、 TRTCParams パラメータの中の roomIdが指定する音声/ビデオルームに参加できます。該当するルームが存在しない場合、SDK は roomId をルームナンバーとする新しいルームを自動作成します。

    appScene パラメータは、SDK のユースケースを指定します。ここでは、TRTCAppSceneVideoCall(ビデオ通話)を使用しますが、このシナリオにおいては、SDK 内部のコーディックおよびネットワークコンポーネントは、映像のスムーズさをより重視し、通話のディレーとラグ率を低減させるものとなっています。

    • 入室に成功すると、SDKがonEnterRoom インターフェースのコールバックを行います。パラメータ:resultが0を上回る時は、入室に成功し、数値は入室に要した時間を表しています(単位はミリ秒(ms))。resultが0を下回る時は、入室に失敗し、数値は入室失敗のエラーコードを表しています。
    • 入室に失敗した場合、SDK は同時に onError インターフェースをコールバックします。パラメータは、errCode(エラーコード:ERR_ROOM_ENTER_FAIL、エラーコードは TXLiteAVCode.hを参照のこと)、errMsg(エラー原因)、extraInfo(保留パラメータ)です。
    • すでに特定のルームにいる場合は、まずexitRoomを呼び出して現在のルームを退出すると、もう一つのルームに入ることができるようになります。
    // TRTCMainViewController.cpp

    void TRTCMainViewController::enterRoom()
    {
    // TRTCParamsの定義はヘッダーファイル TRTCCloudDef.hを参照
    TRTCParams params;
    params.sdkAppId = sdkappid;
    params.userId = userid;
    params.userSig = usersig;
    params.roomId = 908; // 入室したいルームを入力します
    if(m_pTRTCSDK)
    {
    m_pTRTCSDK->enterRoom(params, TRTCAppSceneVideoCall);
    }
    }

    ...

    void TRTCMainViewController::onError(TXLiteAVError errCode, const char* errMsg, void* arg)
    {
    if(errCode == ERR_ROOM_ENTER_FAIL)
    {
    LOGE(L"onError errorCode[%d], errorInfo[%s]", errCode, UTF82Wide(errMsg).c_str())
    ;
    // userSigが合法か、ネットワークが正常かなどをチェックします
    }
    }

    ...

    void TRTCMainViewController::onEnterRoom(int result)
    {
    LOGI(L"onEnterRoom result[%d]", result)
    ;
    if(result >= 0)
    {
    //入室に成功
    }
    else
    {
    //入室失敗、エラーコード = result;
    }
    }
    注意:

    • ユースケースに基づき適切なsceneパラメータを選択してください。誤った選択をすると、ラグ率または画面の解像度が想定のレベルに到達しなくなります。
    • 各端末のユースケースappSceneについては、統一する必要があります。統一していない場合、想定外のトラブルが生じる恐れがあります。

    4. リモート側オーディオストリームの視聴

    TRTC SDKは、デフォルトの状態でリモートの音声ストリームを受信するようになっています。このため追加コードを作成する必要はありません。特定の useridの音声ストリームを受信したくない場合は、 muteRemoteAudioを使用し、ミュートにすることができます。

    5. リモートビデオストリームの視聴

    TRTC SDKは、デフォルトの状態ではリモートのビデオストリームをプルしません。ルーム内のユーザーに上りビデオデータがあるときに、ルーム内の他のユーザーは、ITRTCCloudCallbackの中のonUserVideoAvailable のコールバックによって当該ユーザーのuseridを取得できます。その後、startRemoteViewのメソッドを呼び出せば当該ユーザーのビデオ画面を表示できます。

    setRemoteViewFillModeによって、ビデオ表示モードを Fill または Fit モードに指定することができます。この2種類のモードはビデオサイズはいずれも同じ比率で拡大縮小します。違いは以下のとおりです。

    • Fillモード:ビューウィンドウが全てコンテンツで埋まることを優先的に保証します。拡大縮小後のビデオサイズがビューウィンドウのサイズと一致しない場合、はみ出たビデオの部分はカットされます。
    • Fitモードでは、すべてのビデオコンテンツを確実に表示することが優先されます。拡大・縮小されたビデオサイズと表示ウィンドウのサイズが一致しない場合、塗りつぶされていないウィンドウ領域は黒で塗りつぶされます。
    // TRTCMainViewController.cpp
    void TRTCMainViewController::onUserVideoAvailable(const char* userId, bool available){
    if (available)
    {
    // レンダリングウィンドウのハンドルを取得します。
    CWnd *pRemoteVideoView = GetDlgItem(IDC_REMOTE_VIDEO_VIEW);
    HWND hwnd = pRemoteVideoView->GetSafeHwnd();

    // リモートユーザーのビデオのレンダリングモードを設定します。
    m_pTRTCSDK->setRemoteViewFillMode(TRTCVideoFillMode_Fill);
    // SDK インターフェースを呼び出し、リモートユーザーのストリーミングを再生します。
    m_pTRTCSDK->startRemoteView(userId、 hwnd);
    } else {
    m_pTRTCSDK->stopRemoteView(userId);
    }
    }

    6. ローカル集音のオン/オフ

    TRTC SDKは、デフォルトではローカルのマイクによる集音がオンになっていません。startLocalAudioで、ローカルの集音をオンにして音声ビデオデータを発信することができ、stopLocalAudioでこれをオフにします。

    説明:

    startLocalPreviewの後に引き続きstartLocalAudioを呼び出すことができます。

    7. ローカルビデオ撮影のオン/オフ

    TRTC SDK は、デフォルトではローカルのWebカメラの撮影が有効になっていません。startLocalPreview でローカルのWebカメラをオンにしてプレビュー画面を表示でき、stopLocalPreviewでこれをオフにします。

    • startLocalPreviewを呼び出して、ローカルビデオのレンダリングウィンドウを指定します。SDKがウィンドウのサイズをダイナミックに検出して、rendHwnd が表示する全てのウィンドウでレンダリングを行います
    • setLocalViewFillModeインターフェースを呼び出し、ローカルのビデオレンダリングモードを Fill または Fitに設定します。2種類のモードは、ビデオサイズはいずれも同じ比率で拡大縮小します。違いは次のとおりです。
      • Fill モード:ウィンドウ全てにコンテンツを表示することを優先的に保証します。拡大縮小後のビデオサイズがビューウィンドウのサイズと一致しない場合、はみ出た部分はカットされます。
      • Fitモードでは、すべてのビデオコンテンツを確実に表示することが優先されます。拡大・縮小されたビデオサイズとウィンドウのサイズが一致しない場合、塗りつぶされていないウィンドウ領域は黒で塗りつぶされます。
    // TRTCMainViewController.cpp

    void TRTCMainViewController::onEnterRoom(uint64_t elapsed)
    {
    ...

    // レンダリングウィンドウのハンドルを取得します。
    CWnd *pLocalVideoView = GetDlgItem(IDC_LOCAL_VIDEO_VIEW);
    HWND hwnd = pLocalVideoView->GetSafeHwnd();

    if(m_pTRTCSDK)
    {
    // SDKインターフェースを呼び出し、レンダリングモードおよびレンダリングウィンドウを設定します。
    m_pTRTCSDK->setLocalViewFillMode(TRTCVideoFillMode_Fit);
    m_pTRTCSDK->startLocalPreview(hwnd);
    }

    ...
    }

    8. オーディオ・ビデオデータストリームの遮断

    • ローカルビデオデータの遮断
      ユーザーが通話の途中に、プライバシーを守る目的で、ローカルのビデオデータを隠したい場合は、muteLocalVideoを呼び出して、一時的に、ルーム内の他のユーザーが当該ユーザーの画面を視聴できなくすることができます。

    • ローカル音声データの遮断
      ユーザーが通話の途中に、プライバシーを守る目的で、ローカルの音声データを遮断したい場合は、 muteLocalAudioを呼び出して、一時的に、ルーム内の他のユーザーに当該ユーザーの音声を聞こえなくすることができます。

    • リモートビデオデータの遮断
      stopRemoteViewによって特定の userid のビデオデータを遮断することができます。
      stopAllRemoteViewによって全てのリモートユーザーのビデオデータを遮断することができます。

    • リモート音声データの遮断
      muteRemoteAudio によって特定のuseridの音声データを遮断することができます。
      muteAllRemoteAudioによって全てのリモートユーザーの音声データを遮断することができます。

    9. ルームからの退出

    exitRoomメソッドを呼び出してルームを退出します。通話中かどうかにかかわらず、このメソッドを呼び出せば、ビデオ通話に関するすべてのリソースがリリースされます。

    説明:

    exitRoomを呼び出した後、SDKは複雑な退室のハンドシェイクのプロセスに進みます。SDKがonExitRoomメソッドをコールバックした時に、リソースのリリースが完了します。

    // TRTCMainViewController.cpp

    void TRTCMainViewController::exitRoom()
    {
    if(m_pTRTCSDK)
    {
    m_pTRTCSDK->exitRoom();
    }
    }
    ....
    void TRTCMainViewController::onExitRoom(int reason)
    {
    // 退室に成功しました。reasonパラメータは保留され、まだ使用されていません。

    ...
    }