@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.
package/CHANGELOG.md CHANGED
@@ -17,6 +17,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
17
17
 
18
18
  - Update CHANGELOG.md [skip ci] ([7f6e640](7f6e6409937dc5cddebcb4d34f1226a13d80e963))
19
19
 
20
+ - Update CHANGELOG.md [skip ci] ([37698ca](37698ca1e4884990731657c54d6b99e8d72291dd))
21
+
22
+ - Update CHANGELOG.md for v0.1.9 [skip ci] ([046a02e](046a02e74637afdf771d7e7cc2f954efe588aed8))
23
+
24
+ - FIFO queue documentation with visual diagrams ([53f4dd8](53f4dd8118c55f10dcbe55d42b054cd803731d4f))
25
+
20
26
 
21
27
  ### Miscellaneous Tasks
22
28
 
package/CLAUDE.md CHANGED
@@ -47,4 +47,9 @@ bun run typecheck # Type check only
47
47
  - Documentation is built with MkDocs Material theme
48
48
 
49
49
  ## Recent Changes
50
+ - 001-fifo-notify-queue: Added TypeScript 5.x (Bun runtime) + Bun native APIs, MLX-audio CLI (existing)
50
51
  - 001-qwen-tts: Added [if applicable, e.g., PostgreSQL, CoreData, files or N/A]
52
+
53
+ ## Active Technologies
54
+ - TypeScript 5.x (Bun runtime) + Bun native APIs, MLX-audio CLI (existing) (001-fifo-notify-queue)
55
+ - In-memory array (no persistence per spec) (001-fifo-notify-queue)
package/cliff.toml CHANGED
@@ -49,8 +49,10 @@ commit_parsers = [
49
49
  { message = "^style", group = "Styling" },
50
50
  { message = "^test", group = "Testing" },
51
51
  { message = "^chore\\(release\\): prepare for", skip = true },
52
- { message = "^docs.*update CHANGELOG", skip = true },
53
52
  { message = "^chore.*[Bb]ump version", skip = true },
53
+ { message = "^[Uu]pdate CHANGELOG", skip = true },
54
+ { message = "^[Uu]pdated CHANGELOG", skip = true },
55
+ { message = "\\[skip ci\\].*[Cc]hangelog", skip = true },
54
56
  { message = "^chore", group = "Miscellaneous Tasks" },
55
57
  { body = ".*security", group = "Security" },
56
58
  ]
package/docs/api.md CHANGED
@@ -7,6 +7,7 @@ The voice server provides a simple HTTP API for text-to-speech notifications and
7
7
  ![Voice Server Architecture](assets/voice-server-architecture.png)
8
8
 
9
9
  The voice server uses a modular architecture:
10
+
10
11
  - **Bun Server** - TypeScript HTTP API handling requests and validation
11
12
  - **MLX-audio** - Local TTS backend using the Kokoro-82M model
12
13
  - **macOS Integration** - Native audio playback via afplay
@@ -60,6 +61,7 @@ curl -X POST http://localhost:8888/notify \
60
61
  #### Response
61
62
 
62
63
  **Success (200):**
64
+
63
65
  ```json
64
66
  {
65
67
  "status": "success",
@@ -68,6 +70,7 @@ curl -X POST http://localhost:8888/notify \
68
70
  ```
69
71
 
70
72
  **Error (400):**
