Hướng dẫn về thiết bị máy ảnh cho Android

Loại thiết bị Camera được triển khai bằng 2 đặc điểm: PushAvStreamTransport, xử lý việc truyền luồng âm thanh và video bằng các giao thức dựa trên thao tác đẩy và WebRtcLiveView, cung cấp khả năng kiểm soát luồng phát trực tiếp và tính năng phản hồi bằng giọng nói.

Luôn kiểm tra xem thiết bị có hỗ trợ thuộc tính và lệnh hay không trước khi sử dụng bất kỳ tính năng nào hoặc cố gắng cập nhật thuộc tính. Hãy xem bài viết Điều khiển thiết bị trênAndroid để biết thêm thông tin.

Loại thiết bị Home API Đặc điểm Ứng dụng mẫu Kotlin Trường hợp sử dụng

Máy ảnh

GoogleCameraDevice

home.matter.6006.types.0158

Thiết bị chụp ảnh tĩnh hoặc quay video. Camera có thể có tính năng phát trực tiếp, đàm thoại hai chiều hoặc phát hiện sự kiện.

Đặc điểm bắt buộc
     google PushAvStreamTransport
     google WebRtcLiveView

Camera

Bắt đầu phát trực tiếp

Để bắt đầu phát trực tiếp, hãy gửi chuỗi Giao thức mô tả phiên (SDP) đến phương thức startLiveView() của đặc điểm WebRtcLiveView. Phương thức này sẽ trả về một WebRtcLiveViewTrait.StartLiveViewCommand.Response chứa 3 giá trị:

  • SDP cho phiên.
  • Thời lượng phiên tính bằng giây.
  • Mã phiên, có thể dùng để kéo dài hoặc kết thúc phiên.
suspend fun getWebRtcLiveViewTrait(cameraDevice: HomeDevice) {
 return cameraDevice.type(GoogleCameraDevice).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)

Kéo dài thời gian phát trực tiếp

Sự kiện phát trực tiếp có thời lượng đặt sẵn và sẽ hết hạn sau thời lượng đó. Để kéo dài thời lượng của một luồng đang hoạt động, hãy đưa ra yêu cầu gia hạn bằng phương thức 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
}

Bắt đầu và dừng TalkBack

Để bắt đầu TalkBack, hãy gọi phương thức startTalkback() của đặc điểm WebRtcLiveView. Để dừng, hãy sử dụng 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)
  }
}

Bật và tắt tính năng ghi âm

Để bật tính năng ghi hình của camera, hãy truyền TransportStatusEnum.Active đến phương thức setTransportStatus() của đặc điểm PushAvStreamTransport. Để tắt khả năng ghi, hãy truyền TransportStatusEnum.Inactive. Trong ví dụ sau, chúng ta sẽ gói các lệnh gọi này trong một lệnh gọi duy nhất sử dụng Boolean để bật/tắt khả năng ghi:

// Start or stop recording for all connections.
suspend fun setCameraRecording(trait: PushAvStreamTransport, isOn: Boolean) {
  if(isOn) {
    trait.setTransportStatus(TransportStatusEnum.Active)
  } else {
    trait.setTransportStatus(TransportStatusEnum.Inactive)
  }
}

Việc bật hoặc tắt khả năng ghi hình của camera cũng giống như việc bật hoặc tắt video của camera. Khi video của camera đang bật, camera sẽ ghi hình (cho mục đích ghi lại các sự kiện và đoạn video liên quan).

Khi tính năng ghi hình bị tắt (video camera ở trạng thái tắt):

  • Camera vẫn có thể hiển thị là đang trực tuyến theo connectivityState của loại thiết bị.
  • Bạn không thể truy cập vào phiên phát trực tiếp và camera cũng không phát hiện thấy sự kiện nào trên đám mây.

Kiểm tra xem bạn đã bật tính năng ghi hình hay chưa

Để xác định xem camera có được bật tính năng ghi hình hay không, hãy kiểm tra xem có kết nối nào đang hoạt động hay không. Ví dụ sau đây xác định 2 hàm để thực hiện việc này:

// Get the on/off state
suspend fun onOffState(pushAvStreamTransport: PushAvStreamTransport) {
  return pushAvStreamTransport
    .currentConnections?.any { it.transportStatus == TransportStatusEnum.Active } ?: false
}

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

Một cách khác để kiểm tra là sử dụng hàm findTransport() với một vị từ:

