@madeinoz67/voice-server 0.1.9 → 0.1.11
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/CHANGELOG.md +9 -72
- package/CLAUDE.md +5 -0
- package/bun.lock +13 -13
- package/cliff.toml +10 -3
- package/docs/api.md +4 -0
- package/docs/assets/queue-error-handling-flow.png +0 -0
- package/docs/assets/queue-request-flow-success.png +0 -0
- package/docs/assets/queue-states.png +0 -0
- package/docs/assets/queue-system-overview.png +0 -0
- package/docs/assets/voice-server-architecture.png +0 -0
- package/docs/fifo-queue.md +175 -0
- package/docs/queue-architecture.md +182 -0
- package/homebrew.mxcl.voice-server.plist +33 -0
- package/mkdocs.yml +3 -0
- package/package.json +1 -1
- package/specs/002-fifo-notify-queue/checklists/requirements.md +50 -0
- package/specs/002-fifo-notify-queue/contracts/api.yaml +283 -0
- package/specs/002-fifo-notify-queue/data-model.md +379 -0
- package/specs/002-fifo-notify-queue/plan.md +320 -0
- package/specs/002-fifo-notify-queue/quickstart.md +273 -0
- package/specs/002-fifo-notify-queue/research.md +374 -0
- package/specs/002-fifo-notify-queue/spec.md +125 -0
- package/specs/002-fifo-notify-queue/tasks.md +136 -0
- package/src/ts/models/queue.ts +140 -0
- package/src/ts/server.ts +98 -19
- package/src/ts/services/mlx-tts-client.ts +75 -20
- package/src/ts/services/notification-queue.ts +382 -0
- package/tests/integration/queue-api.test.ts +298 -0
- package/tests/unit/services/notification-queue.test.ts +622 -0
package/mkdocs.yml
CHANGED
package/package.json
CHANGED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# Specification Quality Checklist: FIFO Notification Queue
|
|
2
|
+
|
|
3
|
+
**Purpose**: Validate specification completeness and quality before proceeding to planning
|
|
4
|
+
**Created**: 2026-02-09
|
|
5
|
+
**Feature**: [spec.md](../spec.md)
|
|
6
|
+
|
|
7
|
+
## Content Quality
|
|
8
|
+
|
|
9
|
+
- [x] No implementation details (languages, frameworks, APIs)
|
|
10
|
+
- [x] Focused on user value and business needs
|
|
11
|
+
- [x] Written for non-technical stakeholders
|
|
12
|
+
- [x] All mandatory sections completed
|
|
13
|
+
|
|
14
|
+
## Requirement Completeness
|
|
15
|
+
|
|
16
|
+
- [x] No [NEEDS CLARIFICATION] markers remain
|
|
17
|
+
- [x] Requirements are testable and unambiguous
|
|
18
|
+
- [x] Success criteria are measurable
|
|
19
|
+
- [x] Success criteria are technology-agnostic (no implementation details)
|
|
20
|
+
- [x] All acceptance scenarios are defined
|
|
21
|
+
- [x] Edge cases are identified
|
|
22
|
+
- [x] Scope is clearly bounded
|
|
23
|
+
- [x] Dependencies and assumptions identified
|
|
24
|
+
|
|
25
|
+
## Feature Readiness
|
|
26
|
+
|
|
27
|
+
- [x] All functional requirements have clear acceptance criteria
|
|
28
|
+
- [x] User scenarios cover primary flows
|
|
29
|
+
- [x] Feature meets measurable outcomes defined in Success Criteria
|
|
30
|
+
- [x] No implementation details leak into specification
|
|
31
|
+
|
|
32
|
+
## Notes
|
|
33
|
+
|
|
34
|
+
All validation items passed. Specification is ready for `/speckit.clarify` or `/speckit.plan`.
|
|
35
|
+
|
|
36
|
+
### Validation Results Summary
|
|
37
|
+
|
|
38
|
+
| Category | Status | Details |
|
|
39
|
+
|----------|--------|---------|
|
|
40
|
+
| Content Quality | ✅ PASS | No implementation details, user-focused language |
|
|
41
|
+
| Requirement Completeness | ✅ PASS | All FRs are testable, no clarifications needed |
|
|
42
|
+
| Feature Readiness | ✅ PASS | Success criteria are measurable and tech-agnostic |
|
|
43
|
+
|
|
44
|
+
### Specific Checks Passed
|
|
45
|
+
|
|
46
|
+
1. **Technology Agnostic**: Success criteria use terms like "sequential audio playback" and "201 Accepted response" without mentioning specific frameworks or languages
|
|
47
|
+
2. **Measurable Outcomes**: All 4 success criteria include specific metrics (100ms, 50ms, 100 items, up to 10 simultaneous requests)
|
|
48
|
+
3. **Independent Testability**: Each user story includes an "Independent Test" section describing standalone verification
|
|
49
|
+
4. **Edge Cases**: 5 edge cases identified covering overflow, errors, failures, shutdown, and invalid input
|
|
50
|
+
5. **Scope Boundaries**: Clear "Out of Scope" section excludes features like persistent storage and priority queuing
|
|
@@ -0,0 +1,283 @@
|
|
|
1
|
+
openapi: 3.0.3
|
|
2
|
+
info:
|
|
3
|
+
title: MadeInOz Voice Server - FIFO Notification Queue API
|
|
4
|
+
description: API for the FIFO notification queue feature that prevents audio overlap
|
|
5
|
+
version: 0.2.0
|
|
6
|
+
contact:
|
|
7
|
+
name: MadeInOz
|
|
8
|
+
url: https://github.com/madeinoz67/madeinoz-voice-server
|
|
9
|
+
|
|
10
|
+
servers:
|
|
11
|
+
- url: http://127.0.0.1:8888
|
|
12
|
+
description: Local development server
|
|
13
|
+
|
|
14
|
+
tags:
|
|
15
|
+
- name: Queue
|
|
16
|
+
description: Queue operations
|
|
17
|
+
- name: Health
|
|
18
|
+
description: Health and status endpoints
|
|
19
|
+
|
|
20
|
+
paths:
|
|
21
|
+
/notify:
|
|
22
|
+
post:
|
|
23
|
+
tags: [Queue]
|
|
24
|
+
summary: Queue a voice notification
|
|
25
|
+
description: |
|
|
26
|
+
Submits a voice notification to the queue for processing.
|
|
27
|
+
Returns 201 Accepted immediately when queued successfully.
|
|
28
|
+
Audio playback happens asynchronously in FIFO order.
|
|
29
|
+
operationId: queueNotification
|
|
30
|
+
requestBody:
|
|
31
|
+
required: true
|
|
32
|
+
content:
|
|
33
|
+
application/json:
|
|
34
|
+
schema:
|
|
35
|
+
$ref: '#/components/schemas/NotificationRequest'
|
|
36
|
+
examples:
|
|
37
|
+
basic:
|
|
38
|
+
summary: Basic notification
|
|
39
|
+
value:
|
|
40
|
+
message: "Hello, world"
|
|
41
|
+
withTitle:
|
|
42
|
+
summary: Notification with title
|
|
43
|
+
value:
|
|
44
|
+
title: "System Alert"
|
|
45
|
+
message: "Process completed successfully"
|
|
46
|
+
withVoiceSettings:
|
|
47
|
+
summary: Notification with custom voice
|
|
48
|
+
value:
|
|
49
|
+
title: "Reminder"
|
|
50
|
+
message: "Meeting starting in 5 minutes"
|
|
51
|
+
voice_id: "marrvin"
|
|
52
|
+
voice_settings:
|
|
53
|
+
stability: 0.5
|
|
54
|
+
similarity: 0.75
|
|
55
|
+
speed: 1.0
|
|
56
|
+
volume: 0.8
|
|
57
|
+
responses:
|
|
58
|
+
'201':
|
|
59
|
+
description: Notification queued successfully
|
|
60
|
+
content:
|
|
61
|
+
application/json:
|
|
62
|
+
schema:
|
|
63
|
+
$ref: '#/components/schemas/SuccessResponse'
|
|
64
|
+
example:
|
|
65
|
+
status: "success"
|
|
66
|
+
message: "Notification queued"
|
|
67
|
+
'400':
|
|
68
|
+
description: Invalid request (malformed JSON, missing fields, invalid voice_id)
|
|
69
|
+
content:
|
|
70
|
+
application/json:
|
|
71
|
+
schema:
|
|
72
|
+
$ref: '#/components/schemas/ErrorResponse'
|
|
73
|
+
examples:
|
|
74
|
+
missingMessage:
|
|
75
|
+
summary: Missing required field
|
|
76
|
+
value:
|
|
77
|
+
status: "error"
|
|
78
|
+
message: "Missing required field: message"
|
|
79
|
+
invalidVoiceId:
|
|
80
|
+
summary: Invalid voice ID
|
|
81
|
+
value:
|
|
82
|
+
status: "error"
|
|
83
|
+
message: "Invalid voice_id: unknown_voice"
|
|
84
|
+
emptyAfterSanitization:
|
|
85
|
+
summary: Empty message after sanitization
|
|
86
|
+
value:
|
|
87
|
+
status: "error"
|
|
88
|
+
message: "Invalid input after sanitization"
|
|
89
|
+
'429':
|
|
90
|
+
description: Queue is at maximum capacity (100 items)
|
|
91
|
+
content:
|
|
92
|
+
application/json:
|
|
93
|
+
schema:
|
|
94
|
+
$ref: '#/components/schemas/ErrorResponse'
|
|
95
|
+
example:
|
|
96
|
+
status: "error"
|
|
97
|
+
message: "Queue is full (100 items)"
|
|
98
|
+
'500':
|
|
99
|
+
description: Internal server error
|
|
100
|
+
content:
|
|
101
|
+
application/json:
|
|
102
|
+
schema:
|
|
103
|
+
$ref: '#/components/schemas/ErrorResponse'
|
|
104
|
+
example:
|
|
105
|
+
status: "error"
|
|
106
|
+
message: "Internal server error"
|
|
107
|
+
|
|
108
|
+
/queue/status:
|
|
109
|
+
get:
|
|
110
|
+
tags: [Health]
|
|
111
|
+
summary: Get queue status
|
|
112
|
+
description: |
|
|
113
|
+
Returns the current state of the notification queue including depth,
|
|
114
|
+
processing status, and health indicator.
|
|
115
|
+
operationId: getQueueStatus
|
|
116
|
+
responses:
|
|
117
|
+
'200':
|
|
118
|
+
description: Queue status retrieved successfully
|
|
119
|
+
content:
|
|
120
|
+
application/json:
|
|
121
|
+
schema:
|
|
122
|
+
$ref: '#/components/schemas/QueueStateResponse'
|
|
123
|
+
examples:
|
|
124
|
+
emptyQueue:
|
|
125
|
+
summary: Empty queue, idle
|
|
126
|
+
value:
|
|
127
|
+
depth: 0
|
|
128
|
+
processing_status: "idle"
|
|
129
|
+
health: "healthy"
|
|
130
|
+
processing:
|
|
131
|
+
summary: Queue with items, actively processing
|
|
132
|
+
value:
|
|
133
|
+
depth: 3
|
|
134
|
+
processing_status: "active"
|
|
135
|
+
health: "healthy"
|
|
136
|
+
metrics:
|
|
137
|
+
average_wait_time_ms: 5000
|
|
138
|
+
items_processed: 127
|
|
139
|
+
items_failed: 2
|
|
140
|
+
degraded:
|
|
141
|
+
summary: Queue near capacity
|
|
142
|
+
value:
|
|
143
|
+
depth: 85
|
|
144
|
+
processing_status: "active"
|
|
145
|
+
health: "degraded"
|
|
146
|
+
metrics:
|
|
147
|
+
average_wait_time_ms: 45000
|
|
148
|
+
items_processed: 542
|
|
149
|
+
items_failed: 12
|
|
150
|
+
unavailable:
|
|
151
|
+
summary: TTS system unavailable
|
|
152
|
+
value:
|
|
153
|
+
depth: 5
|
|
154
|
+
processing_status: "idle"
|
|
155
|
+
health: "unavailable"
|
|
156
|
+
|
|
157
|
+
components:
|
|
158
|
+
schemas:
|
|
159
|
+
NotificationRequest:
|
|
160
|
+
type: object
|
|
161
|
+
description: Request to queue a voice notification
|
|
162
|
+
properties:
|
|
163
|
+
title:
|
|
164
|
+
type: string
|
|
165
|
+
maxLength: 100
|
|
166
|
+
description: Notification title (optional for backward compatibility)
|
|
167
|
+
message:
|
|
168
|
+
type: string
|
|
169
|
+
minLength: 1
|
|
170
|
+
maxLength: 500
|
|
171
|
+
description: Text message to synthesize (required)
|
|
172
|
+
voice_id:
|
|
173
|
+
type: string
|
|
174
|
+
description: Voice identifier to use (defaults to server default)
|
|
175
|
+
voice_name:
|
|
176
|
+
type: string
|
|
177
|
+
deprecated: true
|
|
178
|
+
description: Alias for voice_id (use voice_id instead)
|
|
179
|
+
voice_settings:
|
|
180
|
+
$ref: '#/components/schemas/ProsodySettings'
|
|
181
|
+
volume:
|
|
182
|
+
type: number
|
|
183
|
+
minimum: 0.0
|
|
184
|
+
maximum: 1.0
|
|
185
|
+
description: Playback volume (0.0-1.0, defaults to voice setting)
|
|
186
|
+
required:
|
|
187
|
+
- message
|
|
188
|
+
|
|
189
|
+
ProsodySettings:
|
|
190
|
+
type: object
|
|
191
|
+
description: Voice prosody configuration
|
|
192
|
+
properties:
|
|
193
|
+
stability:
|
|
194
|
+
type: number
|
|
195
|
+
minimum: 0.0
|
|
196
|
+
maximum: 1.0
|
|
197
|
+
description: Voice stability (lower = more expressive)
|
|
198
|
+
similarity:
|
|
199
|
+
type: number
|
|
200
|
+
minimum: 0.0
|
|
201
|
+
maximum: 1.0
|
|
202
|
+
description: Voice similarity boost
|
|
203
|
+
style:
|
|
204
|
+
type: string
|
|
205
|
+
description: Voice style (model-dependent)
|
|
206
|
+
speed:
|
|
207
|
+
type: number
|
|
208
|
+
minimum: 0.25
|
|
209
|
+
maximum: 4.0
|
|
210
|
+
description: Playback speed multiplier
|
|
211
|
+
|
|
212
|
+
SuccessResponse:
|
|
213
|
+
type: object
|
|
214
|
+
description: Successful API response
|
|
215
|
+
properties:
|
|
216
|
+
status:
|
|
217
|
+
type: string
|
|
218
|
+
enum: [success]
|
|
219
|
+
description: Response status indicator
|
|
220
|
+
message:
|
|
221
|
+
type: string
|
|
222
|
+
description: Human-readable success message
|
|
223
|
+
required:
|
|
224
|
+
- status
|
|
225
|
+
- message
|
|
226
|
+
|
|
227
|
+
ErrorResponse:
|
|
228
|
+
type: object
|
|
229
|
+
description: Error API response
|
|
230
|
+
properties:
|
|
231
|
+
status:
|
|
232
|
+
type: string
|
|
233
|
+
enum: [error]
|
|
234
|
+
description: Response status indicator
|
|
235
|
+
message:
|
|
236
|
+
type: string
|
|
237
|
+
description: Human-readable error message
|
|
238
|
+
required:
|
|
239
|
+
- status
|
|
240
|
+
- message
|
|
241
|
+
|
|
242
|
+
QueueStateResponse:
|
|
243
|
+
type: object
|
|
244
|
+
description: Current queue state
|
|
245
|
+
properties:
|
|
246
|
+
depth:
|
|
247
|
+
type: integer
|
|
248
|
+
minimum: 0
|
|
249
|
+
maximum: 100
|
|
250
|
+
description: Current number of items in queue
|
|
251
|
+
processing_status:
|
|
252
|
+
type: string
|
|
253
|
+
enum: [idle, active]
|
|
254
|
+
description: Whether queue is actively processing items
|
|
255
|
+
health:
|
|
256
|
+
type: string
|
|
257
|
+
enum: [healthy, degraded, unavailable]
|
|
258
|
+
description: Overall system health indicator
|
|
259
|
+
metrics:
|
|
260
|
+
type: object
|
|
261
|
+
description: Optional queue metrics
|
|
262
|
+
properties:
|
|
263
|
+
average_wait_time_ms:
|
|
264
|
+
type: integer
|
|
265
|
+
minimum: 0
|
|
266
|
+
description: Average wait time for queued items (milliseconds)
|
|
267
|
+
items_processed:
|
|
268
|
+
type: integer
|
|
269
|
+
minimum: 0
|
|
270
|
+
description: Total items processed since server start
|
|
271
|
+
items_failed:
|
|
272
|
+
type: integer
|
|
273
|
+
minimum: 0
|
|
274
|
+
description: Total items that failed since server start
|
|
275
|
+
required:
|
|
276
|
+
- depth
|
|
277
|
+
- processing_status
|
|
278
|
+
- health
|
|
279
|
+
|
|
280
|
+
examples:
|
|
281
|
+
null
|
|
282
|
+
|
|
283
|
+
security: []
|