poly-server 0.1.0__py3-none-any.whl

poly_server/__init__.py

@@ -0,0 +1,8 @@
+"""poly-server: detecção do idioma falado e tradução de interfaces para o Poly."""
+
+__version__ = "0.1.0"
+
+from .app import create_app
+from .config import Settings
+
+__all__ = ["create_app", "Settings", "__version__"]

poly_server/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

poly_server/app.py

@@ -0,0 +1,210 @@
+"""Aplicação FastAPI do poly-server."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from contextlib import asynccontextmanager
+from typing import Callable
+
+import numpy as np
+from fastapi import FastAPI, HTTPException, WebSocket, WebSocketDisconnect
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.concurrency import run_in_threadpool
+from pydantic import BaseModel, Field
+
+from . import __version__
+from .asr import Recognizer, WhisperRecognizer
+from .config import Settings
+from .events import EventHub
+from .listening import ListeningController
+from .translate import ArgosTranslator, CachedTranslator, Translator, UnsupportedLanguagePair
+from .vad import Segmenter, pcm16_to_float32
+
+log = logging.getLogger("poly_server")
+
+
+class TranslateRequest(BaseModel):
+    source_lang: str = "en"
+    target_lang: str
+    texts: dict[str, str] = Field(default_factory=dict)
+
+
+class TranslateResponse(BaseModel):
+    target_lang: str
+    texts: dict[str, str]
+
+
+def create_app(
+    settings: Settings | None = None,
+    *,
+    recognizer: Recognizer | None = None,
+    translator: Translator | None = None,
+    segmenter_factory: Callable[[], Segmenter] | None = None,
+) -> FastAPI:
+    """
+    Cria o app. `recognizer`, `translator` e `segmenter_factory` podem ser
+    trocados (testes, outro motor de tradução, outro modelo de voz).
+    """
+    settings = settings or Settings.from_env()
+    recognizer = recognizer or WhisperRecognizer(
+        settings.whisper_model,
+        device=settings.whisper_device,
+        compute_type=settings.whisper_compute_type,
+        download_root=settings.cache_dir / "whisper",
+    )
+    translator = translator or CachedTranslator(
+        ArgosTranslator(auto_download=settings.auto_download),
+        settings.cache_dir / "translations.sqlite",
+    )
+
+    def make_segmenter() -> Segmenter:
+        if segmenter_factory:
+            return segmenter_factory()
+        return Segmenter(
+            vad_mode=settings.vad_mode,
+            frame_ms=settings.frame_ms,
+            pre_roll_ms=settings.pre_roll_ms,
+            start_trigger_ms=settings.start_trigger_ms,
+            end_trigger_ms=settings.end_trigger_ms,
+            max_utterance_sec=settings.max_utterance_sec,
+        )
+
+    hub = EventHub()
+    state = {"mic": False}
+
+    controller = ListeningController(make_segmenter(), recognizer.recognize, hub.publish)
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        hub.bind(asyncio.get_running_loop())
+        mic = None
+        if settings.mic:
+            from .mic import MicSource
+
+            try:
+                mic = MicSource(controller.feed, device=settings.mic_device)
+                mic.start()
+                state["mic"] = True
+            except RuntimeError as e:
+                log.warning("%s Continuing without local microphone.", e)
+        yield
+        if mic:
+            mic.stop()
+
+    app = FastAPI(title="poly-server", version=__version__, lifespan=lifespan)
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.cors_origins,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    @app.get("/health")
+    def health():
+        return {"ok": True, "version": __version__, "mic": state["mic"]}
+
+    @app.post("/i18n/auto-translate", response_model=TranslateResponse)
+    def auto_translate(req: TranslateRequest):
+        keys = list(req.texts.keys())
+        try:
+            values = translator.translate_many([req.texts[k] for k in keys], req.source_lang, req.target_lang)
+        except UnsupportedLanguagePair as e:
+            raise HTTPException(
+                status_code=422,
+                detail={
+                    "code": "unsupported_language_pair",
+                    "source": e.source,
+                    "target": e.target,
+                    "message": str(e),
+                },
+            ) from e
+        return TranslateResponse(target_lang=req.target_lang, texts=dict(zip(keys, values)))
+
+    @app.websocket("/ws")
+    async def events(ws: WebSocket):
+        """
+        Eventos do microfone local, para todos os clientes. Comandos aceitos:
+        {"type": "config", "listening": "manual"} e
+        {"type": "listen", "action": "start" | "stop"}.
+        """
+        await ws.accept()
+        q = hub.subscribe()
+        manual = False
+
+        async def send_events():
+            while True:
+                await ws.send_json(await q.get())
+
+        async def receive_commands():
+            nonlocal manual
+            while True:
+                msg = await ws.receive_json()
+                kind = msg.get("type")
+                if kind == "config" and msg.get("listening") == "manual" and not manual:
+                    manual = True
+                    controller.add_manual_client()
+                    await ws.send_json({"type": "listening", "listening": controller.listening})
+                elif kind == "listen" and msg.get("action") == "start":
+                    await run_in_threadpool(controller.start)
+                elif kind == "listen" and msg.get("action") == "stop":
+                    await run_in_threadpool(controller.stop)
+
+        tasks = [asyncio.create_task(send_events()), asyncio.create_task(receive_commands())]
+        try:
+            done, _ = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+            for t in done:
+                if t.exception() and not isinstance(t.exception(), WebSocketDisconnect):
+                    log.warning("ws: %s", t.exception())
+        finally:
+            for t in tasks:
+                t.cancel()
+            hub.unsubscribe(q)
+            if manual:
+                controller.remove_manual_client()
+
+    @app.websocket("/ws/audio")
+    async def audio(ws: WebSocket):
+        """
+        Áudio vindo do navegador: mensagens binárias com PCM 16-bit little
+        endian, mono, 16 kHz. Os eventos de reconhecimento voltam só para
+        este cliente: {"type": "speech_start"} quando a fala começa e
+        {"type": "utterance_end"} quando termina, antes do reconhecimento. Mensagens de texto: {"type": "flush"} reconhece a fala em
+        andamento (botão "parar"); {"type": "reset"} descarta o áudio.
+        """
+        await ws.accept()
+        segmenter = make_segmenter()
+
+        async def recognize_and_send(utterance: np.ndarray) -> None:
+            result = await run_in_threadpool(recognizer.recognize, utterance)
+            await ws.send_json(result.to_event())
+
+        try:
+            while True:
+                msg = await ws.receive()
+                if msg["type"] == "websocket.disconnect":
+                    break
+                if msg.get("bytes") is not None:
+                    was_speaking = segmenter.in_speech
+                    utterances = segmenter.feed(pcm16_to_float32(msg["bytes"]))
+                    if not was_speaking and (segmenter.in_speech or utterances):
+                        await ws.send_json({"type": "speech_start"})
+                    for utterance in utterances:
+                        # Avisa já, antes de reconhecer (leva segundos): no
+                        # modo manual o navegador fecha o microfone aqui.
+                        await ws.send_json({"type": "utterance_end"})
+                        await recognize_and_send(utterance)
+                elif msg.get("text"):
+                    kind = json.loads(msg["text"]).get("type")
+                    if kind == "flush":
+                        pending = segmenter.flush()
+                        segmenter.reset()
+                        if pending is not None:
+                            await recognize_and_send(pending)
+                    elif kind == "reset":
+                        segmenter.reset()
+        except WebSocketDisconnect:
+            pass
+
+    return app

poly_server/asr.py

@@ -0,0 +1,76 @@
+"""Reconhecimento de fala: idioma + transcrição."""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Protocol
+
+import numpy as np
+
+
+@dataclass
+class Recognition:
+    language: str
+    confidence: float
+    text: str
+    latency_sec: float
+
+    def to_event(self) -> dict:
+        return {"type": "asr", **asdict(self)}
+
+
+class Recognizer(Protocol):
+    def recognize(self, audio: np.ndarray) -> Recognition: ...
+
+
+class WhisperRecognizer:
+    """faster-whisper. O modelo é carregado na primeira fala (ou em `load()`)."""
+
+    def __init__(
+        self,
+        model: str = "base",
+        *,
+        device: str = "auto",
+        compute_type: str = "int8",
+        download_root: Path | None = None,
+    ) -> None:
+        self._model_name = model
+        self._device = device
+        self._compute_type = compute_type
+        self._download_root = download_root
+        self._model = None
+        self._lock = threading.Lock()
+
+    def load(self):
+        with self._lock:
+            if self._model is None:
+                from faster_whisper import WhisperModel
+
+                self._model = WhisperModel(
+                    self._model_name,
+                    device=self._device,
+                    compute_type=self._compute_type,
+                    download_root=str(self._download_root) if self._download_root else None,
+                )
+        return self._model
+
+    def recognize(self, audio: np.ndarray) -> Recognition:
+        model = self.load()
+        t0 = time.time()
+        # Um modelo por vez: em CPU, rodar duas falas em paralelo só deixa as duas lentas.
+        with self._lock:
+            segments, info = model.transcribe(
+                audio,
+                beam_size=1,
+                condition_on_previous_text=False,
+            )
+            text = "".join(s.text for s in segments).strip()
+        return Recognition(
+            language=info.language,
+            confidence=round(float(info.language_probability), 4),
+            text=text,
+            latency_sec=round(time.time() - t0, 3),
+        )

poly_server/cli.py

@@ -0,0 +1,94 @@
+"""Linha de comando: poly-server serve | download | devices."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+
+from . import __version__
+from .config import Settings
+
+
+def _serve(args: argparse.Namespace) -> None:
+    import uvicorn
+
+    from .app import create_app
+
+    settings = Settings.from_env(
+        host=args.host,
+        port=args.port,
+        whisper_model=args.model,
+        mic_device=args.mic_device,
+        cors_origins=args.cors.split(",") if args.cors else None,
+        mic=False if args.no_mic else None,
+        auto_download=False if args.offline else None,
+    )
+    uvicorn.run(create_app(settings), host=settings.host, port=settings.port)
+
+
+def _download(args: argparse.Namespace) -> None:
+    """Prepara uma instalação offline: modelo de voz + pacotes de tradução."""
+    from .asr import WhisperRecognizer
+    from .translate import ArgosTranslator, UnsupportedLanguagePair
+
+    settings = Settings.from_env(whisper_model=args.model)
+
+    print(f"Downloading speech model '{settings.whisper_model}'...")
+    WhisperRecognizer(settings.whisper_model, download_root=settings.cache_dir / "whisper").load()
+
+    translator = ArgosTranslator(auto_download=True)
+    targets = [t.strip() for t in args.languages.split(",") if t.strip()]
+    failed = []
+    for target in targets:
+        print(f"Translation {args.base} -> {target}...")
+        try:
+            translator.ensure_pair(args.base, target)
+        except UnsupportedLanguagePair:
+            failed.append(target)
+    if failed:
+        print(f"No translation package available for: {', '.join(failed)}", file=sys.stderr)
+        sys.exit(1)
+    print("Done.")
+
+
+def _devices(_: argparse.Namespace) -> None:
+    from .mic import list_input_devices
+
+    for d in list_input_devices():
+        print(f"{d['index']:>3}  {d['name']}  ({d['channels']} ch)")
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(prog="poly-server", description="Speech language detection + UI translation server for Poly.")
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    serve = sub.add_parser("serve", help="start the server")
+    serve.add_argument("--host")
+    serve.add_argument("--port", type=int)
+    serve.add_argument("--model", help="whisper model: tiny, base, small, medium, large-v3")
+    serve.add_argument("--mic-device", help="input device index or name (see `poly-server devices`)")
+    serve.add_argument("--no-mic", action="store_true", help="don't capture the local microphone (browser audio only)")
+    serve.add_argument("--cors", help="comma-separated allowed origins (default: *)")
+    serve.add_argument("--offline", action="store_true", help="never download translation packages")
+    serve.set_defaults(func=_serve)
+
+    download = sub.add_parser("download", help="download models for offline use")
+    download.add_argument("--base", default="en", help="language your UI is written in (default: en)")
+    download.add_argument("--languages", required=True, help="comma-separated target languages, e.g. pt,es,fr,ar")
+    download.add_argument("--model", help="whisper model to download")
+    download.set_defaults(func=_download)
+
+    devices = sub.add_parser("devices", help="list microphones")
+    devices.set_defaults(func=_devices)
+
+    args = parser.parse_args(argv)
+    if getattr(args, "mic_device", None) and str(args.mic_device).isdigit():
+        args.mic_device = int(args.mic_device)
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

