@chrisalvir1/camera-ui-homekit-4k 0.0.0-stage → 0.6.15

package/CHANGELOG.md

@@ -0,0 +1,152 @@
+# Changelog
+
+## [0.6.15] — Camera.UI platform install targets
+
+- Declare macOS, Windows, and Linux on x64 and ARM64 as npm install targets,
+  matching Camera.UI's supported server platforms. Runtime testing remains
+  verified on macOS ARM64 only; the other targets require host-specific checks.
+- Keep the official logo in the published bundle and assert the install target
+  matrix and package version in the bundle smoke test.
+- Publish the Camera.UI-generated `bundle/` artifact rather than the source
+  repository root. This removes source-only runtime dependencies from the npm
+  install path and ships the `cameraui` metadata, `bundle.zip`, and logo that
+  Camera.UI consumes.
+- Embed the pinned HAP runtime and its complete production dependency tree in
+  `bundle.zip`. Camera.UI therefore performs no dependency download after
+  extracting the npm package, avoiding installation failures caused by a
+  user-owned npm cache with incorrect permissions.
+
+## [0.6.14] — npm account scope correction
+
+- Rename the public package from `@chrisalvir/camera-ui-homekit-4k` to
+  `@chrisalvir1/camera-ui-homekit-4k` so its scope matches the authenticated npm
+  username. Update local bundle validation, Camera.UI's development registry,
+  and bundle smoke checks to use the same identity. No camera runtime behavior
+  changed.
+
+## [0.6.13] — public package preparation
+
+- Correct the public README to describe the 0.6.12 runtime evidence and its
+  limits instead of the obsolete 0.4.0 phase status.
+- Narrow the npm package allowlist to compiled runtime files, required HAP
+  runtime files, documentation, and the official logo. This removes stale
+  compiler copies, source maps, and nested binary shims from the release
+  tarball. No media, detection, pairing, or camera runtime behavior changed.
+- Add owner-selected proprietary use terms and public-release metadata. No media,
+  detection, pairing, or camera runtime behavior changed.
+
+## [0.6.12]
+
+- Keep very brief visual events asserted for at least one second so a same-tick SDK start/end cannot collapse into a missed HomeKit notification. Long detections still follow the SDK lifecycle; pending release is canceled on renewed motion and disposed on unpublish. Applies to both H.264 and HEVC exports.
+
+## [0.6.11]
+
+- Preserve Camera.UI motion/object events until their actual SDK end; remove the artificial 15-second motion reset that interrupted long detections for both H.264/HKSV and HEVC/HKSV3. Log HomeKit motion transitions per camera without retaining images or identities.
+- Keep HAP dependencies at the package root so Camera.UI extraction cannot remove them after dependency installation. Bundle smoke now imports the extracted HAP runtime rather than the workspace copy.
+
+## [0.6.10]
+
+- Accept valid legacy HomeKit live requests up to 1080p without rejecting an existing paired controller solely for a different requested resolution. The selected measured-source policy still determines actual video output: native passthrough up to 1080p and 1080p conversion above it. Logs distinguish requested and actual output dimensions.
+
+## [0.6.9]
+
+- H.264 live and HKSV use measured source dimensions: video up to 1920×1080 is passed through; larger sources use a verified H.264 encoder at 1920×1080. Existing negotiated audio routes are retained.
+- Shared Camera.UI detection bridge accepts visual object labels such as car, truck, dog and cat from assigned detectors, including future camera exports. Aggregate event end always releases motion even when closing metadata is empty.
+- HEVC/HKSV3 recording audio receives its persistent one-time first-export default after HAP restores state. Later HomeKit audio choices are retained.
+- HEVC video/audio transport, its recording implementation and pairing identities are preserved. A worker reload briefly interrupts every accessory served by that worker.
+
+## [0.6.8]
+
+- **Camera.UI bundle updates:** The loopback update registry now serves the official `cui bundle` package, including its `bundle.zip`. Camera.UI extracts that bundle into the worker runtime after installation; a source-only package archive could update package metadata while leaving the old runtime code active.
+
+## [0.6.7]
+
+- **Reliable Camera.UI self-updates:** Moved the scoped package registry to a detached loopback daemon with a storage-backed package snapshot and worker lease. Camera.UI can now stop the plugin worker before fetching its replacement without taking down the package endpoint; the daemon exits after the worker has been absent for five minutes.
+- **Fail closed on invalid packages:** Removed the fake 29-byte gzip fallback. The registry refuses to advertise an update unless it can create or verify a real package archive and matching SHA-1/SHA-512 integrity values.
+
+## [0.6.6]
+
+- **Simplified Camera.UI Admin:** Removed redundant global administration, diagnostic-mode, GitHub-updater, and HomeKit-camera tabs; pairing and unlink controls remain with each camera.
+- **Camera.UI-native updates:** Removed the duplicate in-plugin GitHub update flow so plugin updates are managed by Camera.UI.
+- **Removed unused audio settings UI:** Deleted the unconnected audio settings form while retaining the existing audio engines and runtime diagnostics.
+
+## [0.6.5]
+
+- **Camera.UI Backchannel Discovery:** Explicitly probes each exported Camera.UI source for microphone/backchannel support before constructing HAP services. H.264 and HEVC/HKSV3 expose HomeKit talkback only when the selected source reports a supported codec and does not disable backchannel; accessory service updates preserve existing pairing.
+
+## [0.6.3]
+
+- **Universal HEVC & HKSV3 Configuration Parity (IPCAM IPC Blueprint):** All Vimtag cameras (SALA, OFICINA, JARDIN, COCHERA, AREA DE CAFE, RECAMARA) and any newly added HEVC cameras automatically adopt the exact configuration established on IPCAM IPC. Automatically assigns `@chrisalvir/camera-ui-homekit-4k`, `@camera.ui/camera-ui-coreml`, and `@camera.ui/camera-ui-opencv` for full motion, object, face, person, and clip detection.
+- **Go2RTC Stream Preload & Elimination of Audio Teardown Collision:** Configured persistent Go2RTC stream preloading (`preload: audio=&video=`) and disabled RTSP backchannel handshakes (`backchannelDisabled: true`, `#backchannel=0#noBackchannel`) on Vimtag cloud relay sources, preventing WAN timeout disconnects (`i/o timeout`) and resolving Go2RTC's `error="start from CONN state"`.
+- **RTSP Direct Resolution Fallback for Multiplexed Sources:** Refined `resolveDirectCameraRtspUrl` to strictly return direct URLs only for verified private LAN IP addresses (`192.168.x.x`, `10.x.x.x`, `172.16-31.x.x`). For cloud and plugin cameras, gracefully falls back to Camera.UI multiplexed endpoints with proper query parameters (`?video&audio`), guaranteeing that FFmpeg HDS recordings generate complete `moov` initialization segments containing both video and AAC-LC audio tracks.
+- **Auto-Provisioning on Camera Addition (`CameraAutoConfig`):** Added automated configuration synchronization upon camera addition (`onCameraAdded`) and startup (`configureCameras`). Newly added HEVC cameras immediately receive HKSV3 configuration, continuous recording settings, and automatic HomeKit export without manual intervention.
+- **Permanent H.264 & Tapo Isolation:** Kept Tapo and all existing H.264 logic strictly untouched (`src/h264/*` unchanged); future H.264 cameras automatically inherit Tapo's standard H.264 configuration.
+- **FirmwareRevision Update:** Incremented firmware revision to `0.6.3`.
+
+## [0.6.2]
+
+- **Third-Party & Plugin Camera RTSP Direct Resolution Fallback:** Added local go2rtc RTSP endpoint fallback (`rtsp://127.0.0.1:2101/${streamName}`) for cameras integrated via third-party device plugins (e.g., Vimtag) that do not expose external ONVIF RTSP URLs or use `cui://` internal protocols. Eliminates FFmpeg `Protocol not found` exit crashes, restoring continuous live audio and HKSV recordings.
+- **Automatic Frame Worker Activation for Plugin Cameras:** Added proactive RPC connection (`camera.${id}.controller.rpc.connect()`) within `CameraUiAdapter` upon camera attachment. Ensures Camera.UI Frame Workers start automatically when plugin cameras initialize with `connected: false`, enabling instant OpenCV and CoreML motion/person detection.
+- **Dynamic Sensor Assignment Lifecycle Synchronization:** Implemented `onSensorsChanged` hook and notification pipeline in `CameraUiAdapter` to dynamically re-bind motion and occupancy sensors when sensors are attached or reassigned in Camera.UI without requiring a full plugin restart.
+- **Robust Motion Event Keying:** Provided timestamped fallback keys (`evt-${type}-${timestamp}`) for un-keyed detection triggers from OpenCV and CoreML trackers, ensuring reliable HomeKit `MotionDetected` assertions and event clearance.
+- **Dynamic FirmwareRevision Alignment:** Updated accessory creation to dynamically bind `FirmwareRevision` to `buildInfo.packageVersion` (`0.6.2`) across both H.264 and HEVC camera accessories.
+- **Permanent H.264 & HEVC Pipeline Isolation:** Strictly preserved the classic H.264 pipeline (Tapo and all future H.264 additions) with zero changes to `src/h264/*`, while extending HEVC HKSV3 enhancements universally to all current and future HEVC cameras.
+
+## [0.6.1]
+
+- **Automatic Camera Export & Removal of Manual Button:** Cameras assigned to the HOMEKIT 4K plugin are now automatically exported to Apple Home upon activation alongside other plugins (CoreML, OpenCV), eliminating the need for manual button clicks. Removed the redundant «Exportar esta cámara» button from the UI. Pre-warmed pairing QR generation renders the branded setup QR code and manual PIN immediately when entering the pairing section.
+- **HEVC HKSV3 Audio Clock Synchronization (16 kHz):** Scaled Opus RTP timestamps by $16\text{k} / 48\text{k}$ (320 ticks per 20ms frame) to match HomeKit's negotiated 16 kHz audio sample rate (`sampleRate: 1`), eliminating the 3x timestamp forward surge and completely resolving the cyclic 1-second audio / mute stutter.
+- **Parasitic Microphone Whine & Artifact Elimination:** Implemented a specialized Butterworth 2-pole bandpass filter (`highpass=f=150:poles=2,lowpass=f=3500:poles=2`), FFT adaptive noise reduction (`afftdn=nf=-40`), clean gain boost, and switched Opus encoding to `-application voip -b:a 48k -vbr off`, completely eliminating the 6.28 kHz hardware whistle, background cricket buzz, and metallic CELT ringing across all HEVC live streams and recordings.
+- **Independent Audio Jitter Buffer Operation:** Omitted periodic audio RTCP Sender Reports in HKSV3 Multi-Tier RTP so HomeKit plays live audio continuously without inter-stream clock clashes against video.
+- **Universal Multi-Camera Motion Detection:** Preserved unified event processing across Camera.UI plugins, OpenCV, CoreML, and YOLO with edge-trigger dwell safety timers to guarantee reliable successive HKSV recordings for all cameras.
+- **FirmwareRevision Update:** Bumped accessory firmware revision to `0.6.1` across all H.264 and H.265 camera accessories.
+
+## [0.6.0]
+
+- **Live H.264 Audio Engine (Opus + Genuine AAC-ELD):** Resolved silence in Apple Home live streams by implementing dual-engine routing: in-memory zero-latency Opus transcoding via `node-av` with 20ms frame pacing, and real-time AAC-ELD (480 samples/frame) transcoding via FFmpeg `libfdk_aac`.
+- **HomeKit Cache Invalidation:** Bumped accessory `FirmwareRevision` to `0.6.0` to force Apple Home clients to refresh their cached accessory profile and prioritize Opus streaming.
+- **Audio Clock Continuity Calibration:** Synchronized audio timeline continuity clocks with negotiated client sample rates (24kHz / 16kHz / 8kHz).
+- **Embedded Registry & UI Integration:** Updated local package manifests and registry endpoints to expose v0.6.0 and changelog directly within Camera.UI.
+
+## [0.5.9]
+
+- **Gapless stream handover on Wi-Fi reconfigure:** Connects the new FFmpeg live pipeline to Go2RTC before terminating the previous pipeline, eliminating RTSP socket teardown collisions (`read tcp: i/o timeout`) and resolving "Sin respuesta" when viewing on local Wi-Fi.
+- **Bitrate-only reconfigure skip:** Dynamically ignores reconfigure requests that only alter bitrate without changing resolution, avoiding unnecessary FFmpeg restarts.
+- **H.264 audio probe caching:** Caches RTSP audio probe results for 1 hour to prevent RTSP stream saturation during frequent motion and HKSV recording events.
+- **Embedded local registry integration:** Serves npm packuments and tarballs via loopback (`127.0.0.1:4873`), enabling seamless Camera.UI version discovery, one-click updates, and full changelog display.
+
+## [0.5.8]
+
+- **Hot stream reconfigure:** Dynamic resolution scaling and transition support for local Wi-Fi peer-to-peer HomeKit sessions.
+- **Resilient UDP track sockets:** Independent video/audio socket binding for bidirectional RTP and RTCP packets.
+
+## [0.5.6]
+
+- **Dynamic resolution scaling & MTU safety:** MTU-safe packet clamping and dynamic video profile scaling.
+- **Non-blocking audio probe:** Async probe execution with resilient fallback.
+
+## [0.5.5]
+
+- **Native 1080p enforcement for Tapo C402:** Fully removed any residual 2K (2304x1296) code assumptions; strictly enforce native 1080p (1920x1080) matching factory sensor specifications.
+
+## [0.5.0]
+
+- **HKSV classic H.264 recording:** Normalized H.264 recording pipeline with live AAC-LC 48kHz audio transcoding from PCMA/G.711a.
+
+## [0.4.0]
+
+- **HKSV3 preparation:** Integration foundations for HomeKit Secure Video and WebRTC RTP transport.
+
+## [0.3.0]
+
+- On-demand source inspection, conservative source selection and video-only plans.
+- Camera.UI source-to-output comparison and session lifecycle model.
+
+## [0.2.0]
+
+- SDK camera/sensor observables, idempotent subscriptions and neutral capability model.
+- Pinned local HAP compatibility build.
+
+## [0.1.0]
+
+- Phase 1 foundation: independent Camera.UI SDK entry and local bundle.

