@charivo/stt 0.2.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Zeikar
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,41 @@
1
+ # @charivo/stt
2
+
3
+ Stateful STT manager and recording helper for Charivo.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ pnpm add @charivo/stt
9
+ ```
10
+
11
+ ## Usage
12
+
13
+ ```ts
14
+ import { createSTTManager } from "@charivo/stt";
15
+ import { createRemoteSTTTranscriber } from "@charivo/stt/remote";
16
+
17
+ const sttManager = createSTTManager(
18
+ createRemoteSTTTranscriber({ apiEndpoint: "/api/stt" }),
19
+ );
20
+
21
+ await sttManager.start({ language: "ko" });
22
+ const text = await sttManager.stop();
23
+ ```
24
+
25
+ ## Exports
26
+
27
+ - `STTManagerImpl`
28
+ - `createSTTManager(transcriber)`
29
+ - `MediaRecorderHelper`
30
+
31
+ ## Event Bridge
32
+
33
+ `STTManager` accepts an emit-only event bridge through `setEventEmitter(...)`.
34
+ It emits STT lifecycle and error events back into core, and does not subscribe
35
+ through the shared event bus.
36
+
37
+ When connected, the manager emits:
38
+
39
+ - `stt:start`
40
+ - `stt:stop`
41
+ - `stt:error`
@@ -0,0 +1,68 @@
1
+ // src/media-recorder-helper.ts
2
+ var MediaRecorderHelper = class {
3
+ mediaRecorder = null;
4
+ audioChunks = [];
5
+ recording = false;
6
+ /**
7
+ * Start audio recording from user's microphone
8
+ */
9
+ async start() {
10
+ if (this.recording) {
11
+ throw new Error("Already recording");
12
+ }
13
+ const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
14
+ this.mediaRecorder = new MediaRecorder(stream);
15
+ this.audioChunks = [];
16
+ this.mediaRecorder.ondataavailable = (event) => {
17
+ if (event.data.size > 0) {
18
+ this.audioChunks.push(event.data);
19
+ }
20
+ };
21
+ this.mediaRecorder.start();
22
+ this.recording = true;
23
+ }
24
+ /**
25
+ * Stop audio recording and return the recorded audio as a Blob
26
+ */
27
+ async stop() {
28
+ if (!this.recording || !this.mediaRecorder) {
29
+ throw new Error("Not recording");
30
+ }
31
+ return new Promise((resolve, reject) => {
32
+ this.mediaRecorder.onstop = () => {
33
+ const audioBlob = new Blob(this.audioChunks, { type: "audio/webm" });
34
+ this.audioChunks = [];
35
+ this.mediaRecorder?.stream.getTracks().forEach((track) => track.stop());
36
+ this.mediaRecorder = null;
37
+ this.recording = false;
38
+ resolve(audioBlob);
39
+ };
40
+ this.mediaRecorder.onerror = (error) => {
41
+ this.recording = false;
42
+ reject(error);
43
+ };
44
+ this.mediaRecorder.stop();
45
+ });
46
+ }
47
+ /**
48
+ * Check if currently recording
49
+ */
50
+ isRecording() {
51
+ return this.recording;
52
+ }
53
+ /**
54
+ * Abort recording immediately without returning data
55
+ */
56
+ abort() {
57
+ if (this.mediaRecorder) {
58
+ this.mediaRecorder.stream.getTracks().forEach((track) => track.stop());
59
+ this.mediaRecorder = null;
60
+ this.audioChunks = [];
61
+ this.recording = false;
62
+ }
63
+ }
64
+ };
65
+
66
+ export {
67
+ MediaRecorderHelper
68
+ };
@@ -0,0 +1,68 @@
1
+ import { STTManager, STTTranscriber, CharivoEventEmitter, STTOptions } from '@charivo/core';
2
+
3
+ /**
4
+ * STT Manager - Manages STT session state
5
+ *
6
+ * Simplified design: Delegates to STTTranscriber
7
+ * - STTTranscriber handles recording internally
8
+ * - Manager only handles event emission
9
+ * - Thin wrapper for consistent API
10
+ */
11
+ declare class STTManagerImpl implements STTManager {
12
+ private sttTranscriber;
13
+ private eventEmitter?;
14
+ constructor(sttTranscriber: STTTranscriber);
15
+ /**
16
+ * Set event emitter for STT events
17
+ */
18
+ setEventEmitter(eventEmitter: CharivoEventEmitter): void;
19
+ /**
20
+ * Start audio recording (delegates to transcriber)
21
+ */
22
+ start(options?: STTOptions): Promise<void>;
23
+ /**
24
+ * Stop audio recording and get transcription (delegates to transcriber)
25
+ */
26
+ stop(): Promise<string>;
27
+ /**
28
+ * Check if currently recording (delegates to transcriber)
29
+ */
30
+ isRecording(): boolean;
31
+ }
32
+ /**
33
+ * Helper function to create STT Manager
34
+ */
35
+ declare function createSTTManager(sttTranscriber: STTTranscriber): STTManager;
36
+
37
+ /**
38
+ * MediaRecorderHelper - Browser audio recording utility
39
+ *
40
+ * Handles MediaRecorder lifecycle:
41
+ * - Start/stop recording
42
+ * - Audio chunk collection
43
+ * - Stream cleanup
44
+ * - Blob generation
45
+ */
46
+ declare class MediaRecorderHelper {
47
+ private mediaRecorder;
48
+ private audioChunks;
49
+ private recording;
50
+ /**
51
+ * Start audio recording from user's microphone
52
+ */
53
+ start(): Promise<void>;
54
+ /**
55
+ * Stop audio recording and return the recorded audio as a Blob
56
+ */
57
+ stop(): Promise<Blob>;
58
+ /**
59
+ * Check if currently recording
60
+ */
61
+ isRecording(): boolean;
62
+ /**
63
+ * Abort recording immediately without returning data
64
+ */
65
+ abort(): void;
66
+ }
67
+
68
+ export { MediaRecorderHelper, STTManagerImpl, createSTTManager };
@@ -0,0 +1,68 @@
1
+ import { STTManager, STTTranscriber, CharivoEventEmitter, STTOptions } from '@charivo/core';
2
+
3
+ /**
4
+ * STT Manager - Manages STT session state
5
+ *
6
+ * Simplified design: Delegates to STTTranscriber
7
+ * - STTTranscriber handles recording internally
8
+ * - Manager only handles event emission
9
+ * - Thin wrapper for consistent API
10
+ */
11
+ declare class STTManagerImpl implements STTManager {
12
+ private sttTranscriber;
13
+ private eventEmitter?;
14
+ constructor(sttTranscriber: STTTranscriber);
15
+ /**
16
+ * Set event emitter for STT events
17
+ */
18
+ setEventEmitter(eventEmitter: CharivoEventEmitter): void;
19
+ /**
20
+ * Start audio recording (delegates to transcriber)
21
+ */
22
+ start(options?: STTOptions): Promise<void>;
23
+ /**
24
+ * Stop audio recording and get transcription (delegates to transcriber)
25
+ */
26
+ stop(): Promise<string>;
27
+ /**
28
+ * Check if currently recording (delegates to transcriber)
29
+ */
30
+ isRecording(): boolean;
31
+ }
32
+ /**
33
+ * Helper function to create STT Manager
34
+ */
35
+ declare function createSTTManager(sttTranscriber: STTTranscriber): STTManager;
36
+
37
+ /**
38
+ * MediaRecorderHelper - Browser audio recording utility
39
+ *
40
+ * Handles MediaRecorder lifecycle:
41
+ * - Start/stop recording
42
+ * - Audio chunk collection
43
+ * - Stream cleanup
44
+ * - Blob generation
45
+ */
46
+ declare class MediaRecorderHelper {
47
+ private mediaRecorder;
48
+ private audioChunks;
49
+ private recording;
50
+ /**
51
+ * Start audio recording from user's microphone
52
+ */
53
+ start(): Promise<void>;
54
+ /**
55
+ * Stop audio recording and return the recorded audio as a Blob
56
+ */
57
+ stop(): Promise<Blob>;
58
+ /**
59
+ * Check if currently recording
60
+ */
61
+ isRecording(): boolean;
62
+ /**
63
+ * Abort recording immediately without returning data
64
+ */
65
+ abort(): void;
66
+ }
67
+
68
+ export { MediaRecorderHelper, STTManagerImpl, createSTTManager };
package/dist/index.js ADDED
@@ -0,0 +1,147 @@
1
+ "use strict";
2
+ var __defProp = Object.defineProperty;
3
+ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
4
+ var __getOwnPropNames = Object.getOwnPropertyNames;
5
+ var __hasOwnProp = Object.prototype.hasOwnProperty;
6
+ var __export = (target, all) => {
7
+ for (var name in all)
8
+ __defProp(target, name, { get: all[name], enumerable: true });
9
+ };
10
+ var __copyProps = (to, from, except, desc) => {
11
+ if (from && typeof from === "object" || typeof from === "function") {
12
+ for (let key of __getOwnPropNames(from))
13
+ if (!__hasOwnProp.call(to, key) && key !== except)
14
+ __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
15
+ }
16
+ return to;
17
+ };
18
+ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
19
+
20
+ // src/index.ts
21
+ var index_exports = {};
22
+ __export(index_exports, {
23
+ MediaRecorderHelper: () => MediaRecorderHelper,
24
+ STTManagerImpl: () => STTManagerImpl,
25
+ createSTTManager: () => createSTTManager
26
+ });
27
+ module.exports = __toCommonJS(index_exports);
28
+
29
+ // src/stt-manager.ts
30
+ var STTManagerImpl = class {
31
+ sttTranscriber;
32
+ eventEmitter;
33
+ constructor(sttTranscriber) {
34
+ this.sttTranscriber = sttTranscriber;
35
+ }
36
+ /**
37
+ * Set event emitter for STT events
38
+ */
39
+ setEventEmitter(eventEmitter) {
40
+ this.eventEmitter = eventEmitter;
41
+ }
42
+ /**
43
+ * Start audio recording (delegates to transcriber)
44
+ */
45
+ async start(options) {
46
+ this.eventEmitter?.emit("stt:start", { options });
47
+ try {
48
+ await this.sttTranscriber.startRecording(options);
49
+ } catch (error) {
50
+ this.eventEmitter?.emit("stt:error", { error });
51
+ throw error;
52
+ }
53
+ }
54
+ /**
55
+ * Stop audio recording and get transcription (delegates to transcriber)
56
+ */
57
+ async stop() {
58
+ try {
59
+ const transcription = await this.sttTranscriber.stopRecording();
60
+ this.eventEmitter?.emit("stt:stop", { transcription });
61
+ return transcription;
62
+ } catch (error) {
63
+ this.eventEmitter?.emit("stt:error", { error });
64
+ throw error;
65
+ }
66
+ }
67
+ /**
68
+ * Check if currently recording (delegates to transcriber)
69
+ */
70
+ isRecording() {
71
+ return this.sttTranscriber.isRecording();
72
+ }
73
+ };
74
+ function createSTTManager(sttTranscriber) {
75
+ return new STTManagerImpl(sttTranscriber);
76
+ }
77
+
78
+ // src/media-recorder-helper.ts
79
+ var MediaRecorderHelper = class {
80
+ mediaRecorder = null;
81
+ audioChunks = [];
82
+ recording = false;
83
+ /**
84
+ * Start audio recording from user's microphone
85
+ */
86
+ async start() {
87
+ if (this.recording) {
88
+ throw new Error("Already recording");
89
+ }
90
+ const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
91
+ this.mediaRecorder = new MediaRecorder(stream);
92
+ this.audioChunks = [];
93
+ this.mediaRecorder.ondataavailable = (event) => {
94
+ if (event.data.size > 0) {
95
+ this.audioChunks.push(event.data);
96
+ }
97
+ };
98
+ this.mediaRecorder.start();
99
+ this.recording = true;
100
+ }
101
+ /**
102
+ * Stop audio recording and return the recorded audio as a Blob
103
+ */
104
+ async stop() {
105
+ if (!this.recording || !this.mediaRecorder) {
106
+ throw new Error("Not recording");
107
+ }
108
+ return new Promise((resolve, reject) => {
109
+ this.mediaRecorder.onstop = () => {
110
+ const audioBlob = new Blob(this.audioChunks, { type: "audio/webm" });
111
+ this.audioChunks = [];
112
+ this.mediaRecorder?.stream.getTracks().forEach((track) => track.stop());
113
+ this.mediaRecorder = null;
114
+ this.recording = false;
115
+ resolve(audioBlob);
116
+ };
117
+ this.mediaRecorder.onerror = (error) => {
118
+ this.recording = false;
119
+ reject(error);
120
+ };
121
+ this.mediaRecorder.stop();
122
+ });
123
+ }
124
+ /**
125
+ * Check if currently recording
126
+ */
127
+ isRecording() {
128
+ return this.recording;
129
+ }
130
+ /**
131
+ * Abort recording immediately without returning data
132
+ */
133
+ abort() {
134
+ if (this.mediaRecorder) {
135
+ this.mediaRecorder.stream.getTracks().forEach((track) => track.stop());
136
+ this.mediaRecorder = null;
137
+ this.audioChunks = [];
138
+ this.recording = false;
139
+ }
140
+ }
141
+ };
142
+ // Annotate the CommonJS export names for ESM import in node:
143
+ 0 && (module.exports = {
144
+ MediaRecorderHelper,
145
+ STTManagerImpl,
146
+ createSTTManager
147
+ });
package/dist/index.mjs ADDED
@@ -0,0 +1,57 @@
1
+ import {
2
+ MediaRecorderHelper
3
+ } from "./chunk-EKUYDBHB.mjs";
4
+
5
+ // src/stt-manager.ts
6
+ var STTManagerImpl = class {
7
+ sttTranscriber;
8
+ eventEmitter;
9
+ constructor(sttTranscriber) {
10
+ this.sttTranscriber = sttTranscriber;
11
+ }
12
+ /**
13
+ * Set event emitter for STT events
14
+ */
15
+ setEventEmitter(eventEmitter) {
16
+ this.eventEmitter = eventEmitter;
17
+ }
18
+ /**
19
+ * Start audio recording (delegates to transcriber)
20
+ */
21
+ async start(options) {
22
+ this.eventEmitter?.emit("stt:start", { options });
23
+ try {
24
+ await this.sttTranscriber.startRecording(options);
25
+ } catch (error) {
26
+ this.eventEmitter?.emit("stt:error", { error });
27
+ throw error;
28
+ }
29
+ }
30
+ /**
31
+ * Stop audio recording and get transcription (delegates to transcriber)
32
+ */
33
+ async stop() {
34
+ try {
35
+ const transcription = await this.sttTranscriber.stopRecording();
36
+ this.eventEmitter?.emit("stt:stop", { transcription });
37
+ return transcription;
38
+ } catch (error) {
39
+ this.eventEmitter?.emit("stt:error", { error });
40
+ throw error;
41
+ }
42
+ }
43
+ /**
44
+ * Check if currently recording (delegates to transcriber)
45
+ */
46
+ isRecording() {
47
+ return this.sttTranscriber.isRecording();
48
+ }
49
+ };
50
+ function createSTTManager(sttTranscriber) {
51
+ return new STTManagerImpl(sttTranscriber);
52
+ }
53
+ export {
54
+ MediaRecorderHelper,
55
+ STTManagerImpl,
56
+ createSTTManager
57
+ };
@@ -0,0 +1,39 @@
1
+ import { STTTranscriber, STTOptions } from '@charivo/core';
2
+
3
+ interface OpenAISTTConfig {
4
+ apiKey: string;
5
+ defaultModel?: "whisper-1";
6
+ defaultLanguage?: string;
7
+ dangerouslyAllowBrowser?: boolean;
8
+ }
9
+
10
+ type OpenAISTTTranscriberConfig = OpenAISTTConfig;
11
+ /**
12
+ * OpenAI STT Transcriber - STT Transcriber using OpenAI Whisper
13
+ *
14
+ * For local development and testing environments. Not recommended for production due to security concerns.
15
+ * API key is exposed on the client side, so should only be used in server environments or for testing purposes.
16
+ *
17
+ * Handles recording internally using MediaRecorderHelper
18
+ */
19
+ declare class OpenAISTTTranscriber implements STTTranscriber {
20
+ private provider;
21
+ private recorder;
22
+ private recordingOptions?;
23
+ constructor(config: OpenAISTTTranscriberConfig);
24
+ /**
25
+ * Start recording audio from microphone
26
+ */
27
+ startRecording(options?: STTOptions): Promise<void>;
28
+ /**
29
+ * Stop recording and transcribe audio to text
30
+ */
31
+ stopRecording(): Promise<string>;
32
+ /**
33
+ * Check if currently recording
34
+ */
35
+ isRecording(): boolean;
36
+ }
37
+ declare function createOpenAISTTTranscriber(config: OpenAISTTTranscriberConfig): OpenAISTTTranscriber;
38
+
39
+ export { OpenAISTTTranscriber, type OpenAISTTTranscriberConfig, createOpenAISTTTranscriber };
@@ -0,0 +1,39 @@
1
+ import { STTTranscriber, STTOptions } from '@charivo/core';
2
+
3
+ interface OpenAISTTConfig {
4
+ apiKey: string;
5
+ defaultModel?: "whisper-1";
6
+ defaultLanguage?: string;
7
+ dangerouslyAllowBrowser?: boolean;
8
+ }
9
+
10
+ type OpenAISTTTranscriberConfig = OpenAISTTConfig;
11
+ /**
12
+ * OpenAI STT Transcriber - STT Transcriber using OpenAI Whisper
13
+ *
14
+ * For local development and testing environments. Not recommended for production due to security concerns.
15
+ * API key is exposed on the client side, so should only be used in server environments or for testing purposes.
16
+ *
17
+ * Handles recording internally using MediaRecorderHelper
18
+ */
19
+ declare class OpenAISTTTranscriber implements STTTranscriber {
20
+ private provider;
21
+ private recorder;
22
+ private recordingOptions?;
23
+ constructor(config: OpenAISTTTranscriberConfig);
24
+ /**
25
+ * Start recording audio from microphone
26
+ */
27
+ startRecording(options?: STTOptions): Promise<void>;
28
+ /**
29
+ * Stop recording and transcribe audio to text
30
+ */
31
+ stopRecording(): Promise<string>;
32
+ /**
33
+ * Check if currently recording
34
+ */
35
+ isRecording(): boolean;
36
+ }
37
+ declare function createOpenAISTTTranscriber(config: OpenAISTTTranscriberConfig): OpenAISTTTranscriber;
38
+
39
+ export { OpenAISTTTranscriber, type OpenAISTTTranscriberConfig, createOpenAISTTTranscriber };