buzz-me-in 2.2.0-beta.3 → 2.2.0-beta.4

package/.env.example

@@ -58,10 +58,13 @@ 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
+# to send its DTMF. Tapping unlock restarts the window, so the digits are never
+# cut short. 8 s is measured, not guessed: closing the view and then reaching
+# the lock tile under Other took 2.9 s unhurried, and 3 s left 78 ms of margin.
+# The cost of a longer window is that much silence for the caller after you are
+# done, so lower it only if that silence bothers a caller more than a rushed
+# unlock bothers you.
+HOMEKIT_HANGUP_GRACE_MS=8000
 
 # Logging
 # LOG_LEVEL controls minimum emitted level: debug | info | warn | error

package/README.md

@@ -448,12 +448,12 @@ 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":"Hangup scheduled after grace period","component":"homekit","event":"hangup-scheduled","reason":"homekit-session-stopped","callSid":"CA...","sessionId":"...","graceMs":8000}
 {"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.
+The call is not hung up the instant the view closes. It is held open for `HOMEKIT_HANGUP_GRACE_MS` (default 8000) 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

@@ -158,6 +158,7 @@ const activeSessions = new Map();
 // PassThrough stream set by server.js each time a Twilio call connects.
 let currentMulawStream = null;
 let onHapSessionStarted = null;
+let onHapSessionEnded = null;
 
 function getActiveCall() {
   return state.getActiveCall();
@@ -565,7 +566,13 @@ function _stopSession(sessionID, hangUp) {
   // it kills a live call: seen on 2026-09-12, where session ac5c8c21 stopping
   // ended the call under session d332e46a three seconds into the stream.
   const activeCall = getActiveCall();
-  if (hangUp && activeCall && activeSessions.size === 0) {
+  if (activeSessions.size !== 0) return;
+
+  // ffIn is dead and unpiped by now, so tell the media stream to stop writing
+  // into a PassThrough with no consumer. See markHomekitSessionEnded.
+  if (activeCall && onHapSessionEnded) onHapSessionEnded(activeCall.callSid);
+
+  if (hangUp && activeCall) {
     scheduleHangUp(activeCall.callSid, sessionID);
   }
 }
@@ -888,6 +895,10 @@ function setOnHapSessionStarted(handler) {
   onHapSessionStarted = typeof handler === 'function' ? handler : null;
 }
 
+function setOnHapSessionEnded(handler) {
+  onHapSessionEnded = typeof handler === 'function' ? handler : null;
+}
+
 /**
  * Graceful shutdown: tear down streaming sessions and unpublish the
  * accessory so the mDNS advertisement does not linger after exit.
@@ -923,6 +934,7 @@ module.exports = {
   clearMulawPassthrough,
   endHapSession,
   setOnHapSessionStarted,
+  setOnHapSessionEnded,
   shutdown,
   // Exported for tests/homekit-hangup-grace.test.cjs. Reaching the deferred
   // hangup through the streaming delegate would mean standing up a full SRTP

package/package.json

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

package/server.js

@@ -67,6 +67,11 @@ homekit.setOnHapSessionStarted((callSid) => {
   if (mediaStream) mediaStream.markHomekitSessionStarted();
 });
 
+homekit.setOnHapSessionEnded((callSid) => {
+  const mediaStream = activeMediaStreamsByCallSid.get(callSid);
+  if (mediaStream) mediaStream.markHomekitSessionEnded();
+});
+
 // ---------------------------------------------------------------------------
 // Ringtone — one UK-style ringback cycle (400Hz+450Hz dual tone), generated
 // in-process as a WAV buffer. Served at GET /ringtone for debug/manual

package/src/core/config.js

@@ -138,7 +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'),
+  homekitHangupGraceMs: parsePositiveInt('HOMEKIT_HANGUP_GRACE_MS', '8000'),
   streamAuthSecret,
   streamAuthTtlSec: 90,
   statusApiToken,

package/src/core/media-stream.js

@@ -293,6 +293,36 @@ class MediaStream {
     this.stopRingback('homekit-session-started');
   }
 
+  /**
+   * The counterpart to markHomekitSessionStarted, called once the last HomeKit
+   * streaming session stops.
+   *
+   * Without it, forwarding stayed on for the life of the call while the
+   * PassThrough's consumer was gone: _stopSession kills ffIn and unpipes it, so
+   * Twilio audio accumulated in a buffer nobody drained. That matters twice
+   * over. The buffer holds 4 s (32 KB of 8 kHz mu-law), so a longer gap logs
+   * media-frames-dropped for audio that was never going anywhere; and on
+   * reopening the live view the new ffIn inherits the backlog and drains it
+   * faster than real time, which is the "buffered startup audio burst" the
+   * inbound spawn comment already warns about. Either way a rejoin starts
+   * behind live instead of at it.
+   *
+   * This restores the invariant the write path documents: forward live-view
+   * audio only.
+   */
+  markHomekitSessionEnded() {
+    if (!this.hasHomekitSession) return;
+    this.hasHomekitSession = false;
+    // Otherwise a later resume would log against a run of drops that ended
+    // when forwarding stopped.
+    this.droppingFrames = false;
+    this.logger.info('HomeKit session ended; no longer forwarding media', {
+      callSid: this.currentCallSid || undefined,
+      event: 'homekit-session-ended',
+      reason: 'no-active-hap-session',
+    });
+  }
+
   sendRingbackFrame() {
     if (!this.currentCallSid || !this.started || this.closed) return;