73
+
71
74
  ```json
72
75
  {
73
76
  "error": "Message is required"
@@ -112,6 +115,7 @@ curl -X POST http://localhost:8888/pai \
112
115
  #### Request Body
113
116
 
114
117
  Same fields as `/notify`, but uses PAI-optimized defaults:
118
+
115
119
  - Default `voice_id`: "12" (professional male)
116
120
  - Default `volume`: 1.0
117
121
  - Default `voice_enabled`: true
Binary file
@@ -0,0 +1,175 @@
1
+ # FIFO Notification Queue
2
+
3
+ The voice server implements a FIFO (First-In-First-Out) queue for processing voice notifications sequentially, preventing audio overlap when multiple agents send notifications simultaneously.
4
+
5
+ ## Overview
6
+
7
+ ### What Problem Does It Solve?
8
+
9
+ When multiple agents or processes send voice notifications simultaneously:
10
+ - **Before**: Audio would overlap, making notifications unintelligible
11
+ - **After**: Notifications are queued and played sequentially in order
12
+
13
+ ### Key Features
14
+
15
+ - **FIFO Processing**: Notifications processed in the order they arrive
16
+ - **Immediate Acknowledgment**: Returns `201 Accepted` within 100ms
17
+ - **Queue Monitoring**: `GET /queue/status` endpoint for real-time status
18
+ - **Graceful Shutdown**: Queue drains before server exits
19
+ - **Health Tracking**: Monitors queue depth, processing status, and TTS health
20
+
21
+ ## Usage
22
+
23
+ ### Sending Notifications
24
+
25
+ Send a POST request to `/notify`:
26
+
27
+ ```bash
28
+ curl -X POST http://localhost:8888/notify \
29
+ -H "Content-Type: application/json" \
30
+ -d '{
31
+ "title": "Notification",
32
+ "message": "Your notification text here",
33
+ "voice_id": "marrvin"
34
+ }'
35
+ ```
36
+
37
+ **Response:**
38
+ ```json
39
+ {
40
+ "status": "success",
41
+ "message": "Notification accepted and queued",
42
+ "queuePosition": 0,
43
+ "itemId": "queue_1234567890_abc123"
44
+ }
45
+ ```
46
+
47
+ ### Queue Status Monitoring
48
+
49
+ Check queue status in real-time:
50
+
51
+ ```bash
52
+ curl http://localhost:8888/queue/status
53
+ ```
54
+
55
+ **Response:**
56
+ ```json
57
+ {
58
+ "status": "success",
59
+ "depth": 3,
60
+ "processingStatus": "active",
61
+ "health": "healthy",
62
+ "metrics": {
63
+ "itemsProcessed": 42,
64
+ "itemsFailed": 0,
65
+ "averageProcessingTimeMs": 7100
66
+ }
67
+ }
68
+ ```
69
+
70
+ ### Status Values
71
+
72
+ **Queue Depth (`depth`)**
73
+ - Current number of notifications waiting to be processed
74
+ - Maximum: 100 items
75
+
76
+ **Processing Status (`processingStatus`)**
77
+ - `idle`: Queue is empty, not processing
78
+ - `active`: Currently processing a notification
79
+ - `draining`: Processing remaining items (shutdown mode)
80
+ - `stopped`: Queue not accepting new items
81
+
82
+ **Health Indicator (`health`)**
83
+ - `healthy`: Queue operating normally
84
+ - `degraded`: Queue depth above threshold (50 items)
85
+ - `unavailable`: TTS service failing
86
+
87
+ ## Response Codes
88
+
89
+ | Code | Meaning | When Returned |
90
+ |------|---------|---------------|
91
+ | 201 | Accepted | Notification queued successfully |
92
+ | 400 | Bad Request | Invalid request (missing fields, invalid data) |
93
+ | 429 | Too Many Requests | Queue is full (100 items max) |
94
+ | 500 | Internal Error | Server error occurred |
95
+
96
+ ## Configuration
97
+
98
+ Queue behavior can be configured via environment variables:
99
+
100
+ | Variable | Default | Description |
101
+ |----------|---------|-------------|
102
+ | `QUEUE_MAX_DEPTH` | 100 | Maximum queue depth |
103
+ | `QUEUE_DRAIN_TIMEOUT_MS` | 30000 | Shutdown drain timeout (milliseconds) |
104
+ | `QUEUE_DEGRADED_THRESHOLD` | 50 | Depth threshold for degraded health status |
105
+
106
+ ## Graceful Shutdown
107
+
108
+ When the server receives a shutdown signal:
109
+ 1. Sets status to "draining"
110
+ 2. Stops accepting new notifications (returns 503)
111
+ 3. Processes all remaining queued items
112
+ 4. Waits up to 30 seconds for queue to drain
113
+ 5. Logs remaining items if timeout occurs
114
+
115
+ ## Error Handling
116
+
117
+ The queue uses a **skip-on-failure** pattern:
118
+ - Failed notifications are marked as failed
119
+ - Processing continues with next item
120
+ - Failed items don't block the queue
121
+ - Errors are logged for troubleshooting
122
+
123
+ ## Performance
124
+
125
+ - **201 Response Time**: < 100ms (accepts request immediately)
126
+ - **Queue Status Response**: < 50ms
127
+ - **Processing Time**: ~7 seconds per notification (includes TTS generation + playback)
128
+
129
+ ## Examples
130
+
131
+ ### Single Notification
132
+
133
+ ```bash
134
+ curl -X POST http://localhost:8888/notify \
135
+ -H "Content-Type: application/json" \
136
+ -d '{"message": "Task completed", "voice_id": "marrvin"}'
137
+ ```
138
+
139
+ ### Multiple Rapid Notifications
140
+
141
+ ```bash
142
+ # Send 3 notifications rapidly
143
+ for i in {1..3}; do
144
+ curl -X POST http://localhost:8888/notify \
145
+ -H "Content-Type: application/json" \
146
+ -d "{\"message\": \"Notification $i\", \"voice_id\": \"marrvin\"}"
147
+ done
148
+ ```
149
+
150
+ ### Check Queue Status
151
+
152
+ ```bash
153
+ # Watch queue status in real-time
154
+ watch -n 1 'curl -s http://localhost:8888/queue/status | jq .'
155
+ ```
156
+
157
+ ## Troubleshooting
158
+
159
+ ### Queue Not Processing
160
+
161
+ 1. Check queue status: `curl http://localhost:8888/queue/status`
162
+ 2. Verify `processingStatus` is not "stopped"
163
+ 3. Check server logs for errors
164
+
165
+ ### Notifications Not Playing
166
+
167
+ 1. Check TTS health status
168
+ 2. Verify voice_id is valid
169
+ 3. Check audio output device
170
+
171
+ ### Queue Full (429 Response)
172
+
173
+ 1. Wait for current queue to drain
174
+ 2. Check if notifications are completing slowly
175
+ 3. Consider increasing `QUEUE_MAX_DEPTH` if needed
@@ -0,0 +1,182 @@
1
+ # Queue Architecture
2
+
3
+ Technical architecture of the FIFO notification queue system.
4
+
5
+ ## System Overview
6
+
7
+ ![Queue System Overview](assets/queue-system-overview.png)
8
+
9
+ ## Data Models
10
+
11
+ ### QueuedNotification
12
+
13
+ ```typescript
14
+ interface QueuedNotification {
15
+ id: string; // Unique identifier
16
+ request: NotificationRequest; // Original request
17
+ status: QueuedItemStatus; // pending | processing | completed | failed
18
+ arrivedAt: Date; // When queued
19
+ processingStartedAt?: Date; // When processing started
20
+ completedAt?: Date; // When completed
21
+ error?: string; // Error message if failed
22
+ }
23
+ ```
24
+
25
+ ### QueueState
26
+
27
+ ```typescript
28
+ interface QueueState {
29
+ depth: number; // Current queue depth
30
+ processingStatus: QueueProcessingStatus;
31
+ health: QueueHealth; // healthy | degraded | unavailable
32
+ metrics: QueueMetrics;
33
+ }
34
+
35
+ interface QueueMetrics {
36
+ itemsProcessed: number; // Total processed
37
+ itemsFailed: number; // Total failed
38
+ averageProcessingTimeMs: number; // Avg processing time
39
+ }
40
+ ```
41
+
42
+ ## Request Flow
43
+
44
+ ### Successful Notification Flow
45
+
46
+ ![Successful Request Flow](assets/queue-request-flow-success.png)
47
+
48
+ ### Error Handling Flow
49
+
50
+ ![Error Handling Flow](assets/queue-error-handling-flow.png)
51
+
52
+ ## Queue States
53
+
54
+ ![Queue State Transitions](assets/queue-states.png)
55
+
56
+ ## Component Interactions
57
+
58
+ ### NotificationQueue Class
59
+
60
+ ```typescript
61
+ class NotificationQueue {
62
+ private queue: QueuedNotification[] = [];
63
+ private processingStatus: QueueProcessingStatus = "idle";
64
+ private isProcessing = false;
65
+ private ttsProcessor: TTSProcessor;
66
+
67
+ async enqueue(request): Promise<EnqueueResult> {
68
+ // 1. Validate request
69
+ // 2. Check queue depth
70
+ // 3. Add to queue
71
+ // 4. Start processing
72
+ // 5. Return 201 Accepted
73
+ }
74
+
75
+ getQueueState(): QueueState {
76
+ // Return current state
77
+ }
78
+
79
+ async drain(): Promise<DrainResult> {
80
+ // 1. Set status to draining
81
+ // 2. Wait for queue empty (30s timeout)
82
+ // 3. Stop accepting new items
83
+ }
84
+
85
+ private processQueue(): Promise<void> {
86
+ // Single worker processes items sequentially
87
+ while (queue.length > 0 && status !== "stopped") {
88
+ // Process item, handle errors, shift queue
89
+ }
90
+ }
91
+ }
92
+ ```
93
+
94
+ ### TTS Processing Pipeline
95
+
96
+ ```typescript
97
+ async function processTTSWithMacOSNotification(request): Promise<void> {
98
+ // 1. Sanitize input
99
+ // 2. Resolve voice settings
100
+ 3. Display macOS notification (optional)
101
+ // 4. Process TTS:
102
+ // a. Generate audio with MLX-audio
103
+ // b. Play with afplay
104
+ // c. Clean up temp file
105
+ }
106
+ ```
107
+
108
+ ## Performance Characteristics
109
+
110
+ ### Throughput
111
+
112
+ - **Accept Rate**: ~10 requests/second (limited by queue depth)
113
+ - **Processing Rate**: ~1 notification/7 seconds
114
+ - **Queue Depth**: 100 items maximum
115
+ - **Burst Capacity**: Can handle bursts of rapid requests
116
+
117
+ ### Latency
118
+
119
+ - **201 Response**: < 100ms (immediate acceptance)
120
+ - **First Audio**: ~7-10 seconds (TTS generation + playback starts)
121
+ - **Complete Processing**: ~7-10 seconds per notification
122
+
123
+ ### Resource Usage
124
+
125
+ - **Memory**: ~1KB per queued item
126
+ - **Disk**: Temporary audio files (~100KB each, auto-cleaned)
127
+ - **CPU**: MLX-audio TTS generation (Apple Silicon optimized)
128
+
129
+ ## Security Considerations
130
+
131
+ ### Input Validation
132
+
133
+ - Title and message sanitized before TTS
134
+ - Voice ID validated against available voices
135
+ - Request size limits enforced
136
+
137
+ ### Rate Limiting
138
+
139
+ - Applied before queue admission
140
+ - Separate 429 response for queue full
141
+ - Per-client rate limits available
142
+
143
+ ### Error Isolation
144
+
145
+ - Failed notifications don't block queue
146
+ - TTS failures logged but don't crash server
147
+ - Graceful degradation on errors
148
+
149
+ ## Monitoring
150
+
151
+ ### Health Metrics
152
+
153
+ ```json
154
+ {
155
+ "depth": 5,
156
+ "processingStatus": "active",
157
+ "health": "healthy",
158
+ "metrics": {
159
+ "itemsProcessed": 156,
160
+ "itemsFailed": 2,
161
+ "averageProcessingTimeMs": 7123
162
+ }
163
+ }
164
+ ```
165
+
166
+ ### Health Indicators
167
+
168
+ | Health | Condition |
169
+ |--------|-----------|
170
+ | **healthy** | Queue depth < 50, TTS working |
171
+ | **degraded** | Queue depth ≥ 50 OR slow processing |
172
+ | **unavailable** | TTS failures > 50% of requests |
173
+
174
+ ### Logging
175
+
176
+ Key log messages for monitoring:
177
+
178
+ - `Notification queued` - New item added
179
+ - `Processing queued notification` - Processing started
180
+ - `Notification processed successfully` - Item completed
181
+ - `Notification processing failed` - Item failed
182
+ - `Queue drain complete` - Shutdown complete
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.10",
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