// Fetch the current connections
suspend fun queryRecordModeState(trait: PushAvStreamTransport) {
  return trait.findTransport().let {
      it.transportConfigurations.any { it.transportStatus == TransportStatusEnum.Active
    }
}

Cài đặt âm thanh

Bạn có thể kiểm soát nhiều chế độ cài đặt âm thanh của camera thông qua Home API.

Bật hoặc tắt micrô

Để bật hoặc tắt micrô của thiết bị, hãy cập nhật thuộc tính microphoneMuted của đặc điểm CameraAvStreamManagement bằng hàm setMicrophoneMuted Kotlin tích hợp sẵn:

// Turn the device's microphone on or off
suspend fun turnOffMicrophone(disableMicrophone: Boolean, trait: CameraAvStreamManagement) {
  trait.update { setMicrophoneMuted(disableMicrophone) }
}

Bật hoặc tắt tính năng ghi âm

Để bật hoặc tắt tính năng ghi âm cho thiết bị, hãy cập nhật thuộc tính recordingMicrophoneMuted của đặc điểm CameraAvStreamManagement bằng hàm setRecordingMicrophoneMuted Kotlin tích hợp sẵn:

// Turn audio recording on or off for the device
suspend fun turnOffAudioRecording(disableAudioRecording: Boolean, trait: CameraAvStreamManagement) {
  trait.update { setRecordingMicrophoneMuted(disableAudioRecording) }
}

Điều chỉnh âm lượng loa

Để điều chỉnh âm lượng loa cho thiết bị, hãy cập nhật thuộc tính speakerVolumeLevel của đặc điểm CameraAvStreamManagement bằng cách sử dụng hàm setSpeakerVolumeLevel Kotlin tích hợp sẵn:

// Adjust the camera speaker volume
suspend fun adjustSpeakerVolume(volume: Int, trait: CameraAvStreamManagement) {
  trait.update { setSpeakerVolumeLevel(volume.toUbyte()) }
}

Chế độ cài đặt khác

Bạn có thể điều khiển nhiều chế độ cài đặt khác của camera thông qua Home API.

Thay đổi hướng của hình ảnh

Bạn có thể xoay hướng của hình ảnh (video) do camera ghi lại. Bạn chỉ có thể xoay video 180 độ.

Để thay đổi hướng hình ảnh của camera, hãy cập nhật thuộc tính imageRotation của đặc điểm CameraAvStreamManagement bằng hàm setImageRotation Kotlin tích hợp:

// Change the camera's image orientation
val isRotated = false

cameraAvStreamManagement.update { setImageRotation(if (isRotated) 180.toUShort() else 0.toUShort()) }

Bật hoặc tắt chế độ nhìn ban đêm

Để bật hoặc tắt chế độ nhìn ban đêm cho camera, hãy dùng TriStateAutoEnum để cập nhật thuộc tính nightVision của đặc điểm CameraAvStreamManagement bằng hàm setNightVision Kotlin tích hợp sẵn:

// Turn night vision on
cameraAvStreamManagement.update {
  setNightVision(CameraAvStreamManagementTrait.TriStateAutoEnum.On)
}

// Turn night vision off
CameraAvStreamManagement.update {
  setNightVision(CameraAvStreamManagementTrait.TriStateAutoEnum.Off)
}

Thay đổi độ sáng của đèn LED trạng thái

Để thay đổi độ sáng của đèn LED trạng thái, hãy dùng ThreeLevelAutoEnum để cập nhật thuộc tính statusLightBrightness của đặc điểm CameraAvStreamManagement bằng hàm setStatusLightBrightness Kotlin tích hợp:

// Set the LED brightness to high
cameraAvStreamManagement.update {
  setStatusLightBrightness(CameraAvStreamManagementTrait.ThreeLevelAutoEnum.High)
}

// Set the LED brightness to low
cameraAvStreamManagement.update {
  setStatusLightBrightness(CameraAvStreamManagementTrait.ThreeLevelAutoEnum.Low)
}

Thay đổi khung nhìn camera

Khung hiển thị camera giống với tính năng Thu phóng và cắt mà bạn có thể xem trong bài viết hỗ trợ Thu phóng và cải thiện video của camera Nest.

Khung hiển thị được xác định trong một ViewportStruct chứa 4 giá trị, được dùng làm toạ độ của khung hiển thị. Toạ độ được xác định như sau:

(x1,y1) -- (x2,y1)
   |          |
(x1,y2) -- (x2,y2)

Việc xác định các giá trị cho ViewportStruct phụ thuộc vào giao diện người dùng và cách triển khai camera của ứng dụng. Ở cấp độ rất cơ bản, để đặt khung hiển thị của video trên camera, hãy cập nhật thuộc tính viewport của đặc điểm CameraAvStreamManagement bằng ViewportStruct, sử dụng hàm setViewport Kotlin tích hợp sẵn:

cameraAvStreamManagement
  .update { setViewport(
    CameraAvStreamManagementTrait.ViewportStruct(
      x1 = horizontalRange.rangeStart.roundToInt().toUShort(),
      x2 = horizontalRange.rangeEnd.roundToInt().toUShort(),
      y1 = verticalRange.rangeStart.roundToInt().toUShort(),
      y2 = verticalRange.rangeEnd.roundToInt().toUShort(),
    )
) }

Điều chỉnh độ nhạy đánh thức thiết bị

Độ nhạy đánh thức của thiết bị được dùng để tiết kiệm pin bằng cách giảm phạm vi mà thiết bị có thể cảm nhận được hoạt động và tăng thời gian đánh thức sau khi phát hiện thấy hoạt động đó.

Trong Home API, bạn có thể thiết lập chế độ này bằng cách dùng thuộc tính motionSensitivity của triggerOptions trong transportOptions của thiết bị. Các lựa chọn này được xác định trong đặc điểm PushAvStreamTransport cho từng thiết bị.

Bạn chỉ có thể đặt độ nhạy đánh thức thành các giá trị sau:

  • 1 = Thấp
  • 5 = Trung bình
  • 10 = Cao

Quy trình cập nhật là tìm cấu hình truyền tải cho các luồng ghi đang hoạt động bằng lệnh findTransport, sau đó sửa đổi cấu hình bằng giá trị độ nhạy mới bằng lệnh modifyPushTransport:

// Create a struct with the new wake-up sensitivity
val toUpdate =  TransportOptionsStruct(
  triggerOptions =
    TransportTriggerOptionsStruct(
      motionSensitivity =
        OptionalValue.present(wakeUpSensitivity.toUByte())
    )
  )

// Get the configurations for active connections
val connections  = pushAvStreamTransport.findTransport().transportConfigurations
  // Update all recording streams with the new transport options.
  for (connection in connections) {
    if (connection.transportOptions.getOrNull()?.streamUsage == StreamUsageEnum.Recording) {
      trait.modifyPushTransport(
        connectionId = connection.connectionId,
        transportOptions = toUpdate,
      )
    }
  }

Điều chỉnh thời lượng tối đa của sự kiện

Thời lượng tối đa của sự kiện là khoảng thời gian camera sẽ ghi lại một đoạn video cho một sự kiện. Thông qua Home API, bạn có thể định cấu hình giá trị này cho từng thiết bị với cùng độ dài như thông qua GHA, theo khoảng thời gian tính bằng giây:

  • 10 giây
  • 15 giây
  • 30 giây
  • 60 giây (1 phút)
  • 120 giây (2 phút)
  • 180 giây (3 phút)

Trong Home API, bạn có thể thiết lập chế độ này bằng cách dùng thuộc tính motionTimeControl của triggerOptions trong transportOptions của thiết bị. Các lựa chọn này được xác định trong đặc điểm PushAvStreamTransport cho từng thiết bị.

Quy trình cập nhật là tìm cấu hình truyền tải cho các luồng ghi đang hoạt động bằng lệnh findTransport, sau đó sửa đổi cấu hình bằng giá trị độ dài sự kiện mới bằng lệnh modifyPushTransport:

// Create a struct with the new max event length
// where maxDuration is the length in seconds
val toUpdate =  TransportOptionsStruct(
  triggerOptions =
    TransportTriggerOptionsStruct(
      motionTimeControl =
        OptionalValue.present(
          TransportMotionTriggerTimeControlStruct(maxDuration = it.toUInt())
        )
    )
  )

// Get the configurations for active connections
val connections  = pushAvStreamTransport.findTransport().transportConfigurations
  // Update all recording streams with the new transport options.
  for (connection in connections) {
    if (connection.transportOptions.getOrNull()?.streamUsage == StreamUsageEnum.Recording) {
      trait.modifyPushTransport(
        connectionId = connection.connectionId,
        transportOptions = toUpdate,
      )
    }
  }