From 899131b0a1cc1647e701cf7ba6605d8b54daf21e Mon Sep 17 00:00:00 2001
From: RainbowBird <git@luoling.moe>
Date: Tue, 28 Jul 2026 17:58:50 +0800
Subject: [PATCH] feat(stage): add persistent speech mute controls (#2128)

---
 .../renderer/components/Window/TitleBar.vue   |  6 ++
 .../src/renderer/pages/chat.vue               | 26 +++++-
 packages/i18n/src/locales/en/stage.yaml       |  3 +
 packages/i18n/src/locales/es/stage.yaml       |  3 +
 packages/i18n/src/locales/fr/stage.yaml       |  3 +
 packages/i18n/src/locales/ja/stage.yaml       |  3 +
 packages/i18n/src/locales/ko/stage.yaml       |  3 +
 packages/i18n/src/locales/ru/stage.yaml       |  3 +
 packages/i18n/src/locales/vi/stage.yaml       |  3 +
 packages/i18n/src/locales/zh-Hans/stage.yaml  |  3 +
 packages/i18n/src/locales/zh-Hant/stage.yaml  |  3 +
 .../Layouts/MobileInteractiveArea.vue         | 19 ++++-
 .../components/Widgets/ChatActionButtons.vue  | 21 +++++
 .../src/components/Widgets/ChatArea.vue       |  2 +-
 .../composables/useStopSpeakingButton.test.ts | 17 ++++
 .../src/composables/useStopSpeakingButton.ts  | 15 ++--
 .../stage-ui/src/components/scenes/Stage.vue  | 31 ++++++-
 .../src/stores/speech-output-control.test.ts  | 83 ++++++++++++++++++-
 .../src/stores/speech-output-control.ts       | 28 ++++++-
 19 files changed, 257 insertions(+), 18 deletions(-)

diff --git a/apps/stage-tamagotchi/src/renderer/components/Window/TitleBar.vue b/apps/stage-tamagotchi/src/renderer/components/Window/TitleBar.vue
index 0de57df6b..76ce66b8f 100644
--- a/apps/stage-tamagotchi/src/renderer/components/Window/TitleBar.vue
+++ b/apps/stage-tamagotchi/src/renderer/components/Window/TitleBar.vue
@@ -34,6 +34,12 @@ const { platform } = useAppRuntime()
         <div><span select-none whitespace-nowrap text-sm>{{ title }}</span></div>
       </div>
       <div w-full drag-region />
+      <div
+        flex items-center gap-1
+        class="[-webkit-app-region:no-drag]"
+      >
+        <slot name="actions" />
+      </div>
       <div
         bg="hover:neutral-200 hover:dark:neutral-800"
         transition="all duration-200 ease-in-out"
diff --git a/apps/stage-tamagotchi/src/renderer/pages/chat.vue b/apps/stage-tamagotchi/src/renderer/pages/chat.vue
index 413ce790a..0bdf063ae 100644
--- a/apps/stage-tamagotchi/src/renderer/pages/chat.vue
+++ b/apps/stage-tamagotchi/src/renderer/pages/chat.vue
@@ -1,11 +1,15 @@
 <script setup lang="ts">
+import { useStopSpeakingButton } from '@proj-airi/stage-layouts/composables/useStopSpeakingButton'
 import { ChatSessionsDrawer } from '@proj-airi/stage-ui/components'
 import { shallowRef } from 'vue'
+import { useI18n } from 'vue-i18n'
 
 import InteractiveArea from '../components/InteractiveArea.vue'
 import WindowTitleBar from '../components/Window/TitleBar.vue'
 
 const sessionsDrawerOpen = shallowRef(false)
+const { speechMuted, toggleSpeechMuted } = useStopSpeakingButton()
+const { t } = useI18n()
 </script>
 
 <template>
@@ -14,7 +18,27 @@ const sessionsDrawerOpen = shallowRef(false)
       title="Chat"
       icon="i-solar:chat-line-bold"
       @title-click="sessionsDrawerOpen = true"
-    />
+    >
+      <template #actions>
+        <button
+          data-testid="speech-mute-button"
+          :class="[
+            'h-7 w-7 flex items-center justify-center rounded-md outline-none',
+            'text-base transition-colors transition-transform active:scale-95',
+            speechMuted
+              ? 'bg-primary-100 text-primary-600 dark:bg-primary-900/40 dark:text-primary-300'
+              : 'text-neutral-400 hover:bg-neutral-200 hover:text-primary-500 dark:text-neutral-500 dark:hover:bg-neutral-800 dark:hover:text-primary-400',
+          ]"
+          :title="speechMuted ? t('stage.speech-output.unmute') : t('stage.speech-output.mute')"
+          :aria-label="speechMuted ? t('stage.speech-output.unmute') : t('stage.speech-output.mute')"
+          :aria-pressed="speechMuted"
+          @click="toggleSpeechMuted"
+        >
+          <div v-if="speechMuted" class="i-solar:volume-cross-bold-duotone" />
+          <div v-else class="i-solar:volume-loud-bold-duotone" />
+        </button>
+      </template>
+    </WindowTitleBar>
     <InteractiveArea
       v-model:sessions-drawer-open="sessionsDrawerOpen"
       class="interaction-area block"
