pipecat-bithuman 0.1.0__tar.gz

pipecat_bithuman-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+.live/

pipecat_bithuman-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project are listed here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and the project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-30
+
+### Added
+
+- `BitHumanVideoService`: TTS audio in; lip-synced avatar video (`OutputImageRawFrame`, RGB)
+  and paired 16 kHz audio (`TTSAudioRawFrame`) out, rendered in-process by the
+  `bithuman` Python SDK.
+- `TTSStoppedFrame` is held until the avatar has finished speaking the reply.
+- Barge-in: `InterruptionFrame` drops the reply in flight and returns the avatar to idle.
+- Lifecycle: the avatar opens on `StartFrame`; `EndFrame` drains queued speech, then closes;
+  `CancelFrame` and cleanup close at once. Teardown is idempotent.
+- Errors: one `ErrorFrame` per failure with a Pipecat error category; the API secret is
+  scrubbed from error text and never logged; TTS audio passes through by default.
+- `BitHumanRuntime` protocol and `runtime_factory` for tests and SDK wrappers.
+- Minimal Daily example (`examples/bot.py`) and a fake-runtime test suite.
+- Tested with Pipecat v1.12.0 and `bithuman` 2.11.18.

pipecat_bithuman-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, bitHuman, Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pipecat_bithuman-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.5
+Name: pipecat-bithuman
+Version: 0.1.0
+Summary: bitHuman real-time avatar video service for Pipecat: TTS audio in, lip-synced avatar video and audio out.
+Project-URL: Homepage, https://www.bithuman.ai
+Project-URL: Documentation, https://docs.bithuman.ai/platforms/python
+Project-URL: Source, https://github.com/bithuman-product/pipecat-bithuman
+Project-URL: Issues, https://github.com/bithuman-product/pipecat-bithuman/issues
+Project-URL: Changelog, https://github.com/bithuman-product/pipecat-bithuman/blob/main/CHANGELOG.md
+Author: bitHuman, Inc.
+License-Expression: BSD-2-Clause
+License-File: LICENSE
+Keywords: avatar,bithuman,lip-sync,pipecat,real-time,video,voice-agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: bithuman<3,>=2.11.18
+Requires-Dist: numpy>=1.26
+Requires-Dist: pipecat-ai>=1.12.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: expression-2
+Requires-Dist: bithuman[expression-2]<3,>=2.11.18; extra == 'expression-2'
+Description-Content-Type: text/markdown
+
+# pipecat-bithuman
+
+A [bitHuman](https://www.bithuman.ai) avatar for your [Pipecat](https://github.com/pipecat-ai/pipecat) bot.
+Your TTS audio goes in. A lip-synced avatar video, plus the audio that goes with it, comes out.
+
+The avatar renders in your own process, on your own machine, through the
+`bithuman` Python SDK. Both models run live on a standard Linux PC with no GPU.
+Expression 2 animates a character from one portrait. Essence 2 is for photoreal people.
+
+Maintained by bitHuman, Inc. (community integration, not maintained by the Pipecat team).
+
+**Tested with Pipecat v1.12.0**, `bithuman` 2.11.18, Python 3.11 to 3.14.
+
+**Demo (30 s):** [docs/demo.mp4](docs/demo.mp4), rendered through a Pipecat pipeline by
+[`examples/render_demo.py`](examples/render_demo.py) with the Expression 2 sample avatar Wise Pup.
+
+## Install
+
+```bash
+pip install pipecat-bithuman
+# Expression 2 avatars (any character from one portrait):
+pip install "pipecat-bithuman[expression-2]"
+```
+
+## Environment variables
+
+| Variable | Needed | What it is |
+| --- | --- | --- |
+| `BITHUMAN_API_SECRET` | yes | Your bitHuman API secret. Get one at [www.bithuman.ai](https://www.bithuman.ai). The SDK reads it. This package never logs it. |
+| `BITHUMAN_MODEL_PATH` | unless you pass `model_path` | Path to the avatar's `.imx` model file. |
+
+Session time is metered while the avatar is open (talking or idle).
+It closes on `EndFrame`, `CancelFrame` or cleanup.
+
+Rendering bills active session time: 2 credits a minute on your own machine. From 2026-10-12, SDK use requires the Creator plan or higher. See docs.bithuman.ai/pricing.
+
+## Usage
+
+Put `BitHumanVideoService` after the TTS service and before `transport.output()`:
+
+```python
+from pipecat_bithuman import BitHumanVideoService
+
+avatar = BitHumanVideoService(model_path="avatar.imx")  # secret from BITHUMAN_API_SECRET
+
+pipeline = Pipeline([
+    transport.input(), stt, user_aggregator, llm, tts,
+    avatar,                      # TTS audio -> avatar video + audio
+    transport.output(),
+    assistant_aggregator,
+])
+```
+
+Turn on video out in the transport (`video_out_enabled=True`). The service logs the
+frame size on the first frame; set `video_out_width` / `video_out_height` to match.
+
+### What the service does with frames
+
+| In | Out |
+| --- | --- |
+| `TTSAudioRawFrame` | Sent to the avatar. Not forwarded as is. |
+| (avatar frame) | `OutputImageRawFrame` (RGB), while talking and while idle. |
+| (avatar audio) | `TTSAudioRawFrame` (16 kHz mono), paired with each picture. |
+| `TTSStoppedFrame` | Held until the avatar has finished speaking the reply. |
+| `InterruptionFrame` | The avatar drops the reply in flight and goes back to idle. |
+| anything else | Passed on unchanged. |
+
+If the avatar cannot start, or fails mid-session, the service pushes one
+`ErrorFrame` upstream. By default TTS audio then passes through unchanged, so the bot
+keeps talking without video (`audio_passthrough_on_error=False` turns this off).
+Error text is scrubbed of the API secret.
+
+### Options
+
+| Argument | Default | Meaning |
+| --- | --- | --- |
+| `model_path` | `BITHUMAN_MODEL_PATH` | The `.imx` avatar model. |
+| `api_secret` | `BITHUMAN_API_SECRET` | The API secret. |
+| `sync_video_to_audio` | `True` | Sets `sync_with_audio` on each image. |
+| `audio_passthrough_on_error` | `True` | Keep the voice if the avatar fails. |
+| `stop_frame_timeout_s` | `2.0` | Release a held `TTSStoppedFrame` after this much quiet. |
+| `end_drain_timeout_s` | `30.0` | Longest wait on `EndFrame` for queued speech. |
+| `runtime_factory` | SDK | Advanced: your own `BitHumanRuntime` (tests, wrappers). |
+
+## How it maps to the bitHuman Python SDK
+
+| Pipecat | `bithuman.AsyncBithuman` |
+| --- | --- |
+| `StartFrame` | `AsyncBithuman.create(model_path=..., api_secret=...)`, then `run()` |
+| `TTSAudioRawFrame` | `push_audio(pcm, sample_rate, last_chunk=False)` |
+| `TTSStoppedFrame` | `flush()` |
+| `InterruptionFrame` | `interrupt()` |
+| `EndFrame` / `CancelFrame` / cleanup | `shutdown()` |
+
+SDK docs: [docs.bithuman.ai/platforms/python](https://docs.bithuman.ai/platforms/python).
+
+## Run the example
+
+```bash
+pip install "pipecat-bithuman[expression-2]" "pipecat-ai[daily,deepgram,openai,cartesia,silero]"
+export BITHUMAN_API_SECRET=... BITHUMAN_MODEL_PATH=avatar.imx
+export DAILY_ROOM_URL=... DEEPGRAM_API_KEY=... OPENAI_API_KEY=... CARTESIA_API_KEY=... CARTESIA_VOICE_ID=...
+python examples/bot.py
+```
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest            # fakes only: no network, no API secret, no model file
+```
+
+One live test talks to the real SDK. It is skipped unless you set
+`PIPECAT_BITHUMAN_LIVE=1`, `BITHUMAN_API_SECRET` and `BITHUMAN_MODEL_PATH`.
+It opens the avatar for a few seconds, and that time is billed.
+
+## Links
+
+- bitHuman: [www.bithuman.ai](https://www.bithuman.ai)
+- Docs: [docs.bithuman.ai](https://docs.bithuman.ai)
+- Examples: [github.com/bithuman-product/bithuman-examples](https://github.com/bithuman-product/bithuman-examples)
+- Contact: sgu@bithuman.ai
+
+## Licence
+
+BSD 2-Clause, the same as Pipecat. See [LICENSE](LICENSE).
+Copyright (c) 2026, bitHuman, Inc.

pipecat_bithuman-0.1.0/README.md

@@ -0,0 +1,127 @@
+# pipecat-bithuman
+
+A [bitHuman](https://www.bithuman.ai) avatar for your [Pipecat](https://github.com/pipecat-ai/pipecat) bot.
+Your TTS audio goes in. A lip-synced avatar video, plus the audio that goes with it, comes out.
+
+The avatar renders in your own process, on your own machine, through the
+`bithuman` Python SDK. Both models run live on a standard Linux PC with no GPU.
+Expression 2 animates a character from one portrait. Essence 2 is for photoreal people.
+
+Maintained by bitHuman, Inc. (community integration, not maintained by the Pipecat team).
+
+**Tested with Pipecat v1.12.0**, `bithuman` 2.11.18, Python 3.11 to 3.14.
+
+**Demo (30 s):** [docs/demo.mp4](docs/demo.mp4), rendered through a Pipecat pipeline by
+[`examples/render_demo.py`](examples/render_demo.py) with the Expression 2 sample avatar Wise Pup.
+
+## Install
+
+```bash
+pip install pipecat-bithuman
+# Expression 2 avatars (any character from one portrait):
+pip install "pipecat-bithuman[expression-2]"
+```
+
+## Environment variables
+
+| Variable | Needed | What it is |
+| --- | --- | --- |
+| `BITHUMAN_API_SECRET` | yes | Your bitHuman API secret. Get one at [www.bithuman.ai](https://www.bithuman.ai). The SDK reads it. This package never logs it. |
+| `BITHUMAN_MODEL_PATH` | unless you pass `model_path` | Path to the avatar's `.imx` model file. |
+
+Session time is metered while the avatar is open (talking or idle).
+It closes on `EndFrame`, `CancelFrame` or cleanup.
+
+Rendering bills active session time: 2 credits a minute on your own machine. From 2026-10-12, SDK use requires the Creator plan or higher. See docs.bithuman.ai/pricing.
+
+## Usage
+
+Put `BitHumanVideoService` after the TTS service and before `transport.output()`:
+
+```python
+from pipecat_bithuman import BitHumanVideoService
+
+avatar = BitHumanVideoService(model_path="avatar.imx")  # secret from BITHUMAN_API_SECRET
+
+pipeline = Pipeline([
+    transport.input(), stt, user_aggregator, llm, tts,
+    avatar,                      # TTS audio -> avatar video + audio
+    transport.output(),
+    assistant_aggregator,
+])
+```
+
+Turn on video out in the transport (`video_out_enabled=True`). The service logs the
+frame size on the first frame; set `video_out_width` / `video_out_height` to match.
+
+### What the service does with frames
+
+| In | Out |
+| --- | --- |
+| `TTSAudioRawFrame` | Sent to the avatar. Not forwarded as is. |
+| (avatar frame) | `OutputImageRawFrame` (RGB), while talking and while idle. |
+| (avatar audio) | `TTSAudioRawFrame` (16 kHz mono), paired with each picture. |
+| `TTSStoppedFrame` | Held until the avatar has finished speaking the reply. |
+| `InterruptionFrame` | The avatar drops the reply in flight and goes back to idle. |
+| anything else | Passed on unchanged. |
+
+If the avatar cannot start, or fails mid-session, the service pushes one
+`ErrorFrame` upstream. By default TTS audio then passes through unchanged, so the bot
+keeps talking without video (`audio_passthrough_on_error=False` turns this off).
+Error text is scrubbed of the API secret.
+
+### Options
+
+| Argument | Default | Meaning |
+| --- | --- | --- |
+| `model_path` | `BITHUMAN_MODEL_PATH` | The `.imx` avatar model. |
+| `api_secret` | `BITHUMAN_API_SECRET` | The API secret. |
+| `sync_video_to_audio` | `True` | Sets `sync_with_audio` on each image. |
+| `audio_passthrough_on_error` | `True` | Keep the voice if the avatar fails. |
+| `stop_frame_timeout_s` | `2.0` | Release a held `TTSStoppedFrame` after this much quiet. |
+| `end_drain_timeout_s` | `30.0` | Longest wait on `EndFrame` for queued speech. |
+| `runtime_factory` | SDK | Advanced: your own `BitHumanRuntime` (tests, wrappers). |
+
+## How it maps to the bitHuman Python SDK
+
+| Pipecat | `bithuman.AsyncBithuman` |
+| --- | --- |
+| `StartFrame` | `AsyncBithuman.create(model_path=..., api_secret=...)`, then `run()` |
+| `TTSAudioRawFrame` | `push_audio(pcm, sample_rate, last_chunk=False)` |
+| `TTSStoppedFrame` | `flush()` |
+| `InterruptionFrame` | `interrupt()` |
+| `EndFrame` / `CancelFrame` / cleanup | `shutdown()` |
+
+SDK docs: [docs.bithuman.ai/platforms/python](https://docs.bithuman.ai/platforms/python).
+
+## Run the example
+
+```bash
+pip install "pipecat-bithuman[expression-2]" "pipecat-ai[daily,deepgram,openai,cartesia,silero]"
+export BITHUMAN_API_SECRET=... BITHUMAN_MODEL_PATH=avatar.imx
+export DAILY_ROOM_URL=... DEEPGRAM_API_KEY=... OPENAI_API_KEY=... CARTESIA_API_KEY=... CARTESIA_VOICE_ID=...
+python examples/bot.py
+```
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest            # fakes only: no network, no API secret, no model file
+```
+
+One live test talks to the real SDK. It is skipped unless you set
+`PIPECAT_BITHUMAN_LIVE=1`, `BITHUMAN_API_SECRET` and `BITHUMAN_MODEL_PATH`.
+It opens the avatar for a few seconds, and that time is billed.
+
+## Links
+
+- bitHuman: [www.bithuman.ai](https://www.bithuman.ai)
+- Docs: [docs.bithuman.ai](https://docs.bithuman.ai)
+- Examples: [github.com/bithuman-product/bithuman-examples](https://github.com/bithuman-product/bithuman-examples)
+- Contact: sgu@bithuman.ai
+
+## Licence
+
+BSD 2-Clause, the same as Pipecat. See [LICENSE](LICENSE).
+Copyright (c) 2026, bitHuman, Inc.

pipecat_bithuman-0.1.0/examples/bot.py

@@ -0,0 +1,83 @@
+"""Minimal Pipecat bot with a bitHuman avatar, over a Daily room.
+
+Env: BITHUMAN_API_SECRET, BITHUMAN_MODEL_PATH, DAILY_ROOM_URL, DEEPGRAM_API_KEY,
+OPENAI_API_KEY, CARTESIA_API_KEY, CARTESIA_VOICE_ID.
+"""
+
+import asyncio
+import os
+
+from pipecat.audio.vad.silero import SileroVADAnalyzer
+from pipecat.frames.frames import LLMRunFrame
+from pipecat.pipeline.pipeline import Pipeline
+from pipecat.pipeline.worker import PipelineParams, PipelineWorker
+from pipecat.processors.aggregators.llm_context import LLMContext
+from pipecat.processors.aggregators.llm_response_universal import (
+    LLMContextAggregatorPair,
+    LLMUserAggregatorParams,
+)
+from pipecat.services.cartesia.tts import CartesiaTTSService
+from pipecat.services.deepgram.stt import DeepgramSTTService
+from pipecat.services.openai.llm import OpenAILLMService
+from pipecat.transports.daily.transport import DailyParams, DailyTransport
+from pipecat.workers.runner import WorkerRunner
+
+from pipecat_bithuman import BitHumanVideoService
+
+SYSTEM = "You are Pip, a friendly red panda barista. Keep replies short and warm."
+
+
+async def main():
+    transport = DailyTransport(
+        os.environ["DAILY_ROOM_URL"],
+        None,
+        "Pip",
+        DailyParams(
+            audio_in_enabled=True,
+            audio_out_enabled=True,
+            video_out_enabled=True,
+            video_out_width=1280,
+            video_out_height=720,
+        ),
+    )
+    stt = DeepgramSTTService(api_key=os.environ["DEEPGRAM_API_KEY"])
+    llm = OpenAILLMService(api_key=os.environ["OPENAI_API_KEY"])
+    tts = CartesiaTTSService(
+        api_key=os.environ["CARTESIA_API_KEY"],
+        voice_id=os.environ["CARTESIA_VOICE_ID"],
+    )
+    avatar = BitHumanVideoService()  # BITHUMAN_MODEL_PATH + BITHUMAN_API_SECRET
+
+    context = LLMContext([{"role": "system", "content": SYSTEM}])
+    aggregators = LLMContextAggregatorPair(
+        context, user_params=LLMUserAggregatorParams(vad_analyzer=SileroVADAnalyzer())
+    )
+    pipeline = Pipeline(
+        [
+            transport.input(),
+            stt,
+            aggregators.user(),
+            llm,
+            tts,
+            avatar,
+            transport.output(),
+            aggregators.assistant(),
+        ]
+    )
+    worker = PipelineWorker(pipeline, params=PipelineParams(enable_metrics=True))
+
+    @transport.event_handler("on_first_participant_joined")
+    async def on_joined(transport, participant):
+        await worker.queue_frame(LLMRunFrame())  # Pip says hello first
+
+    @transport.event_handler("on_participant_left")
+    async def on_left(transport, participant, reason):
+        await worker.cancel()  # close the avatar: session time stops
+
+    runner = WorkerRunner()
+    await runner.add_workers(worker)
+    await runner.run()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

pipecat_bithuman-0.1.0/examples/render_demo.py

@@ -0,0 +1,73 @@
+"""Render a short demo video through a Pipecat pipeline with BitHumanVideoService.
+
+The speech in a WAV file goes in as TTSAudioRawFrame chunks (as a TTS service would send
+them); the service's OutputImageRawFrame pictures and the 16 kHz speech that goes with
+them come out and are written to an MP4 with ffmpeg.
+
+    BITHUMAN_API_SECRET=...  BITHUMAN_MODEL_PATH=avatar.imx \
+        python examples/render_demo.py speech.wav demo.mp4 [--repeat 2]
+
+Bills the avatar's active session time (see docs.bithuman.ai/pricing). Needs ffmpeg.
+"""
+import argparse
+import asyncio
+import subprocess
+import tempfile
+import wave
+from pathlib import Path
+
+from pipecat.frames.frames import OutputImageRawFrame, TTSAudioRawFrame
+from pipecat.tests.utils import SleepFrame, run_test
+
+from pipecat_bithuman import BitHumanVideoService
+
+CHUNK_S = 0.04  # 40 ms of speech per frame, like a streaming TTS
+
+
+def speech_frames(path: Path, repeat: int) -> list[TTSAudioRawFrame]:
+    with wave.open(str(path)) as w:
+        if w.getnchannels() != 1 or w.getsampwidth() != 2:
+            raise SystemExit("speech must be 16-bit mono PCM WAV")
+        rate, pcm = w.getframerate(), w.readframes(w.getnframes())
+    step = int(rate * CHUNK_S) * 2
+    frames = []
+    for _ in range(repeat):
+        frames += [TTSAudioRawFrame(audio=pcm[i:i + step], sample_rate=rate, num_channels=1,
+                                    context_id="demo") for i in range(0, len(pcm), step)]
+    return frames
+
+
+async def render(speech: Path, out: Path, repeat: int) -> None:
+    sent = speech_frames(speech, repeat)
+    seconds = sum(len(f.audio) / 2 / f.sample_rate for f in sent)
+    down, _ = await run_test(BitHumanVideoService(),
+                             frames_to_send=sent + [SleepFrame(sleep=3.0)], start_timeout=60.0)
+    images = [f for f in down if isinstance(f, OutputImageRawFrame)]
+    audio = b"".join(f.audio for f in down if isinstance(f, TTSAudioRawFrame))
+    if not images:
+        raise SystemExit("no avatar frames came out")
+    w, h = images[0].size
+    fps = round(len(images) / max(seconds, 0.1))
+    with tempfile.TemporaryDirectory() as tmp:
+        wav = Path(tmp) / "speech.wav"
+        with wave.open(str(wav), "wb") as o:
+            o.setnchannels(1), o.setsampwidth(2), o.setframerate(16000), o.writeframes(audio)
+        cmd = ["ffmpeg", "-y", "-loglevel", "error", "-f", "rawvideo", "-pix_fmt", "rgb24",
+               "-s", f"{w}x{h}", "-r", str(fps), "-i", "-", "-i", str(wav),
+               "-c:v", "libx264", "-pix_fmt", "yuv420p", "-c:a", "aac", "-shortest", str(out)]
+        proc = subprocess.Popen(cmd, stdin=subprocess.PIPE)
+        for f in images:
+            proc.stdin.write(f.image)
+        proc.stdin.close()
+        if proc.wait() != 0:
+            raise SystemExit("ffmpeg failed")
+    print(f"{out}: {len(images)} frames at {fps} fps, {w}x{h}, {seconds:.1f} s of speech")
+
+
+if __name__ == "__main__":
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("speech", type=Path)
+    ap.add_argument("out", type=Path)
+    ap.add_argument("--repeat", type=int, default=1)
+    a = ap.parse_args()
+    asyncio.run(render(a.speech, a.out, a.repeat))

pipecat_bithuman-0.1.0/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pipecat-bithuman"
+version = "0.1.0"
+description = "bitHuman real-time avatar video service for Pipecat: TTS audio in, lip-synced avatar video and audio out."
+readme = "README.md"
+license = "BSD-2-Clause"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "bitHuman, Inc." }]
+keywords = ["pipecat", "bithuman", "avatar", "video", "voice-agent", "lip-sync", "real-time"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "pipecat-ai>=1.12.0",
+    "bithuman>=2.11.18,<3",
+    "numpy>=1.26",
+]
+
+[project.optional-dependencies]
+# Expression 2 avatars (any character from one portrait) need the SDK extra.
+expression-2 = ["bithuman[expression-2]>=2.11.18,<3"]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.6",
+]
+
+[project.urls]
+Homepage = "https://www.bithuman.ai"
+Documentation = "https://docs.bithuman.ai/platforms/python"
+Source = "https://github.com/bithuman-product/pipecat-bithuman"
+Issues = "https://github.com/bithuman-product/pipecat-bithuman/issues"
+Changelog = "https://github.com/bithuman-product/pipecat-bithuman/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pipecat_bithuman"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/pipecat_bithuman",
+    "tests",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = [
+    "live: talks to the real bitHuman SDK with a real API secret (bills session time; opt-in only)",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "D", "UP", "B"]
+ignore = ["D105", "D107"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["D"]
+"examples/*" = ["D"]

pipecat_bithuman-0.1.0/src/pipecat_bithuman/__init__.py

@@ -0,0 +1,41 @@
+#
+# Copyright (c) 2026, bitHuman, Inc.
+#
+# SPDX-License-Identifier: BSD-2-Clause
+#
+
+"""bitHuman real-time avatar video service for Pipecat.
+
+TTS audio goes in; lip-synced avatar video and the matching audio come out.
+See ``BitHumanVideoService``.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .runtime import (
+    API_SECRET_ENV,
+    MODEL_PATH_ENV,
+    BitHumanRuntime,
+    RuntimeFactory,
+    resolve_model_path,
+    sdk_runtime_factory,
+)
+from .video import BitHumanServiceError, BitHumanVideoService, BitHumanVideoSettings
+
+try:
+    __version__ = version("pipecat-bithuman")
+except PackageNotFoundError:  # running from a source tree without install
+    __version__ = "0.0.0"
+
+__all__ = [
+    "API_SECRET_ENV",
+    "MODEL_PATH_ENV",
+    "BitHumanRuntime",
+    "BitHumanServiceError",
+    "BitHumanVideoService",
+    "BitHumanVideoSettings",
+    "RuntimeFactory",
+    "resolve_model_path",
+    "sdk_runtime_factory",
+    "__version__",
+]