bevyra-avatar 0.1.0__tar.gz

bevyra_avatar-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+dist/
+src/bevyra_avatar/static/sdk/
+**/__pycache__/

bevyra_avatar-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.5
+Name: bevyra-avatar
+Version: 0.1.0
+Summary: Local browser avatar player controlled from Python
+License: Proprietary
+Requires-Python: >=3.10
+Requires-Dist: aiohttp<4,>=3.10

bevyra_avatar-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bevyra-avatar"
+version = "0.1.0"
+description = "Local browser avatar player controlled from Python"
+requires-python = ">=3.10"
+dependencies = ["aiohttp>=3.10,<4"]
+license = { text = "Proprietary" }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bevyra_avatar"]
+ignore-vcs = true
+
+[tool.hatch.build.targets.sdist]
+include = ["src/bevyra_avatar/**", "pyproject.toml"]
+ignore-vcs = true

bevyra_avatar-0.1.0/src/bevyra_avatar/__init__.py

@@ -0,0 +1,3 @@
+from .player import AvatarWindow
+
+__all__ = ["AvatarWindow"]

bevyra_avatar-0.1.0/src/bevyra_avatar/player.py

@@ -0,0 +1,139 @@
+"""A loopback control bridge for the bundled browser avatar renderer."""
+
+from __future__ import annotations
+
+import asyncio
+import secrets
+import struct
+import webbrowser
+from pathlib import Path
+from typing import Callable
+
+from aiohttp import WSMsgType, web
+
+_STATIC = Path(__file__).resolve().parent / "static"
+
+
+class AvatarWindow:
+    """Render locally in a browser while Python supplies PCM16 speech audio."""
+
+    def __init__(
+        self,
+        avatar_id: str,
+        bundle_dir: str | Path,
+        *,
+        on_event: Callable[[dict], None] | None = None,
+    ) -> None:
+        self.avatar_id = avatar_id
+        self.bundle_dir = Path(bundle_dir).resolve()
+        if not (self.bundle_dir / "web-bundle.json").is_file():
+            raise ValueError(f"portable_v2 bundle missing: {self.bundle_dir}")
+        if not (_STATIC / "sdk" / "index.js").is_file():
+            raise RuntimeError("Browser renderer assets are missing from this Python installation")
+        self.on_event = on_event
+        self._runner: web.AppRunner | None = None
+        self._socket: web.WebSocketResponse | None = None
+        self._ready = asyncio.Event()
+        self._token = secrets.token_urlsafe(32)
+        self.url: str | None = None
+
+    async def start(self, *, open_browser: bool = True, timeout: float = 90) -> str:
+        if self._runner is not None:
+            raise RuntimeError("AvatarWindow has already started")
+        app = web.Application()
+        app.router.add_get("/", self._index)
+        app.router.add_get("/player.js", self._player_script)
+        app.router.add_get("/ws", self._websocket)
+        app.router.add_static("/sdk/", _STATIC / "sdk")
+        app.router.add_static("/avatar/", self.bundle_dir)
+        runner = web.AppRunner(app)
+        await runner.setup()
+        try:
+            site = web.TCPSite(runner, "127.0.0.1", 0)
+            await site.start()
+            port = site._server.sockets[0].getsockname()[1]
+            self._runner = runner
+            self.url = f"http://127.0.0.1:{port}/?token={self._token}"
+            if open_browser:
+                webbrowser.open(self.url)
+                await asyncio.wait_for(self._ready.wait(), timeout)
+            return self.url
+        except BaseException:
+            await runner.cleanup()
+            self._runner = None
+            raise
+
+    def _headers(self, response: web.StreamResponse) -> web.StreamResponse:
+        response.headers["Cross-Origin-Opener-Policy"] = "same-origin"
+        response.headers["Cross-Origin-Embedder-Policy"] = "require-corp"
+        response.headers["Cache-Control"] = "no-store"
+        return response
+
+    async def _index(self, request: web.Request) -> web.StreamResponse:
+        response = web.FileResponse(_STATIC / "player.html")
+        return self._headers(response)
+
+    async def _player_script(self, request: web.Request) -> web.StreamResponse:
+        response = web.FileResponse(_STATIC / "player.js")
+        return self._headers(response)
+
+    async def _websocket(self, request: web.Request) -> web.StreamResponse:
+        if request.query.get("token") != self._token:
+            raise web.HTTPForbidden()
+        expected_origin = f"http://{request.host}"
+        if request.headers.get("Origin") != expected_origin:
+            raise web.HTTPForbidden()
+        if self._socket is not None and not self._socket.closed:
+            raise web.HTTPConflict(text="Avatar already connected")
+        ws = web.WebSocketResponse(heartbeat=20, max_msg_size=4096)
+        await ws.prepare(request)
+        self._socket = ws
+        await ws.send_json({"type": "configure", "avatar_id": self.avatar_id})
+        try:
+            async for message in ws:
+                if message.type is WSMsgType.TEXT:
+                    data = message.json()
+                    if data.get("type") == "ready":
+                        self._ready.set()
+                    if self.on_event:
+                        self.on_event(data)
+        finally:
+            self._ready.clear()
+            if self._socket is ws:
+                self._socket = None
+        return ws
+
+    async def _send(self, payload: dict | bytes) -> None:
+        ws = self._socket
+        if ws is None or ws.closed or not self._ready.is_set():
+            raise RuntimeError("Avatar player is not ready")
+        if isinstance(payload, bytes):
+            await ws.send_bytes(payload)
+        else:
+            await ws.send_json(payload)
+
+    async def write_audio(self, pcm16: bytes, sample_rate: int = 16000) -> None:
+        if not 8000 <= sample_rate <= 96000 or len(pcm16) % 2:
+            raise ValueError("Expected even-length signed PCM16 bytes and a valid sample rate")
+        await self._send(struct.pack("<I", sample_rate) + pcm16)
+
+    async def end_utterance(self) -> None:
+        await self._send({"type": "end"})
+
+    async def interrupt(self) -> None:
+        await self._send({"type": "interrupt"})
+
+    async def close(self) -> None:
+        if self._socket is not None:
+            await self._socket.close()
+        if self._runner is not None:
+            await self._runner.cleanup()
+            self._runner = None
+        self._ready.clear()
+
+    async def __aenter__(self) -> "AvatarWindow":
+        await self.start()
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()

