Chat using Vivox

What for?

Vivoxをアプリケーションで使いやすくするラッパーを提供します。

Vivoxをラップしているこの機能をVivoxラッパーと呼ぶことにします。

VivoxのAPIを使ったログイン/ログアウトやチャンネルへの接続/切断といった実装はどのようなアプリケーションでも同じような実装になります。 VivoxラッパーはそのようなVivoxを使う場合に共通する実装を機能として提供します。

あなたのアプリケーションでVivoxラッパーを使うことでVivoxの導入がスムーズになることを目指しています。

注意

VivoxラッパーはVivoxを使いやすくしますが、Vivoxを知らなくてもVivoxラッパーだけ知っていればボイス/テキストチャットを実現できるわけではありません。 VivoxラッパーはVivoxをそのまま使う場合に使いにくい点や足りない機能を補いますが、ボイス/テキストチャットの処理はVivoxに移譲します。 そのため、Vivoxラッパーを使うにはVivoxを知っていることが前提です。 Vivoxを知らない場合はLearningを参照してVivoxについて学習してください。 このガイドはVivoxを知っている前提で説明しています。

注意

Vivoxは元々存在していたVivox Developer Portalと2021年10月に登場したUnity Gaming Servicesで使用できます。 現時点のVivoxラッパーはVivox Developer Portalに対応しています。 Unity Gaming Servicesには対応していません。 今後Unity Gaming Servicesへの対応を検討します。

Specification

Vivoxラッパーの仕様は次の通りです。

• Vivoxの機能を使用できます。
• Vivoxのクライアント状態をトリガーに処理を追加できます。

Architecture

classDiagram VivoxClient --> VivoxAppConfig VivoxClient ..> VivoxAuthConfig VivoxClient ..> VivoxChannelConfig VivoxChannelConfig --> ChatType IDisposable <|.. VivoxClient class VivoxClient { +Client Client +LoginSession ILoginSession +OnLoggedIn IObservable +OnLoggedOut IObservable +OnRecoveryStateChanged IObservable +OnChannelSessionAdded IObservable +OnChannelSessionRemoved IObservable +OnUserConnected IObservable +OnUserDisconnected IObservable +OnTextMessageReceived IObservable +OnAudioEnergyChanged IObservable +VivoxClient(appConfig) +LoginAsync(authConfig) void +Logout() void +ConnectAsync(channelConfig) void +Disconnect(channelId) void +DisconnectAllChannels() void +SendTextMessage(message, channelIds, language, applicationStanzaNamespace, applicationStanzaBody) void +SendTextMessage(message, channelId, language, applicationStanzaNamespace, applicationStanzaBody) void +SetTransmissionMode(transmissionMode, channelId) void +GetAudioInputDevicesAsync() IAudioDevices +SetAudioInputDeviceAsync(device) void +GetAudioOutputDevicesAsync() IAudioDevices +SetAudioOutputDeviceAsync(device) void } class VivoxAppConfig { +ApiEndPoint string +Domain string +Issuer string +SecretKey string +VivoxAppConfig(apiEndPoint, domain, issuer, secretKey) } class VivoxAuthConfig { +DisplayName string +AccountName string +TokenExpirationDuration TimeSpan +Timeout TimeSpan +VivoxAuthConfig(displayName, accountName, tokenExpirationDuration, timeout) } class ChatType { <<enumeration>> TextAndAudio TextOnly AudioOnly } class VivoxChannelConfig { +ChannelName string +ChatType ChatType +ChannelType ChannelType +Properties Channel3DProperties +TransmissionSwitch bool +TokenExpirationDuration TimeSpan +Timeout TimeSpan VivoxChannelConfig(channelName, chatType, channelType, transmissionSwitch, tokenExpirationDuration, timeout) } class IDisposable { <<system>> }

Installation

Package

https://github.com/extreal-dev/Extreal.Integration.Chat.Vivox.git

Dependencies

Vivoxラッパーは次のパッケージを使います。

• Extreal.Core.Logging
• Vivox Unity SDK
• UniTask
• UniRx

モジュールバージョンと各パッケージバージョンの対応はReleaseを参照ください。

Settings

VivoxClientを初期化します。

Vivox Developer Portalでクライアントからの接続先となるアプリケーションが作成されているものとします。

VivoxClientの初期化にはVivoxへの接続情報を保持するVivoxAppConfigが必要です。 今回は一例としてScriptableObjectでVivoxへの接続情報を設定する方法を紹介します。 VivoxAppConfigを生成するScriptableObjectを作成し、インスペクタでVivoxへの接続情報を設定します。

[CreateAssetMenu(
    menuName = "Config/" + nameof(ChatConfig),
    fileName = nameof(ChatConfig))]
public class ChatConfig : ScriptableObject
{
    [SerializeField] private string apiEndPoint;
    [SerializeField] private string domain;
    [SerializeField] private string issuer;
    [SerializeField] private string secretKey;

