pipecat-ai-humanlike 0.1.0

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

pipecat-ai-humanlike

Humanlike avatar plugin for Pipecat — real-time talking-head video with expression control.

Streams TTS audio to a Humanlike GPU orchestrator and receives lip-synced video frames with facial expressions guided by a natural-language prompt.

Installation

pip install pipecat-ai-humanlike

For faster audio resampling:

pip install pipecat-ai-humanlike[fast]

Quick Start

from pipecat.services.humanlike import HumanlikeVideoService

avatar = HumanlikeVideoService(
    ws_url="ws://your-gpu-server:8000/ws/stream",
    image="./face.png",
    avatar_model="humanlike-homo",
    prompt="warm, friendly, subtly smiling, occasional nods",
)

pipeline = Pipeline([
    transport.input(),
    stt,
    context_aggregator.user(),
    llm,
    tts,
    avatar,               # after TTS, before transport output
    transport.output(),
    context_aggregator.assistant(),
])

Parameters

Parameter	Type	Default	Description
ws_url	str	ws://127.0.0.1:8000/ws/stream	WebSocket URL of the Humanlike GPU orchestrator
image	str | bytes	./face.png	Path to a face image, or raw PNG/JPEG bytes
avatar_model	str	humanlike-homo	Model identifier
prompt	str	warm, friendly, subtly smiling	Expression prompt guiding facial behaviour
seed	int	42	Random seed for reproducible generation
video_width	int	512	Output video width
video_height	int	512	Output video height

Live Expression Updates

Update the expression prompt during a live session:

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

How It Works

1. On pipeline start, connects to the orchestrator via WebSocket and sends the face image + config
2. Intercepts TTSAudioRawFrame from the TTS service, resamples to 16 kHz mono, and streams PCM chunks to the orchestrator
3. Receives JPEG video frames back, decodes them, and pushes OutputImageRawFrame downstream
4. All frames (including audio) pass through so the user still hears the TTS output
5. Shows the reference image as an idle frame until the first GPU-generated frame arrives

License

Apache-2.0