@madeinoz67/voice-server 0.1.9 → 0.1.10

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.
@@ -0,0 +1,140 @@
1
+ /**
2
+ * Queue model types
3
+ * FIFO notification queue for voice server
4
+ */
5
+
6
+ import type { NotificationRequest } from "@/models/notification.js";
7
+
8
+ /**
9
+ * Processing status of a queued notification
10
+ */
11
+ export type QueuedItemStatus = "pending" | "processing" | "completed" | "failed";
12
+
13
+ /**
14
+ * Queued notification item
15
+ */
16
+ export interface QueuedNotification {
17
+ /** Unique identifier for this queued item */
18
+ id: string;
19
+ /** Original notification request */
20
+ request: NotificationRequest;
21
+ /** Current status */
22
+ status: QueuedItemStatus;
23
+ /** Timestamp when item was enqueued */
24
+ arrivedAt: Date;
25
+ /** Timestamp when processing started (if applicable) */
26
+ processingStartedAt?: Date;
27
+ /** Timestamp when processing completed (if applicable) */
28
+ completedAt?: Date;
29
+ /** Error message if processing failed */
30
+ error?: string;
31
+ }
32
+
33
+ /**
34
+ * Processing status of the queue
35
+ */
36
+ export type QueueProcessingStatus = "idle" | "active" | "draining" | "stopped";
37
+
38
+ /**
39
+ * Health indicator for the queue
40
+ */
41
+ export type QueueHealth = "healthy" | "degraded" | "unavailable";
42
+
43
+ /**
44
+ * Queue metrics
45
+ */
46
+ export interface QueueMetrics {
47
+ /** Total number of items processed successfully */
48
+ itemsProcessed: number;
49
+ /** Total number of items that failed */
50
+ itemsFailed: number;
51
+ /** Average processing time in milliseconds */
52
+ averageProcessingTimeMs: number;
53
+ /** Current processing time of active item (if any) */
54
+ currentProcessingTimeMs?: number;
55
+ }
56
+
57
+ /**
58
+ * Current state of the notification queue
59
+ */
60
+ export interface QueueState {
61
+ /** Current number of items in the queue */
62
+ depth: number;
63
+ /** Current processing status */
64
+ processingStatus: QueueProcessingStatus;
65
+ /** Health indicator */
66
+ health: QueueHealth;
67
+ /** Optional metrics */
68
+ metrics?: QueueMetrics;
69
+ }
70
+
71
+ /**
72
+ * Queue configuration
73
+ */
74
+ export interface QueueConfig {
75
+ /** Maximum number of items allowed in the queue */
76
+ maxDepth: number;
77
+ /** Maximum time to wait for queue drain during shutdown (ms) */
78
+ drainTimeoutMs: number;
79
+ /** Queue depth threshold for degraded health status */
80
+ degradedThreshold: number;
81
+ }
82
+
83
+ /**
84
+ * Result of an enqueue operation
85
+ */
86
+ export interface EnqueueResult {
87
+ /** Whether the item was successfully enqueued */
88
+ success: boolean;
89
+ /** HTTP status code */
90
+ statusCode: number;
91
+ /** Human-readable message */
92
+ message: string;
93
+ /** Position in queue (0-indexed) if successful */
94
+ queuePosition?: number;
95
+ /** Item ID if successful */
96
+ itemId?: string;
97
+ }
98
+
99
+ /**
100
+ * Result of a drain operation
101
+ */
102
+ export interface DrainResult {
103
+ /** Whether drain completed successfully */
104
+ success: boolean;
105
+ /** Number of items processed during drain */
106
+ itemsProcessed: number;
107
+ /** Number of items that failed during drain */
108
+ itemsFailed: number;
109
+ /** Whether drain timed out */
110
+ timedOut: boolean;
111
+ /** Remaining items when timed out */
112
+ remainingItems?: number;
113
+ }
114
+
115
+ /**
116
+ * Create a default queue configuration
117
+ */
118
+ export function createDefaultQueueConfig(): QueueConfig {
119
+ return {
120
+ maxDepth: 100,
121
+ drainTimeoutMs: 30000, // 30 seconds
122
+ degradedThreshold: 50,
123
+ };
124
+ }
125
+
126
+ /**
127
+ * Create an empty queue state
128
+ */
129
+ export function createEmptyQueueState(): QueueState {
130
+ return {
131
+ depth: 0,
132
+ processingStatus: "idle",
133
+ health: "healthy",
134
+ metrics: {
135
+ itemsProcessed: 0,
136
+ itemsFailed: 0,
137
+ averageProcessingTimeMs: 0,
138
+ },
139
+ };
140
+ }
package/src/ts/server.ts CHANGED
@@ -1,7 +1,8 @@
1
1
  /**
2
2
  * Qwen TTS Voice Server
3
- * Main Bun HTTP server with /notify, /pai, /health endpoints
3
+ * Main Bun HTTP server with /notify, /pai, /health, /queue/status endpoints
4
4
  * MLX-audio only - Python backend removed
5
+ * FIFO notification queue for sequential processing
5
6
  */
