Hume tts service #2518

zgreathouse · 2025-08-26T23:40:21Z

Please describe the changes in your PR. If it is addressing an issue, please reference that as well.

Adds Hume TTS service
Adds Hume Python SDK (0.11.2) dependency for service

src/pipecat/services/hume/__init__.py

markbackman · 2025-09-29T15:28:14Z

src/pipecat/services/hume/tts.py

+    using the Python SDK and emits `TTSAudioRawFrame`s suitable for Pipecat transports.
+
+    Parameters
+    ----------


Check out the docstrings convention guide:
https://github.com/pipecat-ai/pipecat/blob/main/CONTRIBUTING.md#code-style-and-documentation

src/pipecat/services/hume/tts.py

markbackman · 2025-09-29T15:30:18Z

src/pipecat/services/hume/tts.py

+
+        try:
+            # Instant mode is always enabled here (not user-configurable)
+            async for chunk in self._client.tts.synthesize_json_streaming(


From the TTSService class, there's a chunk_size @property.

@property def chunk_size(self) -> int: """Get the recommended chunk size for audio streaming. This property indicates how much audio we download (from TTS services that require chunking) before we start pushing the first audio frame. This will make sure we download the rest of the audio while audio is being played without causing audio glitches (specially at the beginning). Of course, this will also depend on how fast the TTS service generates bytes. Returns: The recommended chunk size in bytes. """ CHUNK_SECONDS = 0.5 return int(self.sample_rate * CHUNK_SECONDS * 2) # 2 bytes/sample

We've found this work well to avoid audio glitches in playback. It's helpful to use the property so we can uniformly adjust all HTTP based services.

markbackman · 2025-09-29T15:49:16Z

Generally looks good!

Can you also add an example, following the 07-interruptible pattern? Also, add this to the evals list here:
https://github.com/pipecat-ai/pipecat/blob/main/scripts/evals/run-release-evals.py

We use the foundational examples for evals and they're also helpful discovery points for developers trying out services.

If you haven't done so already, make sure to lint your code. You can install the pre-commit hook using uv run pre-commit install from the base of the repo.

Last two things:

Add your service to the README so it can be discovered.
Add docs: https://github.com/pipecat-ai/docs

ivaaan · 2025-10-01T00:27:06Z

@zgreathouse I've addressed the feedback from @markbackman and created this PR: zgreathouse#1

We need to troubleshoot the example as I see all the responses in terminal, but not in Pipecat UI in browser. Once that's fixed, we should be good to go (I hope)

markbackman · 2025-10-01T22:07:39Z

Can you please rebase the PR to resolve the conflicts?

We need to troubleshoot the example as I see all the responses in terminal, but not in Pipecat UI in browser. Once that's fixed, we should be good to go (I hope)

To get text to appear in the console, you need to add an RTVIProcessor and observer. You can see that in use in the quickstart bot file: https://github.com/pipecat-ai/pipecat/blob/main/examples/quickstart/bot.py#L84-L105

We haven't included RTVI for these examples to keep them simple, so this is probably a non-issue. I'll review the PR shortly. Thanks for the quick fixes!

markbackman · 2025-10-01T22:10:28Z

pyproject.toml

 webrtc = [ "aiortc~=1.11.0", "opencv-python~=4.11.0.86" ]
 websocket = [ "websockets>=13.1,<15.0", "fastapi>=0.115.6,<0.117.0" ]
 whisper = [ "faster-whisper~=1.1.1" ]
+fastapi = [


Can you explain this addition? I think it can be removed.

markbackman · 2025-10-01T22:13:10Z

src/pipecat/services/tts_service.py

        """
        return self._sample_rate

-    @property


Was this removed intentionally? This should remain.

markbackman · 2025-10-01T22:14:35Z

examples/foundational/07ad-interruptible-hume.py

+        audio_in_enabled=True,
+        audio_out_enabled=True,
+        vad_analyzer=SileroVADAnalyzer(),
+        audio_out_sample_rate=HUME_SAMPLE_RATE,


Remove. Sample rates should be set in the PipelineParams, not in individual services.

markbackman · 2025-10-01T22:15:38Z

examples/foundational/07ae-interruptible-hume.py

+        pipeline,
+        params=PipelineParams(
+            enable_metrics=True,
+            enable_usage_metrics=True,


Set the sample rate here.

Suggested change

enable_usage_metrics=True,

enable_usage_metrics=True,

audio_out_sample_rate=HUME_SAMPLE_RATE,

This will set the sample rate to HUME_SAMPLE_RATE for all processors that output audio.

markbackman · 2025-10-01T22:16:56Z

examples/foundational/07ad-interruptible-hume.py

+from loguru import logger
+
+from pipecat.audio.vad.silero import SileroVADAnalyzer
+from pipecat.frames.frames import StartFrame


Remove. Unused.

markbackman · 2025-10-01T22:18:26Z

src/pipecat/services/hume/tts.py

+            yield TTSStoppedFrame()
+
+
+__all__ = ["HumeTTSService"]


Remove this.

Suggested change

__all__ = ["HumeTTSService"]

The pattern is to import as:

from pipecat.services.hume.tts import HumeTTSService

markbackman · 2025-10-01T22:25:52Z

src/pipecat/services/hume/tts.py

+            )
+
+        super().__init__(
+            pause_frame_processing=True,


Remove. This should be: super().__init__(sample_rate=sample_rate, **kwargs)

Suggested change

pause_frame_processing=True,

markbackman · 2025-10-01T22:27:26Z

src/pipecat/services/hume/tts.py

+        # Request raw PCM chunks in the streaming JSON
+        pcm_fmt = FormatPcm(type="pcm")
+
+        measuring_ttfb = True


The checks around measuring_ttfb aren't needed. You can remove this variable and the if checks.

markbackman · 2025-10-01T22:33:36Z

src/pipecat/services/hume/tts.py

+
+"""Hume Text-to-Speech service implementation."""
+
+from __future__ import annotations


Is this needed?

Suggested change

from __future__ import annotations

markbackman · 2025-10-01T22:36:44Z

src/pipecat/services/hume/tts.py

+                pcm_bytes = base64.b64decode(audio_b64)
+                self._audio_bytes += pcm_bytes
+
+                # Send the first audio chunk immediately to avoid client-side delays.


I think you want to remove lines 208-216. This is causing duplicate initial audio to be spoken. In removing it, it solves the duplicate issue I was seeing running this file verbatim.

Remove the corresponding first_audio_sent variable on line 194.

markbackman · 2025-10-01T22:38:20Z

src/pipecat/services/hume/tts.py

+            logger.exception(f"{self} error generating TTS: {e}")
+            yield ErrorFrame(error=str(e))
+        finally:
+            # Yield any remaining audio


I think you want to remove this too (lines 230-231). Pipecat takes care of sending audio. You just need to yield TTSAudioRawFrames as you do above.

markbackman · 2025-10-01T22:41:40Z

src/pipecat/services/hume/tts.py

+except ModuleNotFoundError as e:  # pragma: no cover - import-time guidance
+    logger.error(f"Exception: {e}")
+    logger.error("In order to use Hume, you need to `pip install pipecat-ai[hume]`.")
+    raise


Should be:

Suggested change

raise

raise Exception(f"Missing module: {e}")

markbackman · 2025-10-01T22:44:24Z

examples/foundational/07ad-interruptible-hume.py

+from pipecat.services.hume.tts import HUME_SAMPLE_RATE, HumeTTSService
+from pipecat.services.openai.llm import OpenAILLMService
+from pipecat.transports.base_transport import BaseTransport, TransportParams
+from pipecat.transports.network.fastapi_websocket import FastAPIWebsocketParams


Update import path:

Suggested change

from pipecat.transports.network.fastapi_websocket import FastAPIWebsocketParams

from pipecat.transports.websocket.fastapi import FastAPIWebsocketParams

markbackman · 2025-10-01T22:44:41Z

examples/foundational/07ad-interruptible-hume.py

+from pipecat.services.openai.llm import OpenAILLMService
+from pipecat.transports.base_transport import BaseTransport, TransportParams
+from pipecat.transports.network.fastapi_websocket import FastAPIWebsocketParams
+from pipecat.transports.services.daily import DailyParams


Update import path:

Suggested change

from pipecat.transports.services.daily import DailyParams

from pipecat.transports.daily.transport import DailyParams

markbackman · 2025-10-01T22:46:33Z

examples/foundational/07ad-interruptible-hume.py

+        },
+    ]
+
+    context = OpenAILLMContext(messages)


Sorry about this. We just changed the pattern for this. To avoid a deprecation warning, use:

context = LLMContext(messages) context_aggregator = LLMContextAggregatorPair(context)

Import paths are:

from pipecat.processors.aggregators.llm_context import LLMContext from pipecat.processors.aggregators.llm_response_universal import LLMContextAggregatorPair

markbackman · 2025-10-01T22:48:02Z

examples/foundational/07ad-interruptible-hume.py

+        logger.info(f"Client connected")
+        # Kick off the conversation.
+        messages.append({"role": "system", "content": "Please introduce yourself to the user."})
+        await task.queue_frames([context_aggregator.user().get_context_frame()])


Related to the LLMContext change above, you need:

Suggested change

await task.queue_frames([context_aggregator.user().get_context_frame()])

await task.queue_frames([LLMRunFrame()])

LLMRunFrame is imported from:

from pipecat.frames.frames import LLMRunFrame

markbackman · 2025-10-01T22:52:43Z

examples/foundational/07ad-interruptible-hume.py

+
+async def bot(runner_args: RunnerArguments):
+    """Main bot entry point compatible with Pipecat Cloud."""
+    runner_args.transport = "webrtc"


Remove.

You can run foundational examples using the Pipecat development runner, which takes command line args:

SmallWebRTCTransport: uv run 07ad-interruptible-hume.py

DailyTransport: uv run 07ad-interruptible-hume.py --transport daily

SmallWebRTC: uv run 07ad-interruptible-hume.py --transport twilio --proxy YOUR_NGROK_URL

Let's stick to the pattern in this example, so that using these are uniform.

Suggested change

runner_args.transport = "webrtc"

markbackman · 2025-10-01T22:54:47Z

examples/foundational/07ae-interruptible-hume.py

@@ -0,0 +1,124 @@
+#


07ad has been taken. Let's rename to 07ae.

markbackman

LGTM! Thank you 🙌

All that remains is to rebase on the latest main and add a changelog entry. Also, make sure the code is linted. You can install the pre-commit hook (uv run pre-commit install) or run the ./scripts/fix-ruff.sh script to clean up.

codecov · 2025-10-02T21:04:53Z

Codecov Report

❌ Patch coverage is 0% with 75 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/pipecat/services/hume/tts.py	0.00%	75 Missing ⚠️

Files with missing lines	Coverage Δ
src/pipecat/services/hume/tts.py	`0.00% <0.00%> (ø)`

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

jamsea requested review from aconchillo and markbackman August 27, 2025 00:33

markbackman mentioned this pull request Sep 29, 2025

add hume tts integration #2005

Closed

markbackman reviewed Sep 29, 2025

View reviewed changes

src/pipecat/services/hume/__init__.py Show resolved Hide resolved

markbackman reviewed Sep 29, 2025

View reviewed changes

src/pipecat/services/hume/tts.py Show resolved Hide resolved

markbackman reviewed Sep 29, 2025

View reviewed changes

src/pipecat/services/hume/tts.py Outdated Show resolved Hide resolved

markbackman reviewed Sep 29, 2025

View reviewed changes

markbackman reviewed Oct 1, 2025

View reviewed changes

examples/foundational/07ae-interruptible-hume.py

@@ -0,0 +1,124 @@

#

Copy link

Contributor

markbackman Oct 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

07ad has been taken. Let's rename to 07ae.

markbackman approved these changes Oct 2, 2025

View reviewed changes

zgreathouse and others added 5 commits October 2, 2025 13:34

Add hume to .env.example

05fb223

add hume sdk for hume tts service

d9656cb

adds hume tts service

b489de2

add Hume example, small fixes

4ffdabc

fixes based on markbackman review

c1492c5

ivaaan force-pushed the hume-tts-service branch from 137bbe8 to c1492c5 Compare October 2, 2025 20:39

ivaaan added 4 commits October 2, 2025 13:44

Regenerate uv.lock after resolving merge conflicts

f1bbb7b

upd Changelog

fdadb12

upd evals

1b51155

upd Hume version to 2

7692301

markbackman merged commit ad2adb0 into pipecat-ai:main Oct 2, 2025
10 checks passed

	enable_usage_metrics=True,
	enable_usage_metrics=True,
	audio_out_sample_rate=HUME_SAMPLE_RATE,


		"""Hume Text-to-Speech service implementation."""

		from __future__ import annotations

	from pipecat.transports.network.fastapi_websocket import FastAPIWebsocketParams
	from pipecat.transports.websocket.fastapi import FastAPIWebsocketParams

	from pipecat.transports.services.daily import DailyParams
	from pipecat.transports.daily.transport import DailyParams

	await task.queue_frames([context_aggregator.user().get_context_frame()])
	await task.queue_frames([LLMRunFrame()])

Hume tts service #2518

Hume tts service #2518

Uh oh!

Conversation

zgreathouse commented Aug 26, 2025

Please describe the changes in your PR. If it is addressing an issue, please reference that as well.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

markbackman commented Sep 29, 2025

Uh oh!

ivaaan commented Oct 1, 2025

Uh oh!

markbackman commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

markbackman Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

markbackman Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

markbackman Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

markbackman Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

markbackman left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Reviewers

Assignees

markbackman commented Oct 1, 2025 •

edited

Loading

markbackman Oct 1, 2025 •

edited

Loading

markbackman Oct 1, 2025 •

edited

Loading

markbackman Oct 1, 2025 •

edited

Loading

markbackman Oct 1, 2025 •

edited

Loading

markbackman left a comment •

edited

Loading

codecov bot commented Oct 2, 2025 •

edited

Loading