    public VivoxAppConfig ToVivoxAppConfig()
        => new VivoxAppConfig(apiEndPoint, domain, issuer, secretKey);
}

VContainerを使ってVivoxClientを初期化します。

public class ChatControlScope : LifetimeScope
{
    [SerializeField] private ChatConfig chatConfig;

    protected override void Configure(IContainerBuilder builder)
    {
        builder.RegisterComponent(chatConfig.ToVivoxAppConfig());
        builder.Register<VivoxClient>(Lifetime.Singleton);
    }
}

Usage

Vivoxの機能を使用する

Vivoxの機能はVivoxClientが提供します。 VivoxClientが提供していない機能はVivoxClientからVivoxが提供するClientやILoginSessionを取得して実装してください。

var client = vivoxClient.Client;
var loginSession = vivoxClient.LoginSession;

ここではVivoxClientの基本的な使い方をいくつか紹介します。

ボイス/テキストチャットを行うにはまずVivoxのアプリケーションにログインが必要です。 ログインはVivoxClientのLoginAsyncを使います。

var vivoxAuthConfig = new VivoxAuthConfig("Guest");
vivoxClient.LoginAsync(vivoxAuthConfig).Forget();

ログアウトはVivoxClientのLogoutを使います。

vivoxClient.Logout();

チャンネルへの入室はVivoxClientのConnectAsyncを使います。

var vivoxChannelConfig = new VivoxChannelConfig("GuestChannel");
vivoxClient.ConnectAsync(vivoxChannelConfig).Forget();

VivoxChannelConfigはデフォルトでボイスチャットとテキストチャットを有効にします。 ボイスチャットのみ、テキストチャットのみに制限したい場合はChatTypeを指定します。 ボイスチャットのみに制限する場合の例は次の通りです。

var vivoxChannelConfig = new VivoxChannelConfig("GuestChannel", ChatType.AudioOnly);

空間内でのみボイスチャットやテキストチャットをできるようにする場合など、空間からの退室時点で全てのチャンネルから退室する場合はVivoxClientのDisconnectAllChannelsを使います。

vivoxClient.DisconnectAllChannels();

グループチャット機能を提供している場合など、特定のチャンネルから退室する場合はVivoxClientのDisconnectを使います。

vivoxClient.Disconnect(channelId);

テキストチャットのメッセージ送信はVivoxClientのSendTextMessageを使います。

vivoxClient.SendTextMessage(message, channelId);

テキストチャットのメッセージ受信はVivoxClientが発行するイベント通知のOnTextMessageReceivedを使用します。

vivoxClient.OnTextMessageReceived
    .Subscribe(message => /* do something with message */)
    .AddTo(disposables);

Vivoxのクライアント状態をトリガーに処理を追加する

VivoxClientは次のイベント通知を設けています。

• OnLoggedIn
  • タイミング：ログインした直後
  • タイプ：IObservable
  • パラメータ：なし
• OnLoggedOut
  • タイミング：ログアウトした直後
  • タイプ：IObservable
  • パラメータ：なし
• OnRecoveryStateChanged
  • タイミング：予期しないネットワーク切断時のリカバリ状態が変化した直後
  • タイプ：IObservable
  • パラメータ：リカバリ状態
    • ConnectionRecoveryState
• OnChannelSessionAdded
  • タイミング：チャンネルが追加された直後
  • タイプ：IObservable
  • パラメータ：追加されたチャンネルのID
    • ChannelId
• OnChannelSessionRemoved
  • タイミング：チャンネルが削除された直後
  • タイプ：IObservable
  • パラメータ：削除されたチャンネルのID
    • ChannelId
• OnUserConnected
  • タイミング：チャンネルに参加者が入室した直後
    • イベント発生元になったユーザーにもこのイベントが通知されます。
  • タイプ：IObservable
  • パラメータ：入室した参加者
    • IParticipant
    • 参加者がチャンネルに入室したユーザー自身かどうかはIParticipantのIsSelfプロパティで判定します。
• OnUserDisconnected
  • タイミング：チャンネルから参加者が退室した直後
    • イベント発生元になったユーザーにもこのイベントが通知されます。
  • タイプ：IObservable
  • パラメータ：退室した参加者
    • IParticipant
    • 参加者がチャンネルから退室したユーザー自身かどうかはIParticipantのIsSelfプロパティで判定します。
• OnTextMessageReceived
  • タイミング：チャンネルにメッセージが着信した直後
  • タイプ：IObservable
  • パラメータ：着信したメッセージ
    • IChannelTextMessage
• OnAudioEnergyChanged
  • タイミング：参加者の音声の大きさに変化があった直後
  • タイプ：IObservable
  • パラメータ：参加者と音声の大きさ（タプル）
    • IParticipant
    • AudioEnergy