gemilive 0.1.0__tar.gz

gemilive-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saidur Rahman Pulok
+
+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.

gemilive-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: gemilive
+Version: 0.1.0
+Summary: Minimal Gemini Live AI WebSocket proxy for FastAPI — plug and play voice + video AI.
+License-Expression: MIT
+Keywords: gemini,live,ai,voice,video,fastapi,websocket
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi[standard]>=0.115.0
+Requires-Dist: google-genai>=1.70.0
+Requires-Dist: pydantic-settings>=2.13.1
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: websockets>=16.0
+Dynamic: license-file
+
+# gemilive
+
+Plug-and-play **Gemini Live AI** (voice + video) for your FastAPI app.
+
+`gemilive` provides a seamless bridge between a web-based frontend and Google's Gemini Multimodal Live API. It handles the heavy lifting of WebSockets, bidirectional audio streams (16kHz up / 24kHz down), gapless browser PCM playback, and live video framing — allowing you to add conversational AI to your project in just **six lines of code**.
+
+This repo contains both the Python backend plugin (`gemilive`) and the companion JavaScript client (`gemilive-js`).
+
+## 🚀 Features
+
+- **Bidirectional Voice AI**: Real-time PCM audio streaming for natural, fluid conversions. No laggy turn-by-turn.
+- **Multimodal Vision**: The AI can see what your camera sees via 1fps JPEG snapshots.
+- **Zero-Boilerplate Backend**: Just wrap your existing FastAPI app with `mount_gemilive()`.
+- **Lightweight JS SDK**: A clean browser `GemiliveClient` handling media capture and resampling.
+- **Toggleable Media**: Turn your camera off/on mid-session seamlessly.
+
+---
+
+## 🛠️ Installation & Quickstart
+
+Integration requires two pieces: the Python server endpoint and the JavaScript browser client.
+
+### Backend (Python)
+
+Install the pip package:
+```bash
+uv add gemilive
+# or pip install gemilive
+```
+
+Setup requires an API key. You can provide it in code or grab it from your `.env`:
+```env
+GOOGLE_API_KEY=your_gemini_api_key_here
+MODEL_NAME=gemini-3.1-flash-live-preview
+```
+
+Mount it into any FastAPI app:
+```python
+from fastapi import FastAPI
+from gemilive import mount_gemilive
+
+app = FastAPI()
+
+# Mounts the WebSocket route at /ws/live
+mount_gemilive(app, system_prompt="You are a helpful assistant. Keep answers brief.")
+```
+
+### Frontend (JavaScript)
+
+Install the npm package:
+```bash
+npm install gemilive-js
+```
+*Or use via CDN in plain HTML:*
+```html
+<script src="https://cdn.jsdelivr.net/npm/gemilive-js/dist/gemilive.min.js"></script>
+```
+
+Initialize the client, connect, and start talking:
+```javascript
+import { GemiliveClient } from 'gemilive-js';
+
+// Point it to your FastAPI server's mount path
+const client = new GemiliveClient("ws://localhost:8000/ws/live");
+
+client.onMessage = (text) => console.log("Gemini:", text);
+client.onError = (err) => console.error("Error:", err);
+
+// Start the connection (prompts user for Mic & Camera)
+await client.start();
+
+// Disable video mid-session (audio continues)
+// client.toggleVideo(false);
+
+// Stop and disconnect
+// client.stop();
+```
+
+---
+
+## ⚙️ Advanced Configuration
+
+### Python `mount_gemilive()` Overrides
+You can override environment variables dynamically when mounting the API:
+
+```python
+mount_gemilive(
+    app,
+    google_api_key="...",                 # Overrides GOOGLE_API_KEY env 
+    model="gemini-3.1-flash-live-preview",# Overrides MODEL_NAME env
+    voice="Aoede",                        # Optional Gemini Voice ("Aoede", "Charon", etc.)
+    allow_origins=["https://myapp.com"],  # Essential if your frontend is on a different domain
+    debug_mode=True                       # Console logging of message flow
+)
+```
+
+### The System Prompt
+You can set system prompts on the **server-side** (via `mount_gemilive`) or the **client-side** (via `new GemiliveClient(url, { systemPrompt: "..." })`). 
+If both are provided, the server-side prompt takes precedence, and the client-side prompt is appended securely as "Additional context".
+
+---
+
+## 📂 Project Structure (For Contributors)
+
+`gemilive` is developed as a monorepo containing two packages:
+
+```text
+├── gemilive/             # PyPI package source
+│   ├── mount.py        # Public FastAPI installer
+│   ├── config.py       # Pydantic env validation
+│   └── router.py       # Internal WebSocket / GenAI flow
+├── gemilive-js/          # npm package source
+│   ├── src/index.js    # Browser SDK (Web Audio API logic)
+│   └── package.json
+└── main.py             # Sandbox FastAPI app for testing and local dev
+```
+
+For guidelines on local development and how to publish to PyPI and npm, read `PUBLISHING.md`.
+
+---
+
+## ⚠️ Important Considerations
+
+1. **Browser Security**: Browsers restrict microphone/camera access to secure contexts. `getUserMedia` requires **HTTPS** in production. `localhost` works for development.
+2. **Audio Resampling**: Browsers typically record audio at 44.1kHz or 48kHz. The `gemilive-js` SDK seamlessly resamples microphone inputs to **16kHz PCM** to meet Gemini's strict API requirements. Responses from Gemini are returned as 24kHz PCM and gaplessly played back using Javascript time-scheduling.
+
+---
+
+## 📄 License
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

