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))
```
