本文にスキップする
Version: 6.1

グループビデオ通話を始める

PlanetKitを使用することで、1対1通話またはグループ通話のための音声およびビデオ通話機能をアプリに連携できます。このガイドでは、Windowsアプリでグループビデオ通話の実装を開始する方法について説明します。

Note
  • より迅速な開発のために、クイックスタートに基づいてアプリを実装できます。
  • このガイドでは、アプリケーションフレームワークとしてMFCを使用する例を提供します。

前提条件​

  • 使用しているシステムがシステム要件を満たしていることを確認してください。
  • API keyを作成してください。詳しくは、開発環境を参照してください。
  • アクセストークンを作成するアプリサーバーコードを実装してください。詳しくは、アクセストークン作成方法を参照してください。
  • Visual Studio 2022以降と下記のコンポーネントをインストールします（すでにVisual Studioがインストールされている場合は、［ツール］＞［ゲット ツールと機能］に移動してコンポーネントを追加できます）。
    • C++によるデスクトップ開発：［ワークロード］タブで、［C++によるデスクトップ開発］を選択します。
    • 最新のv143ビルドツール用C++ MFC (x86およびx64)：［個別のコンポーネント］タブで、［最新のv143ビルドツール用C++ MFC (x86およびx64)］を選択します。
  • PlanetKit WindowsからPlanetKit SDKをダウンロードしてください。

プロジェクト作成​

Visual Studioを開き、次のように新しいプロジェクトを作成します。

  1. メインメニューから［ファイル］＞［新規作成］＞［プロジェクト］を選択します。
  2. プロジェクト作成ウィンドウのリストからプロジェクトテンプレートを選択します。MFCアプリケーションを作成するには、［MFC アプリ］を選択します。
  3. ［プロジェクト名］にアプリケーションのプロジェクト名を入力し、［作成］をクリックします。
  4. ［MFC アプリケーション］ウィンドウの［アプリケーションの種類］以下［アプリケーションの種類］ドロップダウンから［ダイアログ ベース］を選択し、［完了］をクリックします。

SDKインストール​

次のようにプロジェクトにSDKをインストールします。

  1. ［ソリューション エクスプローラ］でプロジェクト名を右クリックし、［プロパティ］をクリックして次のプロジェクトプロパティを設定します。
    1. ［C/C++］＞［全般］＞［追加インクルードディレクトリ］に移動し、［編集...］をクリックしてPlanetKit SDKのincludeディレクトリの場所を選択します。
    2. ［リンカ］＞［全般］＞［追加のライブラリディレクトリ］に移動し、［編集...］をクリックしてPlanetKit SDKのbinディレクトリの場所を選択します。
    3. ［リンカー］＞［入力］＞［追加の依存ファイル］に移動し、［編集...］をクリックし、開発に使用されているプラットフォームに応じてPlanetKitライブラリの名前を入力します。
      • プラットフォームがx64の場合は、PlanetKit64.libと入力してください。
      • プラットフォームがWin32の場合は、Planetkit.libと入力してください。
  2. ［確認］をクリックします。

SDK初期化​

PlanetKit APIを呼び出すには、まずPlanetKitを初期化する必要があります。Configurationオブジェクトと共にPlanetKitManager::Initialize()を使ってPlanetKitを初期化します。

次に、PlanetKitManager::UpdateServerUrl()を使ってサーバーURL（planet_base_url）を設定する必要があります。利用している開発環境に応じて、適切なplanet_base_urlを使用してください。

void YourApplication::InitializePlanetkit()
{
    PlanetKit::ConfigurationPtr pConfiguration = PlanetKit::Configuration::Create(L"./", L"./");

    PlanetKit::PlanetKitManager::Initialize(pConfiguration);

    PlanetKit::PlanetKitManagerPtr pPlanetKitManager = PlanetKit::PlanetKitManager::GetInstance();

    pPlanetKitManager->UpdateServerUrl(planet_base_url);
}
Note

