pipecat-bithuman 0.1.0__py3-none-any.whl

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__",
+]

pipecat_bithuman/runtime.py

@@ -0,0 +1,120 @@
+#
+# Copyright (c) 2026, bitHuman, Inc.
+#
+# SPDX-License-Identifier: BSD-2-Clause
+#
+
+"""The seam between the Pipecat service and the bitHuman Python SDK.
+
+``BitHumanVideoService`` talks to the avatar only through the small
+:class:`BitHumanRuntime` protocol below. The default factory builds it from
+``bithuman.AsyncBithuman``, the SDK's live-streaming class. Tests (and anyone
+who wants to wrap the SDK) pass their own ``runtime_factory`` instead.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncIterator, Awaitable, Callable
+from typing import Any, Protocol, runtime_checkable
+
+API_SECRET_ENV = "BITHUMAN_API_SECRET"
+MODEL_PATH_ENV = "BITHUMAN_MODEL_PATH"
+
+
+@runtime_checkable
+class BitHumanRuntime(Protocol):
+    """What the service needs from a live bitHuman avatar.
+
+    ``bithuman.AsyncBithuman`` satisfies this protocol as is.
+    """
+
+    async def push_audio(self, data: bytes, sample_rate: int, last_chunk: bool = True) -> None:
+        """Queue int16 little-endian mono PCM for the avatar to speak.
+
+        Args:
+            data: Raw int16 PCM bytes, mono.
+            sample_rate: Sample rate of ``data`` in hertz. The SDK resamples.
+            last_chunk: Whether this chunk ends the current reply.
+        """
+        ...
+
+    async def flush(self) -> None:
+        """Mark the end of the current reply."""
+        ...
+
+    def interrupt(self) -> None:
+        """Drop the reply in flight (barge-in) and stay ready for the next one."""
+        ...
+
+    def run(self) -> AsyncIterator[Any]:
+        """Yield frames at the model's play rate.
+
+        Each frame has ``bgr_image`` (an ``(H, W, 3)`` uint8 BGR array or
+        None), ``audio_chunk`` (the audio that plays with this frame, or None
+        when idle) and ``end_of_speech`` (True on the last frame of a reply).
+
+        Returns:
+            An async iterator of frames.
+        """
+        ...
+
+    async def shutdown(self) -> None:
+        """Stop rendering and release the model and the credential."""
+        ...
+
+
+RuntimeFactory = Callable[[], Awaitable[BitHumanRuntime]]
+
+
+def resolve_model_path(model_path: str | os.PathLike[str] | None) -> str:
+    """Return the avatar model path, from the argument or ``BITHUMAN_MODEL_PATH``.
+
+    Args:
+        model_path: Path to an ``.imx`` avatar model, or None to read the
+            environment.
+
+    Returns:
+        The model path as a string.
+
+    Raises:
+        ValueError: If neither the argument nor the environment names a model.
+    """
+    value = os.fspath(model_path) if model_path is not None else os.getenv(MODEL_PATH_ENV, "")
+    value = value.strip()
+    if not value:
+        raise ValueError(
+            "BitHumanVideoService needs an avatar model: pass model_path='path/to/avatar.imx' "
+            f"or set {MODEL_PATH_ENV}. Download one with the Agents API "
+            "(https://docs.bithuman.ai/platforms/python)."
+        )
+    return value
+
+
+def sdk_runtime_factory(model_path: str, api_secret: str | None = None) -> RuntimeFactory:
+    """Build a factory that opens ``model_path`` with ``bithuman.AsyncBithuman``.
+
+    The avatar renders in this process, on this machine. When ``api_secret``
+    is None the SDK reads ``BITHUMAN_API_SECRET`` from the environment.
+
+    Args:
+        model_path: Path to an ``.imx`` avatar model.
+        api_secret: bitHuman API secret, or None to use the environment.
+
+    Returns:
+        An async callable that returns a ready :class:`BitHumanRuntime`.
+    """
+
+    async def _create() -> BitHumanRuntime:
+        try:
+            from bithuman import AsyncBithuman
+        except ImportError as e:
+            raise ImportError(
+                "The bitHuman Python SDK is not installed. Install it with "
+                "`pip install pipecat-bithuman` (Expression 2 avatars: `pip install "
+                '"pipecat-bithuman[expression-2]"`).'
+            ) from e
+
+        return await AsyncBithuman.create(model_path=model_path, api_secret=api_secret)
+
+    return _create

pipecat_bithuman/video.py

@@ -0,0 +1,628 @@
+#
+# Copyright (c) 2026, bitHuman, Inc.
+#
+# SPDX-License-Identifier: BSD-2-Clause
+#
+
+"""bitHuman video service for Pipecat.
+
+``BitHumanVideoService`` sits between a TTS (or speech-to-speech) service and
+the output transport. It sends the bot's speech to a bitHuman avatar that
+renders in this process, and pushes the avatar's frames downstream: the
+picture as ``OutputImageRawFrame`` and the speech that goes with each picture
+as ``TTSAudioRawFrame``, so the mouth and the voice leave together.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Any
+
+import numpy as np
+from loguru import logger
+from pipecat.frames.frames import (
+    CancelFrame,
+    EndFrame,
+    Frame,
+    InterruptionFrame,
+    OutputImageRawFrame,
+    StartFrame,
+    TTSAudioRawFrame,
+    TTSStoppedFrame,
+)
+from pipecat.processors.frame_processor import FrameDirection
+from pipecat.services.ai_service import AIService
+from pipecat.services.settings import ServiceSettings
+from pipecat.utils.errors import ErrorCategory
+
+from .runtime import (
+    API_SECRET_ENV,
+    BitHumanRuntime,
+    RuntimeFactory,
+    resolve_model_path,
+    sdk_runtime_factory,
+)
+
+# Exception class names raised by the bitHuman SDK, matched by name so this
+# module does not import the SDK (and so wrapped runtimes classify the same way).
+_AUTHENTICATION_ERRORS = frozenset(
+    {
+        "NotAuthorised",
+        "TokenError",
+        "TokenExpiredError",
+        "TokenValidationError",
+        "TokenRequestError",
+    }
+)
+_AUTHORIZATION_ERRORS = frozenset({"AccountStatusError"})
+_INVALID_REQUEST_ERRORS = frozenset(
+    {
+        "InvalidAvatar",
+        "NotSupported",
+        "ModelError",
+        "ModelNotFoundError",
+        "ModelLoadError",
+        "ModelSecurityError",
+        "FileNotFoundError",
+    }
+)
+_MISSING_SECRET_HINTS = ("api_secret is required", "no api secret")
+
+_REDACTED = "***"
+
+
+class BitHumanServiceError(Exception):
+    """An error from the bitHuman avatar, with any API secret removed from its text."""
+
+
+@dataclass
+class BitHumanVideoSettings(ServiceSettings):
+    """Settings for the bitHuman video service.
+
+    The service has no runtime-updatable settings yet. The avatar model is
+    chosen at construction time with ``model_path``.
+    """
+
+    pass
+
+
+@dataclass
+class _Reply:
+    """One bot reply on its way through the avatar.
+
+    Parameters:
+        context_id: The TTS context the reply's audio came from.
+        flushed: Whether the end of the reply was sent to the avatar.
+        flushed_at: Monotonic time of the flush.
+        voiced: Whether the avatar has emitted non-silent audio for it.
+        stop_frames: ``TTSStoppedFrame`` s held until the reply finishes playing.
+    """
+
+    context_id: str | None
+    flushed: bool = False
+    flushed_at: float = 0.0
+    voiced: bool = False
+    stop_frames: list[Frame] = field(default_factory=list)
+
+
+class BitHumanVideoService(AIService):
+    """Lip-synced bitHuman avatar video for a Pipecat bot.
+
+    Place it after the TTS service (or a speech-to-speech LLM) and before
+    ``transport.output()``. It consumes ``TTSAudioRawFrame`` and pushes:
+
+    - ``OutputImageRawFrame`` (RGB) for every avatar frame, while talking and
+      while idle.
+    - ``TTSAudioRawFrame`` (16 kHz mono) with the speech that plays with each
+      frame. The input TTS audio is not forwarded, so the voice is the
+      avatar's copy and stays paired with the picture.
+    - ``TTSStoppedFrame`` only after the avatar has finished speaking the reply.
+
+    On ``InterruptionFrame`` (barge-in) the avatar drops the reply in flight
+    and goes back to idle. The avatar opens on ``StartFrame`` and closes on
+    ``EndFrame``, ``CancelFrame`` or cleanup, whichever comes first.
+
+    If the avatar cannot start or fails mid-session, the service pushes an
+    ``ErrorFrame`` upstream and, by default, passes TTS audio through unchanged
+    so the bot keeps talking without video.
+
+    Rendering runs in this process on this machine through the ``bithuman``
+    Python SDK, and is metered by active session time (talking or idle).
+    """
+
+    Settings = BitHumanVideoSettings
+    _settings: Settings
+
+    def __init__(
+        self,
+        *,
+        model_path: str | os.PathLike[str] | None = None,
+        api_secret: str | None = None,
+        runtime_factory: RuntimeFactory | None = None,
+        sync_video_to_audio: bool = True,
+        audio_passthrough_on_error: bool = True,
+        stop_frame_timeout_s: float = 2.0,
+        end_drain_timeout_s: float = 30.0,
+        settings: Settings | None = None,
+        **kwargs,
+    ):
+        """Initialize the bitHuman video service.
+
+        Args:
+            model_path: Path to the avatar's ``.imx`` model file. Defaults to
+                the ``BITHUMAN_MODEL_PATH`` environment variable.
+            api_secret: bitHuman API secret. Defaults to the
+                ``BITHUMAN_API_SECRET`` environment variable (read by the SDK).
+                It is never logged.
+            runtime_factory: Advanced. An async callable returning an object
+                that implements ``BitHumanRuntime``. Replaces the default,
+                which opens ``model_path`` with ``bithuman.AsyncBithuman``.
+                Useful for tests and for wrapping the SDK.
+            sync_video_to_audio: Mark each image with ``sync_with_audio`` so
+                the output transport shows it only after the audio before it
+                has been sent. Keep the transport's ``video_out_is_live`` off
+                (its default) when this is on.
+            audio_passthrough_on_error: If the avatar fails, forward TTS audio
+                unchanged so the bot still speaks. When False, the audio is
+                dropped.
+            stop_frame_timeout_s: Release a held ``TTSStoppedFrame`` if the
+                avatar has been idle this long after the end of a reply
+                without reporting the end of speech.
+            end_drain_timeout_s: On ``EndFrame``, the longest wait for queued
+                speech to finish playing before the avatar closes.
+            settings: Runtime-updatable settings. The service has none yet.
+            **kwargs: Additional arguments passed to ``AIService``.
+
+        Raises:
+            ValueError: If no avatar model is given and ``runtime_factory`` is
+                not set.
+        """
+        default_settings = self.Settings(model=None)
+        if settings is not None:
+            default_settings.apply_update(settings)
+
+        super().__init__(settings=default_settings, **kwargs)
+
+        if runtime_factory is None:
+            self._model_path: str | None = resolve_model_path(model_path)
+            runtime_factory = sdk_runtime_factory(self._model_path, api_secret)
+        else:
+            self._model_path = os.fspath(model_path) if model_path is not None else None
+
+        self._runtime_factory = runtime_factory
+        # Kept only to scrub secrets out of error text; never logged.
+        self._secrets = tuple(
+            s
+            for s in {api_secret, os.getenv(API_SECRET_ENV), os.getenv("BITHUMAN_API_KEY")}
+            if s and s.strip()
+        )
+
+        self._sync_video_to_audio = sync_video_to_audio
+        self._audio_passthrough_on_error = audio_passthrough_on_error
+        self._stop_frame_timeout_s = stop_frame_timeout_s
+        self._end_drain_timeout_s = end_drain_timeout_s
+
+        self._runtime: BitHumanRuntime | None = None
+        self._render_task: asyncio.Task | None = None
+        self._failed = False
+        self._closing = False
+
+        self._replies: deque[_Reply] = deque()
+        self._drained = asyncio.Event()
+        self._drained.set()
+        self._discard_audio = False
+        self._pending_audio_s = 0.0
+        self._last_voiced_at = 0.0
+        self._awaiting_first_voice = False
+        self._frame_size: tuple[int, int] | None = None
+
+    # ------------------------------------------------------------------
+    # Public properties
+    # ------------------------------------------------------------------
+
+    @property
+    def is_avatar_ready(self) -> bool:
+        """Whether the avatar is open and rendering.
+
+        Returns:
+            True between a successful start and teardown or failure.
+        """
+        return self._runtime is not None and not self._failed
+
+    @property
+    def frame_size(self) -> tuple[int, int] | None:
+        """The avatar's frame size as ``(width, height)``.
+
+        Returns:
+            The size of the first frame the avatar produced, or None before it.
+        """
+        return self._frame_size
+
+    def can_generate_metrics(self) -> bool:
+        """Check if this service can generate processing metrics.
+
+        Returns:
+            True. TTFB is the time from a reply's first audio in to its first
+            voiced avatar frame out.
+        """
+        return True
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def start(self, frame: StartFrame):
+        """Open the avatar and start pushing its frames.
+
+        Args:
+            frame: The start frame.
+        """
+        await super().start(frame)
+        self._closing = False
+        await self._open_runtime()
+
+    async def stop(self, frame: EndFrame):
+        """Let queued speech finish playing, then close the avatar.
+
+        Args:
+            frame: The end frame.
+        """
+        await super().stop(frame)
+        await self._drain_speech()
+        await self._teardown()
+
+    async def cancel(self, frame: CancelFrame):
+        """Close the avatar now, dropping queued speech.
+
+        Args:
+            frame: The cancel frame.
+        """
+        await super().cancel(frame)
+        await self._teardown()
+
+    async def cleanup(self):
+        """Release the avatar. Safe to call more than once."""
+        await super().cleanup()
+        await self._teardown()
+
+    async def _open_runtime(self):
+        if self._runtime is not None or self._failed:
+            return
+        started = time.monotonic()
+        try:
+            runtime = await self._runtime_factory()
+        except Exception as e:
+            await self._fail("the bitHuman avatar could not start", e)
+            return
+        self._runtime = runtime
+        logger.debug(f"{self}: avatar ready in {time.monotonic() - started:.2f} s")
+
+    def _start_render_task(self):
+        # Started only after StartFrame has gone downstream, so nothing below
+        # receives an avatar frame before it has started.
+        runtime = self._runtime
+        if runtime is None or self._render_task is not None:
+            return
+        self._render_task = self.create_task(self._render_loop(runtime), name="bithuman_render")
+
+    async def _teardown(self):
+        """Idempotent teardown shared by stop(), cancel() and cleanup()."""
+        self._closing = True
+        await self._cancel_render_task()
+        await self._close_runtime()
+        self._forget_replies()
+
+    async def _cancel_render_task(self):
+        task, self._render_task = self._render_task, None
+        if task is not None and task is not asyncio.current_task():
+            await self.cancel_task(task)
+
+    async def _close_runtime(self):
+        runtime, self._runtime = self._runtime, None
+        if runtime is None:
+            return
+        try:
+            await runtime.shutdown()
+        except Exception as e:
+            logger.warning(f"{self}: closing the avatar failed: {self._redact(str(e))}")
+
+    # ------------------------------------------------------------------
+    # Frame processing
+    # ------------------------------------------------------------------
+
+    async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Route TTS audio to the avatar and pass everything else on.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame processing.
+        """
+        await super().process_frame(frame, direction)
+
+        if direction != FrameDirection.DOWNSTREAM:
+            await self.push_frame(frame, direction)
+        elif isinstance(frame, StartFrame):
+            await self.push_frame(frame, direction)
+            self._start_render_task()
+        elif isinstance(frame, TTSAudioRawFrame):
+            await self._handle_tts_audio(frame)
+        elif isinstance(frame, TTSStoppedFrame):
+            await self._handle_tts_stopped(frame)
+        elif isinstance(frame, InterruptionFrame):
+            await self._handle_interruption()
+            await self.push_frame(frame, direction)
+        else:
+            await self.push_frame(frame, direction)
+
+    async def _handle_tts_audio(self, frame: TTSAudioRawFrame):
+        runtime = self._runtime
+        if runtime is None or self._failed:
+            if self._failed and self._audio_passthrough_on_error:
+                await self.push_frame(frame)
+            return
+
+        audio = _to_mono_int16(frame.audio, frame.num_channels)
+        if not audio:
+            return
+
+        is_new_reply = not self._replies or self._replies[-1].flushed
+        self._open_reply(frame.context_id)
+        if is_new_reply and len(self._replies) == 1:
+            # TTFB: this reply's first audio in -> its first voiced frame out.
+            self._awaiting_first_voice = True
+            await self.start_ttfb_metrics()
+        self._discard_audio = False
+        self._pending_audio_s += len(audio) / 2.0 / float(frame.sample_rate or 1)
+
+        try:
+            await runtime.push_audio(audio, frame.sample_rate, last_chunk=False)
+        except Exception as e:
+            await self._fail("sending audio to the bitHuman avatar failed", e)
+            if self._audio_passthrough_on_error:
+                await self.push_frame(frame)
+
+    async def _handle_tts_stopped(self, frame: TTSStoppedFrame):
+        runtime = self._runtime
+        if runtime is None or self._failed or not self._replies:
+            await self.push_frame(frame)
+            return
+
+        last = self._replies[-1]
+        last.stop_frames.append(frame)
+        if last.flushed:
+            # A stop with no new audio: keep it behind the speech still playing.
+            return
+        last.flushed = True
+        last.flushed_at = time.monotonic()
+        try:
+            await runtime.flush()
+        except Exception as e:
+            await self._fail("ending the reply on the bitHuman avatar failed", e)
+
+    async def _handle_interruption(self):
+        # The transport stops the bot on interruption, so held stop frames go.
+        self._forget_replies()
+        self._discard_audio = True
+        self._awaiting_first_voice = False
+        runtime = self._runtime
+        if runtime is None or self._failed:
+            return
+        try:
+            runtime.interrupt()
+        except Exception as e:
+            await self._fail("interrupting the bitHuman avatar failed", e)
+
+    def _open_reply(self, context_id: str | None) -> _Reply:
+        if not self._replies or self._replies[-1].flushed:
+            self._replies.append(_Reply(context_id=context_id))
+            self._drained.clear()
+        return self._replies[-1]
+
+    # ------------------------------------------------------------------
+    # Avatar output
+    # ------------------------------------------------------------------
+
+    async def _render_loop(self, runtime: BitHumanRuntime):
+        try:
+            async for avatar_frame in runtime.run():
+                await self._handle_avatar_frame(avatar_frame)
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:
+            if self._runtime is runtime:
+                await self._fail("the bitHuman avatar stopped rendering", e)
+            return
+        if self._runtime is runtime and not self._closing:
+            await self._fail("the bitHuman avatar stream ended unexpectedly", None)
+
+    async def _handle_avatar_frame(self, avatar_frame: Any):
+        image = getattr(avatar_frame, "bgr_image", None)
+        chunk = getattr(avatar_frame, "audio_chunk", None)
+        end_of_speech = bool(getattr(avatar_frame, "end_of_speech", False))
+        now = time.monotonic()
+
+        if image is not None:
+            await self.push_frame(self._to_output_image(image))
+
+        head = self._replies[0] if self._replies else None
+        voiced = False
+        if chunk is not None and head is not None and not self._discard_audio:
+            data, sample_rate = _chunk_bytes(chunk)
+            if data:
+                voiced = bool(np.any(np.frombuffer(data, dtype=np.int16)))
+                # Leading silence (the avatar filling before it speaks) is
+                # dropped; once the reply is voiced every chunk is kept, so
+                # pauses inside the reply keep their length.
+                if voiced or head.voiced:
+                    if voiced and not head.voiced:
+                        head.voiced = True
+                        if self._awaiting_first_voice:
+                            self._awaiting_first_voice = False
+                            await self.stop_ttfb_metrics()
+                    await self.push_frame(
+                        TTSAudioRawFrame(
+                            audio=data,
+                            sample_rate=sample_rate,
+                            num_channels=1,
+                            context_id=head.context_id,
+                        )
+                    )
+                    seconds = len(data) / 2.0 / float(sample_rate or 1)
+                    self._pending_audio_s = max(0.0, self._pending_audio_s - seconds)
+                if voiced:
+                    self._last_voiced_at = now
+
+        if head is None or not head.flushed:
+            return
+        if end_of_speech and not self._discard_audio:
+            await self._release_head()
+        elif not voiced:
+            quiet_since = max(head.flushed_at, self._last_voiced_at)
+            if now - quiet_since >= self._stop_frame_timeout_s:
+                logger.debug(f"{self}: no end of speech from the avatar; releasing TTSStoppedFrame")
+                await self._release_head()
+
+    def _to_output_image(self, bgr: np.ndarray) -> OutputImageRawFrame:
+        rgb = np.ascontiguousarray(bgr[:, :, ::-1])
+        height, width = rgb.shape[0], rgb.shape[1]
+        if self._frame_size is None:
+            self._frame_size = (width, height)
+            logger.info(
+                f"{self}: avatar frames are {width}x{height}; set the transport's "
+                f"video_out_width={width} and video_out_height={height} to avoid resizing"
+            )
+        frame = OutputImageRawFrame(image=rgb.tobytes(), size=(width, height), format="RGB")
+        frame.sync_with_audio = self._sync_video_to_audio
+        return frame
+
+    async def _release_head(self):
+        if not self._replies:
+            return
+        reply = self._replies.popleft()
+        for stop in reply.stop_frames:
+            await self.push_frame(stop)
+        if not self._replies:
+            self._pending_audio_s = 0.0
+            self._drained.set()
+
+    async def _release_all(self):
+        while self._replies:
+            await self._release_head()
+        self._drained.set()
+
+    def _forget_replies(self):
+        self._replies.clear()
+        self._pending_audio_s = 0.0
+        self._drained.set()
+
+    async def _drain_speech(self):
+        runtime = self._runtime
+        if runtime is None or self._failed or not self._replies:
+            return
+        last = self._replies[-1]
+        if not last.flushed:
+            last.flushed = True
+            last.flushed_at = time.monotonic()
+            try:
+                await runtime.flush()
+            except Exception as e:
+                await self._fail("ending the reply on the bitHuman avatar failed", e)
+                return
+        timeout = min(
+            self._end_drain_timeout_s,
+            self._pending_audio_s + self._stop_frame_timeout_s + 1.0,
+        )
+        try:
+            await asyncio.wait_for(self._drained.wait(), timeout=timeout)
+        except TimeoutError:
+            logger.warning(f"{self}: queued speech did not finish in {timeout:.1f} s; closing")
+            await self._release_all()
+
+    # ------------------------------------------------------------------
+    # Errors
+    # ------------------------------------------------------------------
+
+    async def _fail(self, message: str, exception: Exception | None):
+        """Report an avatar failure once, close the avatar and fall back."""
+        already_failed = self._failed
+        self._failed = True
+        self._awaiting_first_voice = False
+        await self._release_all()
+
+        runtime = self._runtime
+        if runtime is not None:
+            self._runtime = None
+            try:
+                await runtime.shutdown()
+            except Exception as e:
+                logger.warning(f"{self}: closing the avatar failed: {self._redact(str(e))}")
+
+        if already_failed:
+            return
+
+        category = self._classify_error(exception) if exception is not None else None
+        detail = self._redact(f"{type(exception).__name__}: {exception}") if exception else ""
+        error_msg = f"{message}: {detail}" if detail else message
+        if self._audio_passthrough_on_error:
+            error_msg += " (TTS audio now passes through without video)"
+
+        reported: Exception | None = exception
+        if exception is not None and self._contains_secret(exception):
+            reported = BitHumanServiceError(detail)
+        await self.push_error(error_msg, exception=reported, category=category)
+
+    def _classify_error(self, exception: Exception) -> ErrorCategory | None:
+        """Map bitHuman SDK exceptions to Pipecat error categories.
+
+        Args:
+            exception: The exception to classify.
+
+        Returns:
+            The category, or None to let Pipecat classify it.
+        """
+        names = {cls.__name__ for cls in type(exception).__mro__}
+        if names & _AUTHENTICATION_ERRORS:
+            return ErrorCategory.AUTHENTICATION
+        if names & _AUTHORIZATION_ERRORS:
+            return ErrorCategory.AUTHORIZATION
+        if names & _INVALID_REQUEST_ERRORS:
+            return ErrorCategory.INVALID_REQUEST
+        text = str(exception).lower()
+        if any(hint in text for hint in _MISSING_SECRET_HINTS):
+            return ErrorCategory.AUTHENTICATION
+        return super()._classify_error(exception)
+
+    def _redact(self, text: str) -> str:
+        for secret in self._secrets:
+            text = text.replace(secret, _REDACTED)
+        return text
+
+    def _contains_secret(self, exception: Exception) -> bool:
+        text = f"{exception!s} {exception!r}"
+        return any(secret in text for secret in self._secrets)
+
+
+def _to_mono_int16(audio: bytes, num_channels: int) -> bytes:
+    """Downmix interleaved int16 PCM to mono."""
+    if num_channels <= 1 or not audio:
+        return audio
+    samples = np.frombuffer(audio, dtype=np.int16)
+    usable = len(samples) - (len(samples) % num_channels)
+    frames = samples[:usable].reshape(-1, num_channels).astype(np.int32)
+    return frames.mean(axis=1).astype(np.int16).tobytes()
+
+
+def _chunk_bytes(chunk: Any) -> tuple[bytes, int]:
+    """Return ``(int16 bytes, sample_rate)`` from an SDK audio chunk."""
+    sample_rate = int(getattr(chunk, "sample_rate", 16000) or 16000)
+    data = getattr(chunk, "bytes", None)
+    if data is None:
+        array = getattr(chunk, "data", None)
+        data = b"" if array is None else np.asarray(array, dtype=np.int16).tobytes()
+    elif callable(data):
+        data = data()
+    return bytes(data), sample_rate

pipecat_bithuman-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+pipecat_bithuman/__init__.py,sha256=InKi5DiuNdqfqVNHDrvwH5Xvfr85nTbQSuwO1ryEUbA,968
+pipecat_bithuman/runtime.py,sha256=iBG7sggbuj5ufexPoKc17jcOZSvmIcFJHyyKdd7xxFk,4001
+pipecat_bithuman/video.py,sha256=W2rRfA0AWc4LAHKmrlQLUBsfbmi-8AUely4tD1pMIO4,23777
+pipecat_bithuman-0.1.0.dist-info/METADATA,sha256=z_oWp8_El-oWJ3YneibpYFpbL3wQyqy1mY2A1KfAD8I,6828
+pipecat_bithuman-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pipecat_bithuman-0.1.0.dist-info/licenses/LICENSE,sha256=EtYBf42QvoD_R35d3a-F3gDwxWTp0PMs8_iz4ZvAcrI,1303
+pipecat_bithuman-0.1.0.dist-info/RECORD,,

pipecat_bithuman-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pipecat_bithuman-0.1.0.dist-info/licenses/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.