gemilive-0.1.0/README.md

@@ -0,0 +1,130 @@
+# gemilive
+
+Plug-and-play **Gemini Live AI** (voice + video) for your FastAPI app.
+
+`gemilive` provides a seamless bridge between a web-based frontend and Google's Gemini Multimodal Live API. It handles the heavy lifting of WebSockets, bidirectional audio streams (16kHz up / 24kHz down), gapless browser PCM playback, and live video framing — allowing you to add conversational AI to your project in just **six lines of code**.
+
+This repo contains both the Python backend plugin (`gemilive`) and the companion JavaScript client (`gemilive-js`).
+
+## 🚀 Features
+
+- **Bidirectional Voice AI**: Real-time PCM audio streaming for natural, fluid conversions. No laggy turn-by-turn.
+- **Multimodal Vision**: The AI can see what your camera sees via 1fps JPEG snapshots.
+- **Zero-Boilerplate Backend**: Just wrap your existing FastAPI app with `mount_gemilive()`.
+- **Lightweight JS SDK**: A clean browser `GemiliveClient` handling media capture and resampling.
+- **Toggleable Media**: Turn your camera off/on mid-session seamlessly.
+
+---
+
+## 🛠️ Installation & Quickstart
+
+Integration requires two pieces: the Python server endpoint and the JavaScript browser client.
+
+### Backend (Python)
+
+Install the pip package:
+```bash
+uv add gemilive
+# or pip install gemilive
+```
+
+Setup requires an API key. You can provide it in code or grab it from your `.env`:
+```env
+GOOGLE_API_KEY=your_gemini_api_key_here
+MODEL_NAME=gemini-3.1-flash-live-preview
+```
+
+Mount it into any FastAPI app:
+```python
+from fastapi import FastAPI
+from gemilive import mount_gemilive
+
+app = FastAPI()
+
+# Mounts the WebSocket route at /ws/live
+mount_gemilive(app, system_prompt="You are a helpful assistant. Keep answers brief.")
+```
+
+### Frontend (JavaScript)
+
+Install the npm package:
+```bash
+npm install gemilive-js
+```
+*Or use via CDN in plain HTML:*
+```html
+<script src="https://cdn.jsdelivr.net/npm/gemilive-js/dist/gemilive.min.js"></script>
+```
+
+Initialize the client, connect, and start talking:
+```javascript
+import { GemiliveClient } from 'gemilive-js';
+
+// Point it to your FastAPI server's mount path
+const client = new GemiliveClient("ws://localhost:8000/ws/live");
+
+client.onMessage = (text) => console.log("Gemini:", text);
+client.onError = (err) => console.error("Error:", err);
+
+// Start the connection (prompts user for Mic & Camera)
+await client.start();
+
+// Disable video mid-session (audio continues)
+// client.toggleVideo(false);
+
+// Stop and disconnect
+// client.stop();
+```
+
+---
+
+## ⚙️ Advanced Configuration
+
+### Python `mount_gemilive()` Overrides
+You can override environment variables dynamically when mounting the API:
+
+```python
+mount_gemilive(
+    app,
+    google_api_key="...",                 # Overrides GOOGLE_API_KEY env 
+    model="gemini-3.1-flash-live-preview",# Overrides MODEL_NAME env
+    voice="Aoede",                        # Optional Gemini Voice ("Aoede", "Charon", etc.)
+    allow_origins=["https://myapp.com"],  # Essential if your frontend is on a different domain
+    debug_mode=True                       # Console logging of message flow
+)
+```
+
+### The System Prompt
+You can set system prompts on the **server-side** (via `mount_gemilive`) or the **client-side** (via `new GemiliveClient(url, { systemPrompt: "..." })`). 
+If both are provided, the server-side prompt takes precedence, and the client-side prompt is appended securely as "Additional context".
+
+---
+
+## 📂 Project Structure (For Contributors)
+
+`gemilive` is developed as a monorepo containing two packages:
+
+```text
+├── gemilive/             # PyPI package source
+│   ├── mount.py        # Public FastAPI installer
+│   ├── config.py       # Pydantic env validation
+│   └── router.py       # Internal WebSocket / GenAI flow
+├── gemilive-js/          # npm package source
+│   ├── src/index.js    # Browser SDK (Web Audio API logic)
+│   └── package.json
+└── main.py             # Sandbox FastAPI app for testing and local dev
+```
+
+For guidelines on local development and how to publish to PyPI and npm, read `PUBLISHING.md`.
+
+---
+
+## ⚠️ Important Considerations
+
+1. **Browser Security**: Browsers restrict microphone/camera access to secure contexts. `getUserMedia` requires **HTTPS** in production. `localhost` works for development.
+2. **Audio Resampling**: Browsers typically record audio at 44.1kHz or 48kHz. The `gemilive-js` SDK seamlessly resamples microphone inputs to **16kHz PCM** to meet Gemini's strict API requirements. Responses from Gemini are returned as 24kHz PCM and gaplessly played back using Javascript time-scheduling.
+
+---
+
+## 📄 License
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