アプリでPlanetKitManager::Initialize()メソッドを最初に一度呼び出す必要があります。ダイアログベースのMFCアプリケーションの場合は、アプリのOnInitDialog()オーバーライド関数でSDKを初期化することをお勧めします。

アクセストークン取得​

クライアントアプリからアプリサーバーにアクセストークンの作成をリクエストしてください。

Note

PlanetKitManager::JoinConference()を呼び出す度に新しいアクセストークンを受け取って使用する必要があります。

グループビデオ通話の参加​

グループビデオ通話に参加するには、IConferenceEventインタフェースのコールバックを実装し、ConferenceParamPtrオブジェクトでPlanetKitManager::JoinConference()を呼び出します。

class YourConferenceEventListener : public IConferenceEvent {
public:
    // This is called when the call is connected.
    // Write your own code in function.
    void OnConnected(PlanetKitConferencePtr pPlanetKitConference, ConferenceConnectedParamPtr pConnectedParam);

    // This is called when the call is disconnected.
    // Write your own code in function.
    void OnDisconnected(PlanetKitConferencePtr pPlanetKitConference, ConferenceDisconnectedParamPtr pDisconnectedParam);

    // This is called when the list of peers is updated.
    // Write your own code here.
    void OnPeerListUpdate(PlanetKitConferencePtr pPlanetKitConference, ConferencePeerUpdateParamPtr pParam);

    // This is called when the video of one or more peers is updated.
    // Write your own code in function.
    void OnPeersVideoUpdated(PlanetKitConferencePtr pPlanetKitConference, ConferenceVideoUpdatedParamPtr pParam);

    ...

    //
    // Also, you should implement other override functions.
    //
}

class YourApplication {
private :
    // Prepare callback event listener instance.
    PlanetKit::SharedPtr<YourConferenceEventListener> m_pYourConferenceEventListener = PlanetKit::MakeAutoPtr<YourConferenceEventListener>();

    // Prepare PlanetKitConference instance.
    PlanetKit::PlanetKitConferencePtr m_pConference;
};

void YourApplication::JoinConferenceExample(const std::wstring strRoomId, const std::wstring strAccessToken) {
    // Prepare local user's ID.
    std::wstring strUserId = "local user's user id";
    std::wstring strServiceId = "local user's service id";

    // Create the UserId object.
    PlanetKit::UserIdPtr pUserId = PlanetKit::UserId::Create(strUserId.c_str(), strServiceId.c_str());

    // Create MakeCallParam with Create API.
    PlanetKit::ConferenceParamPtr pConferenceParam = PlanetKit::ConferenceParam::CreateWithAccessToken(
            pUserId,
            strRoomId.c_str(),
            strServiceId.c_str(),
            strAccessToken.c_str()
        );

    // Set required parameter.
    pConferenceParam->SetConferenceEvent(m_pYourConferenceEventListener);

    // Set the call type to video call
    pConferenceParam->SetIsVideoCall(true);

    // Now you have to create a PlanetKit::PlanetKitConference type object
    // through the PlanetKit::PlanetKitManager::JoinConference() function.
    // Please note that the PlanetKit::PlanetKitConference type object is the main call instance
    // that controls call-related functions after the call setup completion.
    PlanetKit::PlanetKitManagerPtr pPlanetKitManager = PlanetKit::PlanetKitManager::GetInstance();

    // The currently used microphone device must be passed to JoinConference() as an argument.
    // If the microphone in use has not been set, set it using the ChangeMic() of AudioManager.
    // If the microphone is not set, PlanetKit::NullOptional will be retrieved by GetCurrentMic().
    // Passing PlanetKit::NullOptional to JoinConference() will start the conference without a microphone device.
    auto pMic = pPlanetKitManager->GetAudioManager()->GetCurrentMic();

    PlanetKit::SStartResult sStartResult = pPlanetKitManager->JoinConference(pConferenceParam, pMic, &m_pConference);
    if (sStartResult.bSuccess == false) {
        // Handle an error by referring to sStartResult.reason
    }
}
Note

