@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/mkdocs.yml CHANGED
@@ -41,6 +41,9 @@ repo_url: https://github.com/madeinoz67/madeinoz-voice-server
41
41
  nav:
42
42
  - Home: index.md
43
43
  - API: api.md
44
+ - Features:
45
+ - FIFO Queue: fifo-queue.md
46
+ - Queue Architecture: queue-architecture.md
44
47
 
45
48
  markdown_extensions:
46
49
  - pymdownx.highlight:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@madeinoz67/voice-server",
3
- "version": "0.1.9",
3
+ "version": "0.1.11",
4
4
  "description": "PAI voice server using MLX-audio Kokoro TTS",
5
5
  "type": "module",
6
6
  "scripts": {
@@ -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: []