feat(homekit): add HKSV support with motion detection and doorbell functionality

- Introduced HKSV configuration options in homekit.go, allowing for motion detection and doorbell features.
- Implemented API endpoints for triggering motion detection and doorbell events.
- Enhanced server.go to handle HKSV sessions and manage motion detection states.
- Created new accessory types for HKSV and doorbell in accessory.go.
- Added support for audio recording configurations in ch207.go.
- Defined new services for motion detection and doorbell in services_hksv.go.
- Implemented opack encoding/decoding for HDS protocol in opack.go and protocol.go.
- Updated OpenAPI documentation to reflect new endpoints and features.
- Extended schema.json to include HKSV configuration options.

internal/homekit/README.md

@@ -81,6 +81,72 @@ homekit:
     device_private: dahua1  # custom key, default: generated from stream ID
 ```
 
+### HKSV (HomeKit Secure Video)
+
+go2rtc can expose any camera as a HomeKit Secure Video (HKSV) camera. This allows Apple Home to record video clips to iCloud when motion is detected.
+
+**Requirements:**
+- Apple Home Hub (Apple TV, HomePod or iPad) on the same network
+- iCloud storage plan with HomeKit Secure Video support
+- Camera source with H264 video (AAC audio recommended)
+
+**Minimal HKSV config**
+
+```yaml
+streams:
+  outdoor: rtsp://admin:password@192.168.1.123/stream1
+
+homekit:
+  outdoor:
+    hksv: true           # enable HomeKit Secure Video
+    motion: continuous   # always report motion, Home Hub decides what to record
+```
+
+**Full HKSV config**
+
+```yaml
+streams:
+  outdoor:
+    - rtsp://admin:password@192.168.1.123/stream1
+    - ffmpeg:outdoor#video=h264#hardware  # transcode to H264 if needed
+    - ffmpeg:outdoor#audio=aac            # AAC-LC audio for HKSV recording
+
+homekit:
+  outdoor:
+    pin: 12345678
+    name: Outdoor Camera
+    hksv: true
+    motion: api          # motion triggered via API
+```
+
+**HKSV Doorbell config**
+
+```yaml
+homekit:
+  front_door:
+    category_id: doorbell
+    hksv: true
+    motion: api
+```
+
+**Motion modes:**
+
+- `continuous` — MotionDetected is always true; Home Hub continuously receives video and decides what to save. Simplest setup, recommended for most cameras.
+- `api` — motion is triggered externally via HTTP API. Use this with Frigate, ONVIF events, or any other motion detection system.
+
+**Motion API:**
+
+```bash
+# Trigger motion start
+curl -X POST "http://localhost:1984/api/homekit/motion?id=outdoor"
+
+# Clear motion
+curl -X DELETE "http://localhost:1984/api/homekit/motion?id=outdoor"
+
+# Trigger doorbell ring
+curl -X POST "http://localhost:1984/api/homekit/doorbell?id=front_door"
+```
+
 **Proxy HomeKit camera**
 
 - Video stream from HomeKit camera to Apple device (iPhone, Apple TV) will be transmitted directly

internal/homekit/hksv.go

@@ -0,0 +1,289 @@
+package homekit
+
+import (
+	"io"
+	"net"
+	"sync"
+	"time"
+
+	"github.com/AlexxIT/go2rtc/internal/streams"
+	"github.com/AlexxIT/go2rtc/pkg/aac"
+	"github.com/AlexxIT/go2rtc/pkg/core"
+	"github.com/AlexxIT/go2rtc/pkg/h264"
+	"github.com/AlexxIT/go2rtc/pkg/hap"
+	"github.com/AlexxIT/go2rtc/pkg/hap/hds"
+	"github.com/AlexxIT/go2rtc/pkg/mp4"
+	"github.com/pion/rtp"
+)
+
+// hksvSession manages the HDS DataStream connection for HKSV recording
+type hksvSession struct {
+	server  *server
+	hapConn *hap.Conn
+	hdsConn *hds.Conn
+	session *hds.Session
+
+	mu       sync.Mutex
+	consumer *hksvConsumer
+}
+
+func newHKSVSession(srv *server, hapConn *hap.Conn, hdsConn *hds.Conn) *hksvSession {
+	session := hds.NewSession(hdsConn)
+	hs := &hksvSession{
+		server:  srv,
+		hapConn: hapConn,
+		hdsConn: hdsConn,
+		session: session,
+	}
+	session.OnDataSendOpen = hs.handleOpen
+	session.OnDataSendClose = hs.handleClose
+	return hs
+}
+
+func (hs *hksvSession) Run() error {
+	return hs.session.Run()
+}
+
+func (hs *hksvSession) Close() {
+	hs.mu.Lock()
+	defer hs.mu.Unlock()
+	if hs.consumer != nil {
+		hs.stopRecording()
+	}
+	_ = hs.session.Close()
+}
+
+func (hs *hksvSession) handleOpen(streamID int) error {
+	hs.mu.Lock()
+	defer hs.mu.Unlock()
+
+	log.Debug().Str("stream", hs.server.stream).Int("streamID", streamID).Msg("[homekit] HKSV dataSend open")
+
+	if hs.consumer != nil {
+		hs.stopRecording()
+	}
+
+	consumer := newHKSVConsumer(hs.session, streamID)
+	hs.consumer = consumer
+
+	stream := streams.Get(hs.server.stream)
+	if err := stream.AddConsumer(consumer); err != nil {
+		log.Error().Err(err).Str("stream", hs.server.stream).Msg("[homekit] HKSV add consumer failed")
+		hs.consumer = nil
+		return nil // don't kill the session
+	}
+
+	hs.server.AddConn(consumer)
+
+	// wait for tracks to be added, then send init
+	go func() {
+		if err := consumer.waitAndSendInit(); err != nil {
+			log.Error().Err(err).Str("stream", hs.server.stream).Msg("[homekit] HKSV send init failed")
+		}
+	}()
+
+	return nil
+}
+
+func (hs *hksvSession) handleClose(streamID int) error {
+	hs.mu.Lock()
+	defer hs.mu.Unlock()
+
+	log.Debug().Str("stream", hs.server.stream).Int("streamID", streamID).Msg("[homekit] HKSV dataSend close")
+
+	if hs.consumer != nil {
+		hs.stopRecording()
+	}
+	return nil
+}
+
+func (hs *hksvSession) stopRecording() {
+	consumer := hs.consumer
+	hs.consumer = nil
+
+	stream := streams.Get(hs.server.stream)
+	stream.RemoveConsumer(consumer)
+	_ = consumer.Stop()
+	hs.server.DelConn(consumer)
+}
+
+// hksvConsumer implements core.Consumer, generates fMP4 and sends over HDS
+type hksvConsumer struct {
+	core.Connection
+	session  *hds.Session
+	muxer    *mp4.Muxer
+	streamID int
+	seqNum   int
+	mu       sync.Mutex
+	start    bool
+	done     chan struct{}
+}
+
+func newHKSVConsumer(session *hds.Session, streamID int) *hksvConsumer {
+	medias := []*core.Media{
+		{
+			Kind:      core.KindVideo,
+			Direction: core.DirectionSendonly,
+			Codecs: []*core.Codec{
+				{Name: core.CodecH264},
+			},
+		},
+		{
+			Kind:      core.KindAudio,
+			Direction: core.DirectionSendonly,
+			Codecs: []*core.Codec{
+				{Name: core.CodecAAC},
+			},
+		},
+	}
+	return &hksvConsumer{
+		Connection: core.Connection{
+			ID:         core.NewID(),
+			FormatName: "hksv",
+			Protocol:   "hds",
+			Medias:     medias,
+		},
+		session:  session,
+		muxer:    &mp4.Muxer{},
+		streamID: streamID,
+		done:     make(chan struct{}),
+	}
+}
+
+func (c *hksvConsumer) AddTrack(media *core.Media, _ *core.Codec, track *core.Receiver) error {
+	trackID := byte(len(c.Senders))
+
+	codec := track.Codec.Clone()
+	handler := core.NewSender(media, codec)
+
+	switch track.Codec.Name {
+	case core.CodecH264:
+		handler.Handler = func(packet *rtp.Packet) {
+			if !c.start {
+				if !h264.IsKeyframe(packet.Payload) {
+					return
+				}
+				c.start = true
+			}
+
+			c.mu.Lock()
+			b := c.muxer.GetPayload(trackID, packet)
+			if err := c.session.SendMediaFragment(c.streamID, b, c.seqNum); err == nil {
+				c.Send += len(b)
+				c.seqNum++
+			}
+			c.mu.Unlock()
+		}
+
+		if track.Codec.IsRTP() {
+			handler.Handler = h264.RTPDepay(track.Codec, handler.Handler)
+		} else {
+			handler.Handler = h264.RepairAVCC(track.Codec, handler.Handler)
+		}
+
+	case core.CodecAAC:
+		handler.Handler = func(packet *rtp.Packet) {
+			if !c.start {
+				return
+			}
+
+			c.mu.Lock()
+			b := c.muxer.GetPayload(trackID, packet)
+			if err := c.session.SendMediaFragment(c.streamID, b, c.seqNum); err == nil {
+				c.Send += len(b)
+				c.seqNum++
+			}
+			c.mu.Unlock()
+		}
+
+		if track.Codec.IsRTP() {
+			handler.Handler = aac.RTPDepay(handler.Handler)
+		}
+
+	default:
+		return nil // skip unsupported codecs
+	}
+
+	c.muxer.AddTrack(codec)
+	handler.HandleRTP(track)
+	c.Senders = append(c.Senders, handler)
+
+	return nil
+}
+
+func (c *hksvConsumer) waitAndSendInit() error {
+	// wait for at least one track to be added
+	for i := 0; i < 50; i++ {
+		if len(c.Senders) > 0 {
+			break
+		}
+		time.Sleep(100 * time.Millisecond)
+	}
+
+	init, err := c.muxer.GetInit()
+	if err != nil {
+		return err
+	}
+	return c.session.SendMediaInit(c.streamID, init)
+}
+
+func (c *hksvConsumer) WriteTo(io.Writer) (int64, error) {
+	<-c.done
+	return 0, nil
+}
+
+func (c *hksvConsumer) Stop() error {
+	select {
+	case <-c.done:
+	default:
+		close(c.done)
+	}
+	return c.Connection.Stop()
+}
+
+// acceptHDS opens a TCP listener for the HDS DataStream connection from the Home Hub
+func (s *server) acceptHDS(hapConn *hap.Conn, ln net.Listener, salt string) {
+	defer ln.Close()
+
+	if tcpLn, ok := ln.(*net.TCPListener); ok {
+		_ = tcpLn.SetDeadline(time.Now().Add(30 * time.Second))
+	}
+
+	rawConn, err := ln.Accept()
+	if err != nil {
+		log.Error().Err(err).Str("stream", s.stream).Msg("[homekit] HKSV accept failed")
+		return
+	}
+	defer rawConn.Close()
+
+	// Create HDS encrypted connection (controller=false, we are accessory)
+	hdsConn, err := hds.NewConn(rawConn, hapConn.SharedKey, salt, false)
+	if err != nil {
+		log.Error().Err(err).Str("stream", s.stream).Msg("[homekit] HKSV hds conn failed")
+		return
+	}
+
+	s.AddConn(hdsConn)
+	defer s.DelConn(hdsConn)
+
+	session := newHKSVSession(s, hapConn, hdsConn)
+
+	s.mu.Lock()
+	s.hksvSession = session
+	s.mu.Unlock()
+
+	defer func() {
+		s.mu.Lock()
+		if s.hksvSession == session {
+			s.hksvSession = nil
+		}
+		s.mu.Unlock()
+		session.Close()
+	}()
+
+	log.Debug().Str("stream", s.stream).Msg("[homekit] HKSV session started")
+
+	if err := session.Run(); err != nil {
+		log.Debug().Err(err).Str("stream", s.stream).Msg("[homekit] HKSV session ended")
+	}
+}

internal/homekit/homekit.go

@@ -26,6 +26,8 @@ func Init() {
 			DevicePrivate string   `yaml:"device_private"`
 			CategoryID    string   `yaml:"category_id"`
 			Pairings      []string `yaml:"pairings"`
+			HKSV          bool     `yaml:"hksv"`
+			Motion        string   `yaml:"motion"`
 		} `yaml:"homekit"`
 	}
 	app.LoadConfig(&cfg)
@@ -36,6 +38,8 @@ func Init() {
 
 	api.HandleFunc("api/homekit", apiHomekit)
 	api.HandleFunc("api/homekit/accessories", apiHomekitAccessories)
+	api.HandleFunc("api/homekit/motion", apiMotion)
+	api.HandleFunc("api/homekit/doorbell", apiDoorbell)
 	api.HandleFunc("api/discovery/homekit", apiDiscovery)
 
 	if cfg.Mod == nil {
@@ -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. Act as HKSV camera
+			srv.motionMode = conf.Motion
+			if conf.CategoryID == "doorbell" {
+				srv.accessory = camera.NewHKSVDoorbellAccessory("AlexxIT", "go2rtc", name, "-", app.Version)
+			} else {
+				srv.accessory = camera.NewHKSVAccessory("AlexxIT", "go2rtc", name, "-", app.Version)
+			}
 		} else {
-			// 2. Act as basic HomeKit camera
+			// 3. Act as basic HomeKit camera
 			srv.accessory = camera.NewAccessory("AlexxIT", "go2rtc", name, "-", app.Version)
 		}
 
@@ -189,6 +201,37 @@ func findHomeKitURL(sources []string) string {
 	return ""
 }
 
+func apiMotion(w http.ResponseWriter, r *http.Request) {
+	id := r.URL.Query().Get("id")
+	srv := servers[id]
+	if srv == nil {
+		http.Error(w, "server not found: "+id, http.StatusNotFound)
+		return
+	}
+	switch r.Method {
+	case "POST":
+		srv.SetMotionDetected(true)
+	case "DELETE":
+		srv.SetMotionDetected(false)
+	default:
+		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+	}
+}
+
+func apiDoorbell(w http.ResponseWriter, r *http.Request) {
+	if r.Method != "POST" {
+		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	id := r.URL.Query().Get("id")
+	srv := servers[id]
+	if srv == nil {
+		http.Error(w, "server not found: "+id, http.StatusNotFound)
+		return
+	}
+	srv.TriggerDoorbell()
+}
+
 func parseBitrate(s string) int {
 	n := len(s)
 	if n == 0 {

internal/homekit/server.go

@@ -14,6 +14,7 @@ import (
 	"slices"
 	"strings"
 	"sync"
+	"time"
 
 	"github.com/AlexxIT/go2rtc/internal/app"
 	"github.com/AlexxIT/go2rtc/internal/ffmpeg"
@@ -42,6 +43,10 @@ type server struct {
 	proxyURL  string
 	setupID   string
 	stream    string // stream name from YAML
+
+	// HKSV fields
+	motionMode  string // "api", "continuous"
+	hksvSession *hksvSession
 }
 
 func (s *server) MarshalJSON() ([]byte, error) {
@@ -120,9 +125,15 @@ func (s *server) Handle(w http.ResponseWriter, r *http.Request) {
 			handler = homekit.ProxyHandler(s, client.Conn)
 		}
 
+		log.Debug().Str("stream", s.stream).Msgf("[homekit] handler started for %s", conn.RemoteAddr())
+
 		// If your iPhone goes to sleep, it will be an EOF error.
-		if err = handler(controller); err != nil && !errors.Is(err, io.EOF) {
-			log.Error().Err(err).Caller().Send()
+		if err = handler(controller); err != nil {
+			if errors.Is(err, io.EOF) {
+				log.Debug().Str("stream", s.stream).Msgf("[homekit] %s: connection closed (EOF)", conn.RemoteAddr())
+			} else {
+				log.Error().Err(err).Str("stream", s.stream).Caller().Send()
+			}
 			return
 		}
 	}
@@ -226,6 +237,12 @@ func (s *server) PatchConfig() {
 }
 
 func (s *server) GetAccessories(_ net.Conn) []*hap.Accessory {
+	log.Trace().Str("stream", s.stream).Msg("[homekit] GET /accessories")
+	if log.Trace().Enabled() {
+		if b, err := json.Marshal(s.accessory); err == nil {
+			log.Trace().Str("stream", s.stream).RawJSON("accessory", b).Msg("[homekit] accessory JSON")
+		}
+	}
 	return []*hap.Accessory{s.accessory}
 }
 
@@ -321,6 +338,65 @@ func (s *server) SetCharacteristic(conn net.Conn, aid uint8, iid uint64, value a
 				s.DelConn(consumer)
 			}()
 		}
+
+	case camera.TypeSetupDataStreamTransport:
+		var req camera.SetupDataStreamTransportRequest
+		if err := tlv8.UnmarshalBase64(value, &req); err != nil {
+			log.Error().Err(err).Str("stream", s.stream).Msg("[homekit] HKSV parse ch131 failed")
+			return
+		}
+
+		log.Debug().Str("stream", s.stream).Uint8("cmd", req.SessionCommandType).
+			Uint8("transport", req.TransportType).Msg("[homekit] HKSV DataStream setup")
+
+		if req.SessionCommandType != 0 {
+			// 0 = start, 1 = close
+			log.Debug().Str("stream", s.stream).Msg("[homekit] HKSV DataStream close request")
+			if s.hksvSession != nil {
+				s.hksvSession.Close()
+			}
+			return
+		}
+
+		accessoryKeySalt := core.RandString(32, 0)
+		combinedSalt := req.ControllerKeySalt + accessoryKeySalt
+
+		ln, err := net.ListenTCP("tcp", nil)
+		if err != nil {
+			log.Error().Err(err).Str("stream", s.stream).Msg("[homekit] HKSV listen failed")
+			return
+		}
+		port := ln.Addr().(*net.TCPAddr).Port
+
+		resp := camera.SetupDataStreamTransportResponse{
+			Status:           0,
+			AccessoryKeySalt: accessoryKeySalt,
+		}
+		resp.TransportTypeSessionParameters.TCPListeningPort = uint16(port)
+
+		v, err := tlv8.MarshalBase64(resp)
+		if err != nil {
+			ln.Close()
+			return
+		}
+		char.Value = v
+
+		log.Debug().Str("stream", s.stream).Int("port", port).Msg("[homekit] HKSV listening for HDS")
+
+		hapConn := conn.(*hap.Conn)
+		go s.acceptHDS(hapConn, ln, combinedSalt)
+
+	case camera.TypeSelectedCameraRecordingConfiguration:
+		log.Debug().Str("stream", s.stream).Msg("[homekit] HKSV selected recording config")
+		char.Value = value
+
+		if s.motionMode == "continuous" {
+			go s.startContinuousMotion()
+		}
+
+	default:
+		// Store value for all other writable characteristics
+		char.Value = value
 	}
 }
 
@@ -351,6 +427,46 @@ func (s *server) GetImage(conn net.Conn, width, height int) []byte {
 	return b
 }
 
+func (s *server) SetMotionDetected(detected bool) {
+	if s.accessory == nil {
+		return
+	}
+	char := s.accessory.GetCharacter("22") // MotionDetected
+	if char == nil {
+		return
+	}
+	char.Value = detected
+	_ = char.NotifyListeners(nil)
+	log.Debug().Str("stream", s.stream).Bool("motion", detected).Msg("[homekit] motion")
+}
+
+func (s *server) TriggerDoorbell() {
+	if s.accessory == nil {
+		return
+	}
+	char := s.accessory.GetCharacter("73") // ProgrammableSwitchEvent
+	if char == nil {
+		return
+	}
+	char.Value = 0 // SINGLE_PRESS
+	_ = char.NotifyListeners(nil)
+	log.Debug().Str("stream", s.stream).Msg("[homekit] doorbell")
+}
+
+func (s *server) startContinuousMotion() {
+	s.SetMotionDetected(true)
+
+	ticker := time.NewTicker(30 * time.Second)
+	defer ticker.Stop()
+
+	for range ticker.C {
+		if s.accessory == nil {
+			return
+		}
+		s.SetMotionDetected(true)
+	}
+}
+
 func calcName(name, seed string) string {
 	if name != "" {
 		return name