@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/CHANGELOG.md
CHANGED
|
@@ -7,42 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
### Documentation
|
|
9
9
|
|
|
10
|
-
-
|
|
10
|
+
- FIFO queue documentation with visual diagrams ([53f4dd8](53f4dd8118c55f10dcbe55d42b054cd803731d4f))
|
|
11
11
|
|
|
12
|
-
- Update CHANGELOG.md [skip ci] ([e3d8e74](e3d8e74620518f9f5eaeea7cd5d793d05740cf51))
|
|
13
12
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
- Fix repository URL in mkdocs.yml ([60a5fee](60a5feecbcbf8bbe3b91443a3ce86ce9bc796fc3))
|
|
13
|
+
### Features
|
|
17
14
|
|
|
18
|
-
-
|
|
15
|
+
- Add Homebrew launchd plist for voice-server service ([8320799](83207990c29d3080d6d8f85e9fe2f61de7605e06))
|
|
19
16
|
|
|
20
17
|
|
|
21
18
|
### Miscellaneous Tasks
|
|
22
19
|
|
|
23
|
-
-
|
|
24
|
-
|
|
25
|
-
- Skip version bump commits in changelog ([6fc8a2d](6fc8a2dc9913ee5fdb1394d15432fd326b61a1e3))
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
[Unreleased]: https://github.com/madeinoz67/madeinoz-voice-server/compare/trunk...HEAD
|
|
30
|
-
## [0.1.7] - 2026-02-09
|
|
31
|
-
|
|
32
|
-
### Documentation
|
|
33
|
-
|
|
34
|
-
- Update CHANGELOG.md for v0.1.4 [skip ci] ([fe76674](fe76674036f7e7b1decf152ef6ca294ab93da10a))
|
|
20
|
+
- Bump @types/node from 25.2.2 to 25.2.3 ([7d07d72](7d07d725d251b8bcdc54accdddab91a776ff4713))
|
|
35
21
|
|
|
36
|
-
-
|
|
22
|
+
- Bump @typescript-eslint/eslint-plugin ([d8bf7ef](d8bf7ef16649ec199402eef0d044e2bb3744c78b))
|
|
37
23
|
|
|
38
|
-
-
|
|
24
|
+
- Bump typescript-eslint from 8.54.0 to 8.55.0 ([c28e5ea](c28e5ea3ebdf28d046bcc72e41dec653954ada3c))
|
|
39
25
|
|
|
40
|
-
-
|
|
26
|
+
- Bump @typescript-eslint/parser from 8.54.0 to 8.55.0 ([872c91e](872c91eb0c426c70777edd6a98d806e0cbf2d9af))
|
|
41
27
|
|
|
42
|
-
- Update CHANGELOG.md [skip ci] ([c3b7430](c3b74305c6238f94089a4552a4b151e566c84f75))
|
|
43
28
|
|
|
44
|
-
- Update CHANGELOG.md for v0.1.6 [skip ci] ([31657f8](31657f8de48c41e721c8400f9d0e22da155aea27))
|
|
45
29
|
|
|
30
|
+
[Unreleased]: https://github.com/madeinoz67/madeinoz-voice-server/compare/trunk...HEAD
|
|
31
|
+
## [0.1.7] - 2026-02-09
|
|
46
32
|
|
|
47
33
|
### Ci
|
|
48
34
|
|
|
@@ -66,50 +52,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
66
52
|
|
|
67
53
|
### Documentation
|
|
68
54
|
|
|
69
|
-
- Update CHANGELOG.md for v0.1.0 [skip ci] ([1d91e3d](1d91e3d5e18e65b30080c74dae7ecf70a506f021))
|
|
70
|
-
|
|
71
|
-
- Update CHANGELOG.md [skip ci] ([4e77dae](4e77dae378f41f4df76a60cdffacb56e1920f31c))
|
|
72
|
-
|
|
73
|
-
- Add visual assets and architecture diagram ([afeb22c](afeb22c9461924e8767a57a24b0dbfb83ed5ce56))
|
|
74
|
-
|
|
75
|
-
- Update CHANGELOG.md [skip ci] ([7dc28a7](7dc28a7bb9ae20986fa134721b4526b30ab3cfe9))
|
|
76
|
-
|
|
77
|
-
- Update CHANGELOG.md [skip ci] ([ef68568](ef685683a582bdf59e9b52f152bd3c103942fa4f))
|
|
78
|
-
|
|
79
|
-
- Update CHANGELOG.md [skip ci] ([1c1a663](1c1a6634ecfd932cc642601ebbb38f9d03e2cfc3))
|
|
80
|
-
|
|
81
|
-
- Update CHANGELOG.md [skip ci] ([40eee80](40eee80333ba6dddc3ed6e80e23f2853a9a2f31f))
|
|
82
|
-
|
|
83
|
-
- Update CHANGELOG.md [skip ci] ([0788bb3](0788bb3923be7230d8bd5695f6dec3f5634cb656))
|
|
84
|
-
|
|
85
|
-
- Update CHANGELOG.md [skip ci] ([262b9f7](262b9f7c66830ecd11ecad93fc19d0da86212387))
|
|
86
|
-
|
|
87
|
-
- Update CHANGELOG.md [skip ci] ([d9bb5e6](d9bb5e6bef8060c8e34c6201540e04a32beef6a3))
|
|
88
|
-
|
|
89
|
-
- Update CHANGELOG.md [skip ci] ([dcec442](dcec44218dec3bd74912add4a354f7cc7e43534a))
|
|
90
|
-
|
|
91
|
-
- Update CHANGELOG.md [skip ci] ([92ac66c](92ac66c15f86cb020ff005b1ad3d29cd87fcf83a))
|
|
92
|
-
|
|
93
|
-
- Update CHANGELOG.md [skip ci] ([8203d0f](8203d0f85b0979bda76719b6d4545f84b5b0705c))
|
|
94
|
-
|
|
95
|
-
- Update CHANGELOG.md [skip ci] ([f292411](f292411624150bf259ade7fe74e8235e0e0fcb24))
|
|
96
|
-
|
|
97
|
-
- Update CHANGELOG.md [skip ci] ([e6a7556](e6a75562c61fcd21eaeef5e1a46071b0b386c2cd))
|
|
98
|
-
|
|
99
55
|
- Rename project to voice-server ([c7e9209](c7e9209b2eeee1ac2af152f55b01045043cab2b9))
|
|
100
56
|
|
|
101
|
-
- Update CHANGELOG.md [skip ci] ([485f47e](485f47e3001035af7f8a3c39c1a271373d93b675))
|
|
102
|
-
|
|
103
|
-
- Update CHANGELOG.md for v0.1.1 [skip ci] ([6828e7d](6828e7dde9203622acd031cb7c70f2f1220c105e))
|
|
104
|
-
|
|
105
|
-
- Update CHANGELOG.md for v0.1.2 [skip ci] ([9dd2c2f](9dd2c2fe6a9b74117fbb2185e98704f506433ae4))
|
|
106
|
-
|
|
107
|
-
- Update CHANGELOG.md for v0.1.3 [skip ci] ([6894e0d](6894e0d647bfbcc92a4ed631626186421038a35a))
|
|
108
|
-
|
|
109
57
|
- Update npm package name and CI changelog ignore ([3cee42e](3cee42e74e4c5ef9fe9c456c5941036c5a210403))
|
|
110
58
|
|
|
111
|
-
- Update CHANGELOG.md [skip ci] ([369d7c4](369d7c417032169bc77ab3bf30956c961059b72f))
|
|
112
|
-
|
|
113
59
|
|
|
114
60
|
### Features
|
|
115
61
|
|
|
@@ -140,15 +86,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
140
86
|
- Add NPM_TOKEN to npm publish job ([a4f219b](a4f219b6449e8853783814fa0f02089ecb9d012a))
|
|
141
87
|
|
|
142
88
|
|
|
143
|
-
### Documentation
|
|
144
|
-
|
|
145
|
-
- Update CHANGELOG.md [skip ci] ([8b6de06](8b6de06bf64564a68dab8dd0297d0c755f885de5))
|
|
146
|
-
|
|
147
|
-
- Update CHANGELOG.md [skip ci] ([b0b380e](b0b380e0be8b43e9e00873ebe642e0bd9c6b31b9))
|
|
148
|
-
|
|
149
|
-
- Update CHANGELOG.md for v0.1.0 [skip ci] ([3d47e3d](3d47e3d6d3693fcf01712928e431c03e46d8809a))
|
|
150
|
-
|
|
151
|
-
|
|
152
89
|
### Features
|
|
153
90
|
|
|
154
91
|
- MLX-audio Kokoro Voice Server - Drop-in ElevenLabs Replacement ([f5bff4e](f5bff4e3123a31d0bb4d6aa2a3c86aed3000ecb9))
|
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/bun.lock
CHANGED
|
@@ -51,27 +51,27 @@
|
|
|
51
51
|
|
|
52
52
|
"@types/json-schema": ["@types/json-schema@7.0.15", "", {}, "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA=="],
|
|
53
53
|
|
|
54
|
-
"@types/node": ["@types/node@25.2.
|
|
54
|
+
"@types/node": ["@types/node@25.2.3", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-m0jEgYlYz+mDJZ2+F4v8D1AyQb+QzsNqRuI7xg1VQX/KlKS0qT9r1Mo16yo5F/MtifXFgaofIFsdFMox2SxIbQ=="],
|
|
55
55
|
|
|
56
|
-
"@typescript-eslint/eslint-plugin": ["@typescript-eslint/eslint-plugin@8.
|
|
56
|
+
"@typescript-eslint/eslint-plugin": ["@typescript-eslint/eslint-plugin@8.56.0", "", { "dependencies": { "@eslint-community/regexpp": "^4.12.2", "@typescript-eslint/scope-manager": "8.56.0", "@typescript-eslint/type-utils": "8.56.0", "@typescript-eslint/utils": "8.56.0", "@typescript-eslint/visitor-keys": "8.56.0", "ignore": "^7.0.5", "natural-compare": "^1.4.0", "ts-api-utils": "^2.4.0" }, "peerDependencies": { "@typescript-eslint/parser": "^8.56.0", "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0", "typescript": ">=4.8.4 <6.0.0" } }, "sha512-lRyPDLzNCuae71A3t9NEINBiTn7swyOhvUj3MyUOxb8x6g6vPEFoOU+ZRmGMusNC3X3YMhqMIX7i8ShqhT74Pw=="],
|
|
57
57
|
|
|
58
|
-
"@typescript-eslint/parser": ["@typescript-eslint/parser@8.
|
|
58
|
+
"@typescript-eslint/parser": ["@typescript-eslint/parser@8.56.0", "", { "dependencies": { "@typescript-eslint/scope-manager": "8.56.0", "@typescript-eslint/types": "8.56.0", "@typescript-eslint/typescript-estree": "8.56.0", "@typescript-eslint/visitor-keys": "8.56.0", "debug": "^4.4.3" }, "peerDependencies": { "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0", "typescript": ">=4.8.4 <6.0.0" } }, "sha512-IgSWvLobTDOjnaxAfDTIHaECbkNlAlKv2j5SjpB2v7QHKv1FIfjwMy8FsDbVfDX/KjmCmYICcw7uGaXLhtsLNg=="],
|
|
59
59
|
|
|
60
|
-
"@typescript-eslint/project-service": ["@typescript-eslint/project-service@8.
|
|
60
|
+
"@typescript-eslint/project-service": ["@typescript-eslint/project-service@8.56.0", "", { "dependencies": { "@typescript-eslint/tsconfig-utils": "^8.56.0", "@typescript-eslint/types": "^8.56.0", "debug": "^4.4.3" }, "peerDependencies": { "typescript": ">=4.8.4 <6.0.0" } }, "sha512-M3rnyL1vIQOMeWxTWIW096/TtVP+8W3p/XnaFflhmcFp+U4zlxUxWj4XwNs6HbDeTtN4yun0GNTTDBw/SvufKg=="],
|
|
61
61
|
|
|
62
|
-
"@typescript-eslint/scope-manager": ["@typescript-eslint/scope-manager@8.
|
|
62
|
+
"@typescript-eslint/scope-manager": ["@typescript-eslint/scope-manager@8.56.0", "", { "dependencies": { "@typescript-eslint/types": "8.56.0", "@typescript-eslint/visitor-keys": "8.56.0" } }, "sha512-7UiO/XwMHquH+ZzfVCfUNkIXlp/yQjjnlYUyYz7pfvlK3/EyyN6BK+emDmGNyQLBtLGaYrTAI6KOw8tFucWL2w=="],
|
|
63
63
|
|
|
64
|
-
"@typescript-eslint/tsconfig-utils": ["@typescript-eslint/tsconfig-utils@8.
|
|
64
|
+
"@typescript-eslint/tsconfig-utils": ["@typescript-eslint/tsconfig-utils@8.56.0", "", { "peerDependencies": { "typescript": ">=4.8.4 <6.0.0" } }, "sha512-bSJoIIt4o3lKXD3xmDh9chZcjCz5Lk8xS7Rxn+6l5/pKrDpkCwtQNQQwZ2qRPk7TkUYhrq3WPIHXOXlbXP0itg=="],
|
|
65
65
|
|
|
66
|
-
"@typescript-eslint/type-utils": ["@typescript-eslint/type-utils@8.
|
|
66
|
+
"@typescript-eslint/type-utils": ["@typescript-eslint/type-utils@8.56.0", "", { "dependencies": { "@typescript-eslint/types": "8.56.0", "@typescript-eslint/typescript-estree": "8.56.0", "@typescript-eslint/utils": "8.56.0", "debug": "^4.4.3", "ts-api-utils": "^2.4.0" }, "peerDependencies": { "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0", "typescript": ">=4.8.4 <6.0.0" } }, "sha512-qX2L3HWOU2nuDs6GzglBeuFXviDODreS58tLY/BALPC7iu3Fa+J7EOTwnX9PdNBxUI7Uh0ntP0YWGnxCkXzmfA=="],
|
|
67
67
|
|
|
68
|
-
"@typescript-eslint/types": ["@typescript-eslint/types@8.
|
|
68
|
+
"@typescript-eslint/types": ["@typescript-eslint/types@8.56.0", "", {}, "sha512-DBsLPs3GsWhX5HylbP9HNG15U0bnwut55Lx12bHB9MpXxQ+R5GC8MwQe+N1UFXxAeQDvEsEDY6ZYwX03K7Z6HQ=="],
|
|
69
69
|
|
|
70
|
-
"@typescript-eslint/typescript-estree": ["@typescript-eslint/typescript-estree@8.
|
|
70
|
+
"@typescript-eslint/typescript-estree": ["@typescript-eslint/typescript-estree@8.56.0", "", { "dependencies": { "@typescript-eslint/project-service": "8.56.0", "@typescript-eslint/tsconfig-utils": "8.56.0", "@typescript-eslint/types": "8.56.0", "@typescript-eslint/visitor-keys": "8.56.0", "debug": "^4.4.3", "minimatch": "^9.0.5", "semver": "^7.7.3", "tinyglobby": "^0.2.15", "ts-api-utils": "^2.4.0" }, "peerDependencies": { "typescript": ">=4.8.4 <6.0.0" } }, "sha512-ex1nTUMWrseMltXUHmR2GAQ4d+WjkZCT4f+4bVsps8QEdh0vlBsaCokKTPlnqBFqqGaxilDNJG7b8dolW2m43Q=="],
|
|
71
71
|
|
|
72
|
-
"@typescript-eslint/utils": ["@typescript-eslint/utils@8.
|
|
72
|
+
"@typescript-eslint/utils": ["@typescript-eslint/utils@8.56.0", "", { "dependencies": { "@eslint-community/eslint-utils": "^4.9.1", "@typescript-eslint/scope-manager": "8.56.0", "@typescript-eslint/types": "8.56.0", "@typescript-eslint/typescript-estree": "8.56.0" }, "peerDependencies": { "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0", "typescript": ">=4.8.4 <6.0.0" } }, "sha512-RZ3Qsmi2nFGsS+n+kjLAYDPVlrzf7UhTffrDIKr+h2yzAlYP/y5ZulU0yeDEPItos2Ph46JAL5P/On3pe7kDIQ=="],
|
|
73
73
|
|
|
74
|
-
"@typescript-eslint/visitor-keys": ["@typescript-eslint/visitor-keys@8.
|
|
74
|
+
"@typescript-eslint/visitor-keys": ["@typescript-eslint/visitor-keys@8.56.0", "", { "dependencies": { "@typescript-eslint/types": "8.56.0", "eslint-visitor-keys": "^5.0.0" } }, "sha512-q+SL+b+05Ud6LbEE35qe4A99P+htKTKVbyiNEe45eCbJFyh/HVK9QXwlrbz+Q4L8SOW4roxSVwXYj4DMBT7Ieg=="],
|
|
75
75
|
|
|
76
76
|
"acorn": ["acorn@8.15.0", "", { "bin": { "acorn": "bin/acorn" } }, "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg=="],
|
|
77
77
|
|
|
@@ -185,7 +185,7 @@
|
|
|
185
185
|
|
|
186
186
|
"typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
|
|
187
187
|
|
|
188
|
-
"typescript-eslint": ["typescript-eslint@8.
|
|
188
|
+
"typescript-eslint": ["typescript-eslint@8.56.0", "", { "dependencies": { "@typescript-eslint/eslint-plugin": "8.56.0", "@typescript-eslint/parser": "8.56.0", "@typescript-eslint/typescript-estree": "8.56.0", "@typescript-eslint/utils": "8.56.0" }, "peerDependencies": { "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0", "typescript": ">=4.8.4 <6.0.0" } }, "sha512-c7toRLrotJ9oixgdW7liukZpsnq5CZ7PuKztubGYlNppuTqhIoWfhgHo/7EU0v06gS2l/x0i2NEFK1qMIf0rIg=="],
|
|
189
189
|
|
|
190
190
|
"undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
|
|
191
191
|
|
|
@@ -201,7 +201,7 @@
|
|
|
201
201
|
|
|
202
202
|
"@typescript-eslint/typescript-estree/minimatch": ["minimatch@9.0.5", "", { "dependencies": { "brace-expansion": "^2.0.1" } }, "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow=="],
|
|
203
203
|
|
|
204
|
-
"
|
|
204
|
+
"bun-types/@types/node": ["@types/node@25.2.2", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-BkmoP5/FhRYek5izySdkOneRyXYN35I860MFAGupTdebyE66uZaR+bXLHq8k4DirE5DwQi3NuhvRU1jqTVwUrQ=="],
|
|
205
205
|
|
|
206
206
|
"eslint/ignore": ["ignore@5.3.2", "", {}, "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g=="],
|
|
207
207
|
}
|
package/cliff.toml
CHANGED
|
@@ -41,6 +41,16 @@ commit_preprocessors = [
|
|
|
41
41
|
{ pattern = '#([0-9]+)', replace = "https://github.com/madeinoz67/madeinoz-voice-server/issues/$1" },
|
|
42
42
|
]
|
|
43
43
|
commit_parsers = [
|
|
44
|
+
# Skip patterns FIRST (before grouping)
|
|
45
|
+
{ message = "^chore\\(release\\): prepare for", skip = true },
|
|
46
|
+
{ message = "^chore.*[Bb]ump version", skip = true },
|
|
47
|
+
{ message = "[Uu]pdate CHANGELOG", skip = true },
|
|
48
|
+
{ message = "[Uu]pdated CHANGELOG", skip = true },
|
|
49
|
+
{ message = "CHANGELOG.*\\[skip ci\\]", skip = true },
|
|
50
|
+
{ message = "\\[skip ci\\].*CHANGELOG", skip = true },
|
|
51
|
+
{ message = "^docs.*CHANGELOG", skip = true },
|
|
52
|
+
{ message = "^chore.*[Cc]hangelog", skip = true },
|
|
53
|
+
# Grouping patterns (after skip patterns)
|
|
44
54
|
{ message = "^feat", group = "Features" },
|
|
45
55
|
{ message = "^fix", group = "Bug Fixes" },
|
|
46
56
|
{ message = "^docs", group = "Documentation" },
|
|
@@ -48,9 +58,6 @@ commit_parsers = [
|
|
|
48
58
|
{ message = "^refactor", group = "Refactor" },
|
|
49
59
|
{ message = "^style", group = "Styling" },
|
|
50
60
|
{ message = "^test", group = "Testing" },
|
|
51
|
-
{ message = "^chore\\(release\\): prepare for", skip = true },
|
|
52
|
-
{ message = "^docs.*update CHANGELOG", skip = true },
|
|
53
|
-
{ message = "^chore.*[Bb]ump version", skip = true },
|
|
54
61
|
{ message = "^chore", group = "Miscellaneous Tasks" },
|
|
55
62
|
{ body = ".*security", group = "Security" },
|
|
56
63
|
]
|
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
|

|
|
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
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
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
|
+

|
|
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
|
+

|
|
47
|
+
|
|
48
|
+
### Error Handling Flow
|
|
49
|
+
|
|
50
|
+

|
|
51
|
+
|
|
52
|
+
## Queue States
|
|
53
|
+
|
|
54
|
+

|
|
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
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
<?xml version="1.0" encoding="UTF-8"?>
|
|
2
|
+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
|
3
|
+
<plist version="1.0">
|
|
4
|
+
<dict>
|
|
5
|
+
<key>Label</key>
|
|
6
|
+
<string>homebrew.mxcl.voice-server</string>
|
|
7
|
+
<key>ProgramArguments</key>
|
|
8
|
+
<array>
|
|
9
|
+
<string>/opt/homebrew/opt/bun/bin/bun</string>
|
|
10
|
+
<string>run</string>
|
|
11
|
+
<string>/opt/homebrew/opt/voice-server/dist/server.js</string>
|
|
12
|
+
</array>
|
|
13
|
+
<key>RunAtLoad</key>
|
|
14
|
+
<true/>
|
|
15
|
+
<key>KeepAlive</key>
|
|
16
|
+
<true/>
|
|
17
|
+
<key>StandardOutPath</key>
|
|
18
|
+
<string>/opt/homebrew/var/log/voice-server.log</string>
|
|
19
|
+
<key>StandardErrorPath</key>
|
|
20
|
+
<string>/opt/homebrew/var/log/voice-server.log</string>
|
|
21
|
+
<key>EnvironmentVariables</key>
|
|
22
|
+
<dict>
|
|
23
|
+
<key>PATH</key>
|
|
24
|
+
<string>/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
|
|
25
|
+
<key>PORT</key>
|
|
26
|
+
<string>8888</string>
|
|
27
|
+
</dict>
|
|
28
|
+
<key>WorkingDirectory</key>
|
|
29
|
+
<string>/opt/homebrew/opt/voice-server</string>
|
|
30
|
+
<key>UserName</key>
|
|
31
|
+
<string></string>
|
|
32
|
+
</dict>
|
|
33
|
+
</plist>
|