HomeKit Secure Video

[skrashevich]

Summary

Add HomeKit Secure Video (HKSV) support — go2rtc can now expose any camera as an HKSV-compatible device for Apple Home, recording video clips to iCloud when motion is detected.

Key features

• HKSV recording — fragmented MP4 (fMP4) muxer with GOP-based buffering, sent over HDS (HomeKit DataStream) protocol
• Motion detection modes:
  • continuous — always report motion, Home Hub decides what to record
  • detect — automatic P-frame size analysis using EMA baseline (no CPU-heavy decoding needed)
  • api — external trigger via HTTP API (for Frigate, ONVIF events, etc.)
• Doorbell support — category_id: doorbell with ring event API
• Speaker service — optional 2-way audio with backchannel support
• Standalone library — pkg/hksv/ has zero internal/ imports, can be used in any Go project

New packages

Package	Description
pkg/hksv/	HKSV server, consumer (fMP4 + GOP buffer + HDS sender), session management, motion detector, helpers
pkg/hap/hds/	HDS protocol implementation (opack codec, encrypted message framing)
pkg/hap/camera/	HKSV-related HAP services and TLV8 structs (services_hksv.go, ch207.go)

New API endpoints

• POST /api/homekit/motion?id= — trigger motion detection
• DELETE /api/homekit/motion?id= — clear motion detection
• POST /api/homekit/doorbell?id= — trigger doorbell ring event

Configuration

homekit:
  outdoor:
    hksv: true              # enable HKSV
    motion: detect          # continuous | detect | api
    motion_threshold: 2.0   # sensitivity for detect mode
    speaker: true           # enable 2-way audio

Binary size impact

  Branch                        Size   Size (MB)
  ---------------------------------------------------
  master                    18791634    17.92 MB
  hksv                      19012898    18.13 MB

  ---------------------------------------------------
  Difference:           +216.0 KB (+1.17%)
                       (≈ +0.21 MB)

[skrashevich]

It's not ready to merge yet, but it is already fully functional and ready for testing by any user

[mikemwalsh]

I’m going to jump on trying this right away. I’ve been hoping for this for a while!!

[mikemwalsh]

@skrashevich first initial attempt for this was partially successful. I was able to add the camera and the hksv settings were enabled in the home app settings (when/what to record). I set it up to record all motion but it seems that part was not working. No recordings were ever triggered. I am using the basic “continuous” motion config, have not tried to get the motion api hooked up yet.

[skrashevich]

@skrashevich first initial attempt for this was partially successful. I was able to add the camera and the hksv settings were enabled in the home app settings (when/what to record). I set it up to record all motion but it seems that part was not working. No recordings were ever triggered. I am using the basic “continuous” motion config, have not tried to get the motion api hooked up yet.

Try to update to the latest version of this PR

It’s a known bug, I hope i fixed it in c567831

[mikemwalsh]

@skrashevich first initial attempt for this was partially successful. I was able to add the camera and the hksv settings were enabled in the home app settings (when/what to record). I set it up to record all motion but it seems that part was not working. No recordings were ever triggered. I am using the basic “continuous” motion config, have not tried to get the motion api hooked up yet.

Try to update to the latest version of this PR

It’s a known bug, I think I fixed it

Will try this afternoon if possible! Thanks

[skrashevich]

Will try this afternoon if possible! Thanks

In any case, try to re-pair the camera in HomeKit.
Make sure your Apple TV/HomePod (HomeKit hub) has the latest software installed
Make sure you have an active iCloud subscription and haven't exceeded the limit for the number of cameras or storage space

[mikemwalsh]

Worked with the latest commit! I currently use the same cameras via scrypted for this use case. So I can easily do a side by side on functionality.

Great work so far, this is a game changer in my opinion. When this is stable, I can’t wait to try to integrate it directly into thingino on camera (thingino optionally supports go2rtc)

[skrashevich]

Worked with the latest commit! I currently use the same cameras via scrypted for this use case. So I can easily do a side by side on functionality.

Great work so far, this is a game changer in my opinion. When this is stable, I can’t wait to try to integrate it directly into thingino on camera (thingino optionally supports go2rtc)

Although my motion detector implementation is very "cheap" in terms of CPU, I'm not sure if the camera's processor can handle it

[mikemwalsh]

