================== 映像の送受信と描画 ================== 映像を送受信する ================ .. _camera-capturer: カメラの映像を取得する ---------------------- カメラの映像を取得するには、SDK 内部でカメラを管理する方法と、アプリケーション側でカメラを管理する方法の2通りがあります。 .. _manage-camera-on-sdk-side: SDK 内部で CameraVideoCapturer を管理する ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``SoraMediaOption.enableVideoUpstream(eglContext, cameraConfig)`` を使用すると、SDK 内部で ``CameraVideoCapturer`` を生成・管理できます。 この方法ではアプリケーション側で ``CameraVideoCapturer`` を生成する必要はなく、カメラキャプチャの開始と停止は SDK が自動的に行います。Sora への接続時にキャプチャが開始され、切断時に停止されます。 また、 ``initialVideoHardMute`` を ``true`` に設定した場合は、接続時にカメラキャプチャを開始せず、 ``SoraMediaChannel.setVideoHardMute(false)`` を呼び出したタイミングからキャプチャを開始します。 .. code-block:: kotlin val mediaOption = SoraMediaOption() val cameraConfig = SoraMediaOption.SoraCameraConfig( width = 640, height = 480, frameRate = 30, frontFacingFirst = true, initialVideoHardMute = false ) mediaOption.enableVideoUpstream(eglContext, cameraConfig) ``SoraCameraConfig`` のパラメータは次の通りです: - ``width`` - 映像の幅。デフォルト値は 640 です。 - ``height`` - 映像の高さ。デフォルト値は 480 です。 - ``frameRate`` - フレームレート。デフォルト値は 30 です。 - ``frontFacingFirst`` - ``true`` であれば前面カメラを優先します。 ``false`` であれば背面カメラを優先します。デフォルト値は ``true`` です。 - ``initialVideoHardMute`` - ``true`` であれば Sora 接続開始時に映像をハードミュート（カメラを停止）した状態で開始します。デフォルト値は ``false`` です。 .. _manage-camera-on-app-side: アプリケーション側でカメラを管理する ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ カメラの映像を取得するキャプチャラー (``org.webrtc.CameraVideoCapturer``) は `jp.shiguredo.sora.sdk.camera.CameraCapturerFactory`_ を呼ぶと取得できます。 `create()`_ の定義は次の通りです: .. code-block:: kotlin fun create( context: android.content.Context, frontFacingFirst: Boolean = true ): org.webrtc.CameraVideoCapturer? - ``context``: アプリケーションコンテキスト。 ``Activity`` オブジェクトを渡します。 - ``frontFacingFirst``: ``true`` であれば前面カメラを優先します。 ``false`` であれば背面カメラを優先します。デフォルトは ``true`` です。 .. _create(): _static/apidoc/sora-android-sdk/jp.shiguredo.sora.sdk.camera/-camera-capturer-factory/-companion/create.html .. _jp.shiguredo.sora.sdk.camera.CameraCapturerFactory: _static/apidoc/sora-android-sdk/jp.shiguredo.sora.sdk.camera/-camera-capturer-factory/index.html 生成したキャプチャラーを SDK に設定する ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 生成した ``CameraVideoCapturer`` を SDK に設定するには、 ``SoraMediaOption.enableVideoUpstream(capturer, eglContext)`` を使用します。 この方法で CameraVideoCapturer を SDK に設定した場合、カメラキャプチャの開始と停止はアプリケーション側で行う必要があります。 .. code-block:: kotlin fun enableVideoUpstream( capturer: VideoCapturer, eglContext: EglBase.Context?, cameraConfig: SoraCameraConfig? = null, ) {} - ``capturer``: 生成した ``VideoCapturer`` オブジェクト - ``eglContext``: EGL コンテキスト - ``cameraConfig``: カメラの設定。SoraMediaChannel.setVideoHardMute はこの設定を利用します。当該 API を使用する場合は必ず設定してください。 以下は SoraCameraConfig を設定しない enableVideoUpstream の使用例です。 .. code-block:: kotlin class MainActivity : AppCompatActivity() { fun start() { // 背面カメラを優先したい場合の設定例 val capturer = CameraCapturerFactory.create(this, frontFacingFirst = false) val mediaOption = SoraMediaOption() mediaOption.enableVideoUpstream(capturer!!, eglContext) ... } } 映像を描画する ============== Sora Android SDK は基本的に libwebrtc の API を隠蔽していますが、映像の描画には直接 libwebrtc の API を使う必要があります。 UI コンポーネント ----------------- 映像を描画する UI コンポーネントは ``org.webrtc.SurfaceViewRenderer`` です。 ``SurfaceViewRenderer`` は ``android.view.SurfaceView`` のサブクラスであり、 OpenGL ES を利用して映像を描画します。 .. _ui_layout: レイアウト ---------- ``SurfaceViewRenderer`` は一般的なレイアウトと同様に XML ファイルでレイアウトを定義できます。 次に例を示します: .. code-block:: xml 初期化と終了処理 ---------------- ``SurfaceViewRenderer`` で映像を描画する際は、明示的な初期化と終了処理を行う必要があります。 映像の描画を行う前に ``init()`` を呼び出して初期化し、 ``SurfaceViewRenderer`` を使い終えたら ``release()`` を呼び出して終了処理を行います。 終了処理を忘れるとリソースがリークする原因になります。 ``init()`` は EGL の API である ``android.opengl.EGLContext`` を引数に取ります。 ``EGLContext`` は ``org.webrtc.EglBase`` のプロパティであり、他にも様々な箇所で使います。 ``EglBase`` は EGL のレンダリングコンテキストを保持するオブジェクトです。 こちらも使い終えたら ``release()`` で終了処理を行う必要があります。 一般的には、アクティビティの生成時に ``EglBase`` の生成と ``SurfaceViewRenderer`` の初期化を行い、アクティビティの終了時に両方の終了処理を行うとよいでしょう。 次に例を示します: .. code-block:: kotlin class MyActivity : AppCompatActivity() { private val egl: EglBase? = null override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) egl = EglBase.create() // その他の初期化 } // UIの組み立てが終わった直後にこのメソッドを呼ぶようにする fun initRenderers() { // localRenderer, remoteRenderer は XML ファイルで定義済み localRenderer.init(egl.eglContext, null) remoteRenderer.init(egl.eglContext, null) } // このメソッドを最後に必ず呼ぶようにする fun releaseRenderers() { localRenderer.release() remoteRenderer.release() egl.release() } } 動画の左右を反転する -------------------- ``setMirror()`` を呼ぶと動画の左右を反転させることができます。 例 ^^ .. code-block:: kotlin localRenderer.setMirror(true) キャプチャーの操作 ================== SDK 内部でカメラを管理する場合 ------------------------------ SDK 内部でカメラを管理している場合（``SoraMediaOption.enableVideoUpstream`` に ``SoraCameraConfig`` を渡した場合）の操作方法です。 キャプチャーを開始・停止する ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``SoraMediaChannel.setVideoHardMute(muted)`` を呼びます。 引数に ``true`` を指定するとキャプチャーを停止（ハードミュート）し、``false`` を指定すると開始（ハードミュート解除）します。 このメソッドの詳細は :ref:`video-hard-mute` をご確認ください。 カメラを切り替える ^^^^^^^^^^^^^^^^^^ ``SoraMediaChannel.switchCamera(handler)`` を呼びます。 キャプチャーのフォーマットを変更する ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``SoraMediaChannel.changeCaptureFormat()`` を呼ぶと、キャプチャーした映像のサイズとフレームレートを変更できます。 アプリケーション側でカメラを管理する場合 ---------------------------------------- :ref:`manage-camera-on-app-side` の方法で ``CameraVideoCapturer`` を生成した場合の操作方法です。 ``CameraVideoCapturer`` のメソッドを直接呼び出して操作します。 キャプチャーを開始・停止する ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 映像のキャプチャーを開始するには ``CameraVideoCapturer.startCapture()`` を呼びます。 停止するには ``CameraVideoCapturer.stopCapture()`` を呼びます。 カメラを切り替える ^^^^^^^^^^^^^^^^^^ ``CameraVideoCapturer.switchCamera()`` を呼びます。 キャプチャーのフォーマットを変更する ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``CameraVideoCapturer.changeCaptureFormat()`` を呼ぶと、キャプチャーした映像のサイズとフレームレートを変更できます。