buzz-me-in 2.2.0-beta.0 → 2.2.0-beta.2

package/.env.example

@@ -55,6 +55,13 @@ TWILIO_MEDIA_PAYLOAD_MAX_BYTES=512
 TWILIO_UNLOCK_DIGITS=w9w
 # Grace period for SIGINT/SIGTERM graceful shutdown before forced exit.
 SHUTDOWN_GRACE_MS=10000
+# How long the Twilio call is held open after the HomeKit live view closes,
+# before the call is hung up. Backing out of the camera view to the room view
+# tears the stream down, and the lock tile there needs the call to still be up
+# to send its DTMF. Raise this if you find yourself reaching the lock too late;
+# the only cost is that much silence for the caller after you are done.
+# Tapping unlock restarts the window, so the digits are never cut short.
+HOMEKIT_HANGUP_GRACE_MS=3000
 
 # Logging
 # LOG_LEVEL controls minimum emitted level: debug | info | warn | error

package/README.md

@@ -86,7 +86,8 @@ The health endpoints are deliberately unauthenticated so systemd checks, uptime
 - Node.js >= 20
   - Runtime is tested on Node 20+.
   - Repo tooling/CI currently runs on Node 20, 22, and 24.
-- ffmpeg with libx264 and libopus: `sudo apt install ffmpeg`
+- ffmpeg >= 5.1 with libx264 and libopus: `sudo apt install ffmpeg`
+  - The 5.1 floor is the `-ch_layout` option used on the inbound audio pipeline. Debian 12 (bookworm) ships 5.1 and Raspberry Pi OS based on Debian 13 ships 7.1, so apt satisfies this on any currently supported release.
 
 ### Accounts and services
 
@@ -421,6 +422,8 @@ Tap the lock tile in the Home app → set to Unlocked.
 
 The lock tile resets to Secured automatically after 3 seconds.
 
+Two routes reach the lock tile, and they behave differently. The grid button at the bottom right of the camera view brings the lock up _beside_ the running stream, which is the smoother of the two. Backing out to the room view instead closes the camera view and tears the stream down; the lock tile is still there under **Other**, and it works because the call is held open for `HOMEKIT_HANGUP_GRACE_MS` after the view closes. Tapping unlock restarts that window, so the digits are never cut off mid-sequence.
+
 ---
 
 ### Stage 8 — Caller hangs up
@@ -445,10 +448,13 @@ Open the live view, then dismiss it on the iPhone (tap the X / end button).
 **Pass (server log):**
 
 ```text
+{"ts":"...","level":"info","message":"Hangup scheduled after grace period","component":"homekit","event":"hangup-scheduled","reason":"homekit-session-stopped","callSid":"CA...","sessionId":"...","graceMs":3000}
 {"ts":"...","level":"info","message":"Inbound ffmpeg exited","component":"homekit","event":"ffin-exit","reason":"nonzero-exit","exitCode":null,"sessionId":"..."}
 {"ts":"...","level":"info","message":"Hanging up call","component":"twilio-api","event":"hangup","callSid":"CA..."}
 ```
 
