@drakulavich/kesha-voice-kit 1.18.1 → 1.18.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -51,6 +51,32 @@ kesha audio.ogg # transcript to stdout
51
51
 
52
52
  Air-gapped or behind a corporate mirror? See [docs/model-mirror.md](docs/model-mirror.md).
53
53
 
54
+ ## Shell Completions and Manpage
55
+
56
+ The npm package includes bash, zsh, and fish completions plus `kesha(1)`.
57
+ The CLI can print the packaged files, so install paths do not depend on the
58
+ Bun global package layout:
59
+
60
+ ```bash
61
+ # bash
62
+ mkdir -p ~/.local/share/bash-completion/completions
63
+ kesha completions bash > ~/.local/share/bash-completion/completions/kesha
64
+
65
+ # zsh
66
+ mkdir -p ~/.zsh/completions
67
+ kesha completions zsh > ~/.zsh/completions/_kesha
68
+ # add to ~/.zshrc once: fpath=(~/.zsh/completions $fpath); autoload -Uz compinit; compinit
69
+
70
+ # fish
71
+ mkdir -p ~/.config/fish/completions
72
+ kesha completions fish > ~/.config/fish/completions/kesha.fish
73
+
74
+ # manpage
75
+ mkdir -p ~/.local/share/man/man1
76
+ kesha manpage > ~/.local/share/man/man1/kesha.1
77
+ mandb ~/.local/share/man 2>/dev/null || true
78
+ ```
79
+
54
80
  ## Homebrew Install
55
81
 
56
82
  Homebrew installs the Bun-based CLI wrapper. Engine and model downloads remain
@@ -77,6 +103,39 @@ kesha support-bundle --output kesha-support.tar.gz
77
103
 
78
104
  `support-bundle` creates a redacted `.tar.gz` archive for GitHub issues. It includes runtime, engine, cache, optional-component, Stats status, and known Kesha environment settings. It does not include audio, transcripts, model files, or the Stats database.
79
105
 
106
+ ## Local Stats privacy and lifecycle
107
+
108
+ Kesha Stats is disabled by default. When you opt in with `kesha stats enable`,
109
+ Kesha writes a local SQLite database only on your machine:
110
+
111
+ ```bash
112
+ kesha stats status
113
+ kesha stats week
114
+ kesha stats errors
115
+ kesha stats export --format json # or csv
116
+ kesha stats retention 30 # default: 90 days
117
+ kesha stats retention off # keep until reset
118
+ kesha stats reset # delete recorded stats rows
119
+ kesha stats vacuum # compact the SQLite file
120
+ ```
121
+
122
+ The database stores content-free operational records only: command name
123
+ (`transcribe` or `say`), timestamps, success/failure status, app version, item
124
+ count, anonymous stage timings, input/output artifact kind, file extension,
125
+ size, optional duration/sample-rate/channel counts, and sanitized error
126
+ class/code/message.
127
+
128
+ Stats never stores audio bytes, transcripts, input text, generated speech text,
129
+ file names, full file paths, raw stdout/stderr, environment variables, model
130
+ files, API tokens, or cloud identifiers. `support-bundle` reports Stats status
131
+ only; it never includes the Stats SQLite database.
132
+
133
+ By default, Stats prunes rows older than 90 days before writing or exporting
134
+ data. Use `kesha stats retention <days>` to change the TTL or `kesha stats
135
+ retention off` to disable TTL pruning. `kesha stats reset` deletes recorded
136
+ runs, artifacts, timings, and errors while preserving settings such as enabled
137
+ state and retention.
138
+
80
139
  ## Nix Install
81
140
 
82
141
  Alternative reproducible-build path on `aarch64-darwin` / `x86_64-linux`:
@@ -0,0 +1,38 @@
1
+ # bash completion for kesha.
2
+ # Source this file or copy it into your bash-completion directory.
3
+
4
+ _kesha_completion() {
5
+ local cur command opts commands
6
+ COMPREPLY=()
7
+ cur="${COMP_WORDS[COMP_CWORD]}"
8
+ command="${COMP_WORDS[1]}"
9
+ commands="completions doctor install manpage say stats status support-bundle"
10
+
11
+ if [[ "$COMP_CWORD" -eq 1 ]]; then
12
+ if [[ "$cur" == -* ]]; then
13
+ COMPREPLY=( $(compgen -W "--help -h --version -v --json --toon --timestamps --speakers --include-errors --verbose --format --lang --debug --vad --no-vad" -- "$cur") )
14
+ else
15
+ COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
16
+ fi
17
+ return 0
18
+ fi
19
+
20
+ case "$command" in
21
+ completions) opts="--help -h" ;;
22
+ doctor) opts="--help -h --json --redact" ;;
23
+ install) opts="--help -h --coreml --onnx --no-cache --plan --tts --vad --diarize" ;;
24
+ manpage) opts="--help -h" ;;
25
+ say) opts="--help -h --voice --lang --out --rate --list-voices --ssml --format --bitrate --sample-rate --no-expand-abbrev --verbose --debug" ;;
26
+ stats) opts="--help -h --format" ;;
27
+ status) opts="--help -h --disk" ;;
28
+ support-bundle) opts="--help -h --output" ;;
29
+ *) opts="--help -h --version -v --json --toon --timestamps --speakers --include-errors --verbose --format --lang --debug --vad --no-vad" ;;
30
+ esac
31
+
32
+ if [[ "$cur" == -* ]]; then
33
+ COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
34
+ fi
35
+ }
36
+
37
+ complete -F _kesha_completion kesha
38
+ complete -F _kesha_completion parakeet
@@ -0,0 +1,129 @@
1
+ # fish completion for kesha.
2
+ complete -c kesha -f
3
+ complete -c kesha -n '__fish_use_subcommand' -a 'completions' -d 'Print shell completion script for bash, zsh, or fish'
4
+ complete -c kesha -n '__fish_use_subcommand' -a 'doctor' -d 'Collect support diagnostics without changing local state'
5
+ complete -c kesha -n '__fish_use_subcommand' -a 'install' -d 'Download inference engine and models'
6
+ complete -c kesha -n '__fish_use_subcommand' -a 'manpage' -d 'Print the kesha(1) manpage'
7
+ complete -c kesha -n '__fish_use_subcommand' -a 'say' -d 'Synthesize speech from text (TTS). Writes audio to stdout (or --out file). Defaults to WAV; use --format ogg-opus for messenger-ready voice notes.'
8
+ complete -c kesha -n '__fish_use_subcommand' -a 'stats' -d 'Manage local anonymous Kesha Stats'
9
+ complete -c kesha -n '__fish_use_subcommand' -a 'status' -d 'Show backend installation status'
10
+ complete -c kesha -n '__fish_use_subcommand' -a 'support-bundle' -d 'Create a redacted diagnostics archive for support'
11
+ complete -c kesha -n '__fish_use_subcommand' -l help -d 'Show help'
12
+ complete -c kesha -n '__fish_use_subcommand' -s h -d 'Show help'
13
+ complete -c kesha -n '__fish_use_subcommand' -l version -d 'Show version'
14
+ complete -c kesha -n '__fish_use_subcommand' -s v -d 'Show version'
15
+ complete -c kesha -n '__fish_use_subcommand' -l json -d 'Output results as JSON'
16
+ complete -c kesha -n '__fish_use_subcommand' -l toon -d 'Output results as TOON (compact, LLM-friendly encoding of the same data as --json)'
17
+ complete -c kesha -n '__fish_use_subcommand' -l timestamps -d 'Include timestamped transcript segments in JSON/TOON output'
18
+ complete -c kesha -n '__fish_use_subcommand' -l speakers -d 'Include speaker labels in transcript segments. Requires --json / --toon / --format json. Implies --timestamps. Currently darwin-arm64 only (#199).'
19
+ complete -c kesha -n '__fish_use_subcommand' -l include-errors -d 'With --json, output { results, errors } so scripts can read per-file failures without parsing stderr'
20
+ complete -c kesha -n '__fish_use_subcommand' -l verbose -d 'Show language detection details'
21
+ complete -c kesha -n '__fish_use_subcommand' -l format -r -d 'Output format: transcript | json | toon (long-form alias for --json / --toon)'
22
+ complete -c kesha -n '__fish_use_subcommand' -l lang -r -d 'Expected language code (ISO 639-1), warn if mismatch'
23
+ complete -c kesha -n '__fish_use_subcommand' -l debug -d 'Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)'
24
+ complete -c kesha -n '__fish_use_subcommand' -l vad -d 'Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.'
25
+ complete -c kesha -n '__fish_use_subcommand' -l no-vad -d 'Disable VAD preprocessing regardless of duration or install state'
26
+ complete -c kesha -n '__fish_seen_subcommand_from completions' -l help -d 'Show help'
27
+ complete -c kesha -n '__fish_seen_subcommand_from completions' -s h -d 'Show help'
28
+ complete -c kesha -n '__fish_seen_subcommand_from doctor' -l help -d 'Show help'
29
+ complete -c kesha -n '__fish_seen_subcommand_from doctor' -s h -d 'Show help'
30
+ complete -c kesha -n '__fish_seen_subcommand_from doctor' -l json -d 'Output diagnostics as JSON'
31
+ complete -c kesha -n '__fish_seen_subcommand_from doctor' -l redact -d 'Redact secrets and user-home paths from diagnostic output'
32
+ complete -c kesha -n '__fish_seen_subcommand_from install' -l help -d 'Show help'
33
+ complete -c kesha -n '__fish_seen_subcommand_from install' -s h -d 'Show help'
34
+ complete -c kesha -n '__fish_seen_subcommand_from install' -l coreml -d 'Force CoreML backend (macOS arm64)'
35
+ complete -c kesha -n '__fish_seen_subcommand_from install' -l onnx -d 'Force ONNX backend'
36
+ complete -c kesha -n '__fish_seen_subcommand_from install' -l no-cache -d 'Re-download even if cached'
37
+ complete -c kesha -n '__fish_seen_subcommand_from install' -l plan -d 'Show download, disk, and warm-up plan without changing local state'
38
+ complete -c kesha -n '__fish_seen_subcommand_from install' -l tts -d 'Also install TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)'
39
+ complete -c kesha -n '__fish_seen_subcommand_from install' -l vad -d 'Also install Silero VAD (~2.3MB) for long-audio preprocessing'
40
+ complete -c kesha -n '__fish_seen_subcommand_from install' -l diarize -d 'Also install the Sortformer streaming-diarization model (~245MB, darwin-arm64 only — #199)'
41
+ complete -c kesha -n '__fish_seen_subcommand_from manpage' -l help -d 'Show help'
42
+ complete -c kesha -n '__fish_seen_subcommand_from manpage' -s h -d 'Show help'
43
+ complete -c kesha -n '__fish_seen_subcommand_from say' -l help -d 'Show help'
44
+ complete -c kesha -n '__fish_seen_subcommand_from say' -s h -d 'Show help'
45
+ complete -c kesha -n '__fish_seen_subcommand_from say' -l voice -r -d 'Voice id, e.g. en-am_michael'
46
+ complete -c kesha -n '__fish_seen_subcommand_from say' -l lang -r -d 'BCP 47 language code (default en-us)'
47
+ complete -c kesha -n '__fish_seen_subcommand_from say' -l out -r -d 'Write audio to file instead of stdout'
48
+ complete -c kesha -n '__fish_seen_subcommand_from say' -l rate -r -d 'Speaking rate 0.5–2.0'
49
+ complete -c kesha -n '__fish_seen_subcommand_from say' -l list-voices -d 'List installed voices and exit'
50
+ complete -c kesha -n '__fish_seen_subcommand_from say' -l ssml -d 'Parse input as SSML (supports <speak>, <break>; strips unknown tags)'
51
+ complete -c kesha -n '__fish_seen_subcommand_from say' -l format -r -d 'Output format: wav (default) or ogg-opus (Telegram-ready voice note). Inferred from --out extension when omitted.'
52
+ complete -c kesha -n '__fish_seen_subcommand_from say' -l bitrate -r -d 'Opus bitrate in bits/sec (e.g. 32000). Only with --format ogg-opus.'
53
+ complete -c kesha -n '__fish_seen_subcommand_from say' -l sample-rate -r -d 'Opus encoder sample rate (8000/12000/16000/24000/48000). Only with --format ogg-opus.'
54
+ complete -c kesha -n '__fish_seen_subcommand_from say' -l no-expand-abbrev -d 'Disable Russian acronym auto-expansion (ВОЗ → \'вэ о зэ\') for ru-vosk-* voices. <say-as interpret-as=\'characters\'> still works. Applies to Russian (ru-vosk-*) and English (en-*) voices.'
55
+ complete -c kesha -n '__fish_seen_subcommand_from say' -l verbose -d 'Log TTS synthesis time to stderr'
56
+ complete -c kesha -n '__fish_seen_subcommand_from say' -l debug -d 'Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)'
57
+ complete -c kesha -n '__fish_seen_subcommand_from stats' -l help -d 'Show help'
58
+ complete -c kesha -n '__fish_seen_subcommand_from stats' -s h -d 'Show help'
59
+ complete -c kesha -n '__fish_seen_subcommand_from stats' -l format -r -d 'Export format: json | csv'
60
+ complete -c kesha -n '__fish_seen_subcommand_from status' -l help -d 'Show help'
61
+ complete -c kesha -n '__fish_seen_subcommand_from status' -s h -d 'Show help'
62
+ complete -c kesha -n '__fish_seen_subcommand_from status' -l disk -d 'Include recursive cache disk usage'
63
+ complete -c kesha -n '__fish_seen_subcommand_from support-bundle' -l help -d 'Show help'
64
+ complete -c kesha -n '__fish_seen_subcommand_from support-bundle' -s h -d 'Show help'
65
+ complete -c kesha -n '__fish_seen_subcommand_from support-bundle' -l output -r -d 'Write archive to this .tar.gz path'
66
+ complete -c parakeet -f
67
+ complete -c parakeet -n '__fish_use_subcommand' -a 'completions' -d 'Print shell completion script for bash, zsh, or fish'
68
+ complete -c parakeet -n '__fish_use_subcommand' -a 'doctor' -d 'Collect support diagnostics without changing local state'
69
+ complete -c parakeet -n '__fish_use_subcommand' -a 'install' -d 'Download inference engine and models'
70
+ complete -c parakeet -n '__fish_use_subcommand' -a 'manpage' -d 'Print the kesha(1) manpage'
71
+ complete -c parakeet -n '__fish_use_subcommand' -a 'say' -d 'Synthesize speech from text (TTS). Writes audio to stdout (or --out file). Defaults to WAV; use --format ogg-opus for messenger-ready voice notes.'
72
+ complete -c parakeet -n '__fish_use_subcommand' -a 'stats' -d 'Manage local anonymous Kesha Stats'
73
+ complete -c parakeet -n '__fish_use_subcommand' -a 'status' -d 'Show backend installation status'
74
+ complete -c parakeet -n '__fish_use_subcommand' -a 'support-bundle' -d 'Create a redacted diagnostics archive for support'
75
+ complete -c parakeet -n '__fish_use_subcommand' -l help -d 'Show help'
76
+ complete -c parakeet -n '__fish_use_subcommand' -s h -d 'Show help'
77
+ complete -c parakeet -n '__fish_use_subcommand' -l version -d 'Show version'
78
+ complete -c parakeet -n '__fish_use_subcommand' -s v -d 'Show version'
79
+ complete -c parakeet -n '__fish_use_subcommand' -l json -d 'Output results as JSON'
80
+ complete -c parakeet -n '__fish_use_subcommand' -l toon -d 'Output results as TOON (compact, LLM-friendly encoding of the same data as --json)'
81
+ complete -c parakeet -n '__fish_use_subcommand' -l timestamps -d 'Include timestamped transcript segments in JSON/TOON output'
82
+ complete -c parakeet -n '__fish_use_subcommand' -l speakers -d 'Include speaker labels in transcript segments. Requires --json / --toon / --format json. Implies --timestamps. Currently darwin-arm64 only (#199).'
83
+ complete -c parakeet -n '__fish_use_subcommand' -l include-errors -d 'With --json, output { results, errors } so scripts can read per-file failures without parsing stderr'
84
+ complete -c parakeet -n '__fish_use_subcommand' -l verbose -d 'Show language detection details'
85
+ complete -c parakeet -n '__fish_use_subcommand' -l format -r -d 'Output format: transcript | json | toon (long-form alias for --json / --toon)'
86
+ complete -c parakeet -n '__fish_use_subcommand' -l lang -r -d 'Expected language code (ISO 639-1), warn if mismatch'
87
+ complete -c parakeet -n '__fish_use_subcommand' -l debug -d 'Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)'
88
+ complete -c parakeet -n '__fish_use_subcommand' -l vad -d 'Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.'
89
+ complete -c parakeet -n '__fish_use_subcommand' -l no-vad -d 'Disable VAD preprocessing regardless of duration or install state'
90
+ complete -c parakeet -n '__fish_seen_subcommand_from completions' -l help -d 'Show help'
91
+ complete -c parakeet -n '__fish_seen_subcommand_from completions' -s h -d 'Show help'
92
+ complete -c parakeet -n '__fish_seen_subcommand_from doctor' -l help -d 'Show help'
93
+ complete -c parakeet -n '__fish_seen_subcommand_from doctor' -s h -d 'Show help'
94
+ complete -c parakeet -n '__fish_seen_subcommand_from doctor' -l json -d 'Output diagnostics as JSON'
95
+ complete -c parakeet -n '__fish_seen_subcommand_from doctor' -l redact -d 'Redact secrets and user-home paths from diagnostic output'
96
+ complete -c parakeet -n '__fish_seen_subcommand_from install' -l help -d 'Show help'
97
+ complete -c parakeet -n '__fish_seen_subcommand_from install' -s h -d 'Show help'
98
+ complete -c parakeet -n '__fish_seen_subcommand_from install' -l coreml -d 'Force CoreML backend (macOS arm64)'
99
+ complete -c parakeet -n '__fish_seen_subcommand_from install' -l onnx -d 'Force ONNX backend'
100
+ complete -c parakeet -n '__fish_seen_subcommand_from install' -l no-cache -d 'Re-download even if cached'
101
+ complete -c parakeet -n '__fish_seen_subcommand_from install' -l plan -d 'Show download, disk, and warm-up plan without changing local state'
102
+ complete -c parakeet -n '__fish_seen_subcommand_from install' -l tts -d 'Also install TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)'
103
+ complete -c parakeet -n '__fish_seen_subcommand_from install' -l vad -d 'Also install Silero VAD (~2.3MB) for long-audio preprocessing'
104
+ complete -c parakeet -n '__fish_seen_subcommand_from install' -l diarize -d 'Also install the Sortformer streaming-diarization model (~245MB, darwin-arm64 only — #199)'
105
+ complete -c parakeet -n '__fish_seen_subcommand_from manpage' -l help -d 'Show help'
106
+ complete -c parakeet -n '__fish_seen_subcommand_from manpage' -s h -d 'Show help'
107
+ complete -c parakeet -n '__fish_seen_subcommand_from say' -l help -d 'Show help'
108
+ complete -c parakeet -n '__fish_seen_subcommand_from say' -s h -d 'Show help'
109
+ complete -c parakeet -n '__fish_seen_subcommand_from say' -l voice -r -d 'Voice id, e.g. en-am_michael'
110
+ complete -c parakeet -n '__fish_seen_subcommand_from say' -l lang -r -d 'BCP 47 language code (default en-us)'
111
+ complete -c parakeet -n '__fish_seen_subcommand_from say' -l out -r -d 'Write audio to file instead of stdout'
112
+ complete -c parakeet -n '__fish_seen_subcommand_from say' -l rate -r -d 'Speaking rate 0.5–2.0'
113
+ complete -c parakeet -n '__fish_seen_subcommand_from say' -l list-voices -d 'List installed voices and exit'
114
+ complete -c parakeet -n '__fish_seen_subcommand_from say' -l ssml -d 'Parse input as SSML (supports <speak>, <break>; strips unknown tags)'
115
+ complete -c parakeet -n '__fish_seen_subcommand_from say' -l format -r -d 'Output format: wav (default) or ogg-opus (Telegram-ready voice note). Inferred from --out extension when omitted.'
116
+ complete -c parakeet -n '__fish_seen_subcommand_from say' -l bitrate -r -d 'Opus bitrate in bits/sec (e.g. 32000). Only with --format ogg-opus.'
117
+ complete -c parakeet -n '__fish_seen_subcommand_from say' -l sample-rate -r -d 'Opus encoder sample rate (8000/12000/16000/24000/48000). Only with --format ogg-opus.'
118
+ complete -c parakeet -n '__fish_seen_subcommand_from say' -l no-expand-abbrev -d 'Disable Russian acronym auto-expansion (ВОЗ → \'вэ о зэ\') for ru-vosk-* voices. <say-as interpret-as=\'characters\'> still works. Applies to Russian (ru-vosk-*) and English (en-*) voices.'
119
+ complete -c parakeet -n '__fish_seen_subcommand_from say' -l verbose -d 'Log TTS synthesis time to stderr'
120
+ complete -c parakeet -n '__fish_seen_subcommand_from say' -l debug -d 'Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)'
121
+ complete -c parakeet -n '__fish_seen_subcommand_from stats' -l help -d 'Show help'
122
+ complete -c parakeet -n '__fish_seen_subcommand_from stats' -s h -d 'Show help'
123
+ complete -c parakeet -n '__fish_seen_subcommand_from stats' -l format -r -d 'Export format: json | csv'
124
+ complete -c parakeet -n '__fish_seen_subcommand_from status' -l help -d 'Show help'
125
+ complete -c parakeet -n '__fish_seen_subcommand_from status' -s h -d 'Show help'
126
+ complete -c parakeet -n '__fish_seen_subcommand_from status' -l disk -d 'Include recursive cache disk usage'
127
+ complete -c parakeet -n '__fish_seen_subcommand_from support-bundle' -l help -d 'Show help'
128
+ complete -c parakeet -n '__fish_seen_subcommand_from support-bundle' -s h -d 'Show help'
129
+ complete -c parakeet -n '__fish_seen_subcommand_from support-bundle' -l output -r -d 'Write archive to this .tar.gz path'
@@ -0,0 +1,117 @@
1
+ #compdef kesha parakeet
2
+ # zsh completion for kesha.
3
+
4
+ _kesha() {
5
+ local -a commands
6
+ commands=(
7
+ 'completions:Print shell completion script for bash, zsh, or fish'
8
+ 'doctor:Collect support diagnostics without changing local state'
9
+ 'install:Download inference engine and models'
10
+ 'manpage:Print the kesha(1) manpage'
11
+ 'say:Synthesize speech from text (TTS). Writes audio to stdout (or --out file). Defaults to WAV; use --format ogg-opus for messenger-ready voice notes.'
12
+ 'stats:Manage local anonymous Kesha Stats'
13
+ 'status:Show backend installation status'
14
+ 'support-bundle:Create a redacted diagnostics archive for support'
15
+ )
16
+
17
+ if (( CURRENT == 2 )); then
18
+ if [[ "$words[CURRENT]" == -* ]]; then
19
+ _arguments '--help[Show help]' \
20
+ '-h[Show help]' \
21
+ '--version[Show version]' \
22
+ '-v[Show version]' \
23
+ '--json[Output results as JSON]' \
24
+ '--toon[Output results as TOON (compact, LLM-friendly encoding of the same data as --json)]' \
25
+ '--timestamps[Include timestamped transcript segments in JSON/TOON output]' \
26
+ '--speakers[Include speaker labels in transcript segments. Requires --json / --toon / --format json. Implies --timestamps. Currently darwin-arm64 only (#199).]' \
27
+ '--include-errors[With --json, output { results, errors } so scripts can read per-file failures without parsing stderr]' \
28
+ '--verbose[Show language detection details]' \
29
+ '--format=[Output format: transcript | json | toon (long-form alias for --json / --toon)]:format:' \
30
+ '--lang=[Expected language code (ISO 639-1), warn if mismatch]:lang:' \
31
+ '--debug[Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)]' \
32
+ '--vad[Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.]' \
33
+ '--no-vad[Disable VAD preprocessing regardless of duration or install state]'
34
+ else
35
+ _describe -t commands 'kesha command' commands
36
+ fi
37
+ return
38
+ fi
39
+
40
+ case "$words[2]" in
41
+ completions)
42
+ _arguments '--help[Show help]' \
43
+ '-h[Show help]'
44
+ ;;
45
+ doctor)
46
+ _arguments '--help[Show help]' \
47
+ '-h[Show help]' \
48
+ '--json[Output diagnostics as JSON]' \
49
+ '--redact[Redact secrets and user-home paths from diagnostic output]'
50
+ ;;
51
+ install)
52
+ _arguments '--help[Show help]' \
53
+ '-h[Show help]' \
54
+ '--coreml[Force CoreML backend (macOS arm64)]' \
55
+ '--onnx[Force ONNX backend]' \
56
+ '--no-cache[Re-download even if cached]' \
57
+ '--plan[Show download, disk, and warm-up plan without changing local state]' \
58
+ '--tts[Also install TTS models (Kokoro EN + Vosk-TTS RU, ~990MB)]' \
59
+ '--vad[Also install Silero VAD (~2.3MB) for long-audio preprocessing]' \
60
+ '--diarize[Also install the Sortformer streaming-diarization model (~245MB, darwin-arm64 only — #199)]'
61
+ ;;
62
+ manpage)
63
+ _arguments '--help[Show help]' \
64
+ '-h[Show help]'
65
+ ;;
66
+ say)
67
+ _arguments '--help[Show help]' \
68
+ '-h[Show help]' \
69
+ '--voice=[Voice id, e.g. en-am_michael]:voice:' \
70
+ '--lang=[BCP 47 language code (default en-us)]:lang:' \
71
+ '--out=[Write audio to file instead of stdout]:out:' \
72
+ '--rate=[Speaking rate 0.5–2.0]:rate:' \
73
+ '--list-voices[List installed voices and exit]' \
74
+ '--ssml[Parse input as SSML (supports <speak>, <break>; strips unknown tags)]' \
75
+ '--format=[Output format: wav (default) or ogg-opus (Telegram-ready voice note). Inferred from --out extension when omitted.]:format:' \
76
+ '--bitrate=[Opus bitrate in bits/sec (e.g. 32000). Only with --format ogg-opus.]:bitrate:' \
77
+ '--sample-rate=[Opus encoder sample rate (8000/12000/16000/24000/48000). Only with --format ogg-opus.]:sample rate:' \
78
+ '--no-expand-abbrev[Disable Russian acronym auto-expansion (ВОЗ → '\''вэ о зэ'\'') for ru-vosk-* voices. <say-as interpret-as='\''characters'\''> still works. Applies to Russian (ru-vosk-*) and English (en-*) voices.]' \
79
+ '--verbose[Log TTS synthesis time to stderr]' \
80
+ '--debug[Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)]'
81
+ ;;
82
+ stats)
83
+ _arguments '--help[Show help]' \
84
+ '-h[Show help]' \
85
+ '--format=[Export format: json | csv]:format:'
86
+ ;;
87
+ status)
88
+ _arguments '--help[Show help]' \
89
+ '-h[Show help]' \
90
+ '--disk[Include recursive cache disk usage]'
91
+ ;;
92
+ support-bundle)
93
+ _arguments '--help[Show help]' \
94
+ '-h[Show help]' \
95
+ '--output=[Write archive to this .tar.gz path]:output:'
96
+ ;;
97
+ *)
98
+ _arguments '--help[Show help]' \
99
+ '-h[Show help]' \
100
+ '--version[Show version]' \
101
+ '-v[Show version]' \
102
+ '--json[Output results as JSON]' \
103
+ '--toon[Output results as TOON (compact, LLM-friendly encoding of the same data as --json)]' \
104
+ '--timestamps[Include timestamped transcript segments in JSON/TOON output]' \
105
+ '--speakers[Include speaker labels in transcript segments. Requires --json / --toon / --format json. Implies --timestamps. Currently darwin-arm64 only (#199).]' \
106
+ '--include-errors[With --json, output { results, errors } so scripts can read per-file failures without parsing stderr]' \
107
+ '--verbose[Show language detection details]' \
108
+ '--format=[Output format: transcript | json | toon (long-form alias for --json / --toon)]:format:' \
109
+ '--lang=[Expected language code (ISO 639-1), warn if mismatch]:lang:' \
110
+ '--debug[Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)]' \
111
+ '--vad[Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.]' \
112
+ '--no-vad[Disable VAD preprocessing regardless of duration or install state]'
113
+ ;;
114
+ esac
115
+ }
116
+
117
+ _kesha "$@"
package/man/kesha.1 ADDED
@@ -0,0 +1,161 @@
1
+ .TH KESHA 1 "May 2026" "kesha 1.18.2" "User Commands"
2
+ .SH NAME
3
+ kesha \- open-source local voice toolkit
4
+ .SH SYNOPSIS
5
+ .B kesha
6
+ [OPTIONS] AUDIO_FILE...
7
+ .br
8
+ .B kesha
9
+ COMMAND [OPTIONS]
10
+ .SH DESCRIPTION
11
+ Kesha Voice Kit is a local speech-to-text and text-to-speech toolkit with a Bun TypeScript CLI and a Rust engine.
12
+ .SH COMMANDS
13
+ .TP
14
+ .B completions
15
+ Print shell completion script for bash, zsh, or fish
16
+ .TP
17
+ .B doctor
18
+ Collect support diagnostics without changing local state
19
+ .TP
20
+ .B install
21
+ Download inference engine and models
22
+ .TP
23
+ .B manpage
24
+ Print the kesha(1) manpage
25
+ .TP
26
+ .B say
27
+ Synthesize speech from text (TTS). Writes audio to stdout (or \-\-out file). Defaults to WAV; use \-\-format ogg\-opus for messenger\-ready voice notes.
28
+ .TP
29
+ .B stats
30
+ Manage local anonymous Kesha Stats
31
+ .TP
32
+ .B status
33
+ Show backend installation status
34
+ .TP
35
+ .B support-bundle
36
+ Create a redacted diagnostics archive for support
37
+ .SH OPTIONS
38
+ .TP
39
+ .B \-\-json
40
+ Output results as JSON
41
+ .TP
42
+ .B \-\-toon
43
+ Output results as TOON (compact, LLM\-friendly encoding of the same data as \-\-json)
44
+ .TP
45
+ .B \-\-timestamps
46
+ Include timestamped transcript segments in JSON/TOON output
47
+ .TP
48
+ .B \-\-speakers
49
+ Include speaker labels in transcript segments. Requires \-\-json / \-\-toon / \-\-format json. Implies \-\-timestamps. Currently darwin\-arm64 only (#199).
50
+ .TP
51
+ .B \-\-include\-errors
52
+ With \-\-json, output { results, errors } so scripts can read per\-file failures without parsing stderr
53
+ .TP
54
+ .B \-\-verbose
55
+ Show language detection details
56
+ .TP
57
+ .B \-\-format
58
+ Output format: transcript | json | toon (long\-form alias for \-\-json / \-\-toon)
59
+ .TP
60
+ .B \-\-lang
61
+ Expected language code (ISO 639\-1), warn if mismatch
62
+ .TP
63
+ .B \-\-debug
64
+ Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)
65
+ .TP
66
+ .B \-\-vad
67
+ Force Silero VAD preprocessing (kesha install \-\-vad first). Without this, VAD auto\-engages on audio ≥ 120s.
68
+ .TP
69
+ .B \-\-no\-vad
70
+ Disable VAD preprocessing regardless of duration or install state
71
+ .SH SUBCOMMAND OPTIONS
72
+ .SS doctor
73
+ .TP
74
+ .B \-\-json
75
+ Output diagnostics as JSON
76
+ .TP
77
+ .B \-\-redact
78
+ Redact secrets and user\-home paths from diagnostic output
79
+ .SS install
80
+ .TP
81
+ .B \-\-coreml
82
+ Force CoreML backend (macOS arm64)
83
+ .TP
84
+ .B \-\-onnx
85
+ Force ONNX backend
86
+ .TP
87
+ .B \-\-no\-cache
88
+ Re\-download even if cached
89
+ .TP
90
+ .B \-\-plan
91
+ Show download, disk, and warm\-up plan without changing local state
92
+ .TP
93
+ .B \-\-tts
94
+ Also install TTS models (Kokoro EN + Vosk\-TTS RU, ~990MB)
95
+ .TP
96
+ .B \-\-vad
97
+ Also install Silero VAD (~2.3MB) for long\-audio preprocessing
98
+ .TP
99
+ .B \-\-diarize
100
+ Also install the Sortformer streaming\-diarization model (~245MB, darwin\-arm64 only — #199)
101
+ .SS say
102
+ .TP
103
+ .B \-\-voice
104
+ Voice id, e.g. en\-am_michael
105
+ .TP
106
+ .B \-\-lang
107
+ BCP 47 language code (default en\-us)
108
+ .TP
109
+ .B \-\-out
110
+ Write audio to file instead of stdout
111
+ .TP
112
+ .B \-\-rate
113
+ Speaking rate 0.5–2.0
114
+ .TP
115
+ .B \-\-list\-voices
116
+ List installed voices and exit
117
+ .TP
118
+ .B \-\-ssml
119
+ Parse input as SSML (supports <speak>, <break>; strips unknown tags)
120
+ .TP
121
+ .B \-\-format
122
+ Output format: wav (default) or ogg\-opus (Telegram\-ready voice note). Inferred from \-\-out extension when omitted.
123
+ .TP
124
+ .B \-\-bitrate
125
+ Opus bitrate in bits/sec (e.g. 32000). Only with \-\-format ogg\-opus.
126
+ .TP
127
+ .B \-\-sample\-rate
128
+ Opus encoder sample rate (8000/12000/16000/24000/48000). Only with \-\-format ogg\-opus.
129
+ .TP
130
+ .B \-\-no\-expand\-abbrev
131
+ Disable Russian acronym auto\-expansion (ВОЗ → 'вэ о зэ') for ru\-vosk\-* voices. <say\-as interpret\-as='characters'> still works. Applies to Russian (ru\-vosk\-*) and English (en\-*) voices.
132
+ .TP
133
+ .B \-\-verbose
134
+ Log TTS synthesis time to stderr
135
+ .TP
136
+ .B \-\-debug
137
+ Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)
138
+ .SS stats
139
+ .TP
140
+ .B \-\-format
141
+ Export format: json | csv
142
+ .SS status
143
+ .TP
144
+ .B \-\-disk
145
+ Include recursive cache disk usage
146
+ .SS support-bundle
147
+ .TP
148
+ .B \-\-output
149
+ Write archive to this .tar.gz path
150
+ .SH FILES
151
+ .TP
152
+ .B completions/kesha.bash
153
+ Bash completion script included in the npm package.
154
+ .TP
155
+ .B completions/kesha.zsh
156
+ Zsh completion script included in the npm package.
157
+ .TP
158
+ .B completions/kesha.fish
159
+ Fish completion script included in the npm package.
160
+ .SH SEE ALSO
161
+ .BR bun (1)
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@drakulavich/kesha-voice-kit",
3
- "version": "1.18.1",
4
- "description": "Open-source voice toolkit. Speech-to-text (25 langs, ~19x faster than Whisper on Apple Silicon, ONNX fallback on CPU), text-to-speech (Kokoro + Vosk-TTS + ~180 macOS system voices, SSML), voice-activity detection, language detection (107 langs). Rust engine, OpenClaw skill.",
3
+ "version": "1.18.2",
4
+ "description": "Give your local tools a voice: fast STT in 25 languages (~19x faster than Whisper on Apple Silicon, ONNX CPU fallback), TTS via Kokoro/Vosk/macOS voices, VAD + 107-language detection. Rust engine, Bun CLI, OpenClaw skill.",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "kesha": "bin/kesha.js",
@@ -13,6 +13,8 @@
13
13
  },