gemilive-0.1.0/gemilive/__init__.py

@@ -0,0 +1,3 @@
+from .mount import mount_gemilive
+
+__all__ = ["mount_gemilive"]

gemilive-0.1.0/gemilive/config.py

@@ -0,0 +1,37 @@
+from typing import Optional
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic import Field
+
+
+class GemiliveSettings(BaseSettings):
+    """
+    Configuration for the gemilive package.
+
+    All fields can be set via environment variables.
+    The GOOGLE_API_KEY env var maps directly (no prefix).
+    All other settings use the GEMILIVE_ prefix, e.g. GEMILIVE_VOICE.
+    """
+
+    google_api_key: str = Field(default="", validation_alias="GOOGLE_API_KEY")
+    model: str = Field(
+        default="gemini-3.1-flash-live-preview",
+        validation_alias="MODEL_NAME",
+    )
+    voice: Optional[str] = Field(
+        default=None,
+        validation_alias="GEMILIVE_VOICE",
+        description="Gemini voice name (e.g. 'Aoede', 'Charon'). Omit to use Gemini default.",
+    )
+    system_prompt: Optional[str] = Field(
+        default=None,
+        validation_alias="GEMILIVE_SYSTEM_PROMPT",
+        description="Server-side system prompt baked in at mount time.",
+    )
+    debug_mode: bool = Field(default=False, validation_alias="GEMILIVE_DEBUG")
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+        populate_by_name=True,
+    )

gemilive-0.1.0/gemilive/mount.py

@@ -0,0 +1,69 @@
+from typing import List, Optional
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from .config import GemiliveSettings
+from .router import create_router
+
+
+def mount_gemilive(
+    app: FastAPI,
+    *,
+    google_api_key: Optional[str] = None,
+    model: Optional[str] = None,
+    voice: Optional[str] = None,
+    system_prompt: Optional[str] = None,
+    allow_origins: List[str] = ["*"],
+    debug_mode: bool = False,
+) -> None:
+    """
+    Mount the Gemini Live AI WebSocket endpoint onto a FastAPI app.
+
+    All keyword arguments are optional overrides. When omitted, values are
+    read from environment variables (GOOGLE_API_KEY, MODEL_NAME, etc.).
+
+    Args:
+        app:            The FastAPI application instance.
+        google_api_key: Gemini API key. Falls back to GOOGLE_API_KEY env var.
+        model:          Gemini Live model name. Falls back to MODEL_NAME env var.
+        voice:          Gemini voice (e.g. "Aoede", "Charon"). None = Gemini default.
+        system_prompt:  Server-side system prompt baked in at mount time.
+                        Client-supplied prompts are appended as extra context.
+        allow_origins:  CORS origins to allow for WebSocket connections.
+                        Defaults to ["*"]. Restrict in production.
+        debug_mode:     Print verbose logs. Falls back to GEMILIVE_DEBUG env var.
+
+    Example::
+
+        from fastapi import FastAPI
+        from gemilive import mount_gemilive
+
+        app = FastAPI()
+        mount_gemilive(app, system_prompt="You are a helpful assistant.")
+    """
+    # Build settings, applying any explicit overrides on top of env vars
+    settings = GemiliveSettings()
+    if google_api_key is not None:
+        settings = settings.model_copy(update={"google_api_key": google_api_key})
+    if model is not None:
+        settings = settings.model_copy(update={"model": model})
+    if voice is not None:
+        settings = settings.model_copy(update={"voice": voice})
+    if system_prompt is not None:
+        settings = settings.model_copy(update={"system_prompt": system_prompt})
+    if debug_mode:
+        settings = settings.model_copy(update={"debug_mode": True})
+
+    # Add CORS middleware so separate-origin frontends can reach the WebSocket
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=allow_origins,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Register the WebSocket router
+    router = create_router(settings)
+    app.include_router(router)