ユーザーがクライアントアプリでグループ通話ルームに参加するには、ルームのIDが必要なため、アプリケーションで定義した通信チャンネルを通じてルームIDを他のユーザーと共有する必要があります。

ローカルユーザーに対するビデオビューレンダリング​

ローカルユーザーのビデオを表示する方法は2つあります。HWNDを使用する方法と、未加工（raw）のビデオフレームを受信する方法です。

HWND使用​

ローカルユーザーのビデオをレンダリングするHWNDを準備し、PlanetKitConference::AddMyVideoView()を使用してPlanetKitConferenceにHWNDを追加します。

class YourApplication {
public:
  void AddMyVideoView(HWND hMyVideoWindow) {
    m_pConference->AddMyVideoView(hMyVideoWindow);
  }
}

未加工のビデオフレーム使用​

未加工のビデオフレームを受信するためにIVideoReceiverクラスを宣言します。

class YourVideoReceiver : public PlanetKit::IVideoReceiver {
public:
  void OnVideo(const SVideoFrame& pVideoFrame, UserIdPtr pUserID) {
    // Render video using raw video data here.
  }
}

YourVideoReceiverのインスタンスを作成し、PlanetKitConference::AddMyVideoReceiver()を使用してPlanetKitConferenceに追加します。

class YourApplication {
private:
  // Create an instance of YourVideoReceiver.
  PlanetKit::SharedPtr<YourVideoReceiver> m_yourVideoReceiver = PlanetKit::MakeAutoPtr<YourVideoReceiver>();

public:
  void AddMyVideoReceiver() {
    m_pConference->AddMyVideoReceiver(m_yourVideoReceiver);
  }
}

リモートユーザーに対するビデオビューレンダリング​

リモートユーザーのビデオを表示する方法も2つあります。HWNDを使用する方法と、未加工のビデオフレームを受信する方法です。

PeerControlインスタンス作成​

リモートユーザーのビデオ状態を処理するためにIPeerControlEventクラスを宣言します。

class YourPeerControlEvent : public PlanetKit::IPeerControlEvent {
  /// Called when a peer is initialized.
  void OnInitialized(PlanetKit::PeerControlPtr pPeerControl, bool bResult) override;
  /// Called when a peer's video status is updated.
  void OnVideoUpdated(PlanetKit::PeerControlPtr pPeerControl, PlanetKit::SubgroupPtr pSubgroup, const PlanetKit::VideoStatus& videoStatus) override;

  ...
}

PlanetKit::Peer::CreatePeerControl()を使用してPeerControlインスタンスを作成します。

class YourConferenceEventListener : public PlanetKit::IConferenceEvent {
private:
  YourApplication* m_pYourApplication;

public:
  // This is called when the list of peers is updated.
  // Write your own code here.
  void OnPeerListUpdate(PlanetKitConferencePtr pPlanetKitConference, ConferencePeerUpdateParamPtr pParam) {
    // Call event callback API of owner class instance or dispatch event.
    m_pYourApplication->OnPeerListUpdate(pPlanetKitConference, pParam);
  }
};

// Example of a custom data structure for a remote user
class PeerContainer {
private:
  PlanetKit::PeerPtr m_pPeer;
  PlanetKit::PeerControlPtr m_pPeerControl;
  PlanetKit::SharedPtr<IPeerControlEvent> m_pPeerControlEvent = PlanetKit::MakeAutoPtr<YourPeerControlEvent>();

public:
  PeerContainer(PlanetKit::PeerPtr pPeer) {
    m_pPeer = pPeer;

    // Create PeerControl instance
    m_pPeerControl = m_pPeer->CreatePeerControl();

    // Register event class for handling the remote user's video state
    m_pPeerControl->Register(m_pPeerControlEvent);
  }
};

