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, orHTTP 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.