6
7
 
7
8
  import type { NotificationRequest, PaiNotificationRequest } from "@/models/notification.js";
@@ -17,6 +18,8 @@ import { getMLXTTSClient, type MLXTTSClientConfig } from "@/services/mlx-tts-cli
17
18
  import { getVoiceLoader } from "@/services/voice-loader.js";
18
19
  import { getRateLimiter, extractClientId } from "@/middleware/rate-limiter.js";
19
20
  import { getCORSMiddleware } from "@/middleware/cors.js";
21
+ import { NotificationQueue, type TTSProcessor } from "@/services/notification-queue.js";
22
+ import type { QueueState } from "@/models/queue.js";
20
23
  import { $ } from "bun";
21
24
 
22
25
  /**
@@ -29,6 +32,10 @@ interface ServerConfig {
29
32
  enableMacOSNotifications: boolean;
30
33
  /** MLX-audio configuration */
31
34
  mlxConfig: MLXTTSClientConfig;
35
+ /** Queue configuration */
36
+ queueMaxDepth?: number;
37
+ queueDrainTimeoutMs?: number;
38
+ queueDegradedThreshold?: number;
32
39
  }
33
40
 
34
41
  /**
@@ -49,6 +56,9 @@ const DEFAULT_CONFIG: ServerConfig = {
49
56
  streamingInterval: parseFloat(process.env.MLX_STREAMING_INTERVAL || "0.3"),
50
57
  timeout: 10000,
51
58
  },
59
+ queueMaxDepth: parseInt(process.env.QUEUE_MAX_DEPTH || "100", 10),
60
+ queueDrainTimeoutMs: parseInt(process.env.QUEUE_DRAIN_TIMEOUT_MS || "30000", 10),
61
+ queueDegradedThreshold: parseInt(process.env.QUEUE_DEGRADED_THRESHOLD || "50", 10),
52
62
  };
53
63
 
54
64
  /**
@@ -59,6 +69,7 @@ interface ServerState {
59
69
  config: ServerConfig;
60
70
  cors: ReturnType<typeof getCORSMiddleware>;
61
71
  rateLimiter: ReturnType<typeof getRateLimiter>;
72
+ notificationQueue: NotificationQueue;
62
73
  }
63
74
 
64
75
  let serverState: ServerState;
@@ -132,6 +143,34 @@ async function fallbackToMacOSSay(text: string, voiceId?: string): Promise<void>
132
143
  }
133
144
  }
134
145
 
146
+ /**
147
+ * Process TTS request with MLX-audio backend
148
+ * This is used by the notification queue
149
+ */
150
+ async function processTTSWithMacOSNotification(request: NotificationRequest): Promise<void> {
151
+ const title = sanitizeTitle(request.title || "Notification");
152
+ const message = sanitizeMessage(request.message);
153
+
154
+ if (!message) {
155
+ throw new Error("Invalid message after sanitization");
156
+ }
157
+
158
+ // Determine voice settings
159
+ const voiceId = request.voice_id || request.voice_name || serverState.config.defaultVoiceId;
160
+ const voiceSettings = request.voice_settings || DEFAULT_PROSODY;
161
+ const volume = request.volume ?? voiceSettings.volume ?? 1.0;
162
+
163
+ // Display macOS notification
164
+ if (serverState.config.enableMacOSNotifications) {
165
+ await displayMacOSNotification(title, message);
166
+ }
167
+
168
+ // Process TTS if enabled
169
+ if (request.voice_enabled !== false) {
170
+ await processTTS(message, voiceId, voiceSettings, volume);
171
+ }
172
+ }
173
+
135
174
  /**
136
175
  * Process TTS request with MLX-audio backend
137
176
  */
