From 2002b1cc129698acdc041afd07cd46cfc2171005 Mon Sep 17 00:00:00 2001
From: Claude Owner <claude@ejclaw.local>
Date: Tue, 26 May 2026 14:59:43 +0900
Subject: [PATCH] docs(voice): document interrupt-latest as a design choice

VoiceSession.play() replaces the currently playing TTS on every new
message instead of queueing it. Without this comment a future reader
(or code review) is likely to file it as a missing-feature bug, but
the absence of a queue is intentional: in a many-user voice channel,
queueing causes a speaker's own message to lag far behind the chat
context. Document the policy at the call site.
---
 src/classes/VoiceSession.ts | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/classes/VoiceSession.ts b/src/classes/VoiceSession.ts
index 8867004..5f3b6f1 100644
--- a/src/classes/VoiceSession.ts
+++ b/src/classes/VoiceSession.ts
@@ -60,6 +60,13 @@ export class VoiceSession {
     }, this.endTimeMs);
   }
 
+  /**
+   * 새 TTS가 들어오면 이전 재생을 의도적으로 interrupt한다 (큐잉 없음).
+   * 다중 사용자 환경에서 모든 메시지를 큐로 쌓으면 자기 발화가 수십 초
+   * 밀려 채팅 맥락과 어긋나므로, "최신 발화 우선, 앞건 잘림"을 정책으로
+   * 채택했다. generation 카운터는 같은 메시지에 대해 한 번만 play 되도록
+   * 보호하는 용도이고, 이전 mp3가 잘리는 동작 자체는 설계 의도이다.
+   */
   public async play(mp3Buf: Buffer) {
     if (this.isSessionEnd) return;
     const myGen = ++this.generation;