Interface CameraRecordingDelegate

This method is called once the HomeKit Controller acknowledges the endOfStream. A endOfStream is sent by the accessory by setting RecordingPacket.isLast to true in the last packet yielded by the handleRecordingStreamRequest AsyncGenerator.

This method is called to notify the delegate that a recording stream started via handleRecordingStreamRequest was closed.

The method is also called if an ongoing recording stream is closed gracefully (using HDSProtocolSpecificErrorReason.NORMAL). In either case, the delegate should stop supplying further fragments to the recording stream. The AsyncGenerator function must return without yielding any further RecordingPackets. HAP-NodeJS won't send out any fragments from this point onwards.

This method is called to stream the next recording event. It is guaranteed that there is only ever one ongoing recording stream request at a time.

When this method is called return the currently ongoing (or next in case of a potentially queued) recording via a AsyncGenerator. Every yield of the generator represents a complete recording packet. The first packet MUST always be the PacketDataType.MEDIA_INITIALIZATION packet. Any following packet will transport the actual mp4 fragments in PacketDataType.MEDIA_FRAGMENT packets, starting with the content of the prebuffer. Every PacketDataType.MEDIA_FRAGMENT starts with a key frame and must not be longer than the specified duration set via the CameraRecordingConfiguration.mediaContainerConfiguration.fragmentLength selected by the HomeKit Controller in updateRecordingConfiguration.

NOTE: You MUST respect the value of Characteristic.RecordingAudioActive characteristic of the Service.CameraOperatingMode service. When the characteristic is set to false you MUST NOT include audio in the mp4 fragments. You can access the characteristic via the CameraController.recordingManagement.operatingModeService property.

You might throw an error in this method if encountering a non-recoverable state. You may throw a HDSProtocolError to manually define the HDSProtocolSpecificErrorReason for the DATA_SEND CLOSE event.

There are three ways an ongoing recording stream can be closed:

• Closed by the Accessory: There are no further fragments to transmit. The delegate MUST signal this by setting RecordingPacket.isLast to true. Once the HomeKit Controller receives this last fragment it will call acknowledgeStream to notify the accessory about the successful transmission.
• Closed by the HomeKit Controller (expectedly): After the event trigger has been reset, the accessory continues to stream fragments. At some point the HomeKit Controller will decide to shut down the stream by calling closeRecordingStream with a reason of HDSProtocolSpecificErrorReason.NORMAL.
• Closed by the HomeKit Controller (unexpectedly): A HomeKit Controller might at any point decide to close a recording stream if it encounters erroneous state. This is signaled by a call to closeRecordingStream with the respective reason.

Once a close of stream is signaled, the AsyncGenerator function must return gracefully.

For more information about AsyncGenerators you might have a look at:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of

NOTE: HAP-NodeJS guarantees that this method is only called with a valid selected CameraRecordingConfiguration.

NOTE: Don't rely on the streamId for unique identification. Two DataStreamConnections might share the same identifier space.

A call to this method notifies the CameraRecordingDelegate about a change to the CameraRecordingManagement.Active characteristic. This characteristic controls if the camera should react to recording events.

If recording is disabled the camera can stop maintaining its prebuffer. If recording is enabled the camera should start recording into its prebuffer.

A CameraRecordingDelegate should assume active to be false on startup. HAP-NodeJS will persist the state of the Active characteristic across reboots and will call updateRecordingActive accordingly on startup, if recording was previously enabled.

NOTE: HAP-NodeJS cannot guarantee that a CameraRecordingConfiguration is present when recording is activated (e.g. the selected configuration might be erased due to changes in the supplied CameraRecordingOptions, but the camera is still active; or we can't otherwise influence the order which a HomeKit Controller might call those characteristics). However, HAP-NodeJS guarantees that if there is a valid CameraRecordingConfiguration, updateRecordingConfiguration is called before updateRecordingActive (when enabling) to avoid any unnecessary and potentially expensive reconfigurations.

A call to this method signals that the selected (by the HomeKit Controller) recording configuration of the camera has changed.

On startup the delegate should assume configuration = undefined. HAP-NodeJS will persist the state of both across reboots and will call updateRecordingConfiguration on startup if there is a selected configuration present.

NOTE: An update to the recording configuration might happen while there is still a running recording stream. The camera MUST continue to use the previous configuration for the currently running stream and only apply the updated configuration to the next stream.