@charivo/stt 0.9.0 → 0.10.0

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
@@ -37,14 +37,36 @@ const text = await sttManager.stop();
37
37
  `gemini-3.5-transcribe`. `language` is optional and only a soft hint —
38
38
  the model transcribes what it hears even when the hint is wrong. `timeoutMs`
39
39
  defaults to 30s and also covers reading the response body. Inline requests
40
- are capped at 20MB, and there is no streaming: the live transcription model
41
- is a separate transport. Gemini's free-tier rate limit surfaces as a 429
42
- wrapped in a provider error.
40
+ are capped at 20MB, and there is no streaming: `gemini-3.5-transcribe-live`
41
+ is WebSocket-only — `generateContent` rejects it with a 400 — and is served by
42
+ `@charivo/stt/gemini-live` below. Gemini's free-tier rate limit surfaces as a
43
+ 429 wrapped in a provider error.
43
44
  - `@charivo/stt/openai-realtime`: `createOpenAIRealtimeSTTTranscriber({ bootstrap })`
44
45
  (live WebRTC streaming transcriber, `gpt-realtime-whisper`) — the app injects
45
46
  `bootstrap(request) => Promise<{ answerSdp }>`, owns the credentials, and
46
47
  mints the `type: "transcription"` session with `turn_detection: null`; no
47
48
  key-bearing helper is shipped
49
+ - `@charivo/stt/gemini-live`: `createGeminiLiveSTTTranscriber({ bootstrap })`
50
+ (live WebSocket streaming transcriber over the Gemini Live API,
51
+ `gemini-3.5-transcribe-live`) — the app injects
52
+ `bootstrap(request) => Promise<{ url, token }>`, owns the credentials, and
53
+ mints the single-use ephemeral token whose setup pins the model, the `TEXT`
54
+ response modality, and manual VAD. No key-bearing helper is shipped, but
55
+ unlike the OpenAI path's SDP answer that token is itself a credential: the
56
+ browser holds it for the life of one recording. `url` must be the Live
57
+ API's `BidiGenerateContentConstrained` websocket endpoint (the
58
+ ephemeral-token one), with scheme `ws:` or `wss:` (the transcriber rejects
59
+ any other scheme) and no fragment (the native `WebSocket` constructor
60
+ rejects one); the transcriber parses `url` and adds `access_token` as a
61
+ query parameter, so an existing query string on it survives. Pinning manual
62
+ VAD in the token is a requirement rather than a detail: its
63
+ `bidiGenerateContentSetup` replaces the setup frame the transcriber sends
64
+ rather than merging with it, so a bootstrap that leaves manual VAD out
65
+ silently loses the recording — server VAD cuts the audio at every pause,
66
+ each transcription replaces the running snapshot instead of extending it,
67
+ and `stop()` then returns the last segment alone or times out. Each
68
+ `stt:partial` is a whole-recording snapshot that may be *revised*, not a
69
+ delta, so a UI must replace its draft rather than append to it
48
70
 
49
71
  ## Event Bridge
50
72
 
@@ -55,10 +77,11 @@ through the shared event bus.
55
77
  When connected, the manager emits:
56
78
 
57
79
  - `stt:start`
58
- - `stt:partial` (streaming transcribers only, e.g. `@charivo/stt/openai-realtime`)
80
+ - `stt:partial` (streaming transcribers only — `@charivo/stt/openai-realtime`
81
+ and `@charivo/stt/gemini-live`)
59
82
  - `stt:stop`
60
83
  - `stt:error`
61
84
 
62
- For the streaming transcriber, a mid-session failure does not push an event on
63
- its own — it surfaces the next time the app calls `stop()`, which rejects and
85
+ For either streaming transcriber, a mid-session failure does not push an event
86
+ on its own — it surfaces the next time the app calls `stop()`, which rejects and
64
87
  emits `stt:error` (never a successful `stt:stop`).
