Android 攝影機裝置指南

攝影機裝置類型是透過兩種特徵實作： PushAvStreamTransport，可使用推送式通訊協定處理音訊和影片串流傳輸； WebRtcLiveView，可控制即時影像串流和對講功能。 如果實作項目具備攝影機功能，門鈴裝置類型也會使用這些特徵。

Home API 裝置類型 特徵 Kotlin 範例應用程式 用途

相機

GoogleCameraDevice

home.matter.6006.types.0158

可拍攝靜態圖像或影片的裝置。攝影機可能提供可存取的即時串流、雙向通話或偵測事件。

 必要特徵
     google PushAvStreamTransport
     google WebRtcLiveView

 相機

門鈴

GoogleDoorbellDevice

home.matter.6006.types.0113

門外的按鈕啟動裝置後，會發出聲音和/或視覺信號，用於引起門另一側人員的注意。門鈴可能提供無障礙直播、雙向通話或偵測事件。

 必要特徵
     google PushAvStreamTransport
     google WebRtcLiveView

 門鈴

開始直播

如要開始直播，請將工作階段描述通訊協定 (SDP) 字串傳送至 WebRtcLiveView 特徵的 startLiveView() 方法，該方法會傳回 WebRtcLiveViewTrait.StartLiveViewCommand.Response，其中包含三個值：

  • 工作階段的 SDP。
  • 工作階段時間長度 (以秒為單位)。
  • 工作階段 ID，可用於延長或終止工作階段。
suspend fun getWebRtcLiveViewTrait(cameraDevice, cameraDeviceType) {
 return cameraDevice.type(cameraDeviceType).trait(WebRtcLiveView).first {
    it?.metadata?.sourceConnectivity?.connectivityState == ConnectivityState.ONLINE
  }

}

// Start the live view
suspend fun startCameraStream(trait: WebRtcLiveView,offerSdp: String) {
  val response = trait.startLiveView(offerSdp)
  // Response contains three fields (see below)
  return response
}
  ...

// This is used to manage the WebRTC connection
val peerConnection: RTCPeerConnection = ...

   ...

val startResponse = startCameraStream(sdp)
val answerSdp = startResponse?.answerSdp
val sessionDuration = startResponse?.liveSessionDurationSeconds
val mediaSessionId = startResponse?.mediaSessionId

peerConnection.setRemoteDescription(SessionDescription.Type.ANSWER,
                                    answerSdp)

延長直播時間

直播有預設時長，時間一到就會過期。如要延長有效串流的時長，請使用 WebRtcLiveView.extendLiveView() 方法發出延長要求：

// Assuming camera stream has just been started
suspend fun scheduleExtension(trait: WebRtcLiveView, mediaSessionId: String, liveSessionDurationSeconds: UShort ) {
  delay(liveSessionDurationSeconds - BUFFER_SECONDS * 1000)
  val response = trait.extendLiveView(mediaSessionId)
  // returns how long the session will be live for
  return response.liveSessionDurationSeconds
}

啟用及停用錄製功能

如要啟用攝影機的錄影功能，請將 TransportStatusEnum.Active 傳遞至 PushAvStreamTransport 特徵的 setTransportStatus() 方法。如要停用錄製功能，請傳遞 TransportStatusEnum.Inactive。 在以下範例中，我們將這些呼叫包裝在單一呼叫中，並使用 Boolean 切換錄音功能：

// Start or stop recording for all connections.
suspend fun setCameraRecording(isOn: Boolean) {
  val pushAvStreamTransport = getPushAvStreamTransport
  if(isOn) {
    pushAvStreamTransport.setTransportStatus(TransportStatusEnum.Active)
  } else {
    pushAvStreamTransport.setTransportStatus(TransportStatusEnum.Inactive)
  }
}

確認是否已啟用錄製功能

如要判斷攝影機是否已啟用錄影功能，請檢查是否有任何連線處於啟用狀態。以下範例定義了兩個函式來執行這項操作：

// Get the on/off state
suspend fun onOffState(cameraDevice: HomeDevice, cameraDeviceType) {
  // Query the device for pushAvStreamTransport
  val pushAvTrait = getPushAvStreamTransport()
  return pushAvTrait.recordModeActive()
}

// Check to see if the camera's recording capability is enabled
fun PushAvStreamTransport.recordModeActive(): Boolean {
  return currentConnections?.any { it.transportStatus == TransportStatusEnum.Active } ?: false
}

您也可以使用含述詞的 findTransport() 函式進行檢查：

// Fetch the current connections
suspend fun queryRecordModeState(cameraDevice: HomeDevice, cameraDeviceType) {
  val pushAvStreamTransport = getPushAvStreamTransport()
  return pushAvStreamTransport.findTransport().let {
      it.transportConfigurations.any { it.transportStatus == TransportStatusEnum.Active
    }
}

啟動及停止 TalkBack

如要啟動 TalkBack，請呼叫 WebRtcLiveView 特徵的 startTalkback() 方法。如要停止，請使用 stopTalkback()。

// Make sure camera stream is on
suspend fun setTalkback(isOn: Boolean, trait: WebRtcLiveView, mediaSessionId: String) {
  if(isOn) {
    trait.startTalkback(mediaSessionId)
  } else {
    trait.stopTalkback(mediaSessionId)
  }
}