gemilive-0.1.0/gemilive/py.typed

@@ -0,0 +1 @@
+# PEP 561 marker file

gemilive-0.1.0/gemilive/router.py

@@ -0,0 +1,147 @@
+import asyncio
+import base64
+import traceback
+
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect, status
+from google import genai
+from google.genai import types
+
+from .config import GemiliveSettings
+
+
+def create_router(settings: GemiliveSettings) -> APIRouter:
+    """
+    Build and return the FastAPI router for the /ws/live endpoint.
+    Called once at mount time with a resolved config.
+    """
+    router = APIRouter()
+
+    _client = genai.Client(
+        api_key=settings.google_api_key,
+        http_options={"api_version": "v1beta"},
+    )
+
+    # Ensure model name has the required "models/" prefix
+    _model = settings.model if settings.model.startswith("models/") else f"models/{settings.model}"
+
+    async def _receive_from_client(ws: WebSocket, session) -> None:
+        try:
+            while True:
+                data = await ws.receive_json()
+
+                if "text" in data:
+                    if settings.debug_mode:
+                        print(f"[gemilive] text → Gemini: {data['text']}")
+                    await session.send_client_content(
+                        turns=types.Content(
+                            role="user",
+                            parts=[types.Part.from_text(text=data["text"])],
+                        ),
+                        turn_complete=True,
+                    )
+
+                elif "realtimeInput" in data:
+                    for chunk in data["realtimeInput"].get("mediaChunks", []):
+                        mime_type = chunk.get("mimeType")
+                        b64_data = chunk.get("data")
+                        if not mime_type or not b64_data:
+                            continue
+                        decoded = base64.b64decode(b64_data)
+                        if mime_type.startswith("audio/"):
+                            await session.send_realtime_input(
+                                audio=types.Blob(mime_type="audio/pcm", data=decoded)
+                            )
+                        elif mime_type.startswith("image/") or mime_type.startswith("video/"):
+                            await session.send_realtime_input(
+                                video=types.Blob(mime_type=mime_type, data=decoded)
+                            )
+
+        except WebSocketDisconnect:
+            pass
+        except Exception as e:
+            if settings.debug_mode:
+                print(f"[gemilive] client receive error: {e}")
+                traceback.print_exc()
+
+    async def _receive_from_gemini(ws: WebSocket, session) -> None:
+        try:
+            while True:
+                turn = session.receive()
+                async for response in turn:
+                    if response.session_resumption_update is not None:
+                        continue
+                    if getattr(response, "data", None):
+                        await ws.send_json({
+                            "type": "audio",
+                            "mimeType": "audio/pcm",
+                            "data": base64.b64encode(response.data).decode("utf-8"),
+                        })
+                    if getattr(response, "text", None):
+                        await ws.send_json({"type": "text", "text": response.text})
+                await ws.send_json({"type": "turn_complete"})
+
+        except asyncio.CancelledError:
+            pass
+        except Exception as e:
+            if settings.debug_mode:
+                print(f"[gemilive] Gemini receive error: {e}")
+                traceback.print_exc()
+
+    @router.websocket("/ws/live")
+    async def live_endpoint(websocket: WebSocket) -> None:
+        await websocket.accept()
+
+        # --- Setup phase: read system prompt from client, merge with server-side ---
+        try:
+            setup_msg = await websocket.receive_json()
+            client_prompt = setup_msg.get("setup", {}).get("system_prompt", "")
+
+            # Server-side prompt wins; client prompt is appended as extra context
+            if settings.system_prompt and client_prompt:
+                full_prompt = f"{settings.system_prompt}\n\nAdditional context: {client_prompt}"
+            else:
+                full_prompt = settings.system_prompt or client_prompt or ""
+
+        except Exception as e:
+            if settings.debug_mode:
+                print(f"[gemilive] setup error: {e}")
+            await websocket.close(code=status.WS_1003_UNSUPPORTED_DATA)
+            return
+
+        # --- Build Gemini session config ---
+        speech_config = None
+        if settings.voice:
+            speech_config = types.SpeechConfig(
+                voice_config=types.VoiceConfig(
+                    prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name=settings.voice)
+                )
+            )
+
+        config = types.LiveConnectConfig(
+            response_modalities=[types.Modality.AUDIO],
+            **({"system_instruction": types.Content(parts=[types.Part.from_text(text=full_prompt)])} if full_prompt else {}),
+            **({"speech_config": speech_config} if speech_config else {}),
+        )
+
+        # --- Connect to Gemini and run bidirectional streaming ---
+        try:
+            print(f"[gemilive] connecting → {_model}")
+            async with _client.aio.live.connect(model=_model, config=config) as session:
+                print("[gemilive] connected")
+                client_task = asyncio.create_task(_receive_from_client(websocket, session))
+                gemini_task = asyncio.create_task(_receive_from_gemini(websocket, session))
+
+                _, pending = await asyncio.wait(
+                    [client_task, gemini_task],
+                    return_when=asyncio.FIRST_COMPLETED,
+                )
+                for task in pending:
+                    task.cancel()
+
+        except Exception as e:
+            if settings.debug_mode:
+                print(f"[gemilive] Gemini connection error: {e}")
+            if websocket.client_state.name == "CONNECTED":
+                await websocket.close(code=status.WS_1011_INTERNAL_ERROR)
+
+    return router

