livekit-plugins-humanlike 0.1.0

Humanlike avatar plugin for LiveKit Agents — real-time talking-head video with expression control

livekit-plugins-humanlike

Real-time talking-head avatar plugin for LiveKit 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

pip install livekit-plugins-humanlike

Quick start

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:

await avatar.set_prompt("excited, wide eyes, big smile")

Full agent example

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