SkyWay Android SDK

SkyWay Android SDK(以下、Android SDK)は Android デバイス用のアプリケーションから SkyWay を利用するための SDK です。
Android のネイティブなアプリケーションに SkyWay を組み込むことで、デバイス同士やブラウザとのリアルタイム通信を実現できます。

目次

• インストール方法

• SkyWayを用いたアプリ開発の概要

• 用語の解説

• 基本機能の解説

• Tips

• 参考リンク

インストール方法

app/build.gradle に以下の依存関係を追加するだけでSDKのインストールは完了です。

dependencies {
    implementation "com.ntt.skyway:room:$skywayVersion"
}

最新の SDK バージョンはMaven Central Repository にて確認してください。

SkyWayを用いたアプリ開発の概要

SkyWayを利用するためには、通信を開始するまでに以下のステップを踏む必要があります。

1. SkyWay Auth Token を作成する
SkyWayを利用するために必要な認証情報（AuthToken）を作成します。
詳細はSkyWay Auth Token についてをご覧ください。

2. Room を作成する
メディア通信を行うグループの単位を Room と呼びます。
まずは Room を作成する必要があります。（SkyWay Auth Token にRoomを作成する権限が必要）

3. Room に参加してMemberを取得する
作成したRoomに参加し、その結果としてMemberを取得します。
他のクライアントでは、作成済みのRoomを取得して参加します。

4. Room 内に Stream を 公開（Publish）する
Member を使って Room に 映像や音声などのStream の情報を公開（Publish）します。
すると、 Room 上に Stream の公開情報（Publication） が作成されます。

5. Room 内に公開されているStreamの情報（Publication）を購読（Subscribe）する
Room上に作成されたPublication を 他の Member から購読（Subscribe）します。
すると、メディア通信を開始することができ、結果として購読情報（Subscription）が作成されます。
そのSubscriptionから取得したStreamを利用することで、受信した映像や音声を出力することができます。

用語の解説

SkyWayを利用する際に登場する用語について解説します。

Room
Roomは通話を行うグループの単位であり、共通の Room に参加したユーザー同士で通話を行うことができます。
RoomにはP2P Room と SFU Room の 2 種類の Room があり、どちらかを選択して利用できます。
P2P Room は少人数(4人程度)向けで、SFU Room は多人数向けです。

Member
Room に参加しているユーザーのことを Member と呼びます。

Stream
Room 上で送受信できるメディアのことを Stream といいます。
音声、映像、データの3種類の Stream を利用できます。

Publish
Member が Stream を Room に公開することを Publish といいます。
Stream を Publish すると Room 上に Stream に対応する Publication というリソースが作成されます。

Subscribe
Member が Room 上の Publication を受信することを Subscribe といいます。
Subscribe をすると Room 上に Subscription というリソースが作成されます。
Publication を Subscribe した Member は Subscription を通じて Stream にアクセスし映像や音声を受信できます。

基本機能の解説

Android SDKの基本的な機能について解説します。 動作するアプリケーションを作成したい場合は、クイックスタートも合わせてご参照ください。

SkyWayContext

SkyWay利用の開始や終了を行うためのクラスです。 ログレベルなど、アプリケーション全体に影響するオプションの設定も担っています。

SkyWay利用の開始

// 開発環境ではappId/secretで初期化することができます。
val result = SkyWayContext.setupForDev(applicationContext, appId, secretKey, option)

// 本番環境ではAuthTokenを作成し、そちらを利用して初期化してください。
val result = SkyWayContext.setup(applicationContext, authToken)

事前に SkyWay Auth Token の取得が必要になります。

Auth Tokenの更新

Auth Tokenには期限を設定する必要があり、期限が切れるとSkyWayを利用できなくなります。
そのため、Auth Tokenが失効する前に更新してください。

// Auth Tokenの更新が必要なタイミングを検知
SkyWayContext.onTokenRefreshingNeededHandler = {
    // 新しいAuth Tokenに更新
    SkyWayContext.updateAuthToken(newToken)
}

SkyWay利用の終了

SkyWayContext.dispose()

Room

通話グループである Room の作成/取得および操作を行うことができます。 Room には P2PRoom と SFURoom の 2 種類が存在し、API は基本的に共通しています。

Roomの作成・取得

Roomの作成時にnameを指定することができます。 他のクライアントからは同じnameを指定してRoomを取得することができます。

// Roomの作成
val room = P2PRoom.create(name = roomName)

// Roomの取得
val room = P2PRoom.find(name = roomName /* または id = roomId */)

// Roomの取得を試み、存在しなければ作成
val room = P2PRoom.findOrCreate(name = roomName)

Metadata の更新

Room の Metadata を更新することができます

// metadataの取得
val metadata = room.metadata

// metadataの更新
room.updateMetadata("metadata")

Member の Room への参加

Room に参加すると LocalRoomMember インスタンスを取得できます。
RoomMember.Initにはnameとmetadataの設定が可能です。

val localRoomMember = room.join(RoomMember.Init())

LocalRoomMember

Memberの操作を行うことができます。 具体的には、Metadataの更新、Stream の Publish/Subscribe を行うことが出来ます。

Metadata の更新

Member の Metadata を更新することができます

