pipecat-chatfx 0.1.0__tar.gz

pipecat_chatfx-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+.env
+.env.*
+!.env.example
+data/
+*.log
+dist/
+.claude/
+__pycache__/

pipecat_chatfx-0.1.0/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0
+
+- First release: `ChatFXVideoService`, a ChatFX Avatar face and voice for any Pipecat bot. Put it right after your TTS
+  service. Tested with Pipecat v1.15.0 and daily-python 0.37.0.

pipecat_chatfx-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, ChatRep, 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_chatfx-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.5
+Name: pipecat-chatfx
+Version: 0.1.0
+Summary: ChatFX Avatar for Pipecat: a real-time talking face for your Pipecat bot
+Project-URL: Homepage, https://chatfx.com/avatar/
+Project-URL: Documentation, https://chatfx.com/support/avatar-connect/
+Author-email: "ChatRep, Inc." <service@chatfx.com>
+License-Expression: BSD-2-Clause
+License-File: LICENSE
+Keywords: avatar,chatfx,daily,pipecat,realtime,video,voice
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: pipecat-ai[daily]>=1.8
+Description-Content-Type: text/markdown
+
+# ChatFX Avatar for Pipecat
+
+A real-time talking face for your Pipecat bot. Your bot's voice goes to the avatar, and its face and voice come back,
+drawn together so the lips match, as your bot's own video and audio. You keep your own listening, AI and voice; ChatFX
+adds the face, billed by the minute.
+
+Tested with Pipecat v1.15.0.
+
+## Install
+
+```bash
+pip install pipecat-chatfx
+```
+
+Requires Python 3.10+ and `pipecat-ai` 1.8 or newer (it brings `pipecat-ai[daily]`).
+
+## Add your keys
+
+- `CHATFX_AVATAR_API_KEY`: create one under **API keys** at [avatar.chatfx.com](https://avatar.chatfx.com).
+- `DAILY_API_KEY`: from your [Daily dashboard](https://dashboard.daily.co/developers). Running on Pipecat Cloud, you already
+  have one. The avatar meets your bot in a private Daily room in your account, made for each call and removed when it
+  ends, the way Pipecat's own Tavus service works.
+
+Put both in your bot's environment (your `.env`, or your Pipecat Cloud secret set).
+
+## Use it
+
+Put `ChatFXVideoService` right after your TTS service, and turn on your transport's video out at the avatar's size:
+
+```python
+from pipecat_chatfx import ChatFXVideoService
+
+avatar = ChatFXVideoService(avatar_id="chatfx-lois")  # copy the id from the Avatars page
+
+pipeline = Pipeline([
+    transport.input(),
+    stt,
+    user_aggregator,
+    llm,
+    tts,
+    avatar,
+    transport.output(),
+    assistant_aggregator,
+])
+```
+
+```python
+TransportParams(  # or DailyParams
+    audio_in_enabled=True,
+    audio_out_enabled=True,
+    video_out_enabled=True,
+    video_out_is_live=True,
+    video_out_width=912,     # 912 x 512 landscape, 512 x 512 square, 384 x 512 portrait
+    video_out_height=512,
+    video_out_framerate=25,
+)
+```
+
+That's all the code. When your pipeline ends (or is cancelled when the visitor leaves), the avatar's session ends too, so
+billing stops. Your page shows the bot's video as before: the avatar is the bot.
+
+Step by step: [Connecting your agent: Pipecat](https://chatfx.com/support/avatar-connect/#pipecat). A full sample bot
+(Deepgram, OpenAI, Cartesia) comes in this package's source download, in `examples/`: `uv run bot.py`, then open
+http://localhost:7860/client.
+
+## What it does for you
+
+- **Shows a waiting picture.** Until the live face is in, your bot's video is the avatar's picture with "Video starting..."
+  on it.
+- **Greets with the face.** Your bot's first words wait up to 10 seconds for the face, so they come with it.
+- **Never depends on the face.** If the face can't come, or leaves mid-call, your bot carries on with its own voice.
+- **Stops at once when talked over.** An interruption stops the avatar mid-word.
+- **Lets the last words finish.** At the end of a call, the avatar finishes its goodbye before it leaves.
+
+## Options
+
+```python
+ChatFXVideoService(
+    avatar_id="chatfx-lois",
+    api_key=None,                    # defaults to CHATFX_AVATAR_API_KEY
+    daily_api_key=None,              # defaults to DAILY_API_KEY
+    api_url=None,                    # defaults to https://api.chatfx.com
+    face_first_seconds=10.0,         # how long the first words wait for the face
+    start_timeout=120.0,             # how long to keep trying to start the avatar
+    waiting_picture=True,            # show the avatar's picture until the live face is in
+    waiting_text="Video starting...",  # the words on it, in your language (None: no words)
+)
+```
+
+If the avatar can't start (a wrong key, no minutes left), `avatar.failure` says why, with the API's `code`.
+
+## Changelog
+
+- 0.1.0: first release. Tested with Pipecat v1.15.0 and daily-python 0.37.0.
+
+## License
+
+BSD 2-Clause, like Pipecat.

pipecat_chatfx-0.1.0/README.md

@@ -0,0 +1,98 @@
+# ChatFX Avatar for Pipecat
+
+A real-time talking face for your Pipecat bot. Your bot's voice goes to the avatar, and its face and voice come back,
+drawn together so the lips match, as your bot's own video and audio. You keep your own listening, AI and voice; ChatFX
+adds the face, billed by the minute.
+
+Tested with Pipecat v1.15.0.
+
+## Install
+
+```bash
+pip install pipecat-chatfx
+```
+
+Requires Python 3.10+ and `pipecat-ai` 1.8 or newer (it brings `pipecat-ai[daily]`).
+
+## Add your keys
+
+- `CHATFX_AVATAR_API_KEY`: create one under **API keys** at [avatar.chatfx.com](https://avatar.chatfx.com).
+- `DAILY_API_KEY`: from your [Daily dashboard](https://dashboard.daily.co/developers). Running on Pipecat Cloud, you already
+  have one. The avatar meets your bot in a private Daily room in your account, made for each call and removed when it
+  ends, the way Pipecat's own Tavus service works.
+
+Put both in your bot's environment (your `.env`, or your Pipecat Cloud secret set).
+
+## Use it
+
+Put `ChatFXVideoService` right after your TTS service, and turn on your transport's video out at the avatar's size:
+
+```python
+from pipecat_chatfx import ChatFXVideoService
+
+avatar = ChatFXVideoService(avatar_id="chatfx-lois")  # copy the id from the Avatars page
+
+pipeline = Pipeline([
+    transport.input(),
+    stt,
+    user_aggregator,
+    llm,
+    tts,
+    avatar,
+    transport.output(),
+    assistant_aggregator,
+])
+```
+
+```python
+TransportParams(  # or DailyParams
+    audio_in_enabled=True,
+    audio_out_enabled=True,
+    video_out_enabled=True,
+    video_out_is_live=True,
+    video_out_width=912,     # 912 x 512 landscape, 512 x 512 square, 384 x 512 portrait
+    video_out_height=512,
+    video_out_framerate=25,
+)
+```
+
+That's all the code. When your pipeline ends (or is cancelled when the visitor leaves), the avatar's session ends too, so
+billing stops. Your page shows the bot's video as before: the avatar is the bot.
+
+Step by step: [Connecting your agent: Pipecat](https://chatfx.com/support/avatar-connect/#pipecat). A full sample bot
+(Deepgram, OpenAI, Cartesia) comes in this package's source download, in `examples/`: `uv run bot.py`, then open
+http://localhost:7860/client.
+
+## What it does for you
+
+- **Shows a waiting picture.** Until the live face is in, your bot's video is the avatar's picture with "Video starting..."
+  on it.
+- **Greets with the face.** Your bot's first words wait up to 10 seconds for the face, so they come with it.
+- **Never depends on the face.** If the face can't come, or leaves mid-call, your bot carries on with its own voice.
+- **Stops at once when talked over.** An interruption stops the avatar mid-word.
+- **Lets the last words finish.** At the end of a call, the avatar finishes its goodbye before it leaves.
+
+## Options
+
+```python
+ChatFXVideoService(
+    avatar_id="chatfx-lois",
+    api_key=None,                    # defaults to CHATFX_AVATAR_API_KEY
+    daily_api_key=None,              # defaults to DAILY_API_KEY
+    api_url=None,                    # defaults to https://api.chatfx.com
+    face_first_seconds=10.0,         # how long the first words wait for the face
+    start_timeout=120.0,             # how long to keep trying to start the avatar
+    waiting_picture=True,            # show the avatar's picture until the live face is in
+    waiting_text="Video starting...",  # the words on it, in your language (None: no words)
+)
+```
+
+If the avatar can't start (a wrong key, no minutes left), `avatar.failure` says why, with the API's `code`.
+
+## Changelog
+
+- 0.1.0: first release. Tested with Pipecat v1.15.0 and daily-python 0.37.0.
+
+## License
+
+BSD 2-Clause, like Pipecat.

pipecat_chatfx-0.1.0/examples/.env.example

@@ -0,0 +1,14 @@
+# Face (ChatFX Avatar): https://avatar.chatfx.com, under API keys
+CHATFX_AVATAR_API_KEY=
+
+# Where the avatar meets your bot: a private room in your Daily account. https://dashboard.daily.co/developers
+DAILY_API_KEY=
+
+# Speech to text (Deepgram): https://console.deepgram.com
+DEEPGRAM_API_KEY=
+
+# LLM (OpenAI): https://platform.openai.com/api-keys
+OPENAI_API_KEY=
+
+# Voice (Cartesia): https://play.cartesia.ai/keys
+CARTESIA_API_KEY=

pipecat_chatfx-0.1.0/examples/.gitignore

@@ -0,0 +1,4 @@
+.env
+.venv/
+__pycache__/
+*.pyc

pipecat_chatfx-0.1.0/examples/bot.py

@@ -0,0 +1,126 @@
+"""A Pipecat bot with a ChatFX Avatar face.
+
+Speech to text: Deepgram. LLM: OpenAI. Voice: Cartesia. Face: ChatFX Avatar, right after the voice.
+
+Put your keys in .env (see .env.example), then:
+
+    uv run bot.py
+
+and open http://localhost:7860/client. Click Connect and allow the microphone: the avatar appears and says the first message.
+"""
+
+import os
+
+from dotenv import load_dotenv
+from loguru import logger
+from pipecat.audio.vad.silero import SileroVADAnalyzer
+from pipecat.frames.frames import TTSSpeakFrame
+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.runner.types import RunnerArguments
+from pipecat.runner.utils import create_transport
+from pipecat.services.cartesia.tts import CartesiaTTSService
+from pipecat.services.deepgram.stt import DeepgramSTTService
+from pipecat.services.openai.llm import OpenAILLMService
+from pipecat.transports.base_transport import BaseTransport, TransportParams
+from pipecat.transports.daily.transport import DailyParams
+from pipecat.workers.runner import WorkerRunner
+
+from pipecat_chatfx import ChatFXVideoService
+
+load_dotenv(override=True)
+
+SYSTEM_PROMPT = "You are a friendly assistant on a video call. Keep answers short, with no special characters, emojis or markdown: they are spoken."
+FIRST_MESSAGE = "Hello! What can I help you with today?"
+# Copy the id from the Avatars page at avatar.chatfx.com.
+AVATAR_ID = "chatfx-lois"
+# The avatar's size: 912 x 512 for a landscape avatar, 512 x 512 square, 384 x 512 portrait.
+VIDEO_WIDTH = 912
+VIDEO_HEIGHT = 512
+
+# "webrtc" for testing on your machine, "daily" on Pipecat Cloud. The avatar sends 25 pictures a second.
+transport_params = {
+    "daily": lambda: DailyParams(
+        audio_in_enabled=True,
+        audio_out_enabled=True,
+        video_out_enabled=True,
+        video_out_is_live=True,
+        video_out_width=VIDEO_WIDTH,
+        video_out_height=VIDEO_HEIGHT,
+        video_out_framerate=25,
+    ),
+    "webrtc": lambda: TransportParams(
+        audio_in_enabled=True,
+        audio_out_enabled=True,
+        video_out_enabled=True,
+        video_out_is_live=True,
+        video_out_width=VIDEO_WIDTH,
+        video_out_height=VIDEO_HEIGHT,
+        video_out_framerate=25,
+    ),
+}
+
+
+async def run_bot(transport: BaseTransport, runner_args: RunnerArguments):
+    stt = DeepgramSTTService(api_key=os.environ["DEEPGRAM_API_KEY"])
+    llm = OpenAILLMService(api_key=os.environ["OPENAI_API_KEY"], settings=OpenAILLMService.Settings(system_instruction=SYSTEM_PROMPT))
+    tts = CartesiaTTSService(
+        api_key=os.environ["CARTESIA_API_KEY"],
+        # Any Cartesia voice id.
+        settings=CartesiaTTSService.Settings(voice="71a7ad14-091c-4e8e-a314-022ece01c121"),
+    )
+    # CHATFX_AVATAR_API_KEY and DAILY_API_KEY come from .env.
+    avatar = ChatFXVideoService(avatar_id=AVATAR_ID)
+
+    context = LLMContext()
+    user_aggregator, assistant_aggregator = LLMContextAggregatorPair(
+        context,
+        user_params=LLMUserAggregatorParams(vad_analyzer=SileroVADAnalyzer()),
+    )
+
+    pipeline = Pipeline(
+        [
+            transport.input(),
+            stt,
+            user_aggregator,
+            llm,
+            tts,
+            avatar,
+            transport.output(),
+            assistant_aggregator,
+        ]
+    )
+
+    worker = PipelineWorker(
+        pipeline,
+        params=PipelineParams(enable_metrics=True),
+        idle_timeout_secs=runner_args.pipeline_idle_timeout_secs,
+    )
+
+    @transport.event_handler("on_client_connected")
+    async def on_client_connected(transport, client):
+        logger.info("Client connected")
+        await worker.queue_frames([TTSSpeakFrame(FIRST_MESSAGE)])
+
+    @transport.event_handler("on_client_disconnected")
+    async def on_client_disconnected(transport, client):
+        # Ends the avatar's session too, so billing stops.
+        await worker.cancel()
+
+    runner = WorkerRunner(handle_sigint=runner_args.handle_sigint)
+    await runner.add_workers(worker)
+    await runner.run()
+
+
+async def bot(runner_args: RunnerArguments):
+    """Entry point for the local runner and for Pipecat Cloud."""
+    transport = await create_transport(runner_args, transport_params)
+    await run_bot(transport, runner_args)
+
+
+if __name__ == "__main__":
+    from pipecat.runner.run import main
+
+    main()

pipecat_chatfx-0.1.0/examples/pyproject.toml

@@ -0,0 +1,10 @@
+[project]
+name = "chatfx-avatar-pipecat-bot"
+version = "0.1.0"
+description = "A Pipecat bot with a ChatFX Avatar face"
+requires-python = ">=3.11"
+dependencies = [
+  "pipecat-ai[daily,deepgram,cartesia,openai,runner,silero,webrtc]==1.15.0",
+  "pipecat-chatfx==0.1.0",
+  "python-dotenv>=1.0",
+]

pipecat_chatfx-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pipecat-chatfx"
+dynamic = ["version"]
+description = "ChatFX Avatar for Pipecat: a real-time talking face for your Pipecat bot"
+readme = "README.md"
+license = "BSD-2-Clause"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "ChatRep, Inc.", email = "service@chatfx.com" }]
+keywords = ["pipecat", "avatar", "video", "voice", "realtime", "chatfx", "daily"]
+classifiers = [
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Multimedia :: Video",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["pipecat-ai[daily]>=1.8", "aiohttp>=3.9"]
+
+[project.urls]
+Homepage = "https://chatfx.com/avatar/"
+Documentation = "https://chatfx.com/support/avatar-connect/"
+
+[tool.hatch.version]
+path = "src/pipecat_chatfx/version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pipecat_chatfx"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+pythonpath = ["src"]

pipecat_chatfx-0.1.0/src/pipecat_chatfx/__init__.py

@@ -0,0 +1,6 @@
+"""ChatFX Avatar for Pipecat: a real-time talking face for your Pipecat bot. See ChatFXVideoService."""
+
+from .version import __version__
+from .video import ChatFXException, ChatFXVideoService
+
+__all__ = ["ChatFXVideoService", "ChatFXException", "__version__"]

pipecat_chatfx-0.1.0/src/pipecat_chatfx/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"