livekit-plugins-humanlike 0.1.0__tar.gz

livekit_plugins_humanlike-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: livekit-plugins-humanlike
+Version: 0.1.0
+Summary: Humanlike avatar plugin for LiveKit Agents — real-time talking-head video with expression control
+Author: Humanlike AI
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/HumanlikeAI/livekit-plugins-humanlike
+Project-URL: Repository, https://github.com/HumanlikeAI/livekit-plugins-humanlike
+Keywords: livekit,avatar,talking-head,real-time,humanlike
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: livekit-agents>=1.0
+Requires-Dist: numpy
+Requires-Dist: websockets
+Requires-Dist: Pillow
+Provides-Extra: fast
+Requires-Dist: turbojpeg; extra == "fast"
+Requires-Dist: soxr; extra == "fast"
+
+# livekit-plugins-humanlike
+
+Real-time talking-head avatar plugin for [LiveKit Agents](https://docs.livekit.io/agents/).
+
+Streams TTS audio to a GPU-backed avatar orchestrator that returns lip-synced video frames with facial expressions guided by a natural-language prompt.
+
+## Install
+
+```bash
+pip install livekit-plugins-humanlike
+```
+
+## Quick start
+
+```python
+from livekit.plugins.humanlike import AvatarSession
+
+avatar = AvatarSession(
+    orchestrator_url="ws://your-gpu-server:8000/ws/stream",
+    image="/path/to/face.png",
+    avatar_model="humanlike-homo",
+    prompt="warm, friendly, subtly smiling, occasional nods",
+)
+
+# Wire into your LiveKit agent
+await avatar.start(agent_session, room=ctx.room)
+```
+
+## Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `orchestrator_url` | `ws://localhost:8000/ws/stream` | Avatar server WebSocket URL |
+| `image` | `./face.png` | Face image (file path or raw bytes) |
+| `avatar_model` | `humanlike-homo` | Model identifier |
+| `prompt` | `""` | Expression prompt (e.g. "warm, smiling, nods") |
+| `seed` | `42` | Random seed for reproducibility |
+| `video_width` | `512` | Output video width |
+| `video_height` | `512` | Output video height |
+| `tts_sample_rate` | `16000` | Must match your TTS output rate |
+
+## Live expression updates
+
+Update the avatar's expression mid-conversation:
+
+```python
+await avatar.set_prompt("excited, wide eyes, big smile")
+```
+
+## Full agent example
+
+```python
+from livekit.agents import Agent, AgentSession, JobContext, RoomOutputOptions, WorkerOptions, cli
+from livekit.plugins import cartesia, openai, silero
+from livekit.plugins.humanlike import AvatarSession
+
+async def entrypoint(ctx: JobContext):
+    await ctx.connect()
+
+    session = AgentSession(
+        stt=openai.STT(),
+        llm=openai.LLM(model="gpt-4o"),
+        tts=cartesia.TTS(model="sonic-3", sample_rate=16000),
+        vad=silero.VAD.load(),
+    )
+
+    avatar = AvatarSession(
+        orchestrator_url="ws://localhost:8000/ws/stream",
+        image="./face.png",
+        avatar_model="humanlike-homo",
+        prompt="warm, friendly, natural eye movement",
+    )
+    await avatar.start(session, room=ctx.room)
+
+    await session.start(
+        room=ctx.room,
+        agent=Agent(instructions="You are a helpful assistant."),
+        room_output_options=RoomOutputOptions(audio_enabled=False),
+    )
+
+if __name__ == "__main__":
+    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))
+```

livekit_plugins_humanlike-0.1.0/README.md

@@ -0,0 +1,83 @@
+# livekit-plugins-humanlike
+
+Real-time talking-head avatar plugin for [LiveKit Agents](https://docs.livekit.io/agents/).
+
+Streams TTS audio to a GPU-backed avatar orchestrator that returns lip-synced video frames with facial expressions guided by a natural-language prompt.
+
+## Install
+
+```bash
+pip install livekit-plugins-humanlike
+```
+
+## Quick start
+
+```python
+from livekit.plugins.humanlike import AvatarSession
+
+avatar = AvatarSession(
+    orchestrator_url="ws://your-gpu-server:8000/ws/stream",
+    image="/path/to/face.png",
+    avatar_model="humanlike-homo",
+    prompt="warm, friendly, subtly smiling, occasional nods",
+)
+
+# Wire into your LiveKit agent
+await avatar.start(agent_session, room=ctx.room)
+```
+
+## Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `orchestrator_url` | `ws://localhost:8000/ws/stream` | Avatar server WebSocket URL |
+| `image` | `./face.png` | Face image (file path or raw bytes) |
+| `avatar_model` | `humanlike-homo` | Model identifier |
+| `prompt` | `""` | Expression prompt (e.g. "warm, smiling, nods") |
+| `seed` | `42` | Random seed for reproducibility |
+| `video_width` | `512` | Output video width |
+| `video_height` | `512` | Output video height |
+| `tts_sample_rate` | `16000` | Must match your TTS output rate |
+
+## Live expression updates
+
+Update the avatar's expression mid-conversation:
+
+```python
+await avatar.set_prompt("excited, wide eyes, big smile")
+```
+
+## Full agent example
+
+```python
+from livekit.agents import Agent, AgentSession, JobContext, RoomOutputOptions, WorkerOptions, cli
+from livekit.plugins import cartesia, openai, silero
+from livekit.plugins.humanlike import AvatarSession
+
+async def entrypoint(ctx: JobContext):
+    await ctx.connect()
+
+    session = AgentSession(
+        stt=openai.STT(),
+        llm=openai.LLM(model="gpt-4o"),
+        tts=cartesia.TTS(model="sonic-3", sample_rate=16000),
+        vad=silero.VAD.load(),
+    )
+
+    avatar = AvatarSession(
+        orchestrator_url="ws://localhost:8000/ws/stream",
+        image="./face.png",
+        avatar_model="humanlike-homo",
+        prompt="warm, friendly, natural eye movement",
+    )
+    await avatar.start(session, room=ctx.room)
+
+    await session.start(
+        room=ctx.room,
+        agent=Agent(instructions="You are a helpful assistant."),
+        room_output_options=RoomOutputOptions(audio_enabled=False),
+    )
+
+if __name__ == "__main__":
+    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))
+```

livekit_plugins_humanlike-0.1.0/livekit/plugins/humanlike/__init__.py

@@ -0,0 +1,22 @@
+"""
+LiveKit Agents plugin — Humanlike Avatar.
+
+Provides a real-time talking-head avatar with expression-aware generation.
+Streams TTS audio to a GPU-backed avatar orchestrator that returns lip-synced
+video frames with facial expressions guided by a natural-language prompt.
+
+Usage:
+    from livekit.plugins.humanlike import AvatarSession
+
+    avatar = AvatarSession(
+        orchestrator_url="ws://localhost:8000/ws/stream",
+        image="/path/to/face.png",            # or raw bytes
+        avatar_model="humanlike-homo",
+        prompt="warm, friendly, subtly smiling, occasional nods",
+    )
+    await avatar.start(agent_session, room=ctx.room)
+"""
+
+from .avatar import AvatarSession, VideoGenerator
+
+__all__ = ["AvatarSession", "VideoGenerator"]

livekit_plugins_humanlike-0.1.0/livekit/plugins/humanlike/avatar.py

@@ -0,0 +1,399 @@
+"""
+Humanlike avatar — LiveKit Agents VideoGenerator + AvatarSession.
+
+Connects to the avatar orchestrator WebSocket and streams audio in / video
+frames out, with an expression prompt that guides facial behaviour.
+
+Orchestrator WS protocol (extended):
+  1. Client sends JSON config:
+     {
+       "model": "humanlike-homo",
+       "image": "<base64>",
+       "seed": 42,
+       "prompt": "warm, friendly, subtly smiling"
+     }
+  2. Server responds: {"status": "ready", "fps": 25, "chunk_samples": N, ...}
+  3. Client streams binary PCM int16 LE 16 kHz mono chunks
+  4. Server streams binary: [4-byte frame_idx LE uint32][JPEG bytes]
+  5. Client sends empty bytes to end the stream
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import logging
+from pathlib import Path
+
+import numpy as np
+import websockets
+
+from livekit import rtc
+from livekit.agents.voice import avatar as av
+
+logger = logging.getLogger("humanlike-avatar")
+
+PLUGIN_NAME = "humanlike"
+AVATAR_IDENTITY = "humanlike-avatar"
+TARGET_SR = 16000
+
+
+def _resample(samples: np.ndarray, src_sr: int, dst_sr: int) -> np.ndarray:
+    if src_sr == dst_sr:
+        return samples
+    try:
+        import soxr
+        return soxr.resample(samples, src_sr, dst_sr).astype(np.float32)
+    except ImportError:
+        # Fallback: linear interpolation (lower quality but no extra dep)
+        ratio = dst_sr / src_sr
+        n_out = int(len(samples) * ratio)
+        indices = np.linspace(0, len(samples) - 1, n_out)
+        return np.interp(indices, np.arange(len(samples)), samples).astype(np.float32)
+
+
+def _jpeg_to_video_frame(jpeg_bytes: bytes) -> rtc.VideoFrame:
+    """Decode JPEG to RGBA VideoFrame."""
+    try:
+        from turbojpeg import TurboJPEG, TJPF_RGBA
+        _tj = TurboJPEG()
+        rgba = _tj.decode(jpeg_bytes, pixel_format=TJPF_RGBA)
+    except ImportError:
+        from PIL import Image
+        import io
+        img = Image.open(io.BytesIO(jpeg_bytes)).convert("RGBA")
+        rgba = np.array(img)
+
+    h, w = rgba.shape[:2]
+    return rtc.VideoFrame(
+        width=w,
+        height=h,
+        type=rtc.VideoBufferType.RGBA,
+        data=bytes(rgba),
+    )
+
+
+class VideoGenerator(av.VideoGenerator):
+    """
+    LiveKit VideoGenerator that streams audio to the Humanlike avatar
+    orchestrator and yields video frames.
+
+    Parameters
+    ----------
+    ws_url : str
+        WebSocket URL of the avatar orchestrator.
+    image : bytes
+        Reference face image (PNG/JPEG bytes).
+    avatar_model : str
+        Avatar model identifier, e.g. "humanlike-homo".
+    prompt : str
+        Natural-language expression prompt that guides facial behaviour
+        during generation, e.g. "expressive, warm smile, occasional nods".
+    seed : int
+        Random seed for reproducible generation.
+    """
+
+    def __init__(
+        self,
+        ws_url: str,
+        image: bytes,
+        avatar_model: str = "humanlike-homo",
+        prompt: str = "",
+        seed: int = 42,
+    ) -> None:
+        self._ws_url = ws_url
+        self._image_b64 = base64.b64encode(image).decode()
+        self._image_bytes = image
+        self._avatar_model = avatar_model
+        self._prompt = prompt
+        self._seed = seed
+
+        self._ws: websockets.WebSocketClientProtocol | None = None
+        self._fps: float = 25.0
+        self._chunk_samples: int = 0
+
+        self._audio_buf = np.array([], dtype=np.float32)
+        self._out_q: asyncio.Queue = asyncio.Queue()
+        self._recv_task: asyncio.Task | None = None
+        self._idle_task: asyncio.Task | None = None
+        self._idle_frame: rtc.VideoFrame | None = None
+        self._generating = False
+
+    # ------------------------------------------------------------------
+    # Setup
+    # ------------------------------------------------------------------
+
+    async def connect(self) -> None:
+        """Open WS, perform handshake, start background recv loop."""
+        self._ws = await websockets.connect(self._ws_url, max_size=10 * 1024 * 1024)
+
+        config = {
+            "model": self._avatar_model,
+            "image": self._image_b64,
+            "seed": self._seed,
+            "prompt": self._prompt,
+        }
+        await self._ws.send(json.dumps(config))
+        logger.info(
+            "Sent config: model=%s prompt=%r seed=%d",
+            self._avatar_model, self._prompt[:60], self._seed,
+        )
+
+        # Wait for ready
+        while True:
+            raw = await self._ws.recv()
+            if isinstance(raw, str):
+                msg = json.loads(raw)
+                if msg.get("status") == "ready":
+                    self._fps = float(msg.get("fps", 25))
+                    self._chunk_samples = int(msg.get("chunk_samples", 0))
+                    logger.info(
+                        "Orchestrator ready: model=%s fps=%.0f chunk_samples=%d",
+                        self._avatar_model, self._fps, self._chunk_samples,
+                    )
+                    break
+                if "error" in msg:
+                    raise RuntimeError(f"Orchestrator error: {msg['error']}")
+
+        self._recv_task = asyncio.ensure_future(self._recv_loop())
+
+        # Build idle frame from reference image
+        self._idle_frame = _jpeg_to_video_frame(self._image_bytes)
+        self._idle_task = asyncio.ensure_future(self._idle_loop())
+
+    async def _idle_loop(self) -> None:
+        """Push the reference image at fps until the first real chunk arrives."""
+        interval = 1.0 / self._fps
+        while not self._generating and self._idle_frame is not None:
+            await self._out_q.put(self._idle_frame)
+            await asyncio.sleep(interval)
+
+    async def _recv_loop(self) -> None:
+        """Background: read JPEG frames from WS, enqueue as VideoFrames."""
+        try:
+            assert self._ws is not None
+            async for message in self._ws:
+                if not isinstance(message, bytes) or len(message) < 4:
+                    continue
+                jpeg_data = message[4:]  # strip 4-byte frame_idx header
+                try:
+                    frame = _jpeg_to_video_frame(jpeg_data)
+                    await self._out_q.put(frame)
+                except Exception as exc:
+                    logger.warning("Failed to decode frame: %s", exc)
+        except websockets.ConnectionClosed:
+            logger.info("Orchestrator WS closed")
+        except Exception as exc:
+            logger.exception("Recv loop error: %s", exc)
+
+    # ------------------------------------------------------------------
+    # VideoGenerator protocol
+    # ------------------------------------------------------------------
+
+    async def push_audio(self, frame: rtc.AudioFrame | av.AudioSegmentEnd) -> None:
+        if isinstance(frame, av.AudioSegmentEnd):
+            await self._flush_audio()
+            await self._out_q.put(av.AudioSegmentEnd())
+            return
+
+        pcm_f32 = np.frombuffer(frame.data, dtype=np.int16).astype(np.float32) / 32768.0
+        if frame.num_channels > 1:
+            pcm_f32 = pcm_f32.reshape(-1, frame.num_channels).mean(axis=1)
+
+        pcm_f32 = _resample(pcm_f32, frame.sample_rate, TARGET_SR)
+        self._audio_buf = np.concatenate([self._audio_buf, pcm_f32])
+
+        while self._chunk_samples > 0 and len(self._audio_buf) >= self._chunk_samples:
+            chunk = self._audio_buf[: self._chunk_samples]
+            self._audio_buf = self._audio_buf[self._chunk_samples :]
+            await self._send_chunk(chunk)
+
+    def clear_buffer(self) -> None:
+        self._audio_buf = np.array([], dtype=np.float32)
+        while not self._out_q.empty():
+            try:
+                self._out_q.get_nowait()
+            except asyncio.QueueEmpty:
+                break
+
+    def __aiter__(self):
+        return self._output_stream()
+
+    async def _output_stream(self):
+        while True:
+            item = await self._out_q.get()
+            yield item
+
+    # ------------------------------------------------------------------
+    # Prompt update (live)
+    # ------------------------------------------------------------------
+
+    async def set_prompt(self, prompt: str) -> None:
+        """Update the expression prompt mid-session (if orchestrator supports it)."""
+        self._prompt = prompt
+        if self._ws is not None:
+            try:
+                await self._ws.send(json.dumps({"update_prompt": prompt}))
+                logger.info("Expression prompt updated: %r", prompt[:60])
+            except Exception as exc:
+                logger.warning("Failed to send prompt update: %s", exc)
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    async def _flush_audio(self) -> None:
+        if self._chunk_samples > 0 and len(self._audio_buf) > 0:
+            chunk = self._audio_buf
+            self._audio_buf = np.array([], dtype=np.float32)
+            if len(chunk) < self._chunk_samples:
+                chunk = np.pad(chunk, (0, self._chunk_samples - len(chunk)))
+            await self._send_chunk(chunk)
+        if self._ws is not None:
+            try:
+                await self._ws.send(b"")
+            except Exception:
+                pass
+
+    async def _send_chunk(self, chunk: np.ndarray) -> None:
+        if self._ws is None:
+            return
+        if not self._generating:
+            self._generating = True
+            if self._idle_task is not None:
+                self._idle_task.cancel()
+                self._idle_task = None
+        pcm_int16 = (np.clip(chunk, -1.0, 1.0) * 32767).astype(np.int16)
+        await self._ws.send(pcm_int16.tobytes())
+
+    async def aclose(self) -> None:
+        if self._idle_task is not None:
+            self._idle_task.cancel()
+        if self._recv_task is not None:
+            self._recv_task.cancel()
+        if self._ws is not None:
+            await self._ws.close()
+
+    @property
+    def fps(self) -> float:
+        return self._fps
+
+
+class AvatarSession:
+    """
+    High-level Humanlike avatar session for LiveKit Agents.
+
+    Wires up the VideoGenerator with LiveKit's AvatarRunner, DataStream
+    audio routing, and video publishing.
+
+    Parameters
+    ----------
+    orchestrator_url : str
+        WebSocket URL, e.g. "ws://localhost:8000/ws/stream".
+    image : str | bytes
+        Path to a face image, or raw image bytes.
+    avatar_model : str
+        Model identifier. Default "humanlike-homo".
+    prompt : str
+        Expression guidance prompt, e.g. "warm, friendly, subtly smiling".
+        Can be updated live via set_prompt().
+    seed : int
+        Random seed.
+    video_width / video_height : int
+        Output dimensions (should match orchestrator output, default 512).
+    avatar_identity : str
+        LiveKit participant identity for the avatar.
+    tts_sample_rate : int
+        TTS output sample rate (default 16000 to match pipeline).
+    """
+
+    def __init__(
+        self,
+        orchestrator_url: str = "ws://localhost:8000/ws/stream",
+        image: str | bytes = "./face.png",
+        avatar_model: str = "humanlike-homo",
+        prompt: str = "",
+        seed: int = 42,
+        video_width: int = 512,
+        video_height: int = 512,
+        avatar_identity: str = AVATAR_IDENTITY,
+        tts_sample_rate: int = TARGET_SR,
+    ) -> None:
+        self._orchestrator_url = orchestrator_url
+        self._image = image
+        self._avatar_model = avatar_model
+        self._prompt = prompt
+        self._seed = seed
+        self._video_width = video_width
+        self._video_height = video_height
+        self._avatar_identity = avatar_identity
+        self._tts_sample_rate = tts_sample_rate
+        self._runner: av.AvatarRunner | None = None
+        self._gen: VideoGenerator | None = None
+
+    def _load_image(self) -> bytes:
+        if isinstance(self._image, bytes):
+            return self._image
+        return Path(self._image).read_bytes()
+
+    async def start(
+        self,
+        agent_session,
+        room: rtc.Room,
+    ) -> None:
+        """
+        Connect to the orchestrator and wire up the LiveKit room.
+        Must be called before agent_session.start().
+        """
+        image_bytes = self._load_image()
+
+        gen = VideoGenerator(
+            ws_url=self._orchestrator_url,
+            image=image_bytes,
+            avatar_model=self._avatar_model,
+            prompt=self._prompt,
+            seed=self._seed,
+        )
+        await gen.connect()
+        self._gen = gen
+
+        audio_recv = av.DataStreamAudioReceiver(room)
+
+        agent_session.output.audio = av.DataStreamAudioOutput(
+            room=room,
+            destination_identity=self._avatar_identity,
+            sample_rate=self._tts_sample_rate,
+        )
+
+        opts = av.AvatarOptions(
+            video_width=self._video_width,
+            video_height=self._video_height,
+            video_fps=gen.fps,
+            audio_sample_rate=self._tts_sample_rate,
+            audio_channels=1,
+        )
+
+        self._runner = av.AvatarRunner(
+            room=room,
+            audio_recv=audio_recv,
+            video_gen=gen,
+            avatar_opts=opts,
+        )
+        await self._runner.start()
+        logger.info(
+            "Humanlike avatar started: model=%s prompt=%r identity=%s",
+            self._avatar_model, self._prompt[:60], self._avatar_identity,
+        )
+
+    async def set_prompt(self, prompt: str) -> None:
+        """Update the expression prompt on a live session."""
+        self._prompt = prompt
+        if self._gen is not None:
+            await self._gen.set_prompt(prompt)
+
+    async def aclose(self) -> None:
+        if self._runner is not None:
+            await self._runner.aclose()
+        if self._gen is not None:
+            await self._gen.aclose()

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

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: livekit-plugins-humanlike
+Version: 0.1.0
+Summary: Humanlike avatar plugin for LiveKit Agents — real-time talking-head video with expression control
+Author: Humanlike AI
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/HumanlikeAI/livekit-plugins-humanlike
+Project-URL: Repository, https://github.com/HumanlikeAI/livekit-plugins-humanlike
+Keywords: livekit,avatar,talking-head,real-time,humanlike
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: livekit-agents>=1.0
+Requires-Dist: numpy
+Requires-Dist: websockets
+Requires-Dist: Pillow
+Provides-Extra: fast
+Requires-Dist: turbojpeg; extra == "fast"
+Requires-Dist: soxr; extra == "fast"
+
+# livekit-plugins-humanlike
+
+Real-time talking-head avatar plugin for [LiveKit Agents](https://docs.livekit.io/agents/).
+
+Streams TTS audio to a GPU-backed avatar orchestrator that returns lip-synced video frames with facial expressions guided by a natural-language prompt.
+
+## Install
+
+```bash
+pip install livekit-plugins-humanlike
+```
+
+## Quick start
+
+```python
+from livekit.plugins.humanlike import AvatarSession
+
+avatar = AvatarSession(
+    orchestrator_url="ws://your-gpu-server:8000/ws/stream",
+    image="/path/to/face.png",
+    avatar_model="humanlike-homo",
+    prompt="warm, friendly, subtly smiling, occasional nods",
+)
+
+# Wire into your LiveKit agent
+await avatar.start(agent_session, room=ctx.room)
+```
+
+## Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `orchestrator_url` | `ws://localhost:8000/ws/stream` | Avatar server WebSocket URL |
+| `image` | `./face.png` | Face image (file path or raw bytes) |
+| `avatar_model` | `humanlike-homo` | Model identifier |
+| `prompt` | `""` | Expression prompt (e.g. "warm, smiling, nods") |
+| `seed` | `42` | Random seed for reproducibility |
+| `video_width` | `512` | Output video width |
+| `video_height` | `512` | Output video height |
+| `tts_sample_rate` | `16000` | Must match your TTS output rate |
+
+## Live expression updates
+
+Update the avatar's expression mid-conversation:
+
+```python
+await avatar.set_prompt("excited, wide eyes, big smile")
+```
+
+## Full agent example
+
+```python
+from livekit.agents import Agent, AgentSession, JobContext, RoomOutputOptions, WorkerOptions, cli
+from livekit.plugins import cartesia, openai, silero
+from livekit.plugins.humanlike import AvatarSession
+
+async def entrypoint(ctx: JobContext):
+    await ctx.connect()
+
+    session = AgentSession(
+        stt=openai.STT(),
+        llm=openai.LLM(model="gpt-4o"),
+        tts=cartesia.TTS(model="sonic-3", sample_rate=16000),
+        vad=silero.VAD.load(),
+    )
+
+    avatar = AvatarSession(
+        orchestrator_url="ws://localhost:8000/ws/stream",
+        image="./face.png",
+        avatar_model="humanlike-homo",
+        prompt="warm, friendly, natural eye movement",
+    )
+    await avatar.start(session, room=ctx.room)
+
+    await session.start(
+        room=ctx.room,
+        agent=Agent(instructions="You are a helpful assistant."),
+        room_output_options=RoomOutputOptions(audio_enabled=False),
+    )
+
+if __name__ == "__main__":
+    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))
+```

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

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+livekit/__init__.py
+livekit/plugins/__init__.py
+livekit/plugins/humanlike/__init__.py
+livekit/plugins/humanlike/avatar.py
+livekit_plugins_humanlike.egg-info/PKG-INFO
+livekit_plugins_humanlike.egg-info/SOURCES.txt
+livekit_plugins_humanlike.egg-info/dependency_links.txt
+livekit_plugins_humanlike.egg-info/requires.txt
+livekit_plugins_humanlike.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,8 @@
+livekit-agents>=1.0
+numpy
+websockets
+Pillow
+
+[fast]
+turbojpeg
+soxr

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

@@ -0,0 +1 @@
+livekit

livekit_plugins_humanlike-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "livekit-plugins-humanlike"
+version = "0.1.0"
+description = "Humanlike avatar plugin for LiveKit Agents — real-time talking-head video with expression control"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [
+    { name = "Humanlike AI" },
+]
+keywords = ["livekit", "avatar", "talking-head", "real-time", "humanlike"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "livekit-agents>=1.0",
+    "numpy",
+    "websockets",
+    "Pillow",
+]
+
+[project.optional-dependencies]
+fast = ["turbojpeg", "soxr"]
+
+[project.urls]
+Homepage = "https://github.com/HumanlikeAI/livekit-plugins-humanlike"
+Repository = "https://github.com/HumanlikeAI/livekit-plugins-humanlike"
+
+[tool.setuptools.packages.find]
+include = ["livekit*"]

livekit_plugins_humanlike-0.1.0/setup.cfg

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