diff --git a/packages/i18n/src/locales/en/stage.yaml b/packages/i18n/src/locales/en/stage.yaml
index 8a74f65fb..290eea9e2 100644
--- a/packages/i18n/src/locales/en/stage.yaml
+++ b/packages/i18n/src/locales/en/stage.yaml
@@ -20,6 +20,9 @@ send-mode:
   enter: Enter
   ctrl-enter: Ctrl + Enter
   double-enter: Double Enter
+speech-output:
+  mute: Mute voice
+  unmute: Unmute voice
 operations:
   load-models: Load Models
   load-models-status:
diff --git a/packages/i18n/src/locales/es/stage.yaml b/packages/i18n/src/locales/es/stage.yaml
index c5158d655..cc35aaaeb 100644
--- a/packages/i18n/src/locales/es/stage.yaml
+++ b/packages/i18n/src/locales/es/stage.yaml
@@ -20,6 +20,9 @@ send-mode:
   enter: Intro
   ctrl-enter: Ctrl + Intro
   double-enter: Entrada doble
+speech-output:
+  mute: Silenciar voz
+  unmute: Activar voz
 operations:
   load-models: Cargar Modelos
   load-models-status:
diff --git a/packages/i18n/src/locales/fr/stage.yaml b/packages/i18n/src/locales/fr/stage.yaml
index a27e2eba1..367bfd3c6 100644
--- a/packages/i18n/src/locales/fr/stage.yaml
+++ b/packages/i18n/src/locales/fr/stage.yaml
@@ -20,6 +20,9 @@ send-mode:
   enter: Entrée
   ctrl-enter: Ctrl + Entrée
   double-enter: Double Entrée
+speech-output:
+  mute: Couper la voix
+  unmute: Réactiver la voix
 operations:
   load-models: Charger les modèles
   load-models-status:
diff --git a/packages/i18n/src/locales/ja/stage.yaml b/packages/i18n/src/locales/ja/stage.yaml
index 1f0b32ed0..f6dd1338b 100644
--- a/packages/i18n/src/locales/ja/stage.yaml
+++ b/packages/i18n/src/locales/ja/stage.yaml
@@ -20,6 +20,9 @@ send-mode:
   enter: Enter
   ctrl-enter: Ctrl + Enter
   double-enter: Enter二回
+speech-output:
+  mute: 音声をミュート
+  unmute: ミュートを解除
 operations:
   load-models: モデルの読み込み
   load-models-status:
diff --git a/packages/i18n/src/locales/ko/stage.yaml b/packages/i18n/src/locales/ko/stage.yaml
index 049d9ad8f..a217d8766 100644
--- a/packages/i18n/src/locales/ko/stage.yaml
+++ b/packages/i18n/src/locales/ko/stage.yaml
@@ -20,6 +20,9 @@ send-mode:
   enter: 엔터
   ctrl-enter: Ctrl + Enter
   double-enter: Double Enter
