claudio-tts

1import type { Hook, Register } from 'claude-code'
2
3import {
4  DEFAULT_SPEED,
5  DEFAULT_VOLUME,
6  MAX_SPEED,
7  MIN_SPEED,
8  hasSummary,
9  parseTtsArgs,
10  speechText,
11} from './speech'
12
13const MIN_NARRATION = 10
14const USAGE =
15  'Usage: /tts [mute|unmute|status|default on|off|volume 1-10|speed 0.5-1.5|voice <name>|lang <code|auto>|device <names|all|default>|mic <name|default>|update [check|on|off]|disable|enable]'
16
17type Dollar = Parameters<Hook<'turn.start'>>[0]
18
19// Every OS-specific job (audio, process control, music ducking) lives in the `claudio-tts` Python
20// package; this mod only decides what to say and when. CLAUDIO_TTS_PYTHON is set by `install-mod`.
21async function python($: Dollar) {
22  try {
23    return (await $.env.get('CLAUDIO_TTS_PYTHON')) ?? 'python'
24  } catch {
25    return 'python'
26  }
27}
28
29async function cli($: Dollar, args: string[], stdin?: string, timeoutMs = 15000) {
30  const exe = await python($)
31  try {
32    return await $.process.run([exe, '-m', 'claudio_tts', ...args], { stdin, timeoutMs })
33  } catch (error) {
34    $.ui.log(`claudio-tts: ${String(error)}`, { to: 'debug' })
35    return undefined
36  }
37}
38
39async function sessionId($: Dollar) {
40  try {
41    return await $.session.id()
42  } catch {
43    return 'default' // only when the engine cannot name the session (tests); speech still works
44  }
45}
46
47async function stop($: Dollar) {
48  await cli($, ['stop', '--session', await sessionId($)])
49}
50
51const DISABLED = { plugin: 'claudio-tts', key: 'disabled' } as const
52
53// `/tts disable` switches the mod off for this session only: no speech, no status line, no update notice.
54async function isDisabled($: Dollar) {
55  const { value } = await $.state.get(DISABLED)
56  return value === true
57}
58
59async function speak($: Dollar, text: string) {
60  if (await isDisabled($)) return
61  if (await isMuted($)) return
62  const volume = Number((await $.store.get('volume')) ?? DEFAULT_VOLUME)
63  const speed = Number((await $.store.get('speed')) ?? DEFAULT_SPEED)
64  const devices = String((await $.store.get('devices')) ?? 'default')
65  const voice = String((await $.store.get('voice')) ?? '')
66  const lang = String((await $.store.get('lang')) ?? '')
67  await cli(
68    $,
69    [
70      'speak',
71      '--session', await sessionId($),
72      '--volume', String(volume),
73      '--speed', String(speed),
74      '--devices', devices,
75      ...(voice ? ['--voice', voice] : []),
76      ...(lang ? ['--lang', lang] : []),
77    ],
78    text,
79  )
80}
81
82const MUTED = { plugin: 'claudio-tts', key: 'muted' } as const
83
84// This session's switch if it was ever set here, else the startup default (muted unless `/tts default on`).
85async function isMuted($: Dollar) {
86  const { value } = await $.state.get(MUTED)
87  if (value !== undefined) return value
88  return ((await $.store.get('defaultMuted')) ?? true) === true
89}
90
91// Once a day (the Python side caches), say if a newer release exists. Never installs anything.
92async function noticeUpdate($: Dollar) {
93  if (((await $.store.get('updateCheck')) ?? true) !== true) return
94  if (await isDisabled($)) return
95  const found = await cli($, ['update', '--quiet'], undefined, 8000)
96  const line = found?.stdout.trim()
97  if (line) $.ui.status(`${(await isMuted($)) ? 'TTS muted' : 'TTS on'} | update available: /tts update`)
98}
99
100async function showStatus($: Dollar) {
101  if (await isDisabled($)) {
102    $.ui.status(undefined)
103    return
104  }
105  const muted = await isMuted($)
106  $.ui.status(muted ? 'TTS muted' : 'TTS on')
107  // A small file other add-ons (claudio-vibecode) can read to show this session's sound state.
108  await cli($, ['session-state', '--session', await sessionId($), '--muted', muted ? 'on' : 'off'])
109}
110
111export const register: Register = on => {
112  on('session.start', async ($, e, next) => {
113    await $.command.register({
114      name: 'tts',
115      description: 'Spoken replies (per session): /tts [mute|unmute|status|default|volume|speed|voice|lang|device|mic|update]',
116    })
117    await showStatus($)
118    await noticeUpdate($)
119    return next(e)
120  })
121
122  on('command.run', { command: 'tts' }, async ($, e) => {
123    const cmd = parseTtsArgs(e.args)
124    if (!cmd) return { text: USAGE }
125    const volume = Number((await $.store.get('volume')) ?? DEFAULT_VOLUME)
126
127    if (cmd.kind === 'disable' || cmd.kind === 'enable') {
128      await $.state.set(DISABLED, cmd.kind === 'disable')
129      if (cmd.kind === 'disable') await stop($)
130      await showStatus($)
131      return { text: cmd.kind === 'disable' ? 'TTS disabled for this session (/tts enable to turn it back on)' : 'TTS enabled for this session' }
132    }
133
134    if (await isDisabled($)) return { text: 'TTS is disabled. Use /tts enable to turn it back on' }
135
136    if (cmd.kind === 'device') {
137      const current = String((await $.store.get('devices')) ?? 'default')
138      if (cmd.value === undefined) {
139        const listed = await cli($, ['devices'])
140        return {
141          text: `TTS output: ${current}\nAvailable:\n${listed?.stdout.trim() ?? '(could not list devices)'}\nUse /tts device <name,name|all|default>`,
142        }
143      }
144      await $.store.set('devices', cmd.value)
145      await speak($, 'Speech output changed.')
146      return { text: `TTS output: ${cmd.value}` }
147    }
148
149    if (cmd.kind === 'mic') {
150      const current = String((await $.store.get('mic')) ?? 'default')
151      if (cmd.value === undefined) {
152        const inputs = await cli($, ['devices', '--inputs'])
153        return {
154          text: `Microphone: ${current}\nAvailable:\n${inputs?.stdout.trim() ?? '(could not list devices)'}\nUse /tts mic <name|default>`,
155        }
156      }
157      await $.store.set('mic', cmd.value)
158      return { text: `Microphone: ${cmd.value}` }
159    }
160
161    if (cmd.kind === 'update') {
162      if (cmd.value === 'on' || cmd.value === 'off') {
163        await $.store.set('updateCheck', cmd.value === 'on')
164        return { text: `Update check at session start: ${cmd.value}` }
165      }
166      // Typing /tts update is the approval; `check` only looks.
167      const args = cmd.value === 'check' ? ['update', '--check'] : ['update', '--yes']
168      const done = await cli($, args, undefined, 300000)
169      return { text: done?.stdout.trim() || done?.stderr.trim() || 'Could not run the update.' }
170    }
171
172    if (cmd.kind === 'default') {
173      const startMuted = ((await $.store.get('defaultMuted')) ?? true) === true
174      if (cmd.value === undefined) {
175        return { text: `New sessions start ${startMuted ? 'muted' : 'speaking'} (/tts default on|off to change)` }
176      }
177      await $.store.set('defaultMuted', cmd.value === 'off')
178      return { text: `New sessions will start ${cmd.value === 'off' ? 'muted' : 'speaking'}` }
179    }
180
181    if (cmd.kind === 'lang') {
182      const current = String((await $.store.get('lang')) ?? '')
183      if (cmd.value === undefined) {
184        const listed = await cli($, ['languages'])
185        return {
186          text: `Language: ${current || 'auto (the voice\'s own)'}\n${listed?.stdout.trim() ?? '(could not list languages)'}`,
187        }
188      }
189      if (cmd.value === 'auto' || cmd.value === 'default') {
190        await $.store.delete('lang')
191        return { text: 'Language: auto (the voice\'s own)' }
192      }
193      const check = await cli($, ['languages', '--check', cmd.value])
194      if (check && check.exitCode !== 0) {
195        return { text: check.stdout.trim() || `Unknown language '${cmd.value}'. Try /tts lang to list them` }
196      }
197      await $.store.set('lang', cmd.value.toLowerCase())
198      return { text: `Language: ${cmd.value.toLowerCase()} (the current voice will read text as ${cmd.value.toLowerCase()}, with an accent if it has no native voice)` }
199    }
200
201    if (cmd.kind === 'voice') {
202      const current = String((await $.store.get('voice')) ?? '')
203      if (cmd.value === undefined) {
204        const listed = await cli($, ['voices'])
205        return {
206          text: `Voice: ${current || 'default (KOKORO_VOICE or af_sky)'}\n${listed?.stdout.trim() ?? '(could not list voices)'}`,
207        }
208      }
209      if (cmd.value === 'default') {
210        await $.store.delete('voice')
211        return { text: 'Voice reset to the default' }
212      }
213      const check = await cli($, ['voices', '--check', cmd.value])
214      if (check && check.exitCode !== 0) {
215        return { text: check.stdout.trim() || `Unknown voice '${cmd.value}'. Try /tts voice to list them` }
216      }
217      await $.store.set('voice', cmd.value)
218      await speak($, `Hi, this is ${cmd.value.slice(3)}.`)
219      return { text: `Voice: ${cmd.value}` }
220    }
221
222    if (cmd.kind === 'speed') {
223      const speed = Number((await $.store.get('speed')) ?? DEFAULT_SPEED)
224      if (cmd.value === undefined) {
225        return { text: `TTS speed ${speed} (${MIN_SPEED} slow to ${MAX_SPEED} fast, 1 normal)` }
226      }
227      await $.store.set('speed', cmd.value)
228      await speak($, `Speed ${cmd.value}`)
229      return { text: `TTS speed ${cmd.value}` }
230    }
231
232    if (cmd.kind === 'volume') {
233      if (cmd.value === undefined) return { text: `TTS volume ${volume}/10` }
234      await $.store.set('volume', cmd.value)
235      await speak($, `Volume ${cmd.value}`)
236      return { text: `TTS volume ${cmd.value}/10` }
237    }
238
239    const muted = await isMuted($)
240    const next =
241      cmd.kind === 'toggle' ? !muted : cmd.kind === 'mute' ? true : cmd.kind === 'unmute' ? false : muted
242    if (cmd.kind !== 'status') {
243      await $.state.set(MUTED, next)
244      await showStatus($)
245      if (next) await stop($)
246    }
247    const where = String((await $.store.get('devices')) ?? 'default')
248    const pace = Number((await $.store.get('speed')) ?? DEFAULT_SPEED)
249    const chosen = String((await $.store.get('voice')) ?? '') || 'default'
250    const reads = String((await $.store.get('lang')) ?? '') || 'auto'
251    return {
252      text: `${next ? 'TTS muted' : 'TTS on'} (this session), volume ${volume}/10, speed ${pace}, voice ${chosen}, language ${reads}, output ${where}`,
253    }
254  })
255
256  // New prompt: cut off whatever this session is still saying.
257  on('turn.start', async ($, e, next) => {
258    await stop($)
259    return next(e)
260  })
261
262  let narratedTurn: string | undefined
263
264  // Before the first tool call of a turn, read the narration that came ahead of it.
265  on('turn.step', async function* ($, e, next) {
266    let narration = ''
267    for await (const chunk of next(e)) {
268      if (chunk.kind === 'text') narration += chunk.text
269      if (
270        chunk.kind === 'tool' &&
271        e.agentId === undefined &&
272        narratedTurn !== e.turnId &&
273        narration.trim().length > MIN_NARRATION &&
274        !hasSummary(narration)
275      ) {
276        narratedTurn = e.turnId
277        await speak($, speechText(narration))
278      }
279      yield chunk
280    }
281  })
282
283  // The final answer comes from the event itself, so it is always the latest one.
284  on('turn.complete', async ($, e, next) => {
285    if (e.agentId === undefined && e.reason === 'answer' && e.answer.trim()) {
286      await speak($, speechText(e.answer))
287    }
288    return next(e)
289  })
290
291  on('session.end', async ($, e, next) => {
292    await stop($)
293    await cli($, ['session-state', '--session', await sessionId($), '--clear'])
294    return next(e)
295  })
296}
297