class YourApplication {
private:
  std::map<std::wstring, PeerContainer*> m_remoteUsers;

public:
  void OnPeerListUpdate(PlanetKitConferencePtr pPlanetKitConference, ConferencePeerUpdateParamPtr pParam) {

    // Example of handling a remote user
    auto const& arrAdded = pParam->GetAddedPeer();
    for (int index = 0; index < arrAdded.Size(); ++index) {
      auto pPeer = arrAdded.At(index);
      PeerContainer* pPeerContainer = new PeerContainer(pPeer);
      m_remoteUsers[pPeer->GetUserID()->GetID().c_str()] = pPeerContainer;
    }
  }
};

リモートユーザーのビデオ表示​

HWND使用​

ローカルユーザーのビデオをレンダリングするHWNDを準備し、PeerControl::SetView()を使用してPeerControlにHWNDを設定します。

class PeerContainer {
public:
  void SetView(HWND hRemoteVideoWindow) {
    m_pPeerControl->SetView(hRemoteVideoWindow);
  }
}

未加工のビデオフレーム使用​

未加工のビデオフレームを受信するためにIVideoReceiverクラスを宣言します。

class YourVideoReceiver : public PlanetKit::IVideoReceiver {
public:
  void OnVideo(const SVideoFrame& pVideoFrame, UserIdPtr pUserID) {
    // Render video using raw video data here.
  }
}

YourVideoReceiverのインスタンスを作成し、PeerControl::RegisterReceiver()を使用してPlanetKitConferenceに登録します。

class PeerContainer {
private:
  // Create an instance of YourVideoReceiver.
  PlanetKit::SharedPtr<YourVideoReceiver> m_yourVideoReceiver = PlanetKit::MakeAutoPtr<YourVideoReceiver>();

public:
  void RegisterRemoteVideoReceiver() {
    // Register video receiver instance
    m_pPeerControl->RegisterReceiver(m_yourVideoReceiver);
  }
}

リモートユーザーのビデオレンダリングの開始または中止​

PeerControl::StartVideo()またはPeerControl::StopVideo()を使用してリモートユーザーのビデオレンダリングを開始または中止します。

class PeerContainer {
public:
  void StartVideo() {
    m_pPeerControl->StartVideo(PlanetKit::NullOptional, PlanetKit::EVideoResolution::PLNK_VIDEO_RESOLUTION_RECOMMENDED);
  }

  void StopVideo() {
    m_pPeerControl->StopVideo();
  }
}

リモートユーザーのビデオ状態処理​

IPeerControlEventインスタンスを通じてリモートユーザーのビデオ状態を処理します。

class YourPeerControlEvent : public PlanetKit::IPeerControlEvent {
  /// Called when a peer's video status is updated.
  void OnVideoUpdated(PlanetKit::PeerControlPtr pPeerControl, PlanetKit::SubgroupPtr pSubgroup, const PlanetKit::VideoStatus& videoStatus) {
    switch (videoStatus) {
    case PlanetKit::EVideoState::PLNK_VIDEO_STATE_DISABLED:
      // Disabled remote user's video
      break;

    case PlanetKit::EVideoState::PLNK_VIDEO_STATE_ENABLED:
      // Enabled remote user's video
      break;

    case PlanetKit::EVideoState::PLNK_VIDEO_STATE_PAUSED:
      // Paused remote user's video
      break;
    }
  }
}

次のステップ​

以下のドキュメントを参照して、PlanetKitが提供するさまざまな機能と各機能の詳しい使い方を確認してください。

  • 通話フロー：通話タイプ別の通話フローを確認してください。
  • サブグループ：複数の下位グループがあるルームや通訳ルームのような高級機能を実装できるサブグループ機能を確認してください。
  • 拡張機能：画面共有、データセッションなどのさまざまな拡張機能を確認してください。
  • サンプルコード：アプリの実装に参考となるサンプルコードを確認してください。
  • 参照ドキュメント：APIリファレンス、API変更履歴、リリースノートを確認してください。