14
14
  "files": [
15
15
  "bin/",
16
+ "completions/",
17
+ "man/",
16
18
  "src/",
17
19
  "package.json",
18
20
  "tsconfig.json",
@@ -38,6 +40,11 @@
38
40
  "test:unit": "bun test tests/unit/",
39
41
  "test:cli-fast": "bun test tests/unit/ tests/integration/cli-contracts.test.ts tests/integration/e2e-cli.test.ts tests/integration/say.test.ts",
40
42
  "test:integration": "bun test tests/integration/",
43
+ "coverage:ts": "bun run test:cli-fast --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir=coverage/ts",
44
+ "coverage:check:ts": "bun .github/scripts/check-coverage.ts --preset=ts --lcov=coverage/ts/lcov.info --summary=coverage/ts/summary.md",
45
+ "coverage:rust": "mkdir -p coverage/rust && cd rust && cargo llvm-cov nextest --features tts --lcov --output-path ../coverage/rust/lcov.info",
46
+ "coverage:check:rust": "bun .github/scripts/check-coverage.ts --preset=rust --lcov=coverage/rust/lcov.info --summary=coverage/rust/summary.md",
47
+ "generate:shell-artifacts": "bun scripts/generate-shell-artifacts.ts",
41
48
  "lint": "bunx tsc --noEmit",
42
49
  "lint:tsgo": "bunx tsgo --noEmit",
43
50
  "check": "bun run lint && bun run check:versions && bun run test:cli-fast",
@@ -0,0 +1,41 @@
1
+ import { defineCommand } from "citty";
2
+ import { log } from "../log";
3
+
4
+ const SHELL_FILES = {
5
+ bash: "kesha.bash",
6
+ zsh: "kesha.zsh",
7
+ fish: "kesha.fish",
8
+ } as const;
9
+
10
+ type Shell = keyof typeof SHELL_FILES;
11
+
12
+ interface CompletionsCommandArgs {
13
+ shell?: string;
14
+ }
15
+
16
+ function isShell(value: string): value is Shell {
17
+ return value === "bash" || value === "zsh" || value === "fish";
18
+ }
19
+
20
+ export const completionsCommand = defineCommand({
21
+ meta: {
22
+ name: "completions",
23
+ description: "Print shell completion script for bash, zsh, or fish",
24
+ },
25
+ args: {
26
+ shell: {
27
+ type: "positional",
28
+ required: true,
29
+ description: "Shell: bash | zsh | fish",
30
+ },
31
+ },
32
+ async run({ args }: { args: CompletionsCommandArgs }) {
33
+ const shell = args.shell;
34
+ if (!shell || !isShell(shell)) {
35
+ log.error("usage: kesha completions <bash|zsh|fish>");
36
+ process.exit(2);
37
+ }
38
+ const file = new URL(`../../completions/${SHELL_FILES[shell]}`, import.meta.url);
39
+ process.stdout.write(await Bun.file(file).text());
40
+ },
41
+ });
@@ -2,15 +2,17 @@ import { runMain } from "citty";
2
2
  import { existsSync } from "fs";
3
3
  import { log } from "../log";
4
4
  import { suggestCommand } from "../suggest-command";
5
+ import { completionsCommand } from "./completions";
5
6
  import { doctorCommand } from "./doctor";
6
7
  import { installCommand } from "./install";
8
+ import { manpageCommand } from "./manpage";
7
9
  import { sayCommand } from "./say";
8
10
  import { statsCommand } from "./stats";
9
11
  import { statusCommand } from "./status";
10
12
  import { supportBundleCommand } from "./support-bundle";
11
13
  import { mainCommand } from "./main";
12
14
 
13
- const SUBCOMMANDS = ["doctor", "install", "status", "say", "stats", "support-bundle"];
15
+ const SUBCOMMANDS = ["doctor", "install", "status", "say", "stats", "support-bundle", "completions", "manpage"];
14
16
 
15
17
  function isPathLike(arg: string): boolean {
16
18
  return arg.includes(".") || arg.includes("/") || existsSync(arg);
@@ -24,11 +26,21 @@ export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {
24
26
  return;
25
27
  }
26
28
 
29
+ if (firstArg === "completions") {
30
+ await runMain(completionsCommand, { rawArgs: restArgs });
31
+ return;
32
+ }
33
+
27
34
  if (firstArg === "install") {
28
35
  await runMain(installCommand, { rawArgs: restArgs });
29
36
  return;
30
37
  }
31
38
 
39
+ if (firstArg === "manpage") {
40
+ await runMain(manpageCommand, { rawArgs: restArgs });
41
+ return;
42
+ }
43
+
32
44
  if (firstArg === "status") {
33
45
  await runMain(statusCommand, { rawArgs: restArgs });
34
46
  return;