argus-echo 0.1.0__py3-none-any.whl
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.
- argus_echo/__init__.py +16 -0
- argus_echo/_version.py +24 -0
- argus_echo/assets/jfk.flac +0 -0
- argus_echo/check.py +226 -0
- argus_echo/cli.py +46 -0
- argus_echo/contract/__init__.py +36 -0
- argus_echo/contract/stt.py +120 -0
- argus_echo/contract/tts.py +79 -0
- argus_echo/py.typed +0 -0
- argus_echo-0.1.0.dist-info/METADATA +139 -0
- argus_echo-0.1.0.dist-info/RECORD +14 -0
- argus_echo-0.1.0.dist-info/WHEEL +4 -0
- argus_echo-0.1.0.dist-info/entry_points.txt +2 -0
- argus_echo-0.1.0.dist-info/licenses/LICENSE +21 -0
argus_echo/__init__.py
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
"""argus-echo — The Argus suite's speech servers: Miso, XTTS-v2 and Qwen3-TTS behind one HTTP contract, plus a Wyoming bridge"""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
try:
|
|
6
|
+
# Written by hatch-vcs at build time (see pyproject [tool.hatch.build.hooks.vcs]).
|
|
7
|
+
from argus_echo._version import __version__
|
|
8
|
+
except ImportError: # running from a source checkout that hasn't been built
|
|
9
|
+
from importlib.metadata import PackageNotFoundError, version
|
|
10
|
+
|
|
11
|
+
try:
|
|
12
|
+
__version__ = version("argus-echo")
|
|
13
|
+
except PackageNotFoundError:
|
|
14
|
+
__version__ = "0.0.0+unknown"
|
|
15
|
+
|
|
16
|
+
__all__ = ["__version__"]
|
argus_echo/_version.py
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# file generated by vcs-versioning
|
|
2
|
+
# don't change, don't track in version control
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
__all__ = [
|
|
6
|
+
"__version__",
|
|
7
|
+
"__version_tuple__",
|
|
8
|
+
"version",
|
|
9
|
+
"version_tuple",
|
|
10
|
+
"__commit_id__",
|
|
11
|
+
"commit_id",
|
|
12
|
+
]
|
|
13
|
+
|
|
14
|
+
version: str
|
|
15
|
+
__version__: str
|
|
16
|
+
__version_tuple__: tuple[int | str, ...]
|
|
17
|
+
version_tuple: tuple[int | str, ...]
|
|
18
|
+
commit_id: str | None
|
|
19
|
+
__commit_id__: str | None
|
|
20
|
+
|
|
21
|
+
__version__ = version = '0.1.0'
|
|
22
|
+
__version_tuple__ = version_tuple = (0, 1, 0)
|
|
23
|
+
|
|
24
|
+
__commit_id__ = commit_id = None
|
|
Binary file
|
argus_echo/check.py
ADDED
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
"""Check a running engine against the argus-echo contracts it advertises.
|
|
2
|
+
|
|
3
|
+
``/health`` names the engine's capabilities (``tts``, ``stt``); one that names none is a ``tts`` engine. Only the
|
|
4
|
+
matching checks run. Read-only by default: ``/health``, ``/speakers`` and ``/clones`` load nothing. ``speak`` also
|
|
5
|
+
streams one utterance and ``transcribe`` posts one clip, and either loads the model if it is not loaded (that can
|
|
6
|
+
take minutes for Miso 8B).
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import time
|
|
12
|
+
from dataclasses import dataclass, field
|
|
13
|
+
from importlib.resources import files
|
|
14
|
+
from pathlib import Path
|
|
15
|
+
|
|
16
|
+
import httpx
|
|
17
|
+
from argus_cortex.gpu_wire import ResidentHealth
|
|
18
|
+
from pydantic import ValidationError
|
|
19
|
+
|
|
20
|
+
from argus_echo.contract import DEFAULT_CAPABILITIES, StreamFormat, SynthesiseRequest
|
|
21
|
+
from argus_echo.contract.stt import TRANSCRIBE_PATH, Transcription
|
|
22
|
+
|
|
23
|
+
#: The clip ``check --transcribe`` sends by default: President Kennedy's 1961 inaugural address (11 s, public domain
|
|
24
|
+
#: as a work of the US federal government), 16 kHz mono FLAC.
|
|
25
|
+
BUNDLED_CLIP = "jfk.flac"
|
|
26
|
+
BUNDLED_CLIP_WORDS = ("ask", "country")
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
@dataclass
|
|
30
|
+
class Finding:
|
|
31
|
+
name: str
|
|
32
|
+
ok: bool
|
|
33
|
+
detail: str
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
@dataclass
|
|
37
|
+
class Report:
|
|
38
|
+
url: str
|
|
39
|
+
findings: list[Finding] = field(default_factory=list)
|
|
40
|
+
|
|
41
|
+
@property
|
|
42
|
+
def ok(self) -> bool:
|
|
43
|
+
return all(f.ok for f in self.findings)
|
|
44
|
+
|
|
45
|
+
def add(self, name: str, ok: bool, detail: str) -> None:
|
|
46
|
+
self.findings.append(Finding(name, ok, detail))
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def _get_json(client: httpx.Client, report: Report, path: str) -> object | None:
|
|
50
|
+
try:
|
|
51
|
+
r = client.get(path)
|
|
52
|
+
except httpx.HTTPError as exc:
|
|
53
|
+
report.add(f"GET {path}", False, f"request failed: {exc}")
|
|
54
|
+
return None
|
|
55
|
+
if r.status_code != 200:
|
|
56
|
+
report.add(f"GET {path}", False, f"HTTP {r.status_code}: {r.text[:200]}")
|
|
57
|
+
return None
|
|
58
|
+
try:
|
|
59
|
+
return r.json()
|
|
60
|
+
except ValueError:
|
|
61
|
+
report.add(f"GET {path}", False, "body is not JSON")
|
|
62
|
+
return None
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def check(
|
|
66
|
+
url: str,
|
|
67
|
+
*,
|
|
68
|
+
speak: str | None = None,
|
|
69
|
+
speaker: str | None = None,
|
|
70
|
+
timeout: float = 30.0,
|
|
71
|
+
speak_timeout: float = 600.0,
|
|
72
|
+
transcribe: bool | str | Path = False,
|
|
73
|
+
transport: httpx.BaseTransport | None = None,
|
|
74
|
+
) -> Report:
|
|
75
|
+
"""Run the checks against the engine at *url* and return what each found.
|
|
76
|
+
|
|
77
|
+
*transcribe* posts a clip to an ``stt`` engine: ``True`` for the bundled one, or a path to a WAV or FLAC file.
|
|
78
|
+
"""
|
|
79
|
+
url = url.rstrip("/")
|
|
80
|
+
report = Report(url)
|
|
81
|
+
with httpx.Client(base_url=url, timeout=timeout, transport=transport) as client:
|
|
82
|
+
loaded = False
|
|
83
|
+
capabilities: tuple[str, ...] = DEFAULT_CAPABILITIES
|
|
84
|
+
body = _get_json(client, report, "/health")
|
|
85
|
+
if body is not None:
|
|
86
|
+
try:
|
|
87
|
+
health = ResidentHealth.model_validate(body)
|
|
88
|
+
except ValidationError as exc:
|
|
89
|
+
report.add("GET /health", False, f"not argus-cortex ResidentHealth: {exc.errors()[0]['msg']}")
|
|
90
|
+
else:
|
|
91
|
+
extra = body if isinstance(body, dict) else {}
|
|
92
|
+
engine = extra.get("engine") or "?"
|
|
93
|
+
loaded = health.model_state in ("gpu", "cpu")
|
|
94
|
+
advertised = extra.get("capabilities")
|
|
95
|
+
if isinstance(advertised, list) and advertised and all(isinstance(c, str) for c in advertised):
|
|
96
|
+
capabilities = tuple(advertised)
|
|
97
|
+
report.add(
|
|
98
|
+
"GET /health",
|
|
99
|
+
True,
|
|
100
|
+
f"engine={engine} model={extra.get('model')} model_state={health.model_state} busy={health.busy} "
|
|
101
|
+
f"capabilities={','.join(capabilities)}",
|
|
102
|
+
)
|
|
103
|
+
|
|
104
|
+
if "tts" in capabilities:
|
|
105
|
+
_check_tts(client, report, loaded=loaded, speak=speak, speaker=speaker, speak_timeout=speak_timeout)
|
|
106
|
+
if "stt" in capabilities:
|
|
107
|
+
if transcribe:
|
|
108
|
+
clip = None if transcribe is True else Path(transcribe)
|
|
109
|
+
_check_transcribe(client, report, clip, speak_timeout)
|
|
110
|
+
else:
|
|
111
|
+
report.add(f"POST {TRANSCRIBE_PATH}", True, "skipped: transcribing loads the model (--transcribe)")
|
|
112
|
+
return report
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def _check_tts(
|
|
116
|
+
client: httpx.Client, report: Report, *, loaded: bool, speak: str | None, speaker: str | None, speak_timeout: float
|
|
117
|
+
) -> None:
|
|
118
|
+
# On XTTS and Qwen, /speakers takes a model lease, so it would load an unloaded model.
|
|
119
|
+
if loaded or speak:
|
|
120
|
+
speakers = _get_json(client, report, "/speakers")
|
|
121
|
+
if speakers is not None:
|
|
122
|
+
items = speakers.get("speakers") if isinstance(speakers, dict) else None
|
|
123
|
+
ok = isinstance(items, list)
|
|
124
|
+
report.add("GET /speakers", ok, f"{len(items)} speaker(s)" if ok else "no `speakers` list")
|
|
125
|
+
else:
|
|
126
|
+
report.add("GET /speakers", True, "skipped: the model is not loaded, and listing speakers may load it")
|
|
127
|
+
|
|
128
|
+
try:
|
|
129
|
+
r = client.get("/clones")
|
|
130
|
+
except httpx.HTTPError as exc:
|
|
131
|
+
report.add("GET /clones", False, f"request failed: {exc}")
|
|
132
|
+
else:
|
|
133
|
+
if r.status_code == 404:
|
|
134
|
+
report.add("GET /clones", True, "not served by this engine (it keeps no clone list)")
|
|
135
|
+
elif r.status_code != 200:
|
|
136
|
+
report.add("GET /clones", False, f"HTTP {r.status_code}: {r.text[:200]}")
|
|
137
|
+
else:
|
|
138
|
+
try:
|
|
139
|
+
items = r.json().get("clones")
|
|
140
|
+
except (ValueError, AttributeError):
|
|
141
|
+
items = None
|
|
142
|
+
ok = isinstance(items, list)
|
|
143
|
+
report.add("GET /clones", ok, f"{len(items)} clone(s)" if ok else "no `clones` list")
|
|
144
|
+
|
|
145
|
+
if speak:
|
|
146
|
+
_check_stream(client, report, SynthesiseRequest(text=speak, speaker=speaker), speak_timeout)
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
def _check_transcribe(client: httpx.Client, report: Report, clip: Path | None, timeout: float) -> None:
|
|
150
|
+
name = f"POST {TRANSCRIBE_PATH}"
|
|
151
|
+
if clip is None:
|
|
152
|
+
data, filename = files("argus_echo").joinpath("assets", BUNDLED_CLIP).read_bytes(), BUNDLED_CLIP
|
|
153
|
+
else:
|
|
154
|
+
try:
|
|
155
|
+
data, filename = clip.read_bytes(), clip.name
|
|
156
|
+
except OSError as exc:
|
|
157
|
+
report.add(name, False, f"cannot read {clip}: {exc.strerror}")
|
|
158
|
+
return
|
|
159
|
+
start = time.monotonic()
|
|
160
|
+
try:
|
|
161
|
+
r = client.post(TRANSCRIBE_PATH, files={"audio": (filename, data)}, timeout=timeout)
|
|
162
|
+
except httpx.HTTPError as exc:
|
|
163
|
+
report.add(name, False, f"request failed: {exc}")
|
|
164
|
+
return
|
|
165
|
+
total = time.monotonic() - start
|
|
166
|
+
if r.status_code != 200:
|
|
167
|
+
report.add(name, False, f"HTTP {r.status_code}: {r.text[:200]}")
|
|
168
|
+
return
|
|
169
|
+
try:
|
|
170
|
+
result = Transcription.model_validate(r.json())
|
|
171
|
+
except (ValueError, ValidationError) as exc:
|
|
172
|
+
report.add(name, False, f"not an stt Transcription: {str(exc)[:200]}")
|
|
173
|
+
return
|
|
174
|
+
if not result.text.strip():
|
|
175
|
+
report.add(name, False, "empty transcript")
|
|
176
|
+
return
|
|
177
|
+
if clip is None and not all(w in result.text.lower() for w in BUNDLED_CLIP_WORDS):
|
|
178
|
+
report.add(name, False, f"transcript does not match the bundled clip: {result.text[:120]!r}")
|
|
179
|
+
return
|
|
180
|
+
report.add(
|
|
181
|
+
name,
|
|
182
|
+
True,
|
|
183
|
+
f"{result.duration:.1f} s of {result.language} in {total:.2f} s ({len(result.segments)} segment(s)): "
|
|
184
|
+
f"{result.text[:80]!r}",
|
|
185
|
+
)
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
def _check_stream(client: httpx.Client, report: Report, req: SynthesiseRequest, timeout: float) -> None:
|
|
189
|
+
name = "POST /synthesise/stream"
|
|
190
|
+
payload = req.model_dump(exclude_none=True)
|
|
191
|
+
start = time.monotonic()
|
|
192
|
+
first: float | None = None
|
|
193
|
+
n_bytes = 0
|
|
194
|
+
try:
|
|
195
|
+
with client.stream("POST", "/synthesise/stream", json=payload, timeout=timeout) as r:
|
|
196
|
+
if r.status_code != 200:
|
|
197
|
+
r.read()
|
|
198
|
+
report.add(name, False, f"HTTP {r.status_code}: {r.text[:200]}")
|
|
199
|
+
return
|
|
200
|
+
try:
|
|
201
|
+
fmt = StreamFormat.from_headers(r.headers)
|
|
202
|
+
width = fmt.sample_width
|
|
203
|
+
except (ValueError, KeyError) as exc:
|
|
204
|
+
report.add(name, False, f"bad stream headers: {exc}")
|
|
205
|
+
return
|
|
206
|
+
for chunk in r.iter_bytes():
|
|
207
|
+
if chunk and first is None:
|
|
208
|
+
first = time.monotonic() - start
|
|
209
|
+
n_bytes += len(chunk)
|
|
210
|
+
except httpx.HTTPError as exc:
|
|
211
|
+
report.add(name, False, f"request failed: {exc}")
|
|
212
|
+
return
|
|
213
|
+
total = time.monotonic() - start
|
|
214
|
+
if n_bytes == 0:
|
|
215
|
+
report.add(name, False, "no audio")
|
|
216
|
+
return
|
|
217
|
+
if n_bytes % (width * fmt.channels):
|
|
218
|
+
report.add(name, False, f"{n_bytes} bytes is not a whole number of {fmt.audio_format} frames")
|
|
219
|
+
return
|
|
220
|
+
audio_s = fmt.seconds(n_bytes)
|
|
221
|
+
report.add(
|
|
222
|
+
name,
|
|
223
|
+
True,
|
|
224
|
+
f"{audio_s:.2f} s of {fmt.audio_format} {fmt.sample_rate} Hz x{fmt.channels}; "
|
|
225
|
+
f"first byte {first:.2f} s, total {total:.2f} s (RTF {total / audio_s:.2f})",
|
|
226
|
+
)
|
argus_echo/cli.py
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
"""``argus-echo`` command line."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
|
|
7
|
+
import typer
|
|
8
|
+
|
|
9
|
+
from argus_echo import __version__
|
|
10
|
+
from argus_echo.check import check as run_check
|
|
11
|
+
|
|
12
|
+
app = typer.Typer(help="argus-echo: the Argus suite's speech servers.", no_args_is_help=True)
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@app.callback()
|
|
16
|
+
def _main() -> None:
|
|
17
|
+
"""argus-echo: the Argus suite's speech servers."""
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
@app.command()
|
|
21
|
+
def version() -> None:
|
|
22
|
+
"""Print the installed version."""
|
|
23
|
+
typer.echo(__version__)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@app.command()
|
|
27
|
+
def check(
|
|
28
|
+
url: str = typer.Argument(..., help="An engine's base URL, e.g. http://localhost:8140"),
|
|
29
|
+
speak: str | None = typer.Option(
|
|
30
|
+
None, "--speak", help="Also stream this text and check the audio. Loads the model if it is not loaded."
|
|
31
|
+
),
|
|
32
|
+
speaker: str | None = typer.Option(None, "--speaker", help="Built-in speaker for --speak."),
|
|
33
|
+
transcribe: bool = typer.Option(
|
|
34
|
+
False, "--transcribe", help="stt engines: transcribe a bundled clip. Loads the model if it is not loaded."
|
|
35
|
+
),
|
|
36
|
+
clip: Path | None = typer.Option(None, "--clip", help="With --transcribe: a WAV or FLAC file to send instead."),
|
|
37
|
+
timeout: float = typer.Option(30.0, help="Seconds per read-only request."),
|
|
38
|
+
) -> None:
|
|
39
|
+
"""Check a running engine against the contracts it advertises. Exits 1 if any check fails."""
|
|
40
|
+
report = run_check(
|
|
41
|
+
url, speak=speak, speaker=speaker, transcribe=(clip or True) if transcribe else False, timeout=timeout
|
|
42
|
+
)
|
|
43
|
+
for f in report.findings:
|
|
44
|
+
mark = typer.style("ok ", fg="green") if f.ok else typer.style("FAIL", fg="red")
|
|
45
|
+
typer.echo(f"{mark} {f.name}: {f.detail}")
|
|
46
|
+
raise typer.Exit(0 if report.ok else 1)
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
"""The HTTP contracts argus-echo engines speak, one module per capability.
|
|
2
|
+
|
|
3
|
+
- :mod:`argus_echo.contract.tts`: text to speech (Miso, XTTS-v2, Qwen3-TTS).
|
|
4
|
+
- :mod:`argus_echo.contract.stt`: speech to text (the Whisper engine).
|
|
5
|
+
|
|
6
|
+
An engine names the capabilities it serves in ``GET /health`` (``capabilities``); one that names none is a ``tts``
|
|
7
|
+
engine. The TTS names are re-exported here so ``from argus_echo.contract import SynthesiseRequest`` keeps working.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
from argus_echo.contract.tts import (
|
|
13
|
+
AUDIO_FORMAT_HEADER,
|
|
14
|
+
CHANNELS_HEADER,
|
|
15
|
+
SAMPLE_RATE_HEADER,
|
|
16
|
+
SAMPLE_WIDTH,
|
|
17
|
+
StreamFormat,
|
|
18
|
+
SynthesiseRequest,
|
|
19
|
+
)
|
|
20
|
+
|
|
21
|
+
#: The capabilities an engine may advertise in ``GET /health``.
|
|
22
|
+
CAPABILITIES = ("tts", "stt")
|
|
23
|
+
|
|
24
|
+
#: What an engine that advertises nothing is taken to serve.
|
|
25
|
+
DEFAULT_CAPABILITIES = ("tts",)
|
|
26
|
+
|
|
27
|
+
__all__ = [
|
|
28
|
+
"AUDIO_FORMAT_HEADER",
|
|
29
|
+
"CAPABILITIES",
|
|
30
|
+
"CHANNELS_HEADER",
|
|
31
|
+
"DEFAULT_CAPABILITIES",
|
|
32
|
+
"SAMPLE_RATE_HEADER",
|
|
33
|
+
"SAMPLE_WIDTH",
|
|
34
|
+
"StreamFormat",
|
|
35
|
+
"SynthesiseRequest",
|
|
36
|
+
]
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
"""The ``stt`` contract: what a speech-to-text engine speaks.
|
|
2
|
+
|
|
3
|
+
The Whisper engine (``engines/whisper/``) serves it. The full reference, with every field and status code, is the
|
|
4
|
+
"Speech to text" section of ``docs/api.md``.
|
|
5
|
+
|
|
6
|
+
- ``POST /transcribe`` is ``multipart/form-data``: one ``audio`` file (WAV or FLAC) plus the optional
|
|
7
|
+
:class:`TranscribeOptions` fields. It answers a :class:`Transcription`.
|
|
8
|
+
- ``WS /transcribe/stream`` takes raw PCM (:data:`STREAM_SAMPLE_RATE`, :data:`STREAM_AUDIO_FORMAT`, mono) as
|
|
9
|
+
binary frames, cuts it into utterances with voice activity detection, and sends :class:`StreamPartial` while an
|
|
10
|
+
utterance is open and a :class:`StreamFinal` when it ends. The client may open with a :class:`StreamStart` and
|
|
11
|
+
sends :class:`StreamEnd` to flush the last utterance.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
from typing import Literal
|
|
17
|
+
|
|
18
|
+
from pydantic import BaseModel, ConfigDict, Field
|
|
19
|
+
|
|
20
|
+
TRANSCRIBE_PATH = "/transcribe"
|
|
21
|
+
STREAM_PATH = "/transcribe/stream"
|
|
22
|
+
|
|
23
|
+
#: The PCM layout ``/transcribe/stream`` takes: 16 kHz mono little-endian int16, the rate Whisper runs at.
|
|
24
|
+
STREAM_SAMPLE_RATE = 16000
|
|
25
|
+
STREAM_AUDIO_FORMAT = "pcm_s16le"
|
|
26
|
+
STREAM_CHANNELS = 1
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class TranscribeOptions(BaseModel):
|
|
30
|
+
"""The form fields of ``POST /transcribe`` beside the ``audio`` file (and the options of a stream)."""
|
|
31
|
+
|
|
32
|
+
model_config = ConfigDict(extra="forbid")
|
|
33
|
+
|
|
34
|
+
language: str | None = Field(
|
|
35
|
+
None,
|
|
36
|
+
description="ISO 639-1 code of the speech (``en``; a region suffix such as ``en-US`` is dropped). "
|
|
37
|
+
"Detected from the audio when absent.",
|
|
38
|
+
)
|
|
39
|
+
word_timestamps: bool = Field(False, description="Also time each word (``Segment.words``).")
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
class Word(BaseModel):
|
|
43
|
+
"""One word of a segment, with ``word_timestamps``."""
|
|
44
|
+
|
|
45
|
+
start: float = Field(ge=0, description="Seconds from the start of the audio.")
|
|
46
|
+
end: float = Field(ge=0)
|
|
47
|
+
word: str = Field(description="The word as transcribed, with its leading space if it had one.")
|
|
48
|
+
probability: float = Field(ge=0, le=1)
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
class Segment(BaseModel):
|
|
52
|
+
"""A stretch of the transcript with its time span."""
|
|
53
|
+
|
|
54
|
+
start: float = Field(ge=0, description="Seconds from the start of the audio.")
|
|
55
|
+
end: float = Field(ge=0)
|
|
56
|
+
text: str
|
|
57
|
+
words: list[Word] | None = Field(None, description="Present only when ``word_timestamps`` was asked for.")
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
class Transcription(BaseModel):
|
|
61
|
+
"""The answer of ``POST /transcribe``."""
|
|
62
|
+
|
|
63
|
+
text: str = Field(description="The whole transcript: the segments' text joined, stripped. Empty for silence.")
|
|
64
|
+
language: str = Field(description="The language used: the one asked for, or the detected one.")
|
|
65
|
+
language_probability: float | None = Field(
|
|
66
|
+
None, ge=0, le=1, description="Confidence of the detection; null when the language was given."
|
|
67
|
+
)
|
|
68
|
+
duration: float = Field(ge=0, description="Length of the audio in seconds.")
|
|
69
|
+
segments: list[Segment] = Field(default_factory=list)
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
# ── Streaming messages (JSON text frames) ────────────────────────────────────
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
class StreamStart(BaseModel):
|
|
76
|
+
"""Client, optional, before any audio: the stream's options."""
|
|
77
|
+
|
|
78
|
+
type: Literal["start"] = "start"
|
|
79
|
+
language: str | None = None
|
|
80
|
+
word_timestamps: bool = False
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
class StreamEnd(BaseModel):
|
|
84
|
+
"""Client: no more audio. The server finishes the open utterance, sends its final and closes."""
|
|
85
|
+
|
|
86
|
+
type: Literal["end"] = "end"
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
class StreamReady(BaseModel):
|
|
90
|
+
"""Server, first message: the PCM layout it expects and its endpointing settings."""
|
|
91
|
+
|
|
92
|
+
type: Literal["ready"] = "ready"
|
|
93
|
+
sample_rate: int = STREAM_SAMPLE_RATE
|
|
94
|
+
audio_format: str = STREAM_AUDIO_FORMAT
|
|
95
|
+
channels: int = STREAM_CHANNELS
|
|
96
|
+
min_silence_ms: int = Field(description="Silence that ends an utterance.")
|
|
97
|
+
max_utterance_s: float = Field(description="An utterance this long is ended even without silence.")
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
class StreamPartial(BaseModel):
|
|
101
|
+
"""Server: the open utterance transcribed so far. Later partials replace earlier ones."""
|
|
102
|
+
|
|
103
|
+
type: Literal["partial"] = "partial"
|
|
104
|
+
start: float = Field(ge=0, description="Seconds from the start of the stream at which the utterance began.")
|
|
105
|
+
text: str
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
class StreamFinal(Transcription):
|
|
109
|
+
"""Server: one finished utterance. Segment and word times are seconds from the start of the stream."""
|
|
110
|
+
|
|
111
|
+
type: Literal["final"] = "final"
|
|
112
|
+
start: float = Field(ge=0)
|
|
113
|
+
end: float = Field(ge=0)
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
class StreamError(BaseModel):
|
|
117
|
+
"""Server: the stream failed; the socket closes after it."""
|
|
118
|
+
|
|
119
|
+
type: Literal["error"] = "error"
|
|
120
|
+
error: str
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
"""The ``tts`` contract: what every text-to-speech engine speaks.
|
|
2
|
+
|
|
3
|
+
Each engine (Miso, XTTS-v2, Qwen3-TTS) is its own server with its own Python environment, so they share this
|
|
4
|
+
contract rather than code. A client written against it can switch engines by changing a URL. The full reference,
|
|
5
|
+
with every route and status code, is ``docs/api.md``.
|
|
6
|
+
|
|
7
|
+
- ``POST /synthesise`` takes a :class:`SynthesiseRequest` and returns ``audio_url`` (a WAV in the engine's storage).
|
|
8
|
+
- ``POST /synthesise/stream`` takes the same body and streams raw PCM. The format is in the response headers
|
|
9
|
+
(:class:`StreamFormat`): 24 kHz mono little-endian float32 on every engine today.
|
|
10
|
+
- ``GET /speakers``, ``GET /clones``, ``POST /clone-voice`` and the ``/clones/*`` routes manage voices.
|
|
11
|
+
- ``GET /health`` is argus-cortex's :class:`~argus_cortex.gpu_wire.ResidentHealth`, plus engine fields
|
|
12
|
+
(``engine``, ``model``, ``device``). ``POST /admin/{unload,evict,wake}`` take
|
|
13
|
+
``Authorization: Bearer $ARGUS_ADMIN_TOKEN`` and are closed (503) while it is unset.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
from collections.abc import Mapping
|
|
19
|
+
|
|
20
|
+
from pydantic import BaseModel, ConfigDict, Field
|
|
21
|
+
|
|
22
|
+
SAMPLE_RATE_HEADER = "X-Sample-Rate"
|
|
23
|
+
AUDIO_FORMAT_HEADER = "X-Audio-Format"
|
|
24
|
+
CHANNELS_HEADER = "X-Channels"
|
|
25
|
+
|
|
26
|
+
#: Bytes per sample for each ``X-Audio-Format`` an engine may send.
|
|
27
|
+
SAMPLE_WIDTH = {"pcm_f32le": 4, "pcm_s16le": 2}
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class SynthesiseRequest(BaseModel):
|
|
31
|
+
"""The body of ``POST /synthesise`` and ``POST /synthesise/stream``.
|
|
32
|
+
|
|
33
|
+
These fields are accepted by every engine. An engine ignores the ones it has no use for rather than refusing
|
|
34
|
+
them (Miso and XTTS ignore ``voice_description``, ``instruction`` and ``emotion``), so one request works
|
|
35
|
+
everywhere. Engine-specific fields (Miso's ``temperature``, ``topk`` and ``context``) pass through as extras.
|
|
36
|
+
"""
|
|
37
|
+
|
|
38
|
+
model_config = ConfigDict(extra="allow")
|
|
39
|
+
|
|
40
|
+
text: str = Field(min_length=1, description="What to say.")
|
|
41
|
+
voice_clone_id: str | None = Field(None, description="A stored clone (``GET /clones``); wins over ``speaker``.")
|
|
42
|
+
speaker: str | None = Field(None, description="A built-in speaker (``GET /speakers``).")
|
|
43
|
+
language: str = Field("en", description="ISO language code. Miso speaks English only.")
|
|
44
|
+
voice_description: str | None = Field(None, description="Qwen3-TTS: describe a voice to design.")
|
|
45
|
+
instruction: str | None = Field(None, description="Qwen3-TTS: delivery instruction for a built-in speaker.")
|
|
46
|
+
emotion: str = Field("neutral", description="Qwen3-TTS: delivery hint.")
|
|
47
|
+
speed: float | None = Field(None, description="Speaking-rate multiplier. XTTS applies it; Miso and Qwen ignore it.")
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
class StreamFormat(BaseModel):
|
|
51
|
+
"""The PCM layout of a ``/synthesise/stream`` response, read from its headers."""
|
|
52
|
+
|
|
53
|
+
model_config = ConfigDict(frozen=True)
|
|
54
|
+
|
|
55
|
+
sample_rate: int = Field(gt=0)
|
|
56
|
+
audio_format: str
|
|
57
|
+
channels: int = Field(gt=0)
|
|
58
|
+
|
|
59
|
+
@property
|
|
60
|
+
def sample_width(self) -> int:
|
|
61
|
+
"""Bytes per sample. Raises ``KeyError`` for a format this package does not know."""
|
|
62
|
+
return SAMPLE_WIDTH[self.audio_format]
|
|
63
|
+
|
|
64
|
+
def seconds(self, n_bytes: int) -> float:
|
|
65
|
+
"""Duration of *n_bytes* of audio in this format."""
|
|
66
|
+
return n_bytes / (self.sample_width * self.channels * self.sample_rate)
|
|
67
|
+
|
|
68
|
+
@classmethod
|
|
69
|
+
def from_headers(cls, headers: Mapping[str, str]) -> StreamFormat:
|
|
70
|
+
"""Parse the stream headers. Raises ``ValueError`` if one is missing or malformed."""
|
|
71
|
+
lower = {k.lower(): v for k, v in headers.items()}
|
|
72
|
+
try:
|
|
73
|
+
return cls(
|
|
74
|
+
sample_rate=int(lower[SAMPLE_RATE_HEADER.lower()]),
|
|
75
|
+
audio_format=lower[AUDIO_FORMAT_HEADER.lower()],
|
|
76
|
+
channels=int(lower[CHANNELS_HEADER.lower()]),
|
|
77
|
+
)
|
|
78
|
+
except KeyError as exc:
|
|
79
|
+
raise ValueError(f"missing stream header {exc.args[0]!r}") from None
|
argus_echo/py.typed
ADDED
|
File without changes
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: argus-echo
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: The Argus suite's speech servers: Miso, XTTS-v2 and Qwen3-TTS behind one HTTP contract, plus a Wyoming bridge
|
|
5
|
+
Project-URL: Repository, https://github.com/smk762/argus-echo
|
|
6
|
+
Author: smk762
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Classifier: Development Status :: 3 - Alpha
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Typing :: Typed
|
|
16
|
+
Requires-Python: >=3.11
|
|
17
|
+
Requires-Dist: argus-cortex<0.10,>=0.9
|
|
18
|
+
Requires-Dist: httpx>=0.27
|
|
19
|
+
Requires-Dist: pydantic>=2.6
|
|
20
|
+
Requires-Dist: typer>=0.12
|
|
21
|
+
Provides-Extra: dev
|
|
22
|
+
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
|
|
23
|
+
Requires-Dist: pytest>=8.0; extra == 'dev'
|
|
24
|
+
Requires-Dist: ruff==0.15.16; extra == 'dev'
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
|
|
27
|
+
# argus-echo
|
|
28
|
+
|
|
29
|
+
The Argus suite's speech servers: three text-to-speech engines behind one HTTP contract, so a client switches
|
|
30
|
+
engine by changing a URL, and a speech-to-text engine:
|
|
31
|
+
|
|
32
|
+
| Engine | Model | VRAM | Strengths |
|
|
33
|
+
| --- | --- | --- | --- |
|
|
34
|
+
| **miso** | [Miso TTS 8B](https://huggingface.co/MisoLabs/MisoTTS) | ~17 GB | Most natural and expressive; one-shot cloning; English |
|
|
35
|
+
| **xtts** | [Coqui XTTS-v2](https://huggingface.co/coqui/XTTS-v2) | ~2 GB | Multi-clip cloning, 17 languages, low-latency streaming |
|
|
36
|
+
| **qwen** | [Qwen3-TTS](https://huggingface.co/Qwen) 0.6B / 1.7B | small | Built-in speakers, voice design from a description |
|
|
37
|
+
| **whisper** | [Whisper large-v3-turbo](https://huggingface.co/openai/whisper-large-v3-turbo) (faster-whisper) | ~3 GB | Speech to text: 99 languages, word timestamps, live streaming with VAD |
|
|
38
|
+
|
|
39
|
+
Plus **Wyoming bridges** that put any engine, text to speech or speech to text, in front of Home Assistant or
|
|
40
|
+
anything else that speaks [Wyoming](https://github.com/OHF-Voice/wyoming).
|
|
41
|
+
|
|
42
|
+
Every engine loads its model on first use, unloads it when idle, and serves argus-cortex's resident contract
|
|
43
|
+
(`/health`, `/admin/{unload,evict,wake}`), so [argus-iris](https://github.com/smk762/argus-iris) can share a GPU
|
|
44
|
+
between them and other services. [argus-mask](https://github.com/smk762/argus-mask) uses them to give its faces a
|
|
45
|
+
voice.
|
|
46
|
+
|
|
47
|
+
Part of the [Argus suite](https://github.com/smk762/argus-cortex/blob/dev/SUITE.md).
|
|
48
|
+
|
|
49
|
+
## Run
|
|
50
|
+
|
|
51
|
+
Linux, Docker with Compose, an NVIDIA GPU and the
|
|
52
|
+
[NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html).
|
|
53
|
+
Each engine is a Compose profile; run the ones your GPU can hold:
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
cp .env.example .env # bind address, token, storage
|
|
57
|
+
docker compose --profile miso up -d --build # 24 GB card
|
|
58
|
+
docker compose --profile xtts --profile qwen up -d --build # 8 GB card
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Ports: Miso `8140`, XTTS `8141`, Qwen `8142`, Whisper `8144`; Wyoming bridges `10240` (XTTS), `10241` (Miso),
|
|
62
|
+
`10242` (Qwen) and `10243` (Whisper), see [Home Assistant](docs/voice-cloning.md#home-assistant). They are published on
|
|
63
|
+
`ECHO_BIND`, which defaults to `127.0.0.1`; set it to `0.0.0.0` or a LAN address to serve other machines. Miso downloads its ~33 GB checkpoint into `HF_HOME` on first use; the XTTS and Qwen images bake their
|
|
64
|
+
weights in at build time.
|
|
65
|
+
|
|
66
|
+
Check an engine (read-only; `--speak` also streams a sentence, which loads the model):
|
|
67
|
+
|
|
68
|
+
```sh
|
|
69
|
+
uvx argus-echo check http://localhost:8140
|
|
70
|
+
uvx argus-echo check http://localhost:8141 --speak "Hello there." --speaker "Claribel Dervla"
|
|
71
|
+
uvx argus-echo check http://localhost:8144 --transcribe # speech to text: a bundled 11 s clip
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Or by hand:
|
|
75
|
+
|
|
76
|
+
```sh
|
|
77
|
+
curl -s localhost:8140/synthesise/stream -H 'content-type: application/json' \
|
|
78
|
+
-d '{"text": "Hello there."}' --output hello.f32 # 24 kHz mono float32
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Storage
|
|
82
|
+
|
|
83
|
+
Generated WAVs and clones go to S3 (MinIO or any S3-compatible store): set `S3_ENDPOINT_URL` and the credentials
|
|
84
|
+
in `.env`. Each engine has **its own bucket** (`voice-miso`, `voice-xtts`, `voice-qwen` by default), because all
|
|
85
|
+
three store clones under the same keys in different formats. Create the buckets before first use. Miso can store
|
|
86
|
+
on local disk instead (`MISO_STORAGE_BACKEND=local`, the default) and serves those files itself.
|
|
87
|
+
|
|
88
|
+
## Security
|
|
89
|
+
|
|
90
|
+
`/admin/*` is closed until `ARGUS_ADMIN_TOKEN` is set (`openssl rand -hex 32`). **Every other route is open**,
|
|
91
|
+
clone creation and deletion included: keep the ports on a trusted network or behind an authenticating gateway.
|
|
92
|
+
Clone a real person's voice only with their consent. Details: [docs/api.md#security](docs/api.md#security).
|
|
93
|
+
|
|
94
|
+
## Documentation
|
|
95
|
+
|
|
96
|
+
| Doc | Contents |
|
|
97
|
+
| --- | --- |
|
|
98
|
+
| [docs/api.md](docs/api.md) | The shared contract, how the engines differ, health, admin, security |
|
|
99
|
+
| [docs/miso-api.md](docs/miso-api.md), [docs/miso-config.md](docs/miso-config.md) | Miso's full API and every `MISO_*` setting |
|
|
100
|
+
| [docs/xtts.md](docs/xtts.md) | XTTS-v2 settings and licence |
|
|
101
|
+
| [docs/qwen.md](docs/qwen.md) | Qwen3-TTS settings and differences |
|
|
102
|
+
| [docs/whisper.md](docs/whisper.md) | Speech to text: model choice, licences, VRAM, settings |
|
|
103
|
+
| [docs/new-engine.md](docs/new-engine.md) | Checklist for adding an engine (server, image, tests, wiring) |
|
|
104
|
+
| [docs/voice-cloning.md](docs/voice-cloning.md) | What makes a good reference on each engine; Home Assistant |
|
|
105
|
+
|
|
106
|
+
## Layout
|
|
107
|
+
|
|
108
|
+
```
|
|
109
|
+
compose.yaml one profile per engine
|
|
110
|
+
gpu-tenant.yaml the residents argus-iris manages
|
|
111
|
+
engines/<engine>/ each engine's server, Dockerfile and tests (its own Python environment)
|
|
112
|
+
src/argus_echo/ the contracts in Python (contract/tts.py, contract/stt.py), and `argus-echo check`
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
The engines don't import `argus_echo`: their dependencies conflict (Miso pins torch 2.9 for moshi), so they share the
|
|
116
|
+
contract, not code.
|
|
117
|
+
|
|
118
|
+
## Develop
|
|
119
|
+
|
|
120
|
+
```sh
|
|
121
|
+
make install && make test && make lint # the argus_echo package
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Each engine's tests run in its own environment, with the models stubbed (no GPU or weights). The commands are in
|
|
125
|
+
[.github/workflows/engines.yml](.github/workflows/engines.yml), for example:
|
|
126
|
+
|
|
127
|
+
```sh
|
|
128
|
+
cd engines/xtts && uv run --no-project --with "argus-cortex[server]>=0.8,<0.10" --with fastapi --with httpx \
|
|
129
|
+
--with structlog --with boto3 --with numpy --with soundfile --with python-multipart --with pytest \
|
|
130
|
+
python -m pytest -q tests
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
## Licence
|
|
134
|
+
|
|
135
|
+
MIT, see [LICENSE](LICENSE), except [engines/miso/](engines/miso/), which carries the upstream MisoTTS inference
|
|
136
|
+
code under Miso Labs' modified MIT licence ([engines/miso/LICENSE](engines/miso/LICENSE)). Model weights carry
|
|
137
|
+
their own licences: Miso TTS (modified MIT), XTTS-v2 (Coqui Public Model Licence, **non-commercial**), Qwen3-TTS
|
|
138
|
+
(Apache-2.0). Audio from Miso's `/synthesise` carries an imperceptible AI-generated watermark; streamed audio does
|
|
139
|
+
not.
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
argus_echo/__init__.py,sha256=PQiZpDTaBvk9XUVRm0hqWll1jIbpFOhslebYeGJiIog,602
|
|
2
|
+
argus_echo/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
|
|
3
|
+
argus_echo/check.py,sha256=d1pP7B-33Kd5xh65SU5y-3syrhwt2HjzHD05egikIBA,8909
|
|
4
|
+
argus_echo/cli.py,sha256=I3m5v5RcYU2o3THrgy6znWmdmkIR61_M5DD_1cTsH5c,1688
|
|
5
|
+
argus_echo/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
6
|
+
argus_echo/assets/jfk.flac,sha256=gdUoo1rM9b2gAG08MOatEZrhpHIaWYbm451ebqoR0sg,196992
|
|
7
|
+
argus_echo/contract/__init__.py,sha256=G5_Azm3WK_qwyfz9pffMJxvb7HG7EYtAwVE742cOQZQ,1058
|
|
8
|
+
argus_echo/contract/stt.py,sha256=9S-HtjFAc5VMHoQRfn6z0gNUOmnRr3g4MWw4T9-70rM,4602
|
|
9
|
+
argus_echo/contract/tts.py,sha256=613WkYgdH2qX6PdCY_fowyxRhSZMHDd0SsJWGhrHcm0,3895
|
|
10
|
+
argus_echo-0.1.0.dist-info/METADATA,sha256=Aq35_-l8xpVP1LDt0jyL_PHN1XUhm1sB6vvO0yksG4I,6887
|
|
11
|
+
argus_echo-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
12
|
+
argus_echo-0.1.0.dist-info/entry_points.txt,sha256=8kF1Mk2q_wI48G5gHGTc2B77mMtMMog0POUcsbsOdSY,50
|
|
13
|
+
argus_echo-0.1.0.dist-info/licenses/LICENSE,sha256=rVItjFwYlGlMC6dPK1mp0iIQE6ku9HMneX4mNbkuU54,1063
|
|
14
|
+
argus_echo-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 smk762
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|