gemilive-0.1.0/gemilive.egg-info/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: gemilive
+Version: 0.1.0
+Summary: Minimal Gemini Live AI WebSocket proxy for FastAPI — plug and play voice + video AI.
+License-Expression: MIT
+Keywords: gemini,live,ai,voice,video,fastapi,websocket
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi[standard]>=0.115.0
+Requires-Dist: google-genai>=1.70.0
+Requires-Dist: pydantic-settings>=2.13.1
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: websockets>=16.0
+Dynamic: license-file
+
+# gemilive
+
+Plug-and-play **Gemini Live AI** (voice + video) for your FastAPI app.
+
+`gemilive` provides a seamless bridge between a web-based frontend and Google's Gemini Multimodal Live API. It handles the heavy lifting of WebSockets, bidirectional audio streams (16kHz up / 24kHz down), gapless browser PCM playback, and live video framing — allowing you to add conversational AI to your project in just **six lines of code**.
+
+This repo contains both the Python backend plugin (`gemilive`) and the companion JavaScript client (`gemilive-js`).
+
+## 🚀 Features
+
+- **Bidirectional Voice AI**: Real-time PCM audio streaming for natural, fluid conversions. No laggy turn-by-turn.
+- **Multimodal Vision**: The AI can see what your camera sees via 1fps JPEG snapshots.
+- **Zero-Boilerplate Backend**: Just wrap your existing FastAPI app with `mount_gemilive()`.
+- **Lightweight JS SDK**: A clean browser `GemiliveClient` handling media capture and resampling.
+- **Toggleable Media**: Turn your camera off/on mid-session seamlessly.
+
+---
+
+## 🛠️ Installation & Quickstart
+
+Integration requires two pieces: the Python server endpoint and the JavaScript browser client.
+
+### Backend (Python)
+
+Install the pip package:
+```bash
+uv add gemilive
+# or pip install gemilive
+```
+
+Setup requires an API key. You can provide it in code or grab it from your `.env`:
+```env
+GOOGLE_API_KEY=your_gemini_api_key_here
+MODEL_NAME=gemini-3.1-flash-live-preview
+```
+
+Mount it into any FastAPI app:
+```python
+from fastapi import FastAPI
+from gemilive import mount_gemilive
+
+app = FastAPI()
+
+# Mounts the WebSocket route at /ws/live
+mount_gemilive(app, system_prompt="You are a helpful assistant. Keep answers brief.")
+```
+
+### Frontend (JavaScript)
+
+Install the npm package:
+```bash
+npm install gemilive-js
+```
+*Or use via CDN in plain HTML:*
+```html
+<script src="https://cdn.jsdelivr.net/npm/gemilive-js/dist/gemilive.min.js"></script>
+```
+
+Initialize the client, connect, and start talking:
+```javascript
+import { GemiliveClient } from 'gemilive-js';
+
+// Point it to your FastAPI server's mount path
+const client = new GemiliveClient("ws://localhost:8000/ws/live");
+
+client.onMessage = (text) => console.log("Gemini:", text);
+client.onError = (err) => console.error("Error:", err);
+
+// Start the connection (prompts user for Mic & Camera)
+await client.start();
+
+// Disable video mid-session (audio continues)
+// client.toggleVideo(false);
+
+// Stop and disconnect
+// client.stop();
+```
+
+---
+
+## ⚙️ Advanced Configuration
+
+### Python `mount_gemilive()` Overrides
+You can override environment variables dynamically when mounting the API:
+
+```python
+mount_gemilive(
+    app,
+    google_api_key="...",                 # Overrides GOOGLE_API_KEY env 
+    model="gemini-3.1-flash-live-preview",# Overrides MODEL_NAME env
+    voice="Aoede",                        # Optional Gemini Voice ("Aoede", "Charon", etc.)
+    allow_origins=["https://myapp.com"],  # Essential if your frontend is on a different domain
+    debug_mode=True                       # Console logging of message flow
+)
+```
+
+### The System Prompt
+You can set system prompts on the **server-side** (via `mount_gemilive`) or the **client-side** (via `new GemiliveClient(url, { systemPrompt: "..." })`). 
+If both are provided, the server-side prompt takes precedence, and the client-side prompt is appended securely as "Additional context".
+
+---
+
+## 📂 Project Structure (For Contributors)
+
+`gemilive` is developed as a monorepo containing two packages:
+
+```text
+├── gemilive/             # PyPI package source
+│   ├── mount.py        # Public FastAPI installer
+│   ├── config.py       # Pydantic env validation
+│   └── router.py       # Internal WebSocket / GenAI flow
+├── gemilive-js/          # npm package source
+│   ├── src/index.js    # Browser SDK (Web Audio API logic)
+│   └── package.json
+└── main.py             # Sandbox FastAPI app for testing and local dev
+```
+
+For guidelines on local development and how to publish to PyPI and npm, read `PUBLISHING.md`.
+
+---
+
+## ⚠️ Important Considerations
+
+1. **Browser Security**: Browsers restrict microphone/camera access to secure contexts. `getUserMedia` requires **HTTPS** in production. `localhost` works for development.
+2. **Audio Resampling**: Browsers typically record audio at 44.1kHz or 48kHz. The `gemilive-js` SDK seamlessly resamples microphone inputs to **16kHz PCM** to meet Gemini's strict API requirements. Responses from Gemini are returned as 24kHz PCM and gaplessly played back using Javascript time-scheduling.
+
+---
+
+## 📄 License
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