+The call is not hung up the instant the view closes. It is held open for `HOMEKIT_HANGUP_GRACE_MS` (default 3000) so the lock tile still has a call to send DTMF to, then hung up. Reopening the view inside that window logs `hangup-cancelled` instead and the call continues; if the caller hangs up first, the pending hangup logs `hangup-skipped` and does nothing.
+
 **Pass (Twilio):** The call shows as completed in the [Twilio Console call log](https://console.twilio.com/us1/monitor/logs/calls).
 
 ---

package/homekit.js

@@ -277,6 +277,9 @@ const streamingDelegate = {
 // ---------------------------------------------------------------------------
 
 function _startSession(sessionID, s, request, callback) {
+  // Reopening the live view inside the grace window means the user is not
+  // finished after all.
+  cancelPendingHangUp('homekit-session-restarted');
   const videoParams = srtpParams(s.hkVideoKey, s.hkVideoSalt);
   const audioParams = srtpParams(s.hkAudioKey, s.hkAudioSalt);
   const video = request.video;
@@ -291,6 +294,10 @@ function _startSession(sessionID, s, request, callback) {
   // Input 0  – raw mulaw/8kHz from Twilio via stdin
   //   Let the raw audio demuxer derive PTS from sample count. Using wall-clock
   //   timestamps breaks when ffmpeg drains the buffered startup audio burst.
+  //   -ch_layout declares mono rather than -ac counting one channel: a count
+  //   leaves the layout unset, so the decoder guesses it and logs "Guessed
+  //   Channel Layout: mono" on every call. Our stderr handler is a warn, so
+  //   that guess looked like a fault in the journal. Needs ffmpeg >= 5.1.
   //
   // Input 1  – synthetic black video (lavfi color source)
   //   Generates H.264 Baseline/3.1 frames at 15 fps.
@@ -313,8 +320,8 @@ function _startSession(sessionID, s, request, callback) {
     'mulaw',
     '-ar',
     '8000',
-    '-ac',
-    '1',
+    '-ch_layout',
+    'mono',
     '-i',
     'pipe:0',
 
@@ -553,13 +560,85 @@ function _stopSession(sessionID, hangUp) {
 
   const activeCall = getActiveCall();
   if (hangUp && activeCall) {
-    hangUpCall(activeCall.callSid)
+    scheduleHangUp(activeCall.callSid, sessionID);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Deferred hangup
+//
+// Closing the live view is not the same as being finished with the caller. The
+// Home app reaches the lock tile two different ways: the grid button inside the
+// camera view keeps the stream up, but backing out to the room view tears it
+// down, and tapping the lock from there used to find no call left to send DTMF
+// to. Holding the call open briefly after STOP makes both routes work, because
+// unlock needs the call's WebSocket, not a HomeKit streaming session.
+//
+// The call is still hung up when the user really has finished; it just costs
+// config.homekitHangupGraceMs of silence first, ffmpeg having already been
+// killed above.
+// ---------------------------------------------------------------------------
+
+const HANGUP_GRACE_MS = config.homekitHangupGraceMs;
+
+/** @type {{ timer: NodeJS.Timeout, callSid: string, sessionID: string } | null} */
+let pendingHangUp = null;
+
+function cancelPendingHangUp(reason) {
+  if (!pendingHangUp) return;
+  clearTimeout(pendingHangUp.timer);
+  logger.info('Pending hangup cancelled', {
+    event: 'hangup-cancelled',
+    reason,
+    callSid: pendingHangUp.callSid,
+    sessionId: pendingHangUp.sessionID,
+  });
+  pendingHangUp = null;
+}
+
+/**
+ * Restart the grace window, so a hangup cannot land on top of an action the
+ * user has just taken. Without this an unlock tapped late in the window could
+ * be cut off before the intercom acts on the digits.
+ */
+function deferPendingHangUp(reason) {
+  if (!pendingHangUp) return;
+  const { callSid, sessionID } = pendingHangUp;
+  clearTimeout(pendingHangUp.timer);
+  pendingHangUp = null;
+  scheduleHangUp(callSid, sessionID, reason);
+}
+
+function scheduleHangUp(callSid, sessionID, reason = 'homekit-session-stopped') {
+  cancelPendingHangUp('superseded');
+  logger.info('Hangup scheduled after grace period', {
+    event: 'hangup-scheduled',
+    reason,
+    callSid,
+    sessionId: sessionID,
+    graceMs: HANGUP_GRACE_MS,
+  });
+  const timer = setTimeout(() => {
+    pendingHangUp = null;
+    const activeCall = getActiveCall();
+    // The caller may have hung up during the window, and the slot may already
+    // hold a different call. Either way this one is no longer ours to end.
+    if (!activeCall || activeCall.callSid !== callSid) {
+      logger.info('Pending hangup skipped; call already gone', {
+        event: 'hangup-skipped',
+        reason: 'call-no-longer-active',
+        callSid,
+        sessionId: sessionID,
+      });
+      return;
+    }
+    hangUpCall(callSid)
       .then((result) => {
         if (result && result.alreadyEnded) {
           logger.info('Twilio call already ended while stopping HomeKit session', {
             event: 'hangup-call-already-ended',
             reason: 'twilio-call-not-in-progress',
-            callSid: activeCall.callSid,
+            callSid,
             sessionId: sessionID,
           });
         }
@@ -568,12 +647,14 @@ function _stopSession(sessionID, hangUp) {
         logger.error('Failed to hang up call while stopping HomeKit session', {
           event: 'hangup-call-failed',
           reason: 'twilio-hangup-failed',
-          callSid: activeCall.callSid,
+          callSid,
           sessionId: sessionID,
           error,
         });
       });
-  }
+  }, HANGUP_GRACE_MS);
+  timer.unref();
+  pendingHangUp = { timer, callSid, sessionID };
 }
 
 // ---------------------------------------------------------------------------
@@ -607,6 +688,10 @@ lockService
       try {
         await sendDtmfSequence(activeCall, config.twilioUnlockDigits);
         state.markActivity(activeCall.callSid, 'unlock-dtmf');
+        // Unlocking from the room view is the case this grace window exists
+        // for, so give the intercom a full window to act on the digits rather
+        // than whatever was left of the previous one.
+        deferPendingHangUp('unlock-sent');
         logger.info('Sent DTMF unlock over active media stream', {
           event: 'unlock-requested',
           callSid: activeCall.callSid,
@@ -785,6 +870,9 @@ function clearMulawPassthrough(stream) {
  * Does NOT call hangUpCall — the call is already gone.
  */
 function endHapSession() {
+  // The caller is already gone, so a hangup left over from a closed live view
+  // has nothing to end.
+  cancelPendingHangUp('call-ended');
   for (const sessionID of activeSessions.keys()) {
     _stopSession(sessionID, /* hangUp= */ false);
   }
@@ -807,6 +895,7 @@ function setOnHapSessionStarted(handler) {
  * clean stop, restart and reboot.
  */
 function shutdown() {
+  cancelPendingHangUp('shutdown');
   endHapSession();
   removeSdpDir();
   // Nothing to tear down if start() never ran: unpublish() on an accessory
@@ -829,4 +918,10 @@ module.exports = {
   endHapSession,
   setOnHapSessionStarted,
   shutdown,
+  // Exported for tests/homekit-hangup-grace.test.cjs. Reaching the deferred
+  // hangup through the streaming delegate would mean standing up a full SRTP
+  // session, which tests nothing about the timer.
+  scheduleHangUp,
+  cancelPendingHangUp,
+  deferPendingHangUp,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buzz-me-in",
-  "version": "2.2.0-beta.0",
+  "version": "2.2.0-beta.2",
   "description": "HomeKit-compatible apartment intercom via Twilio media streams",
   "main": "server.js",
   "bin": {

package/src/core/config.js

@@ -138,6 +138,7 @@ module.exports = {
   streamStartTimeoutMs: parsePositiveInt('STREAM_START_TIMEOUT_MS', '3000'),
   twilioMediaPayloadMaxBytes: parsePositiveInt('TWILIO_MEDIA_PAYLOAD_MAX_BYTES', '512'),
   shutdownGraceMs: parsePositiveInt('SHUTDOWN_GRACE_MS', '10000'),
+  homekitHangupGraceMs: parsePositiveInt('HOMEKIT_HANGUP_GRACE_MS', '3000'),
   streamAuthSecret,
   streamAuthTtlSec: 90,
   statusApiToken,