+speech-output:
+  mute: 음성 음소거
+  unmute: 음소거 해제
 operations:
   load-models: 모델 불러오기
   load-models-status:
diff --git a/packages/i18n/src/locales/ru/stage.yaml b/packages/i18n/src/locales/ru/stage.yaml
index 17a9d3ed1..69ba1dbe0 100644
--- a/packages/i18n/src/locales/ru/stage.yaml
+++ b/packages/i18n/src/locales/ru/stage.yaml
@@ -20,6 +20,9 @@ send-mode:
   enter: Enter
   ctrl-enter: Ctrl + Enter
   double-enter: Двойной Enter
+speech-output:
+  mute: Отключить озвучивание
+  unmute: Включить озвучивание
 operations:
   load-models: Загрузить модели
   load-models-status:
diff --git a/packages/i18n/src/locales/vi/stage.yaml b/packages/i18n/src/locales/vi/stage.yaml
index b43cf75fc..c8d59b3fa 100644
--- a/packages/i18n/src/locales/vi/stage.yaml
+++ b/packages/i18n/src/locales/vi/stage.yaml
@@ -20,6 +20,9 @@ send-mode:
   enter: Nhập
   ctrl-enter: Ctrl + Enter
   double-enter: Nhập hai lần
+speech-output:
+  mute: Tắt tiếng nói
+  unmute: Bật tiếng nói
 operations:
   load-models: Tải mô hình
   load-models-status:
diff --git a/packages/i18n/src/locales/zh-Hans/stage.yaml b/packages/i18n/src/locales/zh-Hans/stage.yaml
index dd3f1405e..278664784 100644
--- a/packages/i18n/src/locales/zh-Hans/stage.yaml
+++ b/packages/i18n/src/locales/zh-Hans/stage.yaml
@@ -20,6 +20,9 @@ send-mode:
   enter: Enter
   ctrl-enter: Ctrl + Enter
   double-enter: 双击Enter
+speech-output:
+  mute: 静音语音
+  unmute: 恢复语音
 operations:
   load-models: 加载模型
   load-models-status:
diff --git a/packages/i18n/src/locales/zh-Hant/stage.yaml b/packages/i18n/src/locales/zh-Hant/stage.yaml
index dc5399314..34ba92c5e 100644
--- a/packages/i18n/src/locales/zh-Hant/stage.yaml
+++ b/packages/i18n/src/locales/zh-Hant/stage.yaml
@@ -20,6 +20,9 @@ send-mode:
   enter: Enter
   ctrl-enter: Ctrl + Enter
   double-enter: Enter + Enter
+speech-output:
+  mute: 靜音語音
+  unmute: 恢復語音
 operations:
   load-models: 載入模型
   load-models-status:
diff --git a/packages/stage-layouts/src/components/Layouts/MobileInteractiveArea.vue b/packages/stage-layouts/src/components/Layouts/MobileInteractiveArea.vue
index 67624de92..ebedd28a2 100644
--- a/packages/stage-layouts/src/components/Layouts/MobileInteractiveArea.vue
+++ b/packages/stage-layouts/src/components/Layouts/MobileInteractiveArea.vue
@@ -94,7 +94,7 @@ const { isListening, startStreamingTranscription, stopStreamingTranscription } =
     isStageTamagotchi,
   },
 )