bevyra_avatar-0.1.0/src/bevyra_avatar/static/player.html

@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>BeVyra Avatar</title>
+  <style>
+    html,body{margin:0;width:100%;height:100%;background:transparent}
+    canvas{display:block;width:100%;height:100%;object-fit:contain}
+    #start{position:absolute;left:50%;top:50%;transform:translate(-50%,-50%);padding:1em 2em}
+    #status{position:absolute;left:1em;bottom:1em;color:white;background:#222a;padding:.4em}
+  </style>
+</head>
+<body>
+  <canvas id="avatar"></canvas>
+  <button id="start" disabled>Start avatar</button>
+  <div id="status" role="status">Connecting to Python…</div>
+  <script type="module" src="/player.js"></script>
+</body>
+</html>

bevyra_avatar-0.1.0/src/bevyra_avatar/static/player.js

@@ -0,0 +1,61 @@
+import { BevyraAvatar } from "/sdk/index.js";
+
+const status = document.getElementById("status");
+const start = document.getElementById("start");
+const canvas = document.getElementById("avatar");
+const token = new URL(location.href).searchParams.get("token");
+if (!token) throw new Error("Missing session token");
+const socket = new WebSocket(`ws://${location.host}/ws?token=${encodeURIComponent(token)}`);
+socket.binaryType = "arraybuffer";
+let avatar = null;
+let avatarId = null;
+let pending = Promise.resolve();
+let generation = 0;
+const send = (value) => socket.readyState === WebSocket.OPEN && socket.send(JSON.stringify(value));
+const enqueue = (task) => {
+  const current = generation;
+  pending = pending.catch(() => undefined).then(() => {
+    if (current === generation) return task();
+  }).catch((error) => send({ type: "error", message: String(error) }));
+};
+socket.onmessage = async (event) => {
+  if (typeof event.data === "string") {
+    const command = JSON.parse(event.data);
+    if (command.type === "configure") {
+      avatarId = command.avatar_id;
+      start.disabled = false;
+      status.textContent = "Click to start avatar";
+    } else if (command.type === "end") {
+      enqueue(() => avatar.endUtterance());
+    } else if (command.type === "interrupt") {
+      generation++;
+      avatar?.interrupt();
+      pending = Promise.resolve();
+    }
+    return;
+  }
+  const data = new DataView(event.data);
+  const sampleRate = data.getUint32(0, true);
+  const pcm = new Int16Array(event.data.slice(4));
+  enqueue(() => avatar.writeAudio(pcm, sampleRate));
+};
+start.onclick = async () => {
+  start.disabled = true;
+  status.textContent = "Loading avatar…";
+  try {
+    avatar = await BevyraAvatar.mount({
+      avatarId, canvas, bundleBaseUrl: "/avatar/", assetsBaseUrl: "/sdk/dist/",
+      onStage: (stage) => { status.textContent = stage.replaceAll("_", " "); },
+    });
+    avatar.onSpeechStart(() => send({ type: "speech_start" }));
+    avatar.onSpeechEnd(() => send({ type: "speech_end" }));
+    status.remove();
+    start.remove();
+    send({ type: "ready" });
+  } catch (error) {
+    status.textContent = String(error);
+    start.disabled = false;
+    send({ type: "error", message: String(error) });
+  }
+};
+socket.onclose = () => { avatar?.close(); status.textContent = "Python connection closed"; };