Worked with the latest commit! I currently use the same cameras via scrypted for this use case. So I can easily do a side by side on functionality.
Great work so far, this is a game changer in my opinion. When this is stable, I can’t wait to try to integrate it directly into thingino on camera (thingino optionally supports go2rtc)

Although my motion detector implementation is very "cheap" in terms of CPU, I'm not sure if the camera's processor can handle it

With motion set to continuous is it needed?

[skrashevich]

With motion set to continuous is it needed?

No. Continuous is an emulation of a motion sensor that just reports motion event every 30 seconds.

[mikemwalsh]

Worked with the latest commit! I currently use the same cameras via scrypted for this use case. So I can easily do a side by side on functionality.

Great work so far, this is a game changer in my opinion. When this is stable, I can’t wait to try to integrate it directly into thingino on camera (thingino optionally supports go2rtc)

seems like two way audio is broken now though. the talk button has disappeared. (cam in go2rtc via onvif)

[skrashevich]

seems like two way audio is broken now though. the talk button has disappeared. (cam in go2rtc via onvif)

homekit:
  camera1:
    hksv: true
    speaker: true # RTFM !

[nschimme]

Very nice! Do ONVIF motion events trigger the motion for HKSV or do we need a third party program to hit that API?

[skrashevich]

Do ONVIF motion events trigger the motion for HKSV

Currently -- no. I don't have cameras with ONVIF motion detector for such development and testing.

[noelhibbard]

@jaysoffian thanks for confirming that category_id: doorbell breaks pairing for you too. Sync is best for me via flv through ffmpeg like in my example above. Even better then through RTMP.

I'm curious if anyone has actually confirmed if 2way works. Not just confirm that the Talk button is there but actually confirm that sound comes out of the speaker. It's a doorbell so 2way is kind of important for this one. I'd love to ditch the Reolink app and use pure HKSV for the doorbell.

[jaysoffian]

@noelhibbard Thanks for the info on the flv stream. Scrypted works really well with the Reolink Doorbell (including two-way audio with HK), so I continue to use it for that, and use go2rtc for my other cameras. You can point go2rtc at Scrypted's rebroadcast link if you want to get the Reolink into go2rtc. Just offering that as an option in case you haven't explored it.

[mofman]

This is a really exciting enhancement, however I havent been able to get two way audio working either, I get the button but no sound comes through to camera - works fine in frigate however.

[mofman]

Managed to get 2-way audio working in #2259

[VaBanck]

I installed the latest version (dev), but the camera still isn't recording in Homekit. Here's my Homekit config:
domonap_entrance:
hksv: true
motion: detect
speaker: true
name: Domonap
pin: 20182017

[VaBanck]

undefined error=read tcp 192.168.1.240:1984->192.168.1.137:54495: read: connection reset by peer stream=domonap_11 caller=github.com/AlexxIT/go2rtc/pkg/hksv/hksv.go:346

[skrashevich]

With ‘motion: continuous’ recording works?

[VaBanck]

With ‘motion: continuous’ recording works?

It doesn't work in any mode, maybe my camera doesn't allow me to do it

[VaBanck]

[skrashevich]