// metadataの取得
val metadata = member.metadata

// metadataの更新
member.updateMetadata("metadata")

Stream の Publish

Room に Stream を Publish することができます。
また、Room 上の Stream の Publication を Unpublish することができます。
このとき、対象のPublicationに対する Subscription が自動的に Unsubscribe されます。

// Publish
val publication = member.publish(stream)

// Unpublish
member.unpublish(publication)

Publication の Subscribe

Room 上の Publication を Subscribe することができます。

// Subscribe
val subscription = member.subscribe(publication)

// Unsubscribe
member.unsubscribe(subscription)

Source/Stream

Sourceは、SDKから各種メディアへアクセスするAPIを提供します。 また、Publish可能なStream を作成することが出来ます。

SourceからStreamの作成

// マイク音声のソース
AudioSource.start()
val stream = AudioSource.createStream()

// カメラ映像のソース
val device = CameraSource.getFrontCameras(context).first()
val options = CameraSource.CapturingOptions(width, height)
CameraSource.startCapturing(context, device, options)
val stream = CameraSource.createStream()

// 画面共有のソース
ScreenSource.setup(context, mediaProjectionPermissionResultData)
ScreenSource.startCapturing(width, height, frameRate)
val stream = ScreenSource.createStream()

// データソース
val stream = DataSource().createStream()

AudioStreamの再生

ローカルの音声は再生されません。
受信した音声はスピーカーから自動的に再生されます。

VideoStreamの再生

ローカルのカメラ映像を確認するために、再生することができます。
また、受信した映像を再生することができます。

renderer.setup()
stream.addRenderer(renderer)

DataStreamによるデータの送受信

任意のデータの送信ができます。（SFU Room は非対応です）

// データの送信
stream.write("hello")

// データの受信
stream.onDataHandler = {
    Log.d("data received: $it")
}

RoomPublication

Publication の情報の参照と操作ができます。

Metadata の取得・更新

PublicationのMetadata を取得・更新することができます。

// metadataの取得
val metadata = publication.metadata

// metadataの更新
publication.updateMetadata("metadata")

ミュート

Publication に紐ついた映像や音声などの配信を一時停止（ミュート）することができます

// ミュート
publication.disable()

// ミュートの解除
publication.enable()

RoomSubscription

Subscription の情報の参照と Subscription の操作ができます

Stream の参照

Subscription から映像/音声/データの Stream を参照できます。

when (subscription.contentType) {
    Stream.ContentType.VIDEO -> {
        Log.d("subscribe success(Video) : ${subscription.id}")
        (subscription.stream as RemoteVideoStream).addRenderer(remoteRenderer)
    }
    Stream.ContentType.AUDIO -> {
        Log.d("subscribe success(Audio) : ${subscription.id}")
        (subscription.stream as RemoteAudioStream)
    }
    Stream.ContentType.DATA -> {
        Log.d("subscribe success(Data) : ${subscription.id}")
        (subscription.stream as RemoteDataStream).onDataHandler = {
            Log.d("data received: $it")
        }
        (subscription.stream as RemoteDataStream).onDataBufferHandler = {
            Log.d("data received byte: ${it.contentToString()}")
        }
    }
}

Tips

コーデックの指定

Publishを行う際に、メディア通信に優先して利用するコーデックを指定することができます。 codecCapabilities 配列の先頭のコーデックを優先して利用します。 いずれのコーデックにも対応していない場合はデバイスが対応している他のコーデックを自動的に利用します。

val videoPublication = member.publish(
    stream, Publication.Options(
        codecCapabilities = mutableListOf(
            Codec(Codec.MimeType.VP9)
        )
    )
)

val audioPublication = member.publish(
    stream, Publication.Options(
        codecCapabilities = mutableListOf(
            Codec(Codec.MimeType.RED)
        )
    )
)

サイマルキャストの利用

サイマルキャストは、受信側クライアントデバイスが通信品質に合わせて自動的に最適なエンコード設定の映像を受け取る機能です。
VideoStream を Publish する際に複数のエンコード設定を指定することで、サイマルキャストを利用できます。

val publication = member.publish(
    stream, Publication.Options(
        encodings = mutableListOf(
            Encoding(
                id = "high",
                maxBitrate = 2000_000
            ),
            Encoding(
                id = "low",
                maxBitrate = 10_000
            )            
        )
    )
)

受信映像の品質設定

Publication に Simulcast が設定されている場合、preferredEncodingIdに受信する映像品質設定の ID を指定することができます。 なお、通信帯域が輻輳を起こしている場合は、高い品質の映像設定を指定しても低い品質の映像が受信されます。

val subscription = member.subscribe(publication, Subscription.Options(preferredEncodingId = "id"))

受信映像の品質設定を変更する

映像の受信開始後に任意のタイミングで品質設定を変更することができます。 なお、通信帯域が輻輳を起こしている場合は、高い品質の映像設定を指定しても低い品質の映像が受信されます。

val subscriptionEncodings = subscription.publication.encodings
if (subscriptionEncodings.isEmpty()) {
    return
}
subscription.changePreferredEncoding(subscriptionEncodings[0].id)

参考リンク

• クックブック（アプリケーション開発において役立つ様々な情報を紹介しています）