@@ -176,7 +215,7 @@ async function processTTS(
176
215
  }
177
216
 
178
217
  /**
179
- * Handle POST /notify endpoint
218
+ * Handle POST /notify endpoint (now queues requests)
180
219
  */
181
220
  async function handleNotify(request: NotificationRequest): Promise<SuccessResponse | ErrorResponse> {
182
221
  try {
@@ -187,38 +226,45 @@ async function handleNotify(request: NotificationRequest): Promise<SuccessRespon
187
226
  return errorResponse("Missing required field: message");
188
227
  }
189
228
 
190
- // Sanitize input - use default title if not provided
191
- const title = sanitizeTitle(request.title || "Notification");
229
+ // Sanitize input
192
230
  const message = sanitizeMessage(request.message);
193
-
194
231
  if (!message) {
195
232
  return errorResponse("Invalid input after sanitization");
196
233
  }
197
234
 
198
- // Determine voice settings
199
- const voiceId = request.voice_id || request.voice_name || serverState.config.defaultVoiceId;
200
- const voiceSettings = request.voice_settings || DEFAULT_PROSODY;
201
- const volume = request.volume ?? voiceSettings.volume ?? 1.0;
202
-
203
- // Display macOS notification
204
- if (serverState.config.enableMacOSNotifications) {
205
- await displayMacOSNotification(title, message);
206
- }
235
+ // Enqueue the notification
236
+ const result = await serverState.notificationQueue.enqueue(request);
207
237
 
208
- // Process TTS if enabled
209
- if (request.voice_enabled !== false) {
210
- await processTTS(message, voiceId, voiceSettings, volume);
238
+ if (!result.success) {
239
+ return errorResponse(result.message);
211
240
  }
212
241
 
213
- return successResponse();
242
+ // Return 201 Accepted response
243
+ return {
244
+ status: "success",
245
+ message: result.message,
246
+ };
214
247
  } catch (error) {
215
248
  logger.error("Error handling /notify", error as Error);
216
249
  return errorResponse("Internal server error");
217
250
  }
218
251
  }
219
252
 
253
+ /**
254
+ * Handle GET /queue/status endpoint
255
+ */
256
+ async function handleQueueStatus(): Promise<QueueState & { status: "success" }> {
257
+ const queueState = serverState.notificationQueue.getQueueState();
258
+ return {
259
+ status: "success",
260
+ ...queueState,
261
+ };
262
+ }
263
+
220
264
  /**
221
265
  * Handle POST /pai endpoint
266
+ * Note: This bypasses the queue for immediate PAI notifications
267
+ * Can be changed to use queue if desired
222
268
  */