Show the entire go2rtc config (don't forget to delete the passwords)

Are you sure you have an active iCloud subscription that allows you to record from cameras, and their number is not exceeded?

[VaBanck]

Show the entire go2rtc config (don't forget to delete the passwords)

Are you sure you have an active iCloud subscription that allows you to record from cameras, and their number is not exceeded?

streams:
domonap_11:
- webrtc:http://192.168.1.240:8123/api/domonap/webrtc_proxy/pppppp/whep
- ffmpeg:domonap_11#video=h264#audio=aac#audio=opus
homekit:
-domonap_11:
name: 11
hksv: true
motion: detect
motion_threshold: 3
speaker: true
pin: 02182017

[VaBanck]

Icloud+ 2tb, only 4 cameras

[VaBanck]

Show the entire go2rtc config (don't forget to delete the passwords)
Are you sure you have an active iCloud subscription that allows you to record from cameras, and their number is not exceeded?

streams: domonap_11: - webrtc:http://192.168.1.240:8123/api/domonap/webrtc_proxy/pppppp/whep - ffmpeg:domonap_11#video=h264#audio=aac#audio=opus homekit: -domonap_11: name: 11 hksv: true motion: detect motion_threshold: 3 speaker: true pin: 02182017

[VaBanck]

Show the entire go2rtc config (don't forget to delete the passwords)

Are you sure you have an active iCloud subscription that allows you to record from cameras, and their number is not exceeded?

streams: domonap_11: - webrtc:http://192.168.1.240:8123/api/domonap/webrtc_proxy/pppppp/whep - ffmpeg:domonap_11#video=h264#audio=aac#audio=opus homekit: -domonap_11: name: 11 hksv: true motion: detect motion_threshold: 3 speaker: true pin: 02182017

[VaBanck]

16:45:11.348 ERR [hksv] motion detector add consumer failed error="streams: failed to unmarshal SDP: sdp: syntax error at pos 1: "0", exec/rtsp\n[in#0 @ 0x7f8c220360] method DESCRIBE failed: 404 (Not Found)\n[in#0 @ 0x7f8c19a520] Error opening input: Server returned 404 Not Found\nError opening input file rtsp://127.0.0.1:8554/domonap_entrance?video&audio&source=ffmpeg:domonap_entrance%23video%3Dh264%23audio%3Daac%23audio%3Dopus.\nError opening input files: Server returned 404 Not Found\n" stream=domonap_entrance

[dppeak]

Independent validation report, in case it is useful for moving this along. Built and exercised this branch on hardware unrelated to the author's setup, and it works end to end.

Environment

• Synology NAS, linux/amd64, run as an unprivileged host process (not containerised)
• Built from skrashevich/go2rtc@hksv (506cfa7) with CGO_ENABLED=0 GOOS=linux GOARCH=amd64, Go 1.26.5 — clean build, 19 MB binary
• go test ./pkg/hksv/... ./internal/homekit/... — pass
• Source: 1080p10 H.264 (Main, L4.0) pulled over RTSP from another go2rtc instance
• Real HomeKit hub, recording enabled in the Home app, motion: api

Results

Pairing, live view, and HKSV recording all worked. Recording is passthrough — no transcode:

	idle	live view	recording
CPU	0.4%	0.4%	0.7%
RSS	23 MB	22 MB	21–22 MB
ffmpeg processes	0	0	0

[hksv] flush fragment fragSize=67766 seq=10
[hksv] flush fragment fragSize=66389 seq=11
...

Fragments once per second at ~67 KB (≈536 kbps), sequential, with an hksv consumer alongside the live homekit one on a single producer.

Two things worth noting for anyone else reproducing it: HomeKit negotiated 1280x720@30 against the 1080p10 source and accepted the mismatch without transcoding; and running on the host rather than in Docker made the mDNS advertisement work alongside the system's existing Bonjour responder without any SO_REUSEPORT fiddling.

Two small findings

1. Pin silently falls back to the documented example value. pkg/hksv/hksv.go#L152:

if cfg.Pin == "" {
    cfg.Pin = "27041991"
}

That is the same value used throughout pkg/hksv/README.md, so via the Go API — where examples always set Pin explicitly — it is unsurprising. Via go2rtc's YAML config it is easier to trip over, because pin: is optional and nothing warns you. The asymmetry is that device_id and device_private are generated and persisted back to config, so a user reasonably expects pin to behave the same way, and instead gets a publicly documented pairing code.

Suggestion: generate a random pin on first run and persist it like the other pairing fields, or log a warning when falling back.

2. Benign EOF logged as an error during pairing. hksv.go#L293 logs:

ERR github.com/AlexxIT/go2rtc/pkg/hksv/hksv.go:293 > error=EOF

on an aborted PairSetup attempt, even when pairing subsequently succeeds — the Home app appears to open and drop a connection before the successful attempt. Harmless, but it reads as a failure at ERR level and sent me looking for a problem that did not exist. Might be worth demoting an io.EOF on a hijacked connection to debug.

Neither blocks anything. Thanks for the work on this — the standalone pkg/hksv split made it straightforward to evaluate.

[dppeak]

Follow-up to my validation above. This has been running in production for several days now across three more cameras, and one real defect turned up. I have a fix for it if you want it.

HAP is served on the API port, but the auth middleware doesn't exempt it
internal/homekit passes Port: uint16(api.Port), so HAP shares the API listener. middlewareAuth has no path exemption, and HAP can't send HTTP Basic credentials, so native HomeKit can't pair at all once api.username is set. Measured on 1.9.14+dev.506cfa7: POST /pair-setup, /pair-verify and /accessories all return 401.

local_auth isn't the deciding factor here, which is easy to get wrong when debugging. An iPhone is never on loopback, so the LAN path is blocked either way.

The hard part is that nothing looks broken until the very end. The accessory registers, advertises over mDNS, and hands back a valid setup code. Then the Home app just can't add it, and nothing in the logs points at auth.

The obvious workaround isn't a good one either. Turning off API auth leaves the snapshot and stream API open to everything on the LAN, on a security camera, and it breaks any healthcheck that asserts a 401.

Fix
Exempt only /pair-setup and /pair-verify. Neither one ends up unprotected:

pair-setup is guarded by the setup PIN via SRP
pair-verify is guarded by the long-term keys established during pairing
everything after that (/accessories, /characteristics, events) runs inside the encrypted HAP connection that pkg/hksv hijacks from the ResponseWriter, so it never reaches this middleware again
Twelve lines in internal/api/api.go. Applies cleanly at 506cfa7, and go build ./... is clean. I'd rather not push at your in-flight branch uninvited, so let me know if you want it as a PR.

Two other things from production use
motion_threshold doesn't have published guidance, so here's what we measured across three cameras. The idle noise floor tops out at ratio 2.89. Real triggers run 4.46 to 12.51. A night with the house empty produced zero triggers, with events on both sides of the silent window, so that's a real reading rather than logging having quietly stopped.

One trap for anyone tuning this: motion: status is logged at TRC and samples 1 frame in 150, so it shows the noise floor and never the spikes that actually fire. motion: ON is DBG. So log: { homekit: debug } is the level you want when tuning. trace just floods.

[noelhibbard]

@dppeak , in your testing, did you happen to test two way audio? That part seams to be broken.

[mofman]

@dppeak , in your testing, did you happen to test two way audio? That part seams to be broken.

#2259

[dppeak]

@dppeak , in your testing, did you happen to test two way audio? That part seams to be broken.

No. The three cameras I have (two are the same model) report no audio capability at all. Alarm.com returns SupportsDownstreamAudio, SupportsUpstreamAudio and SupportsFullDuplex as false for all three, so there was nothing for me to test.

[Mo3he]

Running this in production across 9 cameras (mixed brands) with HKSV
recording actually working: real clips landing in the Home app. Also
running directly on one of the Axis cameras as an ACAP, which handles
it fine on its own ARM core.

Confirms #2301 (wrong AAC codec enum, stray MaxAudioBitrate). One
addition: the same Bitrate/IFrameInterval-in-Supported-config issue
is in the video config too, not just audio.

Also needed #2438's fixes: TLV8 separator, TLV8 truncating past 255
bytes, the Character.listeners race.

Two more things:

• Bump the mDNS config number when the accessory database changes.
  Bug HKSV never records: wrong AAC codec enum in SupportedAudioRecordingConfiguration #2301 suggested this but didn't implement it. This does (hash of the
  DB), so enabling hksv: true on an already-paired camera doesn't
  need a re-pair.
• recording_resolution for non-16:9 cameras. HKSV tolerates a much
  larger landscape resolution than advertised (4K against the
  default 1080p/720p config records fine), but a portrait source
  against landscape-only configs just stalls: Selected Configuration
  gets picked, DataStream never opens, no error anywhere. This option
  advertises a portrait shape instead while the real video stays full
  resolution and untouched.

Worth flagging for anyone else testing: with motion: continuous, a
clip from an empty room uploads fine and Apple just quietly discards
it. Looks exactly like broken recording, no error, everything reports
healthy, until you notice nothing was actually moving.

Branch is up at https://github.com/Mo3he/go2rtc/tree/hksv if useful.

[dppeak]

Thanks for this, and for the auth fix. I reported that one and you implemented it better than my patch did: registering the paths through HandleFuncNoAuth means the api package stops having to know about homekit's URLs. I have deleted my local patch and I am building from your branch now.

Some independent verification, in case it is useful for deciding what to do with #2130.

I compared your hksv branch against 506cfa7, which is what I had been building. Yours is that commit plus 25, zero behind. Builds clean, go vet clean, HKSV and HAP suites pass.

The part worth flagging: I ran the full suite on both commits and diffed the failing package lists. Zero packages pass on 506cfa7 and fail on yours. Two go the other way:

• pkg/hap/tlv8
• pkg/hap/camera

Both fail on 506cfa7. TestVideoCodecParams there emits 0xff as the separator between repeated tags where it should be 0x00, which your 40845776 fixes. So the current PR head ships with those tests already red.

The other eight failing packages are identical on both commits, so they look environmental or pre-existing rather than anything you introduced.

On the running side, this is early: I rebuilt today. Pairings survived the swap with no re-pair needed, and the accessory that is currently online is streaming and recording normally. Two of my three cameras are off the network at the moment for reasons unrelated to any of this, so I cannot claim three-camera validation today.

Is the plan to fold these fixes into #2130, or would they land better as separate PRs against it? Happy to help test either way. My interest is straightforward: I would like to stop building a pinned fork.

[Mo3he]

Been going back and forth on this, but the fixes belong here rather
than in a separate fork - I opened a PR against skrashevich's hksv
branch with everything folded in: skrashevich#56.
Nothing exotic, mostly what we already discussed plus a few smaller
ones. Let me know if you'd rather split any of it out.

[Matthew1471]

Forgive me but how does this pull differ from #2343 and vice versa?

[dppeak]

They're implementing two different Apple specs, so they aren't really competing versions of the same thing.

#2130 does HKSV the way it has worked since it shipped: live view over classic SRTP RTP, and recordings muxed to fMP4 and sent to the home hub over HDS (HomeKit Data Stream). That's what pkg/hap/hds/ and pkg/hksv/ are in the diff.

#2343 implements the newer HomeKit Secure Video Open Source Compatibility Guide (Developer Preview, capabilities 17.99). Live view moves to WebRTC negotiated over HAP, and recording becomes CMAF segments POSTed to a publishing point the controller hands you, over mTLS with a client cert you CSR for. Hence cmaf_client.go, credentials.go and webrtc_session.go. It also brings HEVC and Opus.

The practical difference today is maturity. #2130 has been open since March and I've had three cameras paired against a fork of it and watched HKSV clips land in iCloud from all three, so that path is proven end to end. #2343's own test plan still has all four on-device boxes unchecked, and it depends on Apple accepting the accessory and providing a live publishing point.

They do both touch internal/homekit/homekit.go, internal/homekit/server.go and pkg/homekit/consumer.go, so they'll conflict textually even though the specs themselves don't overlap.

[Matthew1471]

They're implementing two different Apple specs, so they aren't really competing versions of the same thing.

#2130 does HKSV the way it has worked since it shipped: live view over classic SRTP RTP, and recordings muxed to fMP4 and sent to the home hub over HDS (HomeKit Data Stream). That's what pkg/hap/hds/ and pkg/hksv/ are in the diff.

#2343 implements the newer HomeKit Secure Video Open Source Compatibility Guide (Developer Preview, capabilities 17.99). Live view moves to WebRTC negotiated over HAP, and recording becomes CMAF segments POSTed to a publishing point the controller hands you, over mTLS with a client cert you CSR for. Hence cmaf_client.go, credentials.go and webrtc_session.go. It also brings HEVC and Opus.

The practical difference today is maturity. #2130 has been open since March and I've had three cameras paired against a fork of it and watched HKSV clips land in iCloud from all three, so that path is proven end to end. #2343's own test plan still has all four on-device boxes unchecked, and it depends on Apple accepting the accessory and providing a live publishing point.

They do both touch internal/homekit/homekit.go, internal/homekit/server.go and pkg/homekit/consumer.go, so they'll conflict textually even though the specs themselves don't overlap.

That's really interesting thank you for explaining it. #2130 seems like the one for me to test now - just wiping 5 x MotionEye installs and then I'll see what happens with this branch.

[noelhibbard]

@dppeak , in your testing, did you happen to test two way audio? That part seams to be broken.

#2259

I tested your fork and talk back is working perfect but it doesn't include the HKSV changes add in #2130. It would be great if your fixes made it into #2130.

Edit: I rolled both of Mo3he's PRs and your PR into one build and it's working well.