@homebridge-plugins/homebridge-eufy-security 4.6.0-beta.9 → 4.6.1-beta.0

package/.claude/CLAUDE.md

@@ -0,0 +1,175 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with the homebridge-eufy-security plugin.
+
+## Project Overview
+
+Homebridge plugin that exposes Eufy Security devices to Apple HomeKit. Published as `@homebridge-plugins/homebridge-eufy-security` under the `homebridge-plugins` GitHub organization.
+
+Depends on `eufy-security-client` (upstream: bropat/eufy-security-client) for cloud API, P2P, push notifications, and MQTT communication.
+
+For detailed functional requirements, device coverage, configuration options, and architecture boundaries, see `.claude/PRD.md`.
+
+## Build & Dev Commands
+
+```bash
+npm run build          # rimraf dist -> tsc -> copy media/ to dist/
+npm run build-plugin   # rimraf dist -> tsc (no media copy)
+npm run lint           # eslint 'src/**/*.ts' --max-warnings=0
+npm run lint-fix       # eslint with --fix
+```
+
+- No test suite -- there are no unit or integration tests
+- Output: `dist/`
+- `--max-warnings=0` is enforced -- all warnings must be fixed before committing
+- ESLint uses flat config (`eslint.config.mjs`); `@typescript-eslint/no-explicit-any` is globally disabled -- do not add eslint-disable comments for it
+- Run `npm run lint` and `npm run build` before pushing
+
+## Architecture
+
+Entry point `src/index.ts` registers `EufySecurityPlatform` with Homebridge. The platform class (`src/platform.ts`) is the core -- it initializes the `EufySecurity` client, discovers devices, and creates HomeKit accessories.
+
+**Accessory classes** in `src/accessories/` map Eufy device types to HomeKit services:
+- `BaseAccessory.ts` -- root base class (characteristic registration, service pruning)
+- `Device.ts` (`DeviceAccessory`) -- extends `BaseAccessory`; adds sensor/battery services, property helpers
+- `CameraAccessory` -- cameras, doorbells, floodlights (handles streaming delegates); extends `DeviceAccessory`
+- `StationAccessory` -- base stations (security system service for arm/disarm); extends `BaseAccessory` directly
+- `LockAccessory`, `EntrySensorAccessory`, `MotionSensorAccessory`, `SmartDropAccessory` -- extend `DeviceAccessory`
+- `AutoSyncStationAccessory` -- virtual accessory that syncs station guard mode with HomeKit
+
+**Streaming pipeline** in `src/controller/`:
+- `streamingDelegate.ts` -- HomeKit camera streaming (FFmpeg-based)
+- `recordingDelegate.ts` -- HomeKit Secure Video recording
+- `snapshotDelegate.ts` -- snapshot handling
+- `LocalLivestreamManager.ts` -- manages P2P livestream sessions
+
+**Utilities** in `src/utils/`: logging (`utils.ts`), FFmpeg wrapper (`ffmpeg.ts`), two-way audio (`Talkback.ts`), config schema (`configTypes.ts`), internal interfaces (`interfaces.ts`).
+
+**Constants** in `src/settings.ts`: HKSV segment lengths, snapshot cache ages, streaming bitrate headroom, IDR intervals -- reference this when tuning streaming or recording behaviour.
+
+**Plugin UI** in `homebridge-ui/`: `server.js` (plain JS, eslint-ignored) handles UI server logic and diagnostics generation. The UI and the plugin runtime (`src/`) are **separate processes** that share state through `accessories.json` on disk (written by `src/utils/accessoriesStore.ts`, read by `homebridge-ui/server.js`). Both independently import `eufy-security-client` types (`DeviceType`, `PropertyName`, `Device`, etc.) -- changes to the device/station record shape must be kept in sync between `accessoriesStore.ts` and `server.js`.
+
+### Key source files for device registration and triage
+
+- `src/platform.ts` (`register_device`) -- device registration logic; devices can stack multiple capabilities (independent `if` blocks, not `else if`)
+
+## Key Technical Details
+
+- ESM project (`"type": "module"`, `"module": "NodeNext"`) -- imports must use `.js` extensions (NodeNext resolution requires explicit extensions)
+- TypeScript strict mode, ES2022 target (`noImplicitAny: false` relaxes implicit-any checks)
+- Node.js 20, 22, or 24 required
+- Homebridge >=1.9.0 or ^2.0.0-beta
+- Uses `ffmpeg-for-homebridge` for video transcoding
+- `src/version.ts` is auto-generated at prebuild time -- do not edit manually
+- `prepublishOnly` runs lint + build automatically before `npm publish`
+- For local development, `eufy-security-client` can be pointed to a local path (e.g. `"../eufy-security-client"`)
+
+## Git Workflow
+
+**IMPORTANT: Create the branch BEFORE editing any files.**
+
+```bash
+# Create dedicated branch from beta before making any changes
+git checkout beta-*.*.* && git pull origin beta-*.*.*
+git checkout -b [fix/feat/chore]/<short-description>
+
+# Stage and commit each change individually
+git add <file>
+git commit -m "fix: <concise description of what changed and why>"
+
+# Push and create PR
+git push -u origin fix/<short-description>
+gh pr create --base beta-*.*.* --title "<concise title>" --body-file /tmp/pr-body.md
+```
+
+- Branch from `beta-*.*.*`, not `master`
+- PR target: `beta-*.*.*`
+- Branch naming: `fix/`, `feat/`, `chore/` prefix
+
+### Commit message rules
+
+- Single line, no line breaks mid-sentence
+- Describe the **spirit** of the change, not the code diff
+- No Co-Authored-By
+
+### PR body
+
+- Write to `/tmp/pr-body-<branch>.md` using file creation -- **never** use heredoc (`cat << EOF`) in the terminal (quotes and special characters break it)
+- Describe the **spirit** of the change, not the code diff
+- Concise description of the problem and fix
+- PR body is **not** the release note -- keep it focused on the code change for reviewers
+- No Co-Authored-By
+
+### Release notes
+
+- Write to `/tmp/release-notes-<version>.md` using file creation
+- **Audience is end users** -- focus on what matters to them: new devices, behaviour changes, removed settings, required actions
+- **Concise, bullet-driven** -- no markdown tables, no verbose paragraphs. Short section intros (1-2 sentences max) followed by bullet lists
+- **No internal milestones** -- don't mention "first GA since X" or beta iteration counts
+- **Structure for a branch** (e.g., `4.4.x`), not a single version:
+  - Individual `## v4.4.x` entries at the top with version-specific changes
+  - A shared `## What's in 4.4.x` section below covering the full branch
+- **Required actions front and center** -- if users need to change config or upgrade Node.js, say so early and clearly
+- **Tone**: direct, no filler, no emojis
+
+### Issue comments
+
+- Use `gh issue comment <number> --repo homebridge-plugins/homebridge-eufy-security --body "<message>"`
+- Use first person ("I")
+- Thank the user by @mention
+- Be formal and concise
+- **Audience is end users** -- keep language simple, no internal jargon
+- Don't scope a fix to a specific device when it applies broadly
+- When a fix is merged, check the published beta version (`npm view @homebridge-plugins/homebridge-eufy-security dist-tags`) and mention it in the comment
+
+## Dependency Policy -- `eufy-security-client`
+
+**CRITICAL:**
+- **`beta-*.*.*` branches** -- use the `dev` dist-tag (`"eufy-security-client": "dev"`)
+- **`master` branch** -- **NEVER** use the `dev` dist-tag. Always use a pinned stable version (e.g. `"^3.7.2"`). Before merging to master, replace `"dev"` with the corresponding stable release version.
+
+When updating the `eufy-security-client` version in `package.json`:
+1. Check the upstream changelog and README at https://github.com/bropat/eufy-security-client/blob/master/README.md
+2. Identify breaking changes, new features, or device support changes
+3. Summarize the impact in the PR body
+4. If there are breaking changes, note any required code adjustments
+
+## Skills
+
+Skills in `.claude/skills/` provide structured workflows for common tasks:
+
+| Skill | Purpose |
+|---|---|
+| `planner` | Build a step-by-step action plan with guardrails before coding |
+| `developer` | Execute code changes following an approved plan or direct instructions |
+| `qa` | Verify build, lint, imports, architecture, and git hygiene before pushing |
+| `architect` | Quick codebase questions, mini-bug debugging, workflow improvement |
+| `support` | Triage GitHub issues using diagnostics archives and logs |
+| `new-device-support` | Full workflow to add a new Eufy device type across both repos |
+
+Typical flow: **planner** -> **developer** -> **qa**. Use **architect** for exploration and **support** for issue triage.
+
+## Diagnostic Triage
+
+For issue triage, use the `support` skill with an issue number (e.g. `/support 423`). For the full triage reference, see `.github/prompts/diag-triage.prompt.md`. For adding new device types, use the `new-device-support` skill. Key points:
+
+- Diagnostics archives are encrypted (RSA-4096 + AES-256-GCM); decrypt with `node scripts/decrypt-diagnostics.mjs <file>.tar.gz`
+- Always check archive completeness before analysis -- missing runtime logs means the plugin wasn't running
+- When diagnostics are incomplete or debug is disabled, ask the user to upgrade to the latest [beta](https://github.com/homebridge-plugins/homebridge-eufy-security/wiki/Special-Version-(BETA---RC---HKSV)) and follow the [Basic Troubleshooting](https://github.com/homebridge-plugins/homebridge-eufy-security/wiki/Basic-Troubleshooting) steps to enable Detailed Logging, reproduce the issue, and re-export diagnostics
+- Narrow down whether the issue is in `homebridge-eufy-security` (accessory registration, HomeKit mapping, config handling) or in `eufy-security-client` (device discovery, property events, P2P, push notifications)
+- If the environment indicates HOOBS: label `hoobs` + `wontfix` and close -- HOOBS is not supported
+
+### Label recommendations
+
+| Label | When to use |
+|---|---|
+| `depends on eufy-security-client` | Issue originates in bropat's eufy-security-client library |
+| `device-support` | New device type support request |
+| `debug log missing` | Diagnostics lack logs or debug mode was disabled |
+| `configuration issue` | Problem caused by user config |
+| `livestream` | Camera livestream, video feed, P2P, RTSP, streaming failures |
+| `question` | Further information is requested |
+| `resolved in beta` | Fix already in current beta |
+| `needs triage` | New issue awaiting initial analysis |
+| `duplicate` | Issue or PR already exists |
+| `hoobs` | HOOBS-specific -- label as `hoobs` + `wontfix` and close |

package/.claude/PRD.md

@@ -0,0 +1,241 @@
+# PRD -- homebridge-eufy-security
+
+Product Requirements Document for `@homebridge-plugins/homebridge-eufy-security`.
+
+## Purpose
+
+Expose Eufy Security devices to Apple HomeKit via Homebridge. Users control cameras, doorbells, locks, sensors, base stations, and delivery boxes from the Home app -- including live video, HomeKit Secure Video recording, arm/disarm, and two-way audio.
+
+## Target Users
+
+Homebridge users with Eufy Security hardware who want native HomeKit integration without Eufy's official HomeKit firmware (limited or unavailable for most devices).
+
+## System Requirements
+
+| Requirement | Value |
+|---|---|
+| Node.js | 20, 22, or 24 |
+| Homebridge | >=1.9.0 or ^2.0.0-beta |
+| Eufy Account | Dedicated guest account (admin accounts blocked) |
+| FFmpeg | Bundled via `ffmpeg-for-homebridge` |
+
+---
+
+## Functional Requirements
+
+### FR-1: Device Discovery & Registration
+
+- Connect to Eufy cloud via `eufy-security-client` (cloud API, P2P, push notifications, MQTT)
+- Discover stations and devices automatically on plugin startup
+- Batch device processing with 10-second debounce to avoid thrashing during sync
+- Hot-add/remove devices after initial discovery completes
+- Restore cached accessories across Homebridge restarts
+- Prune stale cached accessories when `cleanCache: true`
+- Devices can stack multiple capabilities (camera + motion sensor + doorbell) via independent registration blocks
+
+### FR-2: Camera Streaming
+
+#### FR-2.1: Live Streaming
+- P2P direct stream (default, low latency)
+- RTSP stream (opt-in per camera)
+- FFmpeg transcoding to H.264 + AAC-ELD with SRTP encryption
+- Hardware encoder detection: VideoToolbox (macOS), V4L2 (Raspberry Pi), VAAPI/QSV (Linux)
+- Fallback to libx264 software encoding
+- Configurable max resolution, bitrate, frame rate
+- Max concurrent streams per camera (default 2)
+- Configurable livestream duration (default 30s, max 86400s)
+- RTCP keep-alive monitoring with inactivity timeout
+
+#### FR-2.2: HomeKit Secure Video (HKSV)
+- Record motion/doorbell events as fMP4 fragments
+- 4-second segment length (HomeKit requirement)
+- 8-second timeshift buffer for pre-motion capture
+- Audio recording (AAC-ELD or AAC-LC per HomeKit config)
+- Snapshot capture during active recording
+- Max 3 segment errors before connection reset
+
+#### FR-2.3: Snapshots
+- Four handling modes: AlwaysFresh, Balanced, CloudOnly (default), Auto
+- Intelligent caching with configurable thresholds (fresh: 15s, balanced: 30s)
+- Placeholder images for offline/disabled/unavailable states
+- Cloud snapshot skip within 30s of livestream capture (prevents quality degradation)
+
+#### FR-2.4: Two-Way Audio (Talkback)
+- Bidirectional audio via duplex stream
+- Caches audio data until device is ready
+- 2-second silence auto-stop
+- Configurable channel count (mono default)
+
+### FR-3: Security System (Stations)
+
+- Map Eufy guard modes to HomeKit security states (Stay, Away, Night, Off)
+- Per-station guard mode mapping (configurable numeric mode values)
+- Manual alarm trigger with configurable duration and HomeKit mode filter
+- Alarm arm delay and alarm event handling via push notifications
+- Multi-station sync via virtual AutoSyncStationAccessory (opt-in)
+
+### FR-4: Locks
+
+- Lock/unlock control via HomeKit LockMechanism service
+- Lock jammed state detection via push notifications
+- Lock management service (auto-security timeout, admin-only access)
+
+### FR-5: Sensors
+
+#### FR-5.1: Motion Sensors
+- Standalone motion detection service
+- Camera-integrated motion with configurable timeout
+- Multi-event support: person, pet, vehicle, sound, crying, dog, stranger
+
+#### FR-5.2: Entry Sensors (Contact Sensors)
+- Door/window open/closed state
+
+### FR-6: Doorbells
+
+- ProgrammableSwitchEvent on ring
+- Optional motion-triggers-doorbell mode
+- Optional indoor chime control switch
+- Snapshot delay on doorbell ring (configurable)
+
+### FR-7: Floodlights
+
+- Lightbulb service for floodlight control
+- Combined camera + light capabilities
+
+### FR-8: Smart Drop (Package Boxes)
+
+- One-way open via LockMechanism
+- Package delivery detection via ContactSensor
+
+### FR-9: Per-Device Switches
+
+- Enable/disable device switch
+- Motion detection toggle switch
+- Light control switch (floodlights)
+- Indoor chime toggle switch
+- All switches individually configurable per camera
+
+---
+
+## Configuration Requirements
+
+### CR-1: Global Configuration
+- Eufy credentials (username, password, device name)
+- Country code (ISO 3166-1 alpha-2)
+- Polling interval (default 10 minutes)
+- Global guard mode mapping (hkHome, hkAway, hkNight, hkOff)
+- Device/station ignore lists by serial number
+- Debug logging toggle (`enableDetailedLogging`)
+- Log file opt-out (`omitLogFiles`)
+- Cache cleanup toggle (`cleanCache`, default true)
+- Auto-sync station mode toggle
+- Embedded PKCS1 support toggle (Node.js <24.5 workaround)
+
+### CR-2: Per-Camera Configuration
+- Stream source: P2P or RTSP
+- Enable/disable camera streaming entirely
+- Snapshot handling method (AlwaysFresh, Balanced, CloudOnly, Auto)
+- Audio enable/disable
+- Talkback enable/disable with channel count
+- HKSV recording duration
+- Motion timeout
+- Per-switch visibility (enable, motion, light, indoor chime)
+- Full FFmpeg video config override (codec, resolution, bitrate, filters, encoder options, custom binary path)
+
+### CR-3: Per-Station Configuration
+- Guard mode mapping overrides (hkHome, hkAway, hkNight, hkOff)
+- Manual alarm trigger modes and duration
+
+---
+
+## Plugin UI Requirements
+
+### UI-1: Device Discovery
+- Login flow with TFA and captcha support
+- Discovery progress reporting (authenticating, queuing, processing, done)
+- Skip button for unsupported device intel wait
+- Admin account detection and blocking
+
+### UI-2: Device Management
+- Display discovered stations and devices with type, capabilities, power status
+- Show unsupported devices separately
+- Detect running plugin via heartbeat (accessories.json `storedAt` < 90s old)
+- Load stored accessories from cache when plugin is not running
+
+### UI-3: Diagnostics
+- Generate encrypted diagnostics archive (RSA-4096 + AES-256-GCM)
+- Rate-limited to 60-second minimum between downloads
+- Archive includes: config (sanitized), all log files, accessories.json, system info
+- Decryptable via `node scripts/decrypt-diagnostics.mjs`
+
+### UI-4: Storage Management
+- Reset plugin storage (persistent.json, accessories.json)
+- Clean all storage option
+- System info endpoint (plugin version, Node.js version, host OS)
+
+---
+
+## Non-Functional Requirements
+
+### NFR-1: Logging
+- Rotating file streams (daily rotation, max 3 archives, 200MB limit)
+- Styled console output (color-coded by level)
+- Debug mode adds file:line references and library-level logging
+- Separate log streams: plugin, library, UI server, UI library, FFmpeg (global + per-camera + snapshots)
+
+### NFR-2: Reliability
+- Connection retry (3 attempts, 30s backoff) on Eufy cloud failure
+- P2P stream retry with exponential backoff (2-10s, max 3 attempts, 15s timeout per attempt)
+- Multi-consumer stream sharing via reference counting (streaming, recording, snapshots share one P2P connection)
+- 5-second grace period before stopping shared P2P stream
+- Node.js MaxListeners raised to 30 for multi-camera setups
+- fMP4 box validation (max 50MB per box) during HKSV recording
+
+### NFR-3: Compatibility
+- ESM module (`"type": "module"`, `"module": "NodeNext"`)
+- TypeScript strict mode, ES2022 target
+- PKCS1 padding workaround for Node.js 20/22 (restored natively in Node.js 24.5+)
+- Hardware codec probing at startup with graceful software fallback
+
+### NFR-4: Security
+- Encrypted credential persistence (never logged)
+- Guest account enforcement (admin account usage blocked)
+- TFA/captcha graceful handling with shutdown and re-auth prompt
+- Diagnostics archives encrypted before export
+
+---
+
+## Architecture Boundaries
+
+### homebridge-eufy-security (this plugin)
+- Accessory registration and HomeKit service mapping
+- FFmpeg transcoding pipeline
+- Configuration handling and validation
+- Plugin UI (device discovery, diagnostics, storage management)
+- accessories.json persistence for UI communication
+
+### eufy-security-client (upstream dependency)
+- Eufy cloud API authentication and communication
+- P2P connection establishment and stream management
+- Push notification and MQTT event handling
+- Device type classification and property management
+- Command execution (arm/disarm, lock/unlock, etc.)
+
+Issues must be triaged to the correct layer. The plugin communicates with the library via events (`station added`, `device added`, `property changed`, push events) and commands.
+
+---
+
+## Device Type Coverage
+
+| Category | HomeKit Services |
+|---|---|
+| Cameras | CameraRTPStreamManagement, MotionSensor, optional Switches |
+| Doorbells | Doorbell + Camera services, ProgrammableSwitchEvent |
+| Floodlights | Camera + Lightbulb services |
+| Base Stations | SecuritySystem (arm/disarm), optional manual alarm Switch |
+| Smart Locks | LockMechanism, LockManagement |
+| Entry Sensors | ContactSensor |
+| Motion Sensors | MotionSensor |
+| Smart Drop | LockMechanism (open-only), ContactSensor (package detect) |
+| Video Locks | Camera + Lock services (LockWifiVideo) |
+| Auto-Sync Station | Virtual SecuritySystem syncing multiple stations |

package/.claude/docs/debug-recording-lessons.md

@@ -0,0 +1,91 @@
+# Debug Recording Pipeline — Lessons Learned (PRs #888–#894, 2026-03-26)
+
+Six PRs in one day to fix a feature that should have landed in one or two. Root causes were not understanding the FFmpeg process architecture, fixing symptoms instead of root causes, and not testing against real hardware before merging.
+
+## 1. Understand the P2P FFmpeg process architecture BEFORE touching it
+
+P2P cameras use SEPARATE FFmpeg processes for video and audio. The video process has only one input (raw H264 via TCP). There is no `input 1` for audio. Any `-map 1:a` on the video process will fail silently or crash.
+
+**Rule**: Before adding FFmpeg arguments, trace the FULL command that gets spawned. Check `ffmpeg-<serial>.log` in diagnostics. Verify what each input index maps to.
+
+**Why**: PRs #888, #890, #891 all tried to add audio to the video process file tee — impossible by architecture. Three PRs wasted.
+
+**How to apply**: When modifying `getCombinedArguments()` or `buildRawMuxArgs()`, always log or mentally construct the full FFmpeg command and verify each `-i` and `-map` index.
+
+## 2. Homebridge plugin UI runs in an iframe with strict CSP
+
+Homebridge enforces `frame-src 'self' data: https://developers.homebridge.io`. This means:
+- `data:` URIs work for downloads
+- `blob:` URLs are BLOCKED
+
+**Rule**: Never use `URL.createObjectURL()` / `blob:` for downloads in the plugin UI. Use the same `btoa()` + `data:` URI pattern as diagnostics download.
+
+**Why**: PR #893 switched to Blob URLs for "memory efficiency", immediately broke downloads. Had to revert.
+
+**How to apply**: When writing download logic in `homebridge-ui/`, copy the pattern from `diagnostics.js` `_downloadDiagnostics()`. Check CSP before changing.
+
+## 3. Destroy PassThrough forks when their consumer dies
+
+When piping a source stream to multiple PassThrough forks via `.pipe()`, if ANY fork's consumer dies (e.g., FFmpeg crashes) and the fork is not destroyed, it fills its internal buffer (16KB default) and applies permanent backpressure on the source — starving ALL other consumers.
+
+**Rule**: Always destroy PassThrough forks when their downstream consumer exits. Store references and destroy in cleanup handlers.
+
+**Why**: PR #888 created forks without cleanup. The bug was masked by 4MB highWaterMark in #890, exposed when removed in #891, finally fixed in #893.
+
+**How to apply**: Any time you create a `new PassThrough()` and pipe a shared source into it, ensure the fork is destroyed when its consumer (FFmpeg, socket, etc.) exits. Use both socket `close` handler AND session cleanup as belt-and-suspenders.
+
+## 4. FFmpeg ignores stdin when reading from TCP
+
+When FFmpeg reads input from a TCP socket (`-i tcp://...`), it is blocked in the socket read loop and does NOT monitor stdin. Writing `'q'` or `'q\n'` to stdin has no effect. The process will never exit gracefully via stdin.
+
+**Rule**: To stop FFmpeg reading from TCP, destroy the TCP socket. FFmpeg detects EOF and exits cleanly, finalizing the container.
+
+**Why**: PR #888 used `stdin.write('q')`, #893 added newline, neither worked. FFmpeg was always SIGKILL'd after timeout. PR #894 fixed it by destroying the socket.
+
+**How to apply**: In `stopSessionBySerial()`, destroy `session.videoSocket` and `session.audioSocket` instead of writing to stdin.
+
+## 5. P2P data is inherently bursty — never use wallclock timestamps
+
+`-use_wallclock_as_timestamps 1` assigns PTS based on when FFmpeg receives each frame. P2P delivers data in bursts at every level: initial buffer dump, ongoing video chunks (~1.3s gaps between bursts), and audio (entire ADTS batch arrives in one TCP write). Wallclock faithfully records these arrival times, producing choppy video and crushed audio (25s of audio crammed into 2ms of timestamps).
+
+Deferred piping (PR #891) only prevents the initial buffer dump. It does NOT make ongoing P2P delivery real-time.
+
+**Rule**: Never use `-use_wallclock_as_timestamps` for P2P recordings. Use `-fflags +genpts -r <fps>` for video (generates smooth PTS from declared framerate) and `-fflags +genpts` for audio (generates PTS from sample rate). The FPS comes from `metadata.videoFPS`.
+
+**Why**: PR #888 used wallclock -> burst -> 0.07s. PR #894 used wallclock + deferred piping -> choppy video (1.3s frame gaps) and silent audio (all timestamps within 2ms). PR #897 uses genpts + fps from metadata.
+
+**How to apply**: In `buildRawMuxArgs()`, use `-fflags +genpts -r <fps>` before each input. Deferred piping in `LocalLivestreamManager.onStationLivestreamStart` is still needed to prevent the initial buffer burst from skewing the generated PTS.
+
+## 6. The processed file tee copies raw INPUT, not encoded OUTPUT
+
+In FFmpeg multi-output, `-map 0:v -c:v copy` on a second output copies from INPUT 0 (raw P2P), not the encoded output of the first output. To capture the encoded stream, you'd need the `tee` muxer (blocked by SRTP params) or double encoding (wasteful).
+
+**Rule**: Don't use the file tee to capture "what HomeKit sees". It captures the raw P2P feed. For P2P cameras, use DebugRecordingManager instead (captures both video+audio). Keep the file tee only for RTSP cameras where DebugRecordingManager doesn't apply.
+
+**Why**: PRs #888-#891 assumed the file tee captured the encoded stream. It never did.
+
+## 7. HomeKit probes streams with a stop/restart cycle
+
+HomeKit sends startStream -> runs for 2-3s -> sends stopStream -> waits -> sends startStream again. This is normal probe behavior. If the file recording uses the P2P sessionId (which persists across HomeKit sessions), the second start overwrites the first file.
+
+**Rule**: For any per-HomeKit-session file recording, use `request.sessionID` (HomeKit's session ID), not the P2P livestream sessionId.
+
+**How to apply**: Relevant if the RTSP file tee is ever extended. Currently moot for P2P since the file tee was removed.
+
+## 8. Test against real hardware before merging
+
+Every PR #888-#893 was merged and found broken on the next beta. A single 15-second test (enable debug livestream -> stream camera -> check recording) would have caught most issues immediately.
+
+**Rule**: Before merging debug recording changes, the test plan MUST actually be executed. At minimum: enable feature, stream for 15s, ffprobe the output, check eufy-security.log for errors.
+
+**Why**: The ADTS crash (FFmpeg exit 255) was visible in the very first test. The 0.07s duration was visible in the first ffprobe. Six PRs could have been two.
+
+## 9. Fragmented MP4 breaks VLC and QuickTime
+
+`-movflags frag_keyframe+empty_moov` writes fragmented MP4 (fMP4) — designed for live streaming, not file playback. VLC shows ~1s of content then stops. QuickTime can't play it at all.
+
+**Rule**: Use `-movflags +faststart` for debug recordings written to disk. Standard MP4 with moov relocated to the start is universally playable.
+
+**Why**: PR #897 used fMP4 for crash resilience (already-written fragments survive SIGKILL). But graceful shutdown via socket destroy (lesson #4) makes this unnecessary. PR #898 switched to faststart.
+
+**How to apply**: Only use `frag_keyframe+empty_moov` when streaming to a non-seekable output (e.g., HTTP). For file output, always use `+faststart`.

package/.claude/docs/hksv-recording-fix.md

@@ -0,0 +1,160 @@
+# HKSV Recording Reliability Fix
+
+**PR:** [#878](https://github.com/homebridge-plugins/homebridge-eufy-security/pull/878)
+**Branch:** `fix/hksv-recording-reliability`
+**Affects:** All cameras with HomeKit Secure Video enabled
+
+---
+
+## Problem
+
+HKSV recordings never appeared in the Apple Home timeline. Users could enable HKSV in Apple Home settings, but no recordings were captured on motion events. Two independent issues combined to make HKSV completely non-functional.
+
+## Root Cause 1: HKSV state lost on every restart
+
+### How HKSV state persistence works
+
+When a user enables HKSV for a camera in Apple Home:
+
+1. HomeKit sets the `Active` characteristic to `true` on the `CameraRecordingManagement` service
+2. HAP-NodeJS stores this in two places:
+   - The `cachedAccessories` JSON (service characteristic values)
+   - The `ControllerStorage` file (controller-specific state)
+3. On next boot, `CameraController._initWithServices()` restores services from cache
+4. `ControllerStorage.restoreController()` calls `deserialize()` to restore `recordingActive`
+
+### What was broken
+
+`CameraAccessory.configureVideoStream()` removed two controller-managed services (`CameraOperatingMode` and `DataStreamTransportManagement`) from the cached accessory before calling `configureController()`. This was added to prevent a "duplicate UUID error".
+
+However, this broke the restoration flow:
+
+```
+HAP-NodeJS CameraController._initWithServices():
+
+  IF all 3 services found in cache:
+    → Reuse cached services (preserves Active state) ✓
+
+  ELSE (any service missing):
+    → Create NEW services with Active=false ✗
+```
+
+By removing 2 of the 3 services, every restart forced the `ELSE` path, resetting `recordingActive` to `false`. HomeKit set `Active=true` once, but it was lost on every boot.
+
+### The fix
+
+Removed the stale service removal code entirely. HAP-NodeJS's `_initWithServices()` already handles service reuse through its `serializedControllers` path — the "duplicate UUID error" it was designed to prevent doesn't occur when services are properly managed by the controller.
+
+## Root Cause 2: P2P cold-start delay
+
+### The timing problem
+
+When HomeKit requests an HKSV recording after motion detection, the recording delegate must:
+
+1. Establish a P2P connection to the camera (`getLocalLiveStream()`)
+2. Start FFmpeg to transcode the stream
+3. Begin yielding fMP4 fragments to HomeKit
+
+Step 1 takes **~4.8 seconds** (observed in diagnostics). HomeKit has an approximate **5-second timeout** for the first data. This means recordings frequently failed to start in time.
+
+### How reference implementations solve this
+
+| Plugin | Approach | Prebuffer Duration |
+|--------|----------|--------------------|
+| homebridge-unifi-protect | Always-on RTSP timeshift buffer | Configurable |
+| Scrypted | Ring buffer, 2.5x HomeKit's prebufferLength | 10s default |
+| homebridge-camera-ui | Always-on prebuffer | 4s |
+
+All use prebuffering. For battery-powered Eufy cameras, always-on prebuffering is not viable.
+
+### The fix: motion-triggered P2P pre-warming
+
+When the plugin detects motion (before HomeKit even requests a recording), it proactively starts the P2P connection:
+
+```
+Motion Detected → Plugin sets MotionDetected=true on characteristic
+                → Plugin calls preWarmStream() (P2P starts in background)
+                → HomeKit receives motion notification
+                → HomeKit sends DATA_SEND OPEN → handleRecordingStreamRequest()
+                → getLocalLiveStream() returns instantly (P2P already warm)
+```
+
+A new `preWarmStream()` method on `LocalLivestreamManager` starts the P2P connection without creating a consumer fork. The stream auto-cleans up after the `STOP_GRACE_MS` (5 seconds) grace period if HomeKit doesn't request a recording.
+
+RTSP cameras are excluded from pre-warming since their stream URL is immediately available.
+
+## Additional fix: updateRecordingActive log bug
+
+`recordingDelegate.ts` line 282 had swapped log arguments:
+
+```typescript
+// Before (wrong — message as camera name, camera name as message):
+log.debug(`Recording: ${active}`, this.accessory.displayName);
+
+// After (correct):
+log.info(this.camera.getName(), `HKSV recording enabled/disabled by HomeKit.`);
+```
+
+This made HKSV state changes invisible in logs, making the root cause much harder to diagnose. Promoted to INFO level since this is a critical diagnostic signal.
+
+## HKSV Recording Flow (Architecture Reference)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     eufy-security-client                     │
+│  Device emits 'motion detected' / 'person detected' / etc.  │
+└──────────────────────────┬──────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    CameraAccessory.ts                         │
+│  1. characteristic.updateValue(true)  → HomeKit notified     │
+│  2. preWarmStream()                   → P2P starts warming   │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+              ┌────────────┴────────────┐
+              │                         │
+              ▼                         ▼
+┌──────────────────────┐   ┌─────────────────────────────────┐
+│  LocalLivestream     │   │  HAP-NodeJS RecordingManagement  │
+│  Manager.ts          │   │                                   │
+│  P2P connecting...   │   │  HomeKit receives MotionDetected  │
+│  Stream warming...   │   │  HomeKit decides to record        │
+│  ✓ Stream ready     │   │  DATA_SEND OPEN →                 │
+└──────────┬───────────┘   └───────────────┬───────────────────┘
+           │                               │
+           │                               ▼
+           │               ┌───────────────────────────────────┐
+           │               │  recordingDelegate.ts              │
+           │               │  handleRecordingStreamRequest()    │
+           └──────────────►│  configureInputSource()            │
+             P2P already   │    → getLocalLiveStream() instant  │
+             warm!         │  FFmpeg starts                     │
+                           │  yield fMP4 fragments → HomeKit    │
+                           └───────────────────────────────────┘
+```
+
+## Files Changed
+
+| File | Change |
+|------|--------|
+| `src/accessories/CameraAccessory.ts` | Removed stale service removal; added motion-triggered pre-warming |
+| `src/controller/LocalLivestreamManager.ts` | Added `preWarmStream()` method; updated `isStreamActive()` |
+| `src/controller/recordingDelegate.ts` | Fixed `updateRecordingActive` log arguments |
+
+## User Impact
+
+### After upgrading
+
+Users who had HKSV enabled but never saw recordings should see them start working. Some users may need to:
+
+1. Restart Homebridge after the upgrade
+2. If recordings still don't appear, toggle HKSV off and on in Apple Home:
+   - Open Home app → Camera settings → Recording Options → Disable → Re-enable
+
+### Battery considerations
+
+The P2P pre-warming starts a livestream connection on every motion event. For battery-powered cameras:
+- The stream only runs for 5 seconds if HomeKit doesn't request a recording
+- This is similar to what already happens for snapshot fetching on motion
+- Impact on battery life should be minimal but is worth monitoring