@@ -18,8 +18,10 @@ interface GeminiSTTConfig {
18
18
  * `STTOptions.language` is optional and only a soft hint — the model
19
19
  * transcribes what it hears even when the hint is wrong.
20
20
  *
21
- * One request per utterance, with no streaming; the live transcription model is
22
- * a separate transport. Measured latency is 1.5-3.4s on a 4s clip.
21
+ * One request per utterance, with no streaming: the live transcription model
22
+ * (`gemini-3.5-transcribe-live`) is WebSocket-only, `generateContent` rejects
23
+ * it with a 400, and it is served by `@charivo/stt/gemini-live`. Measured
24
+ * latency is 1.5-3.4s on a 4s clip.
23
25
  *
24
26
  * The free tier allows 3 requests per minute; beyond that the 429 surfaces as a
25
27
  * CharivoProviderError carrying Google's retry hint.
@@ -18,8 +18,10 @@ interface GeminiSTTConfig {
18
18
  * `STTOptions.language` is optional and only a soft hint — the model
19
19
  * transcribes what it hears even when the hint is wrong.
20
20
  *
21
- * One request per utterance, with no streaming; the live transcription model is
22
- * a separate transport. Measured latency is 1.5-3.4s on a 4s clip.
21
+ * One request per utterance, with no streaming: the live transcription model
22
+ * (`gemini-3.5-transcribe-live`) is WebSocket-only, `generateContent` rejects
23
+ * it with a 400, and it is served by `@charivo/stt/gemini-live`. Measured
24
+ * latency is 1.5-3.4s on a 4s clip.
23
25
  *
24
26
  * The free tier allows 3 requests per minute; beyond that the 429 surfaces as a
25
27
  * CharivoProviderError carrying Google's retry hint.
@@ -0,0 +1,19 @@
1
+ import { STTTranscriber } from '@charivo/core';
2
+
3
+ interface GeminiLiveTranscriptionSessionRequest {
4
+ session: {
5
+ model: string;
6
+ language?: string;
7
+ };
8
+ }
9
+ interface GeminiLiveTranscriptionBootstrap {
10
+ url: string;
11
+ token: string;
12
+ }
13
+ type GeminiLiveTranscriptionBootstrapFn = (request: GeminiLiveTranscriptionSessionRequest) => Promise<GeminiLiveTranscriptionBootstrap>;
14
+ interface GeminiLiveSTTTranscriberConfig {
15
+ bootstrap: GeminiLiveTranscriptionBootstrapFn;
16
+ }
17
+ declare function createGeminiLiveSTTTranscriber(config: GeminiLiveSTTTranscriberConfig): STTTranscriber;
18
+
19
+ export { type GeminiLiveSTTTranscriberConfig, type GeminiLiveTranscriptionBootstrap, type GeminiLiveTranscriptionBootstrapFn, type GeminiLiveTranscriptionSessionRequest, createGeminiLiveSTTTranscriber };
@@ -0,0 +1,19 @@
1
+ import { STTTranscriber } from '@charivo/core';
2
+
3
+ interface GeminiLiveTranscriptionSessionRequest {
4
+ session: {
5
+ model: string;
6
+ language?: string;
7
+ };
8
+ }
9
+ interface GeminiLiveTranscriptionBootstrap {
10
+ url: string;
11
+ token: string;
12
+ }
13
+ type GeminiLiveTranscriptionBootstrapFn = (request: GeminiLiveTranscriptionSessionRequest) => Promise<GeminiLiveTranscriptionBootstrap>;
14
+ interface GeminiLiveSTTTranscriberConfig {
15
+ bootstrap: GeminiLiveTranscriptionBootstrapFn;
16
+ }
17
+ declare function createGeminiLiveSTTTranscriber(config: GeminiLiveSTTTranscriberConfig): STTTranscriber;
18
+
19
+ export { type GeminiLiveSTTTranscriberConfig, type GeminiLiveTranscriptionBootstrap, type GeminiLiveTranscriptionBootstrapFn, type GeminiLiveTranscriptionSessionRequest, createGeminiLiveSTTTranscriber };