Skip to content

Experimental HomeKit Secure Video open-source (WebRTC + HEVC + CMAF recording) #2343

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rursache wants to merge 8 commits into
base: master
Choose a base branch
from
Open

Experimental HomeKit Secure Video open-source (WebRTC + HEVC + CMAF recording) #2343

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
cd24ab4
Support longer HAP type IDs and tlv8 bool for HKSV
rursache Jul 10, 2026
73db5ef
Add HKSV open-source HAP types, TLV8 structs and services
rursache Jul 10, 2026
cfd6ce3
Add HomeKit WebRTC session manager and HEVC consumer path
rursache Jul 10, 2026
4d0f4e9
Wire HKSV WebRTC handlers and experimental hksv config flag
rursache Jul 10, 2026
a3272bc
Add HKSV unit tests and document experimental hksv option
rursache Jul 10, 2026
c2e8a60
Implement full HKSV CMAF recording pipeline
rursache Jul 10, 2026
a75905a
Harden HKSV recording tests and fix tlv8 separator
rursache Jul 10, 2026
88c8335
Add HAP server handler tests and fix write-response races
rursache Jul 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 51 additions & 14 deletions examples/homekit_info/main.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,20 +8,28 @@ import (
)

var servs = map[string]string{
"3E": "Accessory Information",
"7E": "Security System",
"85": "Motion Sensor",
"96": "Battery",
"A2": "Protocol Information",
"110": "Camera RTP Stream Management",
"112": "Microphone",
"113": "Speaker",
"121": "Doorbell",
"129": "Data Stream Transport Management",
"204": "Camera Recording Management",
"21A": "Camera Operating Mode",
"22A": "Wi-Fi Transport",
"239": "Accessory Runtime Information",
"3E": "Accessory Information",
"7E": "Security System",
"85": "Motion Sensor",
"96": "Battery",
"A2": "Protocol Information",
"110": "Camera RTP Stream Management",
"112": "Microphone",
"113": "Speaker",
"121": "Doorbell",
"129": "Data Stream Transport Management",
"204": "Camera Recording Management",
"21A": "Camera Operating Mode",
"22A": "Wi-Fi Transport",
"239": "Accessory Runtime Information",
"8000": "Camera Buffer Management",
"8010": "Camera Capabilities",
"8021": "Camera Motion Zones",
"8031": "Camera Multi-Tier RTP Stream Management",
"8032": "Camera Global Operating Mode",
"8033": "Camera WebRTC Stream Management",
"8050": "Camera Key Management",
"8080": "Camera Client Certificate Management",
}

