SkyWay iOS SDK API Reference

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

インストール方法

Swift Package Manager に対応しています。
以下のリポジトリで公開しています。

https://github.com/skyway/ios-sdk

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 に参加したユーザー同士で通話を行うことができます。

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 にアクセスし映像や音声を受信できます。

基本機能の解説

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

Context

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

SkyWay 利用の開始

// 開発環境ではappId/secretKeyで初期化することができます。
try await Context.setupForDev(withAppId: appId, secretKey: secret, options: .init())

// 本番環境ではAuthTokenを作成し、そちらを利用して初期化してください。
try await Context.setup(withToken: token, options: .init())

Auth Token の更新

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

Context.delegate = self

// MARK: - ContextDelegate
func shouldUpdateToken() {
    Context.updateToken(newToken)
}

SkyWay 利用の終了

try await Context.dispose()

Room

通話グループである Room の作成/取得および操作を行うことができます。

Room の作成・取得

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

// Roomの作成
let options = Room.InitOptions()
options.name = roomName
let room = try await Room.create(with: options)

// Roomの取得
let query = Room.Query()
query.name = roomName
// query.id = roomId // idでの取得も可能
let room = try await Room.find(by: query)

// Roomの取得を試み、存在しなければ作成
let options = Room.InitOptions()
options.name = roomName
let room = try await Room.findOrCreate(with: options)

Metadata の更新

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

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

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

Member の Room への参加

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

let options = Room.MemberInitOptions()
let member = try await room.join(with: options)

LocalRoomMember

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

Metadata の更新

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

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

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

Stream の Publish

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

// Publish
let options =  RoomPublicationOptions()
let publication = try await member.publish(stream, options: options)

// Unpublish
try await member.unpublish(publication.id)

RoomPublicationOptions でメディアの通信方式を P2P と SFU の2種類から選択します。
指定しなかった場合は P2P が選択されます。

P2P

let options =  RoomPublicationOptions()
options.type = .P2P
let publication = try await member.publish(stream, options: options)

SFU

maxSubscribers では Publish した Stream を Subscribe できる数の上限値を指定できます。
指定しない場合、maxSubscribers には 10 がセットされます。
maxSubscribers の最大値は 99 です。

let options =  RoomPublicationOptions()
options.type = .SFU
options.maxSubscribers = 5
let publication = try await member.publish(stream, options: options)

サイマルキャストの利用

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

let options =  RoomPublicationOptions()
options.type = .SFU

let lowEnc =  Encoding()
lowEnc.id = "low"
lowEnc.maxBitrate = 10_000

let highEnc = Encoding()
highEnc.id = "high"
highEnc.maxBitrate = 2000 * 1000

options.encodings = [lowEnc, highEnc]

let publication = try await member.publish(stream, options: options)

コーデックの指定

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

videoOptions.codecCapabilities = [Codec(mimeType: "video/vp9")]
let videoPublication = try await member.publish(videoStream, options: videoOptions)

audioOptions.codecCapabilities = [Codec(mimeType: "audio/red")]
let audioPublication = try await member.publish(audioStream, options: audioOptions)

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

// Subscribe
let subscription = try await member.subscribe(publicationId: publication.id, options: nil)

// Unsubscribe
try await member.unsubscribe(subscriptionId: subscription.id)

Source/Stream

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

Source から Stream の作成

// マイク音声のソース
let audioSource = MicrophoneAudioSource()
let stream = audioSource.createStream()

// カメラ映像のソース
let frontCamera = CameraVideoSource.supportedCameras().first(where: { $0.position == .front })
try await CameraVideoSource.shared().startCapturing(with: frontCamera, options: nil)
let stream = CameraVideoSource.shared().createStream()

// 画面共有のソース
let source = CustomFrameVideoSource()
RPScreenRecorder.shared().startCapture { buffer, _, err in
    guard err == nil else {
        return
    }
    source.updateFrame(with: buffer)
} completionHandler: { _ in }

let stream = source.createStream()

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

AudioStream の再生

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

VideoStream の再生

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

// ローカル
CameraVideoSource.shared().attach(cameraPreviewView)

// リモート
remoteVideoStream.attach(videoView)

DataStreamによるデータの送受信

任意のデータを送信できます。（SFU 通信では使用できません）

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

// データの受信
stream.delegate = self

// MARK: - RemoteDataStreamDelegate
func dataStream(_ dataStream: RemoteDataStream, didReceive string: String) {
    print(string)
}

RoomPublication

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

Metadata の取得・更新

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

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

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

ミュート

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

// ミュート
try await publication.disable()

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

RoomSubscription

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

Stream の参照

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

switch subscription.contentType {
    case .audio:
        let stream = subscription.stream as! RemoteAudioStream
        // do something
    case .video:
        let stream = subscription.stream as! RemoteVideoStream
        // do something
    case .data:
        let stream = subscription.stream as! RemoteDataStream
        // do something
}

受信映像の品質設定

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

let options = SubscriptionOptions()
options.preferredEncodingId = preferredEncodingId
let subscription = try await member.subscribe(publicationId: publication.id, options: options)

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

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

let encodings = subscription.publication?.encodings ?? []
if encodings.isEmpty {
    return
}
_ = subscription.changePreferredEncoding(encodingId: encodings[0].id!)

Tips

Room 単位でメディアの通信方式を指定する

P2PRoom もしくは SFURoom を使用することであらかじめメディアの通信方式を指定できます。
それぞれの API は Room と共通しています。
なお、 P2PRoom における SFU 通信の利用、 SFURoom における P2P 通信の利用はできません。

参考リンク

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

SkyWay iOS SDK API Reference

目次

インストール方法

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

用語の解説

基本機能の解説

Context

SkyWay 利用の開始

Auth Token の更新

SkyWay 利用の終了

Room

Room の作成・取得

Metadata の更新

Member の Room への参加

LocalRoomMember

Metadata の更新

Stream の Publish

P2P

SFU

サイマルキャストの利用

コーデックの指定

Publication の Subscribe

Source/Stream

Source から Stream の作成

AudioStream の再生

VideoStream の再生

DataStreamによるデータの送受信

RoomPublication

Metadata の取得・更新

ミュート

RoomSubscription

Stream の参照

受信映像の品質設定

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

Tips

Room 単位でメディアの通信方式を指定する

参考リンク