IVS Android Broadcast SDK の開始方法 | Low-Latency Streaming

このドキュメントでは、Amazon IVS Low-Latency Streaming Android Broadcast SDK の使用を開始するための手順について説明します。

ライブラリのインストール

Amazon IVS Android Broadcast ライブラリを Android 開発環境に追加するには、ライブラリを以下に示すモジュールの build.gradle ファイル (最新バージョンの Amazon IVS Broadcast SDK) に追加します。

repositories {
    mavenCentral()
}
dependencies {
     implementation 'com.amazonaws:ivs-broadcast:1.24.0'
}

または、SDK を手動でインストールするには、次の場所から最新バージョンをダウンロードします。

デバッグ情報を含む SDK の使用

また、デバッグ情報を含む Android Broadcast SDK のバージョンも公開しています。このバージョンを使用すると、IVS Broadcast SDK (つまり、libbroadcastcore.so ) でクラッシュした場合、Firebase Crashlytics のデバッグレポート (スタックトレース) の品質を向上させることができます。これらのクラッシュを IVS SDK チームに報告すると、高品質のスタックトレースにより、問題の修正が容易になります。

このバージョンの SDK を使用するには、Gradle ビルドファイルに以下を含めます。

implementation "com.amazonaws:ivs-broadcast:$version:unstripped@aar"

以下の代わりに上記の行を使用します。

implementation "com.amazonaws:ivs-broadcast:$version@aar"

Firebase Crashlytics へのシンボルのアップロード

Gradle ビルドファイルが Firebase Crashlytics 用に設定されていることを確認します。以下の Google の指示に従ってください。

https://firebase.google.com/docs/crashlytics/ndk-reports

com.google.firebase:firebase-crashlytics-ndk を依存関係として必ず含めてください。

リリース用にアプリを構築する場合、Firebase Crashlytics プラグインは情報を自動的にアップロードするはずです。情報を手動でアップロードするには、次のいずれかを実行します。

gradle uploadCrashlyticsSymbolFileRelease

./gradlew uploadCrashlyticsSymbolFileRelease

(情報が自動と手動の両方で 2 回アップロードされても問題ありません)。

Release .apk の肥大化を防ぐ

リリース .apk ファイルをパッケージ化する前に、Android Gradle Plugin は共有ライブラリ (IVS Broadcast SDK の libbroadcastcore.so ライブラリを含む) からデバッグ情報を自動的に削除しようとします。ただし、これはときに動作しないことがあります。その結果、.apk ファイルが肥大化し、Android Gradle プラグインから、「デバッグ情報を削除できず、そのまま .so ファイルをパッケージ化している」という警告メッセージが表示される可能性があります。このような場合は、以下のことを試してみます。

詳細については、「問題レポート」を参照してください。

イベントリスナーの作成

イベントリスナーを設定すると、状態更新、デバイス変更通知、エラー、およびセッションオーディオ情報を受信できます。

BroadcastSession.Listener broadcastListener = 
          new BroadcastSession.Listener() {
    @Override
    public void onStateChanged(@NonNull BroadcastSession.State state) {
        Log.d(TAG, "State=" + state);
    }

    @Override
    public void onError(@NonNull BroadcastException exception) {
        Log.e(TAG, "Exception: " + exception);
    }
};

必要なアクセス許可

アプリはユーザーのカメラとマイクへのアクセス許可を要求する必要があります。(これは、Amazon IVS に特有なものではなく、カメラやマイクにアクセスする必要があるアプリケーションには必須です。)

ここでは、ユーザーがすでにアクセス許可を付与しているかどうかを確認し、付与していない場合は、許可を求めます。

final String[] requiredPermissions =
         { Manifest.permission.CAMERA, Manifest.permission.RECORD_AUDIO };

for (String permission : requiredPermissions) {
    if (ContextCompat.checkSelfPermission(this, permission) 
                != PackageManager.PERMISSION_GRANTED) {
        // If any permissions are missing we want to just request them all.
        ActivityCompat.requestPermissions(this, requiredPermissions, 0x100);
        break;
    }
}

ここでは、ユーザーの応答を取得します。

@Override
public void onRequestPermissionsResult(int requestCode, 
                                      @NonNull String[] permissions,
                                      @NonNull int[] grantResults) {
    super.onRequestPermissionsResult(requestCode,
               permissions, grantResults);
    if (requestCode == 0x100) {
        for (int result : grantResults) {
            if (result == PackageManager.PERMISSION_DENIED) {
                return;
            }
        }
        setupBroadcastSession();
    }
}

ブロードキャストセッションの作成

ブロードキャストインターフェースは com.amazonaws.ivs.broadcast.BroadcastSession です。以下に示すように、プリセットを使用して初期化します。初期化中にエラーが発生した場合（コーデックの設定に失敗など）、BroadcastListener にエラーメッセージが表示され、broadcastSession.isReady が false になります。

重要: Amazon IVS Broadcast SDK for Android へのすべての呼び出しは、SDK がインスタンス化されたスレッドで行う必要があります。別のスレッドからの呼び出しにより、SDK は致命的なエラーをスローし、ブロードキャストを停止します。

// Create a broadcast-session instance and sign up to receive broadcast
// events and errors.
Context ctx = getApplicationContext();
broadcastSession = new BroadcastSession(ctx,
                       broadcastListener,
                       Presets.Configuration.STANDARD_PORTRAIT,
                       Presets.Devices.FRONT_CAMERA(ctx));

また、「ブロードキャストセッションの作成 (詳細バージョン)」も参照してください。

プレビュー用に ImagePreviewView を設定する

アクティブなカメラデバイスのプレビューを表示する場合は、デバイスのプレビュー ImagePreviewView をビュー階層に追加します。

// awaitDeviceChanges will fire on the main thread after all pending devices 
// attachments have been completed
broadcastSession.awaitDeviceChanges(() -> {
    for(Device device: session.listAttachedDevices()) {
        // Find the camera we attached earlier
        if(device.getDescriptor().type == Device.Descriptor.DeviceType.CAMERA) {
            LinearLayout previewHolder = findViewById(R.id.previewHolder);
            ImagePreviewView preview = ((ImageDevice)device).getPreviewView();
            preview.setLayoutParams(new LinearLayout.LayoutParams(
                    LinearLayout.LayoutParams.MATCH_PARENT,
                    LinearLayout.LayoutParams.MATCH_PARENT));
            previewHolder.addView(preview);
        }
    }
});

ブロードキャストを開始する

GetChannel エンドポイントの ingestEndpoint レスポンスフィールドで受信するホスト名には、 rtmps:// を先頭に追加し、/app を末尾に追加する必要があります。URL は、rtmps://{{ ingestEndpoint }}/app の形式にする必要があります。

broadcastSession.start(IVS_RTMPS_URL, IVS_STREAMKEY);

Android Broadcast SDK は RTMPS 取り込みのみをサポートしています (安全ではない RTMP 取り込みはサポートしていません)。

ブロードキャストを停止する

broadcastSession.stop();

ブロードキャストセッションを解放する

broadcastSession.release() メソッドは、ブロードキャストセッションが使用されなくなったときに呼び出され、ライブラリが使用するリソースを解放する必要があります。

@Override
protected void onDestroy() {
    super.onDestroy();
    previewHolder.removeAllViews();
    broadcastSession.release();
}