var chars = map[string]string{
Expand Down Expand Up @@ -81,6 +89,35 @@ var chars = map[string]string{

"66": "Security System Current State",
"67": "Security System Target State",

// HKSV open-source (Developer Preview 17.99)
"8011": "Camera Capabilities",
"8013": "Buffer Upload Command",
"8014": "Buffer Event Command",
"8015": "Buffer Event Sequence Number",
"8016": "Camera Recording Publishing Point",
"8017": "Buffer Activity Command",
"8022": "Camera Zones",
"8041": "Streaming Enabled",
"8043": "Supported Video Stream Tiers",
"8044": "Supported Audio Stream Tiers",
"8045": "RTP Streaming Control",
"8051": "Camera Key",
"8052": "Camera Key ID",
"8053": "WebRTC Solicit Offer",
"8054": "WebRTC Provide Answer",
"8056": "WebRTC Streaming Control",
"8057": "WebRTC Number of Active Sessions",
"8058": "WebRTC Reoffer",
"8059": "WebRTC Supported Video Stream Tiers",
"805A": "WebRTC Supported Audio Stream Tiers",
"805B": "Sensor UUID",
"805C": "WebRTC Update Session",
"8081": "Camera Client CSR",
"8082": "Camera Client Certificate",
"8083": "Camera Client Certificate Status",
"8086": "Contributing Sensors",
"8087": "Motion Enabled",
}

func main() {
Expand Down
26 changes: 25 additions & 1 deletion internal/homekit/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,8 @@ HomeKit module can work in two modes:

**Important**

- HomeKit cameras support only H264 video and OPUS audio
- Classic HomeKit cameras support H264 video and OPUS audio
- With experimental `hksv: true`, the accessory also advertises HEVC (H.265) and WebRTC live view per Apple's HomeKit Secure Video Open Source Compatibility Guide (Developer Preview 17.99)

### Server Configuration

Expand Down Expand Up @@ -79,8 +80,31 @@ homekit:
name: Dahua camera # custom camera name, default: generated from stream ID
device_id: dahua1 # custom ID, default: generated from stream ID
device_private: dahua1 # custom key, default: generated from stream ID
hksv: true # experimental: HKSV open-source (WebRTC + HEVC tiers + CMAF certs)
```

### Experimental HKSV open-source (`hksv: true`)

Implements the HAP services from [issue #2297](https://github.com/AlexxIT/go2rtc/issues/2297) / Apple's
[HomeKit Secure Video Open Source Compatibility Guide](https://developer.apple.com/download/files/HomeKit-Secure-Video-Open-Source-Compatibility-Guide.pdf)
(Developer Preview, capabilities version `17.99`):

- Camera Capabilities, Global Operating Mode, Motion Zones
- Multi-tier RTP stream management (High/Medium/Low, HEVC + H.264, Opus)
- WebRTC Stream Management (solicit-offer / provide-answer over HAP, min 6 sessions)
- Classic RTP kept with 5 concurrent stream slots
- CMAF recording stack:
- 8s ring pre-buffer from the source stream
- Client CSR + certificate install (mTLS identity for ingest)
- Content key management (stored for CENC; clear fMP4 uploaded, transport protected by mTLS)
- Publishing point URL + server CAs from the controller
- Buffer activity / upload / event queue with HAP write-response and sequence notifies
- DASH-IF Interface-1 POST of init + media segments to the publishing point

The guide is a Developer Preview and may change before release. Full end-to-end Secure Video
in Apple Home still depends on Apple accepting the accessory after pairing and providing a
live publishing point URL.

**Proxy HomeKit camera**

- Video stream from HomeKit camera to Apple device (iPhone, Apple TV) will be transmitted directly
Expand Down
14 changes: 13 additions & 1 deletion internal/homekit/homekit.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,9 @@ func Init() {
DevicePrivate string `yaml:"device_private"`
CategoryID string `yaml:"category_id"`
Pairings []string `yaml:"pairings"`
// HKSV enables experimental HomeKit Secure Video open-source services
// (WebRTC live view, multi-tier HEVC, CMAF recording ingest). Spec version 17.99
HKSV bool `yaml:"hksv"`
} `yaml:"homekit"`
}
app.LoadConfig(&cfg)
Expand Down Expand Up @@ -71,6 +74,7 @@ func Init() {
stream: id,
pairings: conf.Pairings,
setupID: setupID,
hksv: conf.HKSV,
}

srv.hap = &hap.Server{
Expand Down Expand Up @@ -102,8 +106,16 @@ func Init() {
if url := findHomeKitURL(stream.Sources()); url != "" {
// 1. Act as transparent proxy for HomeKit camera
srv.proxyURL = url
} else if conf.HKSV {
// 2. Experimental HKSV open-source camera (WebRTC + HEVC + CMAF recording)
srv.accessory = camera.NewHKSVAccessory("AlexxIT", "go2rtc", name, "-", app.Version, id)
srv.webrtc = homekit.NewWebRTCManager(newHomeKitPeerConnection)
srv.recording = homekit.NewRecordingManager()
srv.recording.OnEventSeq = srv.notifyEventSequence
go srv.startRecordingBuffer()
log.Info().Str("stream", id).Msg("[homekit] HKSV open-source enabled (experimental, capabilities 17.99)")
} else {
// 2. Act as basic HomeKit camera
// 3. Act as basic HomeKit camera
srv.accessory = camera.NewAccessory("AlexxIT", "go2rtc", name, "-", app.Version)
}

Expand Down
Loading