223
269
  async function handlePai(request: PaiNotificationRequest): Promise<SuccessResponse | ErrorResponse> {
224
270
  try {
@@ -233,7 +279,7 @@ async function handlePai(request: PaiNotificationRequest): Promise<SuccessRespon
233
279
  const title = sanitizeTitle(request.title);
234
280
  const message = sanitizeMessage(request.message);
235
281
 
236
- // Use default DA voice settings
282
+ // Determine voice settings
237
283
  const voiceId = serverState.config.defaultVoiceId;
238
284
  const voiceSettings = DEFAULT_PROSODY;
239
285
  const volume = 1.0;
@@ -316,11 +362,21 @@ async function parseJsonBody<T>(req: Request): Promise<T> {
316
362
  export async function startServer(config: Partial<ServerConfig> = {}): Promise<void> {
317
363
  // Initialize server state
318
364
  const finalConfig = { ...DEFAULT_CONFIG, ...config };
365
+
366
+ // Create notification queue
367
+ const ttsProcessor: TTSProcessor = processTTSWithMacOSNotification;
368
+ const notificationQueue = new NotificationQueue(ttsProcessor, {
369
+ maxDepth: finalConfig.queueMaxDepth,
370
+ drainTimeoutMs: finalConfig.queueDrainTimeoutMs,
371
+ degradedThreshold: finalConfig.queueDegradedThreshold,
372
+ });
373
+
319
374
  serverState = {
320
375
  healthStatus: createDefaultHealthStatus(),
321
376
  config: finalConfig,
322
377
  cors: getCORSMiddleware(),
323
378
  rateLimiter: getRateLimiter(),
379
+ notificationQueue,
324
380
  };
325
381
 
326
382
  const { port, host } = finalConfig;
@@ -330,6 +386,11 @@ export async function startServer(config: Partial<ServerConfig> = {}): Promise<v
330
386
  logger.info(`TTS Backend: MLX-audio`, {
331
387
  model: finalConfig.mlxConfig.model,
332
388
  });
389
+ logger.info(`Notification Queue: enabled`, {
390
+ maxDepth: finalConfig.queueMaxDepth,
391
+ drainTimeoutMs: finalConfig.queueDrainTimeoutMs,
392
+ degradedThreshold: finalConfig.queueDegradedThreshold,
393
+ });
333
394
 
334
395
  // Initialize MLX-audio client
335
396
  try {
@@ -400,6 +461,11 @@ export async function startServer(config: Partial<ServerConfig> = {}): Promise<v
400
461
  if (path === "/notify" && req.method === "POST") {
401
462
  const body = await parseJsonBody<NotificationRequest>(req);
402
463
  responseData = await handleNotify(body);
464
+
465
+ // Return 201 for successful queue operations
466
+ const statusCode = (responseData as SuccessResponse).status === "success" ? 201 : 400;
467
+ const response = Response.json(responseData, { status: statusCode });
468
+ return serverState.cors.addCorsHeaders(response, origin);
403
469
  }
404
470
  // POST /pai
405
471
  else if (path === "/pai" && req.method === "POST") {
@@ -410,6 +476,10 @@ export async function startServer(config: Partial<ServerConfig> = {}): Promise<v
410
476
  else if (path === "/health" && req.method === "GET") {
411
477
  responseData = await handleHealth();
412
478
  }
479
+ // GET /queue/status
480
+ else if (path === "/queue/status" && req.method === "GET") {
481
+ responseData = await handleQueueStatus();
482
+ }
413
483
  // 404 Not Found
414
484
  else {
415
485
  return Response.json(
@@ -439,6 +509,15 @@ export async function startServer(config: Partial<ServerConfig> = {}): Promise<v
439
509
  const shutdown = async () => {
440
510
  logger.info("Shutting down server...");
441
511
 
512
+ // Drain notification queue
513
+ logger.info("Draining notification queue...");
514
+ const drainResult = await serverState.notificationQueue.drain();
515
+ logger.info("Queue drain complete", {
516
+ itemsProcessed: drainResult.itemsProcessed,
517
+ itemsFailed: drainResult.itemsFailed,
518
+ timedOut: drainResult.timedOut,
519
+ });
520
+
442
521
  // Stop rate limiter
443
522
  serverState.rateLimiter.stop();
444
523
 
@@ -100,21 +100,24 @@ export class MLXTTSClient {
100
100
  args.push("--speed", this.config.speed.toString());
101
101
  }
102
102
 
103
- // For streaming, use smaller interval for smoother playback (< 0.5s)
104
- const streamingInterval = stream ? (this.config.streamingInterval || 0.3) : 2.0;
105
- args.push("--streaming_interval", streamingInterval.toString());
106
-
107
- // Add --play flag for streaming mode to enable audio playback
103
+ // Only add streaming_interval for actual streaming mode
104
+ // Do NOT add --play when using afplay for playback (avoids double audio)
105
+ // When stream=false, generate file without any streaming behavior
108
106
  if (stream) {
109
- args.push("--play");
107
+ // For streaming, use smaller interval for smoother playback (< 0.5s)
108
+ const streamingInterval = this.config.streamingInterval || 0.3;
109
+ args.push("--streaming_interval", streamingInterval.toString());
110
+ // NOTE: We DON'T add --play here because we use afplay instead
111
+ // This prevents MLX-audio from playing audio through sounddevice
110
112
  }
111
113
 
112
- logger.debug("Executing MLX-audio command", { args: args.join(" ") });
114
+ logger.info("Executing MLX-audio command", { args: args.join(" ") });
113
115
 
114
- // For streaming mode, MLX-audio plays audio directly via sounddevice
115
- // We just need to wait for completion and return minimal response
116
+ // For streaming mode, generate audio to file and play with afplay
117
+ // This avoids MLX-audio's buggy sounddevice implementation that
118
+ // closes the audio stream before playback completes
116
119
  if (stream) {
117
- logger.info("MLX-audio streaming mode - audio will play directly via sounddevice");
120
+ logger.info("MLX-audio streaming mode - generating audio file for playback");
118
121
 
119
122
  // Set ESPEAK_DATA_PATH for Kokoro model
120
123
  const env = {
@@ -122,31 +125,83 @@ export class MLXTTSClient {
122
125
  ESPEAK_DATA_PATH: "/opt/homebrew/Cellar/espeak-ng/1.52.0/share/espeak-ng-data",
123
126
  };
124
127
 
125
- // Use inherit for stderr so sounddevice can access audio device properly
126
- // and we can see any error messages
128
+ // Generate audio file WITHOUT --play flag
127
129
  const proc = Bun.spawn(args, {
128
- stdout: "inherit",
129
- stderr: "inherit",
130
+ stdout: "pipe",
131
+ stderr: "pipe",
130
132
  env,
131
133
  });
132
134
 
133
- // Wait for streaming to complete
135
+ // Wait for generation to complete
136
+ const stderr = await new Promise<string>((resolve) => {
137
+ const reader = proc.stderr!.getReader();
138
+ const chunks: Buffer[] = [];
139
+
140
+ const read = () => {
141
+ reader.read().then(({ done, value }) => {
142
+ if (done) {
143
+ resolve(Buffer.concat(chunks).toString());
144
+ return;
145
+ }
146
+ if (value) {
147
+ chunks.push(value as Buffer);
148
+ }
149
+ read();
150
+ });
151
+ };
152
+ read();
153
+ });
154
+
134
155
  const exitCode = await proc.exited;
135
156
 
136
157
  if (exitCode !== 0) {
137
- throw new Error(`MLX-audio streaming failed with exit code ${exitCode}`);
158
+ throw new Error(`MLX-audio generation failed with exit code ${exitCode}: ${stderr}`);
159
+ }
160
+
161
+ // Find the generated audio file
162
+ const audioFile = `${filePrefix}_000.wav`;
163
+ if (!existsSync(audioFile)) {
164
+ throw new Error(`MLX-audio did not generate expected audio file: ${audioFile}`);
165
+ }
166
+
167
+ logger.info("Audio file generated, playing with afplay", { path: audioFile });
168
+
169
+ // Play audio with afplay (macOS native, reliable sequential playback)
170
+ const playStartTime = Date.now();
171
+ logger.info("Spawning afplay process", { file: audioFile });
172
+
173
+ const afplayProc = Bun.spawn(["afplay", audioFile], {
174
+ stdout: "pipe",
175
+ stderr: "pipe",
176
+ });
177
+
178
+ logger.info("afplay spawned", { pid: afplayProc.pid });
179
+ const afplayExitCode = await afplayProc.exited;
180
+ logger.info("afplay exited", { pid: afplayProc.pid, exitCode: afplayExitCode });
181
+
182
+ if (afplayExitCode !== 0) {
183
+ logger.warn("afplay exited with non-zero code", { code: afplayExitCode });
184
+ }
185
+
186
+ const playTimeMs = Date.now() - playStartTime;
187
+
188
+ // Clean up temp file after playback
189
+ try {
190
+ unlinkSync(audioFile);
191
+ } catch {
192
+ logger.warn("Failed to clean up temp file", { path: audioFile });
138
193
  }
139
194
 
140
195
  const processingTimeMs = Date.now() - startTime;
141
196
 
142
- logger.info("MLX-audio streaming complete", {
197
+ logger.info("MLX-audio streaming with afplay complete", {
143
198
  processing_time_ms: processingTimeMs,
199
+ playback_time_ms: playTimeMs,
144
200
  });
145
201
 
146
- // Return minimal response for streaming (audio played directly)
147
202
  return {
148
- audio_data: "", // No audio data returned when streaming
149
- duration_ms: 0, // Duration unknown for streaming
203
+ audio_data: "",
204
+ duration_ms: 0,
150
205
  format: "streaming",
151
206
  sample_rate: 24000,
152
207
  };