################
クイックスタート
################

この章では、 Sora Android SDK を使った、
シンプルなクイックスタートアプリケーションを実行するまでの流れを紹介します。

- メディアデータ (映像と音声) の送信と受信
- 送受信する映像の描画
- 端末のデバイス (カメラとマイク) の使用

ソースコードは次のリポジトリで配布しています。

- `sora-android-sdk-quickstart <https://github.com/shiguredo/sora-android-sdk-quickstart>`_

用意するもの
============

- WebRTC SFU Sora バージョン |sora_version| 以降
- Android |android_version| 以降 (シミュレーターは不可)
- Android Studio バージョン |android_studio_version| 以降

Sora については、ここでは次の条件での運用を仮定します。
詳しくは Sora のドキュメントを参照してください。

- Sora のホスト名: "sora.example.com"
- デモ機能: 有効
- WebSocket の接続に WebSocket over TLS を使用
- チャネル ID: sora

以下、アプリケーションのダウンロード、依存ライブラリのダウンロードと配置、
アプリケーションの設定と起動の順に説明します。

Android Studio のセットアップ
=================================

`Android Studio <https://developer.android.com/studio/index.html>`_ をダウンロードし、
`インストール方法 <https://developer.android.com/studio/install.html>`_
に従いセットアップしてください。

クィックスタートアプリケーションのダウンロード
==============================================

クイックスタートアプリケーションのソースコードは `sora-android-sdk-quickstart <https://github.com/shiguredo/sora-android-sdk-quickstart>`_ リポジトリで配布しています。
git コマンドで最新のタグを指定してクローンしてください ::

 $ git clone --branch <X.Y.Z> https://github.com/shiguredo/sora-android-sdk-quickstart.git
 $ cd sora-android-sdk-quickstart

SDK への依存設定
================

本アプリケーションは Sora Android SDK への依存を持ちます。
以下、設定方法を記します。github からクローンしたコードベースには
これらの設定は入っています。

JitPack リポジトリの追加
------------------------

Sora Android SDK は `JitPack <https://jitpack.io/>`_ から取得できます。
そのため、トップレベルの ``build.gradle`` で JitPack のリポジトリを追加します。 ::

    allprojects {
        repositories {
            jcenter()
            google()
            maven { url 'https://jitpack.io' }  // この行を追加する
        }
    }

Sora Android SDK のバージョン設定
---------------------------------

同じ ``build.gradle`` にて、SDK のバージョンを定義しておきましょう。
``X.Y.Z`` は使用する SDK のバージョンを入れてください。最新版は
|sora_android_sdk_version| です。 ::

    buildscript {
        // 中略
        ext.sora_android_sdk_version = 'X.Y.Z' // この行を追加する
    }

この定義は次の implementation 依存の追加で参照しますが、ここでは定義せずに、
次の設定に直書きしても構いません。

Sora Android SDK への依存を追加する
-----------------------------------

次に Sora Android SDK への依存を追加します。
SDK を利用するモジュールのビルド設定ファイル(ここでは ``quickstart/build.gradle`` )に
以下の設定を追加します。 ::

    dependencies {
        // 中略
        // 以下の 3 行を追加する
        implementation("com.github.shiguredo:sora-android-sdk:${sora_android_sdk_version}@aar") {
            transitive = true
        }
    }

以上で SDK を利用するための依存設定は完了です。

**補足** ``transitive`` を指定しない場合は libwebrtc のバージョンとして |libwebrtc_version| を指定してください。 ::

        api "com.github.shiguredo:shiguredo-webrtc-android:${libwebrtc_version}"

**注意** libwebrtc のバージョンは Sora Android SDK のバージョンと個別に指定可能ですが、特定バージョンのみで
動作を確認しています。必ず SDK バージョンに対応する libwebrtc のバージョンを指定してください。


アプリケーションの設定
======================

クィックスタートアプリケーションの実行には Sora の URL を設定する必要があります。
Sora の URL を ``gradle.properties`` に設定します。

``gradle.properties.example`` を元に ``gradle.properties`` を作成します。 ::

  $ cp gradle.properties.example gradle.properties


このファイルでは、接続する Sora のシグナリングエンドポイント URL ``signaling_endpoint``
を指定します。環境に応じて設定してください。
好みでチャネル ID ``channel_id`` の指定も可能です(そのままでも結構です)。

``gradle.properties``::

    # Setting Sora's signaling endpoint and channel_id
    signaling_endpoint = wss://sora.example.com/signaling
    channel_id         = sora

以上でアプリケーションの設定は完了です。
クローンしたディレクトリを Android Studio で開き、アプリケーションの起動を行ってください。

アプリケーションの起動
======================

Android 端末をマシンに接続します。Sora Android SDK はシミュレーターに対応していません。実機を利用してください)。
そして、接続した Android 端末を選択してビルド・実行します
(メニュー "Run" > "Run (quickstart)")。

起動したアプリケーションの画面で、 START ボタンをタップすると映像、音声の送受信処理が開始されます。

カメラとマイクの権限許可を取得する
--------------------------------------------

Sora Android SDK で映像の送受信を行うにはカメラ(android.permission.RECORD_AUDIO) と音声(android.permission.RECORD_AUDIO)の権限許可が必要です。

アプリケーションで権限許可を取得するようにします。

Sora に接続する
-----------------------------

起動したアプリケーションの画面で、 START ボタンをタップすると Sora に接続します。
接続に成功するとカメラ(あれば前面カメラ優先)の映像が表示されます。

接続できなかった場合は Sora のエンドポイント URL やネットワークの状態を確認してください。

このアプリケーションでは、次のパラメータで Sora に接続しています。

- Sora への接続

  - `マルチストリーム <https://sora-doc.shiguredo.jp/MULTISTREAM>`_
- 映像コーデック: VP9
- 音声コーデック: OPUS

双方向でビデオチャットするには、例えば、PC ブラウザから Sora のデモ機能のマルチストリーム接続
を行うと、クイックスタートアプリケーションに相手側の映像が表示されます。
もちろん、Android 端末をもうひとつ用意して本アプリケーションをインストール、起動しても
よいですし、iOS アプリケーションとのビデオチャットも可能です。

参考
====================

- PC ブラウザからのアクセス: `Sora 開発者ツール <https://sora-doc.shiguredo.jp/DEVTOOLS>`_
- Sora iOS SDK: `Sora iOS SDK のドキュメント <https://sora-ios-sdk.shiguredo.jp/>`_