poly_server/config.py

@@ -0,0 +1,71 @@
+"""Configuração do servidor, lida de variáveis de ambiente POLY_*."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+from typing import Any
+
+
+def _default_cache_dir() -> Path:
+    base = os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache"
+    return Path(base) / "poly-server"
+
+
+@dataclass
+class Settings:
+    host: str = "127.0.0.1"
+    port: int = 8000
+    # Origens liberadas no CORS. "*" libera qualquer uma.
+    cors_origins: list[str] = field(default_factory=lambda: ["*"])
+
+    # Captura o microfone do próprio computador (modo quiosque). Com False,
+    # o áudio só chega pelo navegador, via WebSocket /ws/audio.
+    mic: bool = True
+    # Índice ou nome do dispositivo de entrada (veja `poly-server devices`).
+    mic_device: int | str | None = None
+
+    # Modelo do faster-whisper: tiny, base, small, medium, large-v3...
+    whisper_model: str = "base"
+    whisper_device: str = "auto"  # auto, cpu, cuda
+    whisper_compute_type: str = "int8"
+
+    # Segmentação da fala
+    vad_mode: int = 2  # 0 = menos agressivo, 3 = mais agressivo
+    frame_ms: int = 30  # webrtcvad aceita 10, 20 ou 30
+    pre_roll_ms: int = 200
+    start_trigger_ms: int = 150
+    end_trigger_ms: int = 600
+    max_utterance_sec: float = 12.0
+
+    cache_dir: Path = field(default_factory=_default_cache_dir)
+    # Baixa pacotes de tradução sob demanda. Em quiosque offline, deixe False
+    # e use `poly-server download` na instalação.
+    auto_download: bool = True
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> "Settings":
+        values: dict[str, Any] = {}
+        for f in fields(cls):
+            raw = os.environ.get(f"POLY_{f.name.upper()}")
+            if raw is not None:
+                values[f.name] = _parse(f.name, raw)
+        values.update({k: v for k, v in overrides.items() if v is not None})
+        return cls(**values)
+
+
+def _parse(name: str, raw: str) -> Any:
+    if name in {"port", "vad_mode", "frame_ms", "pre_roll_ms", "start_trigger_ms", "end_trigger_ms"}:
+        return int(raw)
+    if name == "max_utterance_sec":
+        return float(raw)
+    if name in {"mic", "auto_download"}:
+        return raw.strip().lower() in {"1", "true", "yes", "on"}
+    if name == "cors_origins":
+        return [o.strip() for o in raw.split(",") if o.strip()]
+    if name == "cache_dir":
+        return Path(raw).expanduser()
+    if name == "mic_device":
+        return int(raw) if raw.isdigit() else raw
+    return raw

poly_server/events.py

@@ -0,0 +1,39 @@
+"""Distribui eventos de reconhecimento para todos os clientes conectados."""
+
+from __future__ import annotations
+
+import asyncio
+
+
+class EventHub:
+    """
+    Cada cliente do WebSocket /ws recebe todos os eventos. (Na versão anterior
+    havia uma fila única, e com duas abas abertas cada evento ia só para uma.)
+    """
+
+    def __init__(self) -> None:
+        self._subscribers: set[asyncio.Queue[dict]] = set()
+        self._loop: asyncio.AbstractEventLoop | None = None
+
+    def bind(self, loop: asyncio.AbstractEventLoop) -> None:
+        self._loop = loop
+
+    def subscribe(self) -> asyncio.Queue[dict]:
+        q: asyncio.Queue[dict] = asyncio.Queue(maxsize=100)
+        self._subscribers.add(q)
+        return q
+
+    def unsubscribe(self, q: asyncio.Queue[dict]) -> None:
+        self._subscribers.discard(q)
+
+    def _deliver(self, event: dict) -> None:
+        for q in list(self._subscribers):
+            if q.full():
+                q.get_nowait()  # cliente lento: descarta o evento mais antigo
+            q.put_nowait(event)
+
+    def publish(self, event: dict) -> None:
+        """Pode ser chamado de qualquer thread."""
+        if self._loop is None:
+            return
+        self._loop.call_soon_threadsafe(self._deliver, event)

poly_server/listening.py

@@ -0,0 +1,104 @@
+"""Controle de escuta do microfone local: contínua ou sob demanda (botão)."""
+
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Callable
+
+import numpy as np
+
+from .asr import Recognition
+from .vad import Segmenter
+
+log = logging.getLogger("poly_server")
+
+
+class ListeningController:
+    """
+    Recebe o áudio do microfone local e decide o que vai para o
+    reconhecimento.
+
+    - Modo contínuo (padrão): toda fala detectada é reconhecida.
+    - Modo manual: enquanto algum cliente pedir `listening: "manual"`, o áudio
+      só é processado entre `start()` e o fim da fala (silêncio) ou `stop()`.
+    """
+
+    def __init__(
+        self,
+        segmenter: Segmenter,
+        recognize: Callable[[np.ndarray], Recognition],
+        publish: Callable[[dict], None],
+    ) -> None:
+        self._segmenter = segmenter
+        self._recognize = recognize
+        self._publish = publish
+        self._lock = threading.Lock()
+        self._manual_clients = 0
+        self._listening = False
+
+    @property
+    def manual(self) -> bool:
+        return self._manual_clients > 0
+
+    @property
+    def listening(self) -> bool:
+        return self._listening
+
+    def add_manual_client(self) -> None:
+        with self._lock:
+            self._manual_clients += 1
+            self._reset()
+
+    def remove_manual_client(self) -> None:
+        with self._lock:
+            self._manual_clients = max(0, self._manual_clients - 1)
+            if self._manual_clients == 0:
+                self._listening = False
+
+    def start(self) -> None:
+        with self._lock:
+            self._reset()
+            self._listening = True
+        self._publish({"type": "listening", "listening": True})
+
+    def stop(self) -> None:
+        """Para de escutar e reconhece o que já foi dito, se houver."""
+        with self._lock:
+            was_listening = self._listening
+            self._listening = False
+            pending = self._segmenter.flush()
+            self._reset()
+        if pending is not None:
+            self._emit(pending)
+        if was_listening:
+            self._publish({"type": "listening", "listening": False})
+
+    def feed(self, block: np.ndarray) -> None:
+        """Chamado pela thread do microfone."""
+        with self._lock:
+            if self.manual and not self._listening:
+                return
+            was_speaking = self._segmenter.in_speech
+            utterances = self._segmenter.feed(block)
+            started = not was_speaking and (self._segmenter.in_speech or bool(utterances))
+            ended = bool(utterances) and self.manual
+            if ended:
+                # Fim da fala (silêncio): a escuta manual termina aqui.
+                self._listening = False
+                self._reset()
+        if started:
+            self._publish({"type": "speech_start"})
+        for u in utterances:
+            self._emit(u)
+        if ended:
+            self._publish({"type": "listening", "listening": False})
+
+    def _emit(self, audio: np.ndarray) -> None:
+        try:
+            self._publish(self._recognize(audio).to_event())
+        except Exception:
+            log.exception("recognition failed")
+
+    def _reset(self) -> None:
+        self._segmenter.reset()

poly_server/mic.py

@@ -0,0 +1,78 @@
+"""Captura do microfone local (modo quiosque)."""
+
+from __future__ import annotations
+
+import logging
+import queue
+import threading
+from typing import Callable
+
+import numpy as np
+
+from .vad import SAMPLE_RATE
+
+log = logging.getLogger("poly_server")
+
+
+def _sounddevice():
+    try:
+        import sounddevice
+    except (ImportError, OSError) as e:  # OSError: PortAudio ausente no sistema
+        raise RuntimeError(
+            "Local microphone capture needs sounddevice + PortAudio: "
+            "pip install 'poly-server[mic]' (and libportaudio2 on Linux)."
+        ) from e
+    return sounddevice
+
+
+def list_input_devices() -> list[dict]:
+    sd = _sounddevice()
+    return [
+        {"index": i, "name": d["name"], "channels": d["max_input_channels"]}
+        for i, d in enumerate(sd.query_devices())
+        if d["max_input_channels"] > 0
+    ]
+
+
+class MicSource:
+    """Lê o microfone numa thread e entrega blocos float32 mono 16 kHz."""
+
+    def __init__(self, on_audio: Callable[[np.ndarray], None], device: int | str | None = None) -> None:
+        self._on_audio = on_audio
+        self._device = device
+        self._queue: queue.Queue[np.ndarray] = queue.Queue()
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+
+    def start(self) -> None:
+        sd = _sounddevice()
+
+        def callback(indata, frames, time_info, status):
+            if status:
+                log.warning("mic: %s", status)
+            self._queue.put(indata[:, 0].copy())
+
+        def run():
+            try:
+                with sd.InputStream(
+                    samplerate=SAMPLE_RATE,
+                    channels=1,
+                    dtype="float32",
+                    callback=callback,
+                    device=self._device,
+                ):
+                    log.info("mic: capturing from %s", self._device if self._device is not None else "default device")
+                    while not self._stop.is_set():
+                        try:
+                            block = self._queue.get(timeout=0.5)
+                        except queue.Empty:
+                            continue
+                        self._on_audio(block)
+            except Exception:
+                log.exception("mic: capture stopped")
+
+        self._thread = threading.Thread(target=run, name="poly-mic", daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()

poly_server/translate.py

@@ -0,0 +1,151 @@
+"""Tradução de textos: Argos Translate (offline) + cache em disco."""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+import threading
+from pathlib import Path
+from typing import Protocol
+
+log = logging.getLogger("poly_server")
+
+
+class UnsupportedLanguagePair(Exception):
+    def __init__(self, source: str, target: str) -> None:
+        super().__init__(f"no translation available for {source} -> {target}")
+        self.source = source
+        self.target = target
+
+
+class Translator(Protocol):
+    def translate_many(self, texts: list[str], source: str, target: str) -> list[str]: ...
+
+
+def normalize_lang(code: str | None) -> str:
+    if not code:
+        return "en"
+    return str(code).strip().lower().replace("_", "-").split("-")[0]
+
+
+class ArgosTranslator:
+    """
+    Usa os pacotes do Argos instalados e, se `auto_download`, baixa os que
+    faltarem. Quando não existe pacote direto (ex.: pt -> ja), traduz passando
+    pelo idioma `pivot` (inglês), que é como a maioria dos pacotes do Argos é
+    publicada.
+    """
+
+    def __init__(self, *, auto_download: bool = True, pivot: str = "en") -> None:
+        self.auto_download = auto_download
+        self.pivot = pivot
+        self._ready: set[tuple[str, str]] = set()
+        self._lock = threading.Lock()
+        self._index_updated = False
+
+    def _installed_pairs(self) -> set[tuple[str, str]]:
+        from argostranslate import package
+
+        return {(p.from_code, p.to_code) for p in package.get_installed_packages()}
+
+    def _install(self, source: str, target: str) -> bool:
+        from argostranslate import package
+
+        if not self.auto_download:
+            return False
+        if not self._index_updated:
+            package.update_package_index()
+            self._index_updated = True
+        pkg = next(
+            (p for p in package.get_available_packages() if p.from_code == source and p.to_code == target),
+            None,
+        )
+        if pkg is None:
+            return False
+        log.info("Argos: installing %s -> %s", source, target)
+        package.install_from_path(pkg.download())
+        return True
+
+    def _ensure_direct(self, source: str, target: str) -> bool:
+        if (source, target) in self._installed_pairs():
+            return True
+        return self._install(source, target)
+
+    def ensure_pair(self, source: str, target: str) -> None:
+        if source == target or (source, target) in self._ready:
+            return
+        with self._lock:
+            if (source, target) in self._ready:
+                return
+            ok = self._ensure_direct(source, target)
+            if not ok and self.pivot not in (source, target):
+                ok = self._ensure_direct(source, self.pivot) and self._ensure_direct(self.pivot, target)
+            if not ok:
+                raise UnsupportedLanguagePair(source, target)
+            self._ready.add((source, target))
+
+    def _translate_one(self, text: str, source: str, target: str) -> str:
+        from argostranslate import translate
+
+        if (source, target) in self._installed_pairs():
+            return translate.translate(text, source, target)
+        middle = translate.translate(text, source, self.pivot)
+        return translate.translate(middle, self.pivot, target)
+
+    def translate_many(self, texts: list[str], source: str, target: str) -> list[str]:
+        source, target = normalize_lang(source), normalize_lang(target)
+        if source == target:
+            return list(texts)
+        self.ensure_pair(source, target)
+        memo: dict[str, str] = {}
+        out = []
+        for t in texts:
+            if t not in memo:
+                memo[t] = self._translate_one(t, source, target) if t.strip() else t
+            out.append(memo[t])
+        return out
+
+
+class CachedTranslator:
+    """Guarda as traduções em SQLite: o mesmo texto não é traduzido duas vezes."""
+
+    def __init__(self, inner: Translator, path: Path) -> None:
+        self.inner = inner
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self._db = sqlite3.connect(path, check_same_thread=False)
+        self._db.execute(
+            "CREATE TABLE IF NOT EXISTS translations ("
+            " source TEXT, target TEXT, text TEXT, translation TEXT,"
+            " PRIMARY KEY (source, target, text))"
+        )
+        self._db.commit()
+        self._lock = threading.Lock()
+
+    def translate_many(self, texts: list[str], source: str, target: str) -> list[str]:
+        source, target = normalize_lang(source), normalize_lang(target)
+        found: dict[str, str] = {}
+        unique = list(dict.fromkeys(texts))
+
+        with self._lock:
+            for i in range(0, len(unique), 500):
+                chunk = unique[i : i + 500]
+                rows = self._db.execute(
+                    "SELECT text, translation FROM translations WHERE source = ? AND target = ?"
+                    f" AND text IN ({','.join('?' * len(chunk))})",
+                    [source, target, *chunk],
+                ).fetchall()
+                found.update(rows)
+
+        missing = [t for t in unique if t not in found]
+        if missing:
+            translated = self.inner.translate_many(missing, source, target)
+            new = dict(zip(missing, translated))
+            found.update(new)
+            with self._lock:
+                self._db.executemany(
+                    "INSERT OR REPLACE INTO translations VALUES (?, ?, ?, ?)",
+                    [(source, target, k, v) for k, v in new.items()],
+                )
+                self._db.commit()
+
+        return [found[t] for t in texts]

poly_server/vad.py

@@ -0,0 +1,110 @@
+"""Separa o áudio contínuo em falas (utterances) usando detecção de voz."""
+
+from __future__ import annotations
+
+import collections
+from typing import Callable
+
+import numpy as np
+
+SAMPLE_RATE = 16000
+
+IsSpeech = Callable[[bytes, int], bool]
+
+
+def float32_to_pcm16(x: np.ndarray) -> bytes:
+    return (np.clip(x, -1.0, 1.0) * 32767.0).astype(np.int16).tobytes()
+
+
+def pcm16_to_float32(data: bytes) -> np.ndarray:
+    return np.frombuffer(data, dtype=np.int16).astype(np.float32) / 32768.0
+
+
+class Segmenter:
+    """
+    Recebe áudio mono 16 kHz em blocos de qualquer tamanho e devolve as falas
+    completas: começa quando há voz por `start_trigger_ms`, termina após
+    `end_trigger_ms` de silêncio ou ao atingir `max_utterance_sec`.
+    """
+
+    def __init__(
+        self,
+        *,
+        vad_mode: int = 2,
+        frame_ms: int = 30,
+        pre_roll_ms: int = 200,
+        start_trigger_ms: int = 150,
+        end_trigger_ms: int = 600,
+        max_utterance_sec: float = 12.0,
+        is_speech: IsSpeech | None = None,
+    ) -> None:
+        if is_speech is None:
+            import webrtcvad
+
+            is_speech = webrtcvad.Vad(vad_mode).is_speech
+        self._is_speech = is_speech
+
+        self.frame_len = int(SAMPLE_RATE * frame_ms / 1000)
+        self._start_frames = max(1, start_trigger_ms // frame_ms)
+        self._end_frames = max(1, end_trigger_ms // frame_ms)
+        self._max_frames = int(max_utterance_sec * 1000 / frame_ms)
+
+        self._ring: collections.deque[np.ndarray] = collections.deque(
+            maxlen=max(0, pre_roll_ms // frame_ms)
+        )
+        self._voiced: list[np.ndarray] = []
+        self._in_speech = False
+        self._speech_run = 0
+        self._silence_run = 0
+        self._buffer = np.zeros((0,), dtype=np.float32)
+
+    def feed(self, samples: np.ndarray) -> list[np.ndarray]:
+        self._buffer = np.concatenate([self._buffer, samples.astype(np.float32, copy=False)])
+        done: list[np.ndarray] = []
+
+        while len(self._buffer) >= self.frame_len:
+            frame = self._buffer[: self.frame_len]
+            self._buffer = self._buffer[self.frame_len :]
+            speech = self._is_speech(float32_to_pcm16(frame), SAMPLE_RATE)
+
+            if not self._in_speech:
+                self._ring.append(frame)
+                self._speech_run = self._speech_run + 1 if speech else 0
+                if self._speech_run >= self._start_frames:
+                    self._in_speech = True
+                    self._voiced = list(self._ring)
+                    self._ring.clear()
+                    self._speech_run = 0
+                    self._silence_run = 0
+            else:
+                self._voiced.append(frame)
+                self._silence_run = 0 if speech else self._silence_run + 1
+                if self._silence_run >= self._end_frames or len(self._voiced) >= self._max_frames:
+                    done.append(np.concatenate(self._voiced))
+                    self._voiced = []
+                    self._in_speech = False
+                    self._silence_run = 0
+
+        return done
+
+    @property
+    def in_speech(self) -> bool:
+        return self._in_speech
+
+    def reset(self) -> None:
+        """Descarta tudo o que estava em andamento."""
+        self._ring.clear()
+        self._voiced = []
+        self._in_speech = False
+        self._speech_run = 0
+        self._silence_run = 0
+        self._buffer = np.zeros((0,), dtype=np.float32)
+
+    def flush(self) -> np.ndarray | None:
+        """Entrega a fala em andamento, se houver (ex.: ao fechar a conexão)."""
+        if not self._in_speech or not self._voiced:
+            return None
+        out = np.concatenate(self._voiced)
+        self._voiced = []
+        self._in_speech = False
+        return out

poly_server-0.1.0.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.5
+Name: poly-server
+Version: 0.1.0
+Summary: Speech language detection and offline UI translation server for Poly voice-driven interfaces.
+Project-URL: Homepage, https://github.com/VictorAGuerra/Poly-SLID-Interface-Translator
+Project-URL: Repository, https://github.com/VictorAGuerra/Poly-SLID-Interface-Translator
+Project-URL: Issues, https://github.com/VictorAGuerra/Poly-SLID-Interface-Translator/issues
+Author: Victor A. Guerra
+License-Expression: MIT
+License-File: LICENSE
+Keywords: accessibility,i18n,kiosk,language-detection,self-service,speech,translation,whisper
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Software Development :: Internationalization
+Requires-Python: >=3.10
+Requires-Dist: argostranslate>=1.9
+Requires-Dist: fastapi>=0.115
+Requires-Dist: faster-whisper>=1.1
+Requires-Dist: numpy>=1.24
+Requires-Dist: uvicorn[standard]>=0.30
+Requires-Dist: webrtcvad-wheels>=2.0.14
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: mic
+Requires-Dist: sounddevice>=0.5; extra == 'mic'
+Description-Content-Type: text/markdown
+
+# poly-server
+
+**English** · [Português](#português)
+
+Speech language detection and offline UI translation server for
+[Poly](https://www.npmjs.com/package/@swalay/poly-react), voice-driven
+interfaces for self-service kiosks.
+
+- **Speech → language** with [faster-whisper](https://github.com/SYSTRAN/faster-whisper).
+- **UI translation** with [Argos Translate](https://github.com/argosopentech/argos-translate),
+  fully offline, with an English pivot when there's no direct language pair
+  and a persistent SQLite cache.
+- **Two audio modes:** the server's own microphone (kiosk: screen and server on
+  the same machine) or audio streamed from the browser.
+- Nothing leaves the device: no cloud APIs.
+
+## Install
+
+```bash
+# CPU-only PyTorch first (Argos needs it); avoids ~3 GB of CUDA libraries
+pip install torch --index-url https://download.pytorch.org/whl/cpu
+pip install "poly-server[mic]"
+```
+
+The `mic` extra enables local microphone capture (needs PortAudio:
+`sudo apt install libportaudio2` on Debian/Ubuntu). Skip it if audio only
+comes from the browser.
+
+## Run
+
+```bash
+poly-server serve                     # http://127.0.0.1:8000, local microphone
+poly-server serve --no-mic            # browser audio only
+poly-server devices                   # list microphones
+poly-server serve --mic-device 2
+```
+
+### Offline kiosks
+
+Download everything once during installation, then run without network:
+
+```bash
+poly-server download --base en --languages pt,es,fr,ar,ja,zh
+poly-server serve --offline
+```
+
+## Configuration
+
+Every option can be set with a `POLY_*` environment variable:
+
+| Variable | Default | |
+| --- | --- | --- |
+| `POLY_HOST` / `POLY_PORT` | `127.0.0.1` / `8000` | |
+| `POLY_CORS_ORIGINS` | `*` | Comma-separated allowed origins. |
+| `POLY_MIC` | `true` | Capture the local microphone. |
+| `POLY_MIC_DEVICE` | system default | Input device index or name. |
+| `POLY_WHISPER_MODEL` | `base` | `tiny`, `base`, `small`, `medium`, `large-v3`. |
+| `POLY_WHISPER_DEVICE` | `auto` | `cpu`, `cuda`, `auto`. |
+| `POLY_WHISPER_COMPUTE_TYPE` | `int8` | |
+| `POLY_VAD_MODE` | `2` | 0 (lenient) to 3 (aggressive) voice detection. |
+| `POLY_END_TRIGGER_MS` | `600` | Silence that ends an utterance. |
+| `POLY_MAX_UTTERANCE_SEC` | `12` | |
+| `POLY_CACHE_DIR` | `~/.cache/poly-server` | Models and translation cache. |
+| `POLY_AUTO_DOWNLOAD` | `true` | Download translation packages on demand. |
+
+## API
+
+| Endpoint | |
+| --- | --- |
+| `GET /health` | `{ ok, version, mic }` |
+| `POST /i18n/auto-translate` | `{ source_lang, target_lang, texts: { key: text } }` → `{ target_lang, texts }`. Returns `422` with `code: "unsupported_language_pair"` when no translation exists. |
+| `WS /ws` | Recognition events from the local microphone, broadcast to every client. Send `{"type":"config","listening":"manual"}` to listen only on demand, then `{"type":"listen","action":"start"\|"stop"}`; the server replies with `{"type":"listening","listening":bool}` and `{"type":"speech_start"}`. |
+| `WS /ws/audio` | Send binary PCM16 LE mono 16 kHz; receive `{"type":"speech_start"}` / `{"type":"utterance_end"}` as speech starts and ends, then the recognition event. Text messages: `{"type":"flush"}` recognizes the speech in progress, `{"type":"reset"}` discards it. |
+
+Event: `{ "type": "asr", "language": "pt", "confidence": 0.97, "text": "...", "latency_sec": 1.4 }`
+
+### Embedding
+
+```python
+from poly_server import Settings, create_app
+
+app = create_app(Settings(mic=False, whisper_model="small"))
+```
+
+`create_app` also accepts custom `recognizer` and `translator` objects, to plug
+in another speech model or translation service.
+
+## License
+
+MIT
+
+---
+
+## Português
+
+Servidor de detecção do idioma falado e tradução offline de interfaces para o
+Poly.
+
+- **Fala → idioma** com faster-whisper.
+- **Tradução** com Argos Translate, 100% offline, passando pelo inglês quando
+  não há pacote direto entre dois idiomas, e com cache em disco (SQLite).
+- **Dois modos de áudio:** o microfone do próprio servidor (quiosque) ou o
+  áudio enviado pelo navegador.
+- Nada sai do aparelho: nenhuma API na nuvem.
+
+Instalação, execução e configuração: veja os comandos acima. Para quiosques
+sem internet, rode `poly-server download` na instalação e depois
+`poly-server serve --offline`.

poly_server-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+poly_server/__init__.py,sha256=nWgA07lcHtwMmj54YvbOeYvk-vuiV78StlbrDoSYLUw,221
+poly_server/__main__.py,sha256=bYt9eEaoRQWdejEHFD8REx9jxVEdZptECFsV7F49Ink,30
+poly_server/app.py,sha256=LIvgchzoHbuX3T4X74Q9y3ysIc9yHR9oz3eZBYOTjO8,7838
+poly_server/asr.py,sha256=xSC4rBRe6MQZ337Y8eHBz_5EeK-tfcf1YHN3v6W8aA8,2161
+poly_server/cli.py,sha256=w8NMie1Rx93SFPjGMumwiLYCyxtY3vG6nAIIumV-V_s,3707
+poly_server/config.py,sha256=75J9cFeWhNQCwTXA61nDUFitNqdLjbCS5XZff560IFQ,2525
+poly_server/events.py,sha256=QKF8T7_M6AOkEK6DSUMMPzPqHxz_M62In7a2UV0kgS8,1253
+poly_server/listening.py,sha256=8A8KdIT78PIa45WRUXOsE-r1EBItNGw2zaAe9Jnukbw,3254
+poly_server/mic.py,sha256=1rbWK-DmMcEaEnBhupS_zZJaMyCEocVydrLP27V2E-g,2434
+poly_server/translate.py,sha256=sBgx3JKq-nXrXG4e7LJDnrrQft1BkNLSlBLLS6y6T7I,5601
+poly_server/vad.py,sha256=g1_K4I6WOgAO6ji1CzopwBuYlgAhwLIIyTnCWs-QmlM,3771
+poly_server-0.1.0.dist-info/METADATA,sha256=FqHlEWsBpxVO7egosxK9-D8BeSqcbUAI--0YbJcuz2o,5624
+poly_server-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+poly_server-0.1.0.dist-info/entry_points.txt,sha256=wFdQLFXPm1Z4qsUoCzuTPRLDTjrDl1L17V-0COHzztI,53
+poly_server-0.1.0.dist-info/licenses/LICENSE,sha256=PIxwkioaxYjQqUU2qSOoVZVDAiPcW9MZ2Kq9l_ec01o,1073
+poly_server-0.1.0.dist-info/RECORD,,

poly_server-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

poly_server-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+poly-server = poly_server.cli:main

poly_server-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victor A. Guerra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.