gemilive-0.1.0/gemilive.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+gemilive/__init__.py
+gemilive/config.py
+gemilive/mount.py
+gemilive/py.typed
+gemilive/router.py
+gemilive.egg-info/PKG-INFO
+gemilive.egg-info/SOURCES.txt
+gemilive.egg-info/dependency_links.txt
+gemilive.egg-info/requires.txt
+gemilive.egg-info/top_level.txt

gemilive-0.1.0/gemilive.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gemilive-0.1.0/gemilive.egg-info/requires.txt

@@ -0,0 +1,5 @@
+fastapi[standard]>=0.115.0
+google-genai>=1.70.0
+pydantic-settings>=2.13.1
+python-dotenv>=1.2.2
+websockets>=16.0

gemilive-0.1.0/gemilive.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+gemilive
+gemilive-js

gemilive-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "gemilive"
+version = "0.1.0"
+description = "Minimal Gemini Live AI WebSocket proxy for FastAPI — plug and play voice + video AI."
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+keywords = ["gemini", "live", "ai", "voice", "video", "fastapi", "websocket"]
+dependencies = [
+    "fastapi[standard]>=0.115.0",
+    "google-genai>=1.70.0",
+    "pydantic-settings>=2.13.1",
+    "python-dotenv>=1.2.2",
+    "websockets>=16.0",
+]
+
+[tool.setuptools.packages.find]
+include = ["gemilive*"]

gemilive-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+