-const { showStopSpeakingButton, stopSpeakingFromChat } = useStopSpeakingButton()
+const { showStopSpeakingButton, speechMuted, stopSpeakingFromChat, toggleSpeechMuted } = useStopSpeakingButton()
 const toggleTranscription = () => isListening.value ? stopStreamingTranscription() : startStreamingTranscription()
 
 async function handleSubmit() {
@@ -227,6 +227,23 @@ onMounted(() => {
               </Transition>
             </button>
           </HearingConfigDialog>
+          <button
+            data-testid="speech-mute-button"
+            :class="[
+              'w-fit flex items-center self-end justify-center rounded-xl border-2 border-solid p-2 backdrop-blur-md',
+              'border-neutral-100/60 text-neutral-500 transition-colors active:scale-95 dark:border-neutral-800/30 dark:text-neutral-400',
+              speechMuted
+                ? 'bg-primary-100/80 text-primary-600 dark:bg-primary-900/60 dark:text-primary-300'
+                : 'bg-neutral-50/70 hover:text-primary-500 dark:bg-neutral-800/70 dark:hover:text-primary-400',
+            ]"
+            :title="speechMuted ? t('stage.speech-output.unmute') : t('stage.speech-output.mute')"
+            :aria-label="speechMuted ? t('stage.speech-output.unmute') : t('stage.speech-output.mute')"
+            :aria-pressed="speechMuted"
+            @click="toggleSpeechMuted"
+          >
+            <div v-if="speechMuted" class="i-solar:volume-cross-bold-duotone size-5" />
+            <div v-else class="i-solar:volume-loud-bold-duotone size-5" />
+          </button>
           <button border="2 solid neutral-100/60 dark:neutral-800/30" bg="neutral-50/70 dark:neutral-800/70" w-fit flex items-center self-end justify-center rounded-xl p-2 backdrop-blur-md title="Theme" @click="toggleDark()">
             <Transition name="fade" mode="out-in">
               <div v-if="isDark" i-solar:moon-outline size-5 text="neutral-500 dark:neutral-400" />
diff --git a/packages/stage-layouts/src/components/Widgets/ChatActionButtons.vue b/packages/stage-layouts/src/components/Widgets/ChatActionButtons.vue
index 185ea66e5..3cf43b585 100644
--- a/packages/stage-layouts/src/components/Widgets/ChatActionButtons.vue
+++ b/packages/stage-layouts/src/components/Widgets/ChatActionButtons.vue
@@ -5,15 +5,19 @@ import { useChatSessionStore } from '@proj-airi/stage-ui/stores/chat/session-sto
 import { useTheme } from '@proj-airi/ui'
 import { storeToRefs } from 'pinia'
 import { ref } from 'vue'
+import { useI18n } from 'vue-i18n'
 
 import ViewControls from '../Layouts/InteractiveArea/Actions/ViewControls.vue'
 
+import { useStopSpeakingButton } from '../../composables/useStopSpeakingButton'
 import { BackgroundDialogPicker } from '../Backgrounds'
 
 const { cleanupMessages } = useChatMaintenanceStore()
 const { messages } = storeToRefs(useChatSessionStore())
 const { trackChatMessagesCleared } = useAnalytics()
 const { isDark, toggleDark } = useTheme()
+const { speechMuted, toggleSpeechMuted } = useStopSpeakingButton()
+const { t } = useI18n()
 
 const backgroundDialogOpen = ref(false)
 
@@ -30,6 +34,23 @@ function handleCleanupMessages() {
 <template>
   <BackgroundDialogPicker v-model="backgroundDialogOpen" />
   <div absolute bottom--8 right-0 flex gap-2>
+    <button
+      data-testid="speech-mute-button"
+      :class="[
+        'max-h-[10lh] min-h-[1lh] flex items-center justify-center rounded-md p-2 outline-none',
+        'text-lg transition-colors transition-transform active:scale-95',
+        speechMuted
+          ? 'bg-primary-100 text-primary-600 dark:bg-primary-900/40 dark:text-primary-300'
+          : 'bg-neutral-100 text-neutral-500 hover:text-primary-500 dark:bg-neutral-800 dark:text-neutral-400 dark:hover:text-primary-400',
+      ]"
+      :title="speechMuted ? t('stage.speech-output.unmute') : t('stage.speech-output.mute')"
+      :aria-label="speechMuted ? t('stage.speech-output.unmute') : t('stage.speech-output.mute')"
+      :aria-pressed="speechMuted"
+      @click="toggleSpeechMuted"
+    >
+      <div v-if="speechMuted" class="i-solar:volume-cross-bold-duotone" />
+      <div v-else class="i-solar:volume-loud-bold-duotone" />
+    </button>
     <ViewControls />
     <button
       class="max-h-[10lh] min-h-[1lh]"
diff --git a/packages/stage-layouts/src/components/Widgets/ChatArea.vue b/packages/stage-layouts/src/components/Widgets/ChatArea.vue
index 4d88feb60..7b00a58e0 100644
--- a/packages/stage-layouts/src/components/Widgets/ChatArea.vue
+++ b/packages/stage-layouts/src/components/Widgets/ChatArea.vue
@@ -302,7 +302,7 @@ watch(sendMode, () => {
       </div>
 
       <div
-        absolute bottom-2 right-2 z-10 flex items-center
+        absolute bottom-2 right-2 z-10 flex items-center gap-1
       >
         <button
           v-if="showStopSpeakingButton"
diff --git a/packages/stage-layouts/src/composables/useStopSpeakingButton.test.ts b/packages/stage-layouts/src/composables/useStopSpeakingButton.test.ts
index c53336d52..9c1576e53 100644
--- a/packages/stage-layouts/src/composables/useStopSpeakingButton.test.ts
+++ b/packages/stage-layouts/src/composables/useStopSpeakingButton.test.ts
@@ -4,7 +4,9 @@ import { ref } from 'vue'
 import { useStopSpeakingButton } from './useStopSpeakingButton'
 
 const nowSpeaking = ref(false)
+const speechMuted = ref(false)
 const requestStopSpeakingMock = vi.fn()
+const toggleSpeechMutedMock = vi.fn()
 const trackTtsStopClickedMock = vi.fn()
 
 vi.mock('@proj-airi/stage-ui/stores/audio', () => ({
@@ -16,6 +18,8 @@ vi.mock('@proj-airi/stage-ui/stores/audio', () => ({
 vi.mock('@proj-airi/stage-ui/stores/speech-output-control', () => ({
   useSpeechOutputControlStore: () => ({
     requestStopSpeaking: requestStopSpeakingMock,
+    speechMuted,
+    toggleSpeechMuted: toggleSpeechMutedMock,
   }),
 }))
 
@@ -69,4 +73,17 @@ describe('useStopSpeakingButton', () => {
       reason: 'manual-all',
     })
   })
+
+  it('exposes persisted mute state and toggles it through the shared output store', () => {
+    speechMuted.value = true
+    toggleSpeechMutedMock.mockClear()
+
+    const controls = useStopSpeakingButton()
+
+    expect(controls.speechMuted.value).toBe(true)
+
+    controls.toggleSpeechMuted()
+
+    expect(toggleSpeechMutedMock).toHaveBeenCalledOnce()
+  })
 })
diff --git a/packages/stage-layouts/src/composables/useStopSpeakingButton.ts b/packages/stage-layouts/src/composables/useStopSpeakingButton.ts
index 305b1acd3..72fdea230 100644
--- a/packages/stage-layouts/src/composables/useStopSpeakingButton.ts
+++ b/packages/stage-layouts/src/composables/useStopSpeakingButton.ts
@@ -5,20 +5,15 @@ import { storeToRefs } from 'pinia'
 import { computed } from 'vue'
 
 /**
- * Connects chat UI stop-speaking controls to the active stage speech output host.
+ * Connects chat speech controls to the active Stage output host.
  *
- * Use when:
- * - Chat input UI needs to stop assistant TTS playback without cancelling text generation.
- *
- * Expects:
- * - A Stage instance is mounted and consumes speech output stop requests.
- *
- * Returns:
- * - Visibility state for the button and click handlers for manual stops.
+ * Manual stops affect current playback without cancelling text generation.
+ * Mute is persisted by the shared store and also blocks future TTS sessions.
  */
 export function useStopSpeakingButton() {
   const { nowSpeaking } = storeToRefs(useSpeakingStore())
   const speechOutputControlStore = useSpeechOutputControlStore()
+  const { speechMuted } = storeToRefs(speechOutputControlStore)
   const { trackTtsStopClicked } = useAnalytics()
 
   const showStopSpeakingButton = computed(() => nowSpeaking.value)
@@ -35,7 +30,9 @@ export function useStopSpeakingButton() {
 
   return {
     showStopSpeakingButton,
+    speechMuted,
     stopSpeakingFromChat,
     stopAllSpeaking,
+    toggleSpeechMuted: speechOutputControlStore.toggleSpeechMuted,
   }
 }
diff --git a/packages/stage-ui/src/components/scenes/Stage.vue b/packages/stage-ui/src/components/scenes/Stage.vue
index 7eec8d4b8..66f905f1e 100644
--- a/packages/stage-ui/src/components/scenes/Stage.vue
+++ b/packages/stage-ui/src/components/scenes/Stage.vue
@@ -93,7 +93,8 @@ const {
 const { mouthOpenSize, nowSpeaking } = storeToRefs(useSpeakingStore())
 const { audioContext } = useAudioContext()
 const currentAudioSource = ref<AudioBufferSourceNode>()
-const { latestStopRequest } = storeToRefs(useSpeechOutputControlStore())
+const speechOutputControlStore = useSpeechOutputControlStore()
+const { latestStopRequest, speechMuted } = storeToRefs(speechOutputControlStore)
 const lastVrmInteractionAt = new Map<VrmInteractionTarget, number>()
 const VRM_INTERACTION_COOLDOWN_MS = 450
 
@@ -391,6 +392,9 @@ const speechPipeline = createSpeechPipeline<AudioBuffer>({
     if (signal.aborted)
       return null
 
+    if (speechMuted.value)
+      return null
+
     if (activeSpeechProvider.value === 'speech-noop')
       return null
 
@@ -693,6 +697,9 @@ function resolveStreamingSessionModel(): string | null {
 }
 
 function buildStreamingSnapshot(): StreamingSessionSnapshot | null {
+  if (speechMuted.value)
+    return null
+
   // Snapshotted once per session, so a mid-session provider/voice swap
   // does not corrupt an in-flight session — the watcher below detects
   // changes and tears down explicitly. Returns `null` when streaming
@@ -790,15 +797,24 @@ watch(latestStopRequest, (request) => {
   stopSpeechOutput(request.reason)
 })
 
+watch(speechMuted, (muted) => {
+  if (muted)
+    stopSpeechOutput('muted')
+}, { immediate: true })
+
 chatHookCleanups.push(onBeforeMessageComposed(async () => {
   officialAutoTtsTrackedForTurn = false
   playbackManager.stopAll('new-message')
-
-  setupAnalyser()
-  await setupLipSync()
   resetAssistantSpeechSurface('new-message')
 
   currentSession?.cancel('new-message')
+  currentSession = null
+
+  if (speechMuted.value)
+    return
+
+  setupAnalyser()
+  await setupLipSync()
   currentSession = openTtsSession()
 }))
 
@@ -811,6 +827,13 @@ chatHookCleanups.push(onTokenLiteral(async (literal) => {
 }))
 
 chatHookCleanups.push(onTokenSpecial(async (special) => {
+  // Muting speech must not suppress non-audio signals such as emotion, motion,
+  // delay, or plugin calls that normally travel through the TTS session.
+  if (speechMuted.value) {
+    await playSpecialToken(special)
+    return
+  }
+
   currentSession?.appendSpecial(special)
 }))
 
diff --git a/packages/stage-ui/src/stores/speech-output-control.test.ts b/packages/stage-ui/src/stores/speech-output-control.test.ts
index e4635a08a..b209173d0 100644
--- a/packages/stage-ui/src/stores/speech-output-control.test.ts
+++ b/packages/stage-ui/src/stores/speech-output-control.test.ts
@@ -1,13 +1,61 @@
 import { createPinia, setActivePinia } from 'pinia'
-import { beforeEach, describe, expect, it } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { nextTick } from 'vue'
 
 import { useSpeechOutputControlStore } from './speech-output-control'
 
+class MemoryStorage implements Storage {
+  readonly values = new Map<string, string>()
+
+  get length() {
+    return this.values.size
+  }
+
+  clear() {
+    this.values.clear()
+  }
+
+  getItem(key: string) {
+    return this.values.get(key) ?? null
+  }
+
+  key(index: number) {
+    return [...this.values.keys()][index] ?? null
+  }
+
+  removeItem(key: string) {
+    this.values.delete(key)
+  }
+
+  setItem(key: string, value: string) {
+    this.values.set(key, value)
+  }
+}
+
 describe('speech output control store', () => {
   beforeEach(() => {
+    const localStorage = new MemoryStorage()
+    vi.stubGlobal('Storage', MemoryStorage)
+    vi.stubGlobal('StorageEvent', class {
+      constructor(
+        readonly type: string,
+        readonly init: StorageEventInit,
+      ) {}
+    })
+    vi.stubGlobal('localStorage', localStorage)
+    vi.stubGlobal('window', {
+      addEventListener: vi.fn(),
+      dispatchEvent: vi.fn(() => true),
+      localStorage,
+      removeEventListener: vi.fn(),
+    })
     setActivePinia(createPinia())
   })
 
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
   it('records manual chat stop-speaking requests with monotonic sequence numbers', () => {
     const store = useSpeechOutputControlStore()
 
@@ -38,4 +86,37 @@ describe('speech output control store', () => {
       reason: 'manual-all',
     })
   })
+
+  it('persists mute state and requests an immediate stop when mute is enabled', async () => {
+    const store = useSpeechOutputControlStore()
+
+    expect(store.speechMuted).toBe(false)
+
+    store.setSpeechMuted(true)
+
+    expect(store.speechMuted).toBe(true)
+    expect(store.latestStopRequest).toEqual({
+      id: 1,
+      reason: 'muted',
+    })
+
+    await nextTick()
+    setActivePinia(createPinia())
+    const restoredStore = useSpeechOutputControlStore()
+
+    expect(restoredStore.speechMuted).toBe(true)
+  })
+
+  it('does not publish another stop request when speech output is unmuted', () => {
+    const store = useSpeechOutputControlStore()
+    store.setSpeechMuted(true)
+
+    store.setSpeechMuted(false)
+
+    expect(store.speechMuted).toBe(false)
+    expect(store.latestStopRequest).toEqual({
+      id: 1,
+      reason: 'muted',
+    })
+  })
 })
diff --git a/packages/stage-ui/src/stores/speech-output-control.ts b/packages/stage-ui/src/stores/speech-output-control.ts
index eee9a60df..cf47610c1 100644
--- a/packages/stage-ui/src/stores/speech-output-control.ts
+++ b/packages/stage-ui/src/stores/speech-output-control.ts
@@ -1,7 +1,8 @@
+import { useLocalStorage } from '@vueuse/core'
 import { defineStore } from 'pinia'
 import { ref } from 'vue'
 
-export type SpeechOutputStopReason = 'manual-chat' | 'manual-all'
+export type SpeechOutputStopReason = 'manual-chat' | 'manual-all' | 'muted'
 
 /**
  * Represents a user-requested stop-speaking command for the stage output host.
@@ -14,6 +15,9 @@ export interface SpeechOutputStopRequest {
 }
 
 export const useSpeechOutputControlStore = defineStore('speech-output-control', () => {
+  const speechMuted = useLocalStorage('settings/speech/output-muted', false, {
+    window: typeof window === 'undefined' ? undefined : window,
+  })
   const latestStopRequest = ref<SpeechOutputStopRequest>()
   let nextRequestId = 1
 
@@ -36,8 +40,30 @@ export const useSpeechOutputControlStore = defineStore('speech-output-control',
     }
   }
 
+  /**
+   * Enables or disables automatic assistant speech output.
+   *
+   * Enabling mute also publishes a stop request so an active Stage host can
+   * cancel synthesis, streaming transport, queued audio, and current playback.
+   */
+  function setSpeechMuted(muted: boolean) {
+    if (speechMuted.value === muted)
+      return
+
+    speechMuted.value = muted
+    if (muted)
+      requestStopSpeaking('muted')
+  }
+
+  function toggleSpeechMuted() {
+    setSpeechMuted(!speechMuted.value)
+  }
+
   return {
     latestStopRequest,
+    speechMuted,
     requestStopSpeaking,
+    setSpeechMuted,
+    toggleSpeechMuted,
   }
 })