package/LICENSE.md

@@ -0,0 +1,21 @@
+HOMEKIT 4K PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2026 Chrisalvir. All rights reserved.
+
+Permission is granted to download, install, and run an unmodified copy of
+HOMEKIT 4K with Camera.UI for lawful personal or commercial use. This permission
+does not transfer ownership of the software.
+
+You may not modify, adapt, translate, or create derivative works from HOMEKIT
+4K. You may not redistribute, sublicense, republish, or sell copies of the
+software. Any permission beyond downloading, installing, and running an
+unmodified copy requires prior written permission from the copyright holder.
+
+The copyright notice and this license must accompany any permitted unmodified
+copy.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHOR OR COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY
+ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# HOMEKIT 4K — by Chrisalvir
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+![HOMEKIT 4K — by Chrisalvir](logo.png)
+
+HomeKit 4K exports cameras assigned to the plugin in Camera.UI as separate
+Apple Home accessories. Camera.UI remains the source of camera streams,
+capabilities, sensors, and detector configuration.
+
+**Next release prepared: 0.6.15 (not published).** Runtime behavior was
+validated on the developer MacBook with Camera.UI 2.3.0 using package 0.6.12.
+Version 0.6.14 fixed the npm scope to match the owner's npm account and did not
+change camera runtime behavior. Runtime evidence and limits are in
+[`docs/deployment-0.6.12.md`](docs/deployment-0.6.12.md).
+
+## Current behavior
+
+- H.264 sources at or below 1920×1080 are sent without video transcoding;
+  measured larger H.264 sources use a 1920×1080 output path. Audio is handled
+  separately according to HomeKit negotiation.
+- HEVC/H.265 uses its separate live and HKSV3 paths. HEVC recording and live
+  implementations are isolated from the H.264 resolution policy.
+- Camera.UI motion and visual detection events feed HomeKit's motion trigger for
+  both H.264/HKSV and HEVC/HKSV3 accessories. The bridge forwards observations;
+  it does not force-enable CoreML/OpenCV, bypass their zones or thresholds, or
+  dictate Apple's final People/Animals/Vehicles classification.
+- HomeKit recording choices and clip classification are controlled by the
+  paired Home Hub and the settings in Apple Home. A plugin event or HDS media
+  request alone does not prove that Apple saved a clip. In the latest real
+  validation, a Tapo vehicle event reached the bridge and caused a Home Hub
+  media request; saved vehicle/animal clips were not yet confirmed.
+- Pairing identities and per-camera persistent settings are stored by the
+  Camera.UI plugin runtime. Do not delete them when updating the package.
+
+## Requirements and installation
+
+The package declares Camera.UI >=2.3.0 and Node.js >=22.18.0. Starting with
+0.6.15, npm allows installation on macOS, Windows, and Linux on x64 or ARM64.
+The runtime has only been exercised on macOS ARM64; Windows, Linux, and macOS
+Intel still need real-host validation before they can be called verified.
+In Camera.UI's plugin store, search for the shorter text `camera-ui-homekit-4k`
+and select the scoped package `@chrisalvir1/camera-ui-homekit-4k`.
+
+## Development
+
+```sh
+pnpm install --frozen-lockfile
+pnpm check
+pnpm test:coverage
+pnpm bundle:camera-ui
+pnpm smoke:bundle
+```
+
+Automated checks and real-host evidence are different: test results do not
+replace playback, recording, or detection confirmation in Apple Home. See the
+validation documents under [`docs/`](docs/).
+
+## Public release status
+
+The package uses a proprietary license: users may download, install, and run an
+unmodified copy; modifying or redistributing it is not permitted without the
+author's written permission. Check npm for the first public release and use
+Camera.UI's supported plugin installer when the package becomes available
+there. See
+[`docs/npm-publication-readiness.md`](docs/npm-publication-readiness.md).

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@chrisalvir1/camera-ui-homekit-4k",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "displayName": "HOMEKIT 4K — by Chrisalvir",
+  "version": "0.6.15",
+  "description": "Exports Camera.UI cameras to Apple Home with H.264/HKSV and HEVC/HKSV3 streaming paths.",
+  "homepage": "https://github.com/Chrisalvir1/homekit-4k",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Chrisalvir1/homekit-4k.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Chrisalvir1/homekit-4k/issues"
+  },
+  "author": "Chrisalvir",
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "bundle.zip",
+    "CHANGELOG.md",
+    "logo.png"
+  ],
+  "engines": {
+    "node": ">=22.18.0",
+    "camera.ui": ">=2.3.0"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "arm64",
+    "x64"
+  ],
+  "scripts": {
+    "build": "node scripts/build-vendored-hap.mjs && node scripts/build.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.tests.json",
+    "lint": "eslint src tests scripts contract.ts cameraui.config.ts",
+    "test": "tsc -p tsconfig.tests.json && node --test .test-dist/tests/*.test.js",
+    "test:coverage": "tsc -p tsconfig.tests.json && node --experimental-test-coverage --test-coverage-include='**/.test-dist/src/**' --test-coverage-exclude='**/generated/**' --test .test-dist/tests/*.test.js",
+    "test:media": "pnpm build && node scripts/media-lab/test-controlled-transcode.mjs",
+    "test:fixture-determinism": "pnpm build && node scripts/media-lab/test-fixture-determinism.mjs",
+    "verify:phase3-evidence": "node scripts/media-lab/verify-phase3-evidence.mjs",
+    "collect:phase3-evidence": "node scripts/media-lab/collect-phase3-evidence.mjs",
+    "check": "pnpm build && pnpm typecheck && pnpm lint && pnpm test",
+    "smoke:bundle": "node scripts/smoke-bundle.mjs",
+    "examples": "pnpm build && node scripts/examples.mjs",
+    "bundle:camera-ui": "pnpm build && cui bundle && node scripts/finalize-camera-ui-bundle.mjs",
+    "publish:camera-ui": "pnpm bundle:camera-ui && npm publish ./bundle --access public --registry=https://registry.npmjs.org/",
+    "test:audio": "pnpm build && node scripts/audio-lab/test-audio.mjs"
+  },
+  "homekit4k": {
+    "releaseChannel": "stable"
+  },
+  "packageManager": "pnpm@11.25.0",
+  "keywords": [
+    "camera-ui-plugin",
+    "camera-ui",
+    "homekit"
+  ],
+  "cameraui": {
+    "protocolLevel": 2
+  }
+}