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 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,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ argus-echo = argus_echo.cli:app
@@ -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.