1const OPEN = '<!-- TTS_SUMMARY'
2const CLOSE = 'TTS_SUMMARY -->'
3
4/** The text to read aloud for a reply: the TTS_SUMMARY block if present, else the whole text. */
5export const speechText = (text: string): string => {
6  const start = text.indexOf(OPEN)
7  if (start !== -1) {
8    const rest = text.slice(start + OPEN.length)
9    const end = rest.indexOf(CLOSE)
10    const summary = end === -1 ? '' : rest.slice(0, end).trim()
11    if (summary) return summary
12  }
13  return text.trim().slice(0, 5000)
14}
15
16/** Narration before a tool call is skipped when it carries a summary block; the final answer reads that. */
17export const hasSummary = (text: string): boolean => text.includes(OPEN)
18
19export type TtsCommand =
20  | { kind: 'toggle' | 'mute' | 'unmute' | 'status' | 'disable' | 'enable' }
21  | { kind: 'volume'; value?: number }
22  | { kind: 'device'; value?: string }
23  | { kind: 'mic'; value?: string }
24  | { kind: 'speed'; value?: number }
25  | { kind: 'voice'; value?: string }
26  | { kind: 'lang'; value?: string }
27  | { kind: 'default'; value?: 'on' | 'off' }
28  | { kind: 'update'; value?: 'check' | 'on' | 'off' }
29
30export const DEFAULT_VOLUME = 10
31export const DEFAULT_SPEED = 1
32export const MIN_SPEED = 0.5
33export const MAX_SPEED = 1.5
34
35/** Parses `/tts` arguments; undefined when they make no sense. Volume is a whole number 1-10. */
36export const parseTtsArgs = (args: string): TtsCommand | undefined => {
37  const trimmed = args.trim()
38  const [word = '', ...restWords] = trimmed.toLowerCase().split(/\s+/)
39  const rest = restWords.join(' ')
40  if (word === '') return { kind: 'toggle' }
41  if (word === 'mute' || word === 'off') return { kind: 'mute' }
42  if (word === 'unmute' || word === 'on') return { kind: 'unmute' }
43  if (word === 'disable') return { kind: 'disable' }
44  if (word === 'enable') return { kind: 'enable' }
45  if (word === 'status') return { kind: 'status' }
46  if (word === 'volume' || word === 'vol') {
47    if (rest === '') return { kind: 'volume' }
48    const value = Number(rest)
49    return Number.isInteger(value) && value >= 1 && value <= 10 ? { kind: 'volume', value } : undefined
50  }
51  if (word === 'device' || word === 'devices' || word === 'output') {
52    return rest === '' ? { kind: 'device' } : { kind: 'device', value: rest.replace(/\s*,\s*/g, ',') }
53  }
54  if (word === 'mic' || word === 'microphone') {
55    const name = rest.replace(/\s*\(default\)\s*$/, '').trim()
56    return name === '' ? { kind: 'mic' } : { kind: 'mic', value: name }
57  }
58  if (word === 'speed' || word === 'pace') {
59    if (rest === '') return { kind: 'speed' }
60    const value = Number(rest)
61    return Number.isFinite(value) && value >= MIN_SPEED && value <= MAX_SPEED ? { kind: 'speed', value } : undefined
62  }
63  if (word === 'default' || word === 'startup') {
64    if (rest === '') return { kind: 'default' }
65    if (rest === 'on' || rest === 'off') return { kind: 'default', value: rest }
66  }
67  if (word === 'voice' || word === 'voices') {
68    return rest === '' || word === 'voices' ? { kind: 'voice' } : { kind: 'voice', value: rest }
69  }
70  if (word === 'lang' || word === 'language') {
71    return rest === '' ? { kind: 'lang' } : { kind: 'lang', value: rest }
72  }
73  if (word === 'update' || word === 'upgrade') {
74    if (rest === '') return { kind: 'update' }
75    if (rest === 'check' || rest === 'on' || rest === 'off') return { kind: 'update', value: rest }
76  }
77  return undefined
78}
79

1declare module 'claude-code' {
2  interface PluginState {
3    // `disabled`: this session is switched off completely (/tts disable).
4    // Whether this session is muted; unset until the person mutes or unmutes it here.
5    'claudio-tts': { muted: boolean; disabled: boolean }
6  }
7}
8