Fix HKSV recording stream closure with prebuffer integration and H.264 optimization

[Copilot]

This PR fixes a critical issue where HomeKit Secure Video (HKSV) recording would close immediately with "reason: 6" (STREAM FORMAT INCOMPATIBILITY) when prebuffer is enabled on cameras.

Problem

Users with prebuffer-enabled cameras experienced HKSV recording failures:

[Door] Recording stream request received for stream ID: 1
[Door] Recording stream closed for stream ID: 1, reason: 6

The issue occurred because:

1. handleRecordingStreamRequest() didn't ensure prebuffer was initialized before use
2. this.preBuffer could be undefined when prebuffer was enabled, causing stream format incompatibility
3. Hardcoded H.264 parameters weren't optimized for HKSV requirements

Solution

Prebuffer Integration Fix

• Added prebuffer initialization check in handleRecordingStreamRequest()
• Ensures startPreBuffer() is called before attempting to use prebuffer data
• Added robust error handling for prebuffer failures with graceful fallback

HKSV-Compatible H.264 Parameters

• Use dynamic configuration-specified profile and level instead of hardcoded values
• Improved bitrate handling with proper maxrate and bufsize calculations from configuration
• Changed preset from ultrafast to veryfast for better encoding stability
• Added frame rate parameter from HKSV configuration

Enhanced Error Handling & Diagnostics

• Added detailed diagnostic logging for all HKSV reason codes (especially reason 6)
• Enhanced FFmpeg process startup error handling with process ID tracking
• Improved audio codec integration with proper logging

Testing

The fix has been validated with:

• Synthetic video source generating HKSV-compatible MP4 fragments
• H.264 baseline profile, level 3.1 confirmed working
• AAC audio encoding validated
• Comprehensive test coverage added for RecordingDelegate

After the fix, users should see continuous HKSV recording:

[Door] Recording stream request received for stream ID: 1
[Door] HKSV: Prebuffer enabled, ensuring prebuffer is started
[Door] HKSV: Prebuffer initialization completed
[Door] HKSV: FFmpeg process started for stream 1, PID: 12345
[Door] HKSV: Yielding fragment #1, size: 2048, total: 2048 bytes
... (continuous recording beyond prebuffer window)

Fixes #1509.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• 192.168.1.100
  • Triggering command: ffmpeg -hide_banner -rtsp_transport tcp -i rtsp://admin:password@192.168.1.100:554/cam/realmonitor?channel=1&subtype=0 -f lavfi -i anullsrc=cl=mono:r=32000 -f mp4 -acodec aac -profile:a aac_low -ar 32000 -b:a 64k -ac 1 -sn -dn -vcodec libx264 -pix_fmt yuv420p -profile:v baseline -level:v 3.1 -preset veryfast -tune zerolatency -b:v 2048k -maxrate 2457k -bufsize 4096k -g 30 -keyint_min 15 -sc_threshold 0 -force_key_frames expr:gte(t,n_forced*1) -r 15 -movflags frag_keyframe+empty_moov+default_base_moof+omit_tfhd_offset pipe:1 (packet block)
  • Triggering command: ffmpeg -hide_banner -rtsp_transport tcp -i rtsp://admin:password@192.168.1.100:554/cam/realmonitor?channel=1&subtype=0 -f lavfi -i anullsrc=cl=mono:r=32000 -f mp4 -acodec aac -profile:a aac_low -ar 32000 -b:a 64k -ac 1 -sn -dn -vcodec libx264 -pix_fmt yuv420p -profile:v baseline -level:v 3.1 -preset veryfast -tune zerolatency -b:v 1000k -maxrate 1200k -bufsize 2000k -g 30 -keyint_min 15 -sc_threshold 0 -force_key_frames expr:gte(t,n_forced*1) -r 15 -movflags frag_keyframe+empty_moov+default_base_moof+omit_tfhd_offset pipe:1 (packet block)
• esm.ubuntu.com
  • Triggering command: /usr/lib/apt/methods/https (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.