Skip to main content

pipecat-finesse

Finesse text-to-speech for Pipecat.

Finesse streams speech in 60 languages, 22 of them Indian, from your own cloned voices or the Finesse catalog. This package adds FinesseTTSService, which speaks over the Finesse realtime WebSocket:

  • Streams as the LLM writes. Text goes to Finesse as it arrives, so speech starts before the reply is finished.
  • One context per turn. All sentences of an LLM turn share one Finesse context, so prosody carries across them.
  • Interruptions. When the user talks over the bot, the turn is cancelled on the server and its remaining audio is dropped; the connection stays open for the next turn.
  • Any pipeline rate. 8 kHz telephony pipelines get 8 kHz audio straight from Finesse, with no resampling; other rates below its native 24 kHz, such as 16 kHz, are resampled for you.

Maintained by Flam, the company that builds Finesse.

Compatibility

Tested with Pipecat v1.12.0 and v1.16.0 (pipecat-ai>=1.12,<2). See the changelog for updates.

Install

pip install pipecat-finesse

Use

from pipecat.transcriptions.language import Language
from pipecat_finesse import FinesseTTSService

tts = FinesseTTSService(  # reads FINESSE_API_KEY
    settings=FinesseTTSService.Settings(
        voice="<your voice id>",
        language=Language.HI,
    ),
)

Put it in a pipeline where any other TTS service goes. examples/voice_agent.py is a complete voice agent (Deepgram, OpenAI, Finesse) that runs in your browser:

cp .env.example .env   # fill in the keys
uv run --with "pipecat-ai[deepgram,openai,runner,silero,webrtc]" examples/voice_agent.py

Getting a key and a voice

Create an API key in the Finesse dashboard under Settings → API keys. Pick a voice from the dashboard's voice library, one of your cloned voices, or list them with the List voices API; use the voice's id.

Settings

Setting Default Notes
voice required Flam voice id
language Language.EN Pipecat Language or a Finesse code; mapped to Finesse codes (Odia ory, Nepali npi, Egyptian Arabic ar-EG → arz, Gulf Arabic ar-AE → afb, ...)
num_step server default (32) 1-32, quality vs latency
guidance_scale server default (2.0) 0-10
length_scale server default (1.0) speaking rate, higher is slower

Constructor options: api_key, sample_rate, idle_flush_ms (how long the server waits before speaking a partial sentence, 200-5000 ms) and client_name (added to the X-Finesse-Client header so you can tell your apps apart in Finesse analytics).

Voice and language apply per turn: a change takes effect from the next turn.

Errors and limits

  • A refused connection reports the HTTP status and Finesse error code, e.g. HTTP 429 (concurrency_limited, retry after 1s) when you are at your plan's concurrent-stream limit, or HTTP 503 (upstream_busy, ...) when the service is at capacity. The service retries with backoff.
  • Each open connection holds one of your plan's concurrent streams until it closes.
  • Errors for one turn (for example voice_not_found) end that turn and leave the connection open.
  • If the connection drops mid-turn, or the server cancels a turn, the turn ends with an error instead of going silent, and the next turn reconnects.
  • A slow first audio (a long first sentence, a busy engine) is still played: the service waits up to 10 s (stop_frame_timeout_s) before giving up on a turn's audio.

API reference: Realtime WebSocket.

Development

uv sync
uv run pytest                    # unit tests against a fake server
FINESSE_LIVE=1 FINESSE_API_KEY=... FINESSE_VOICE_ID=... \
  FINESSE_URL=<non-production realtime URL> \
  uv run pytest tests/test_live.py

License

BSD 2-Clause, the same as Pipecat.

Metadata

Release files for pipecat-finesse 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pipecat-finesse 0.1.0
File Size Uploaded Provenance Actions
pipecat_finesse-0.1.0.tar.gz 10.4 kB Without provenance Details for pipecat_finesse-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pipecat-finesse 0.1.0
File Interpreter ABI Platform Actions
pipecat_finesse-0.1.0-py3-none-any.whl Python 3 none any Details for pipecat_finesse-0.1.0-py3-none-any.whl

Total release size: 21.6 kB

Release files / pipecat_finesse-0.1.0.tar.gz

Download URL pipecat_finesse-0.1.0.tar.gz
Size 10.4 kB
Tags Source
SHA-256 checksum
How to use checksums
43f4e2dc10b7c1b9c04d80f928dfcd791c7650db54c95cfbda9dd20a19372cf1
BLAKE2b-256 checksum
How to use checksums
5104bbf8ea4a94f65501198e992d92ee5231c23e12ccf8dfa09a6fb9bec7ae84
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / pipecat_finesse-0.1.0-py3-none-any.whl

Download URL pipecat_finesse-0.1.0-py3-none-any.whl
Size 11.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
180344019bd6ca08a24e506bba2603224a35b0bc60a4b9d3a39d30f326814392
BLAKE2b-256 checksum
How to use checksums
8526e1fe4f635386c282706ef19b06e18ddfefd820ed273cdfe22a47bcf2b25f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for pipecat-finesse 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page