Skip to main content
Finesse by Flam: text-to-speech plugin for Pipecat

PyPI version Python 3.11+ Pipecat 1.12+ Status: beta License: BSD-2-Clause

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.

Contributing

See CONTRIBUTING.md for setup, the checks CI runs, and live tests.

License

BSD 2-Clause, the same as Pipecat.

Metadata

Release files for pipecat-finesse 0.1.1

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.1
File Size Uploaded Provenance Actions
pipecat_finesse-0.1.1.tar.gz 10.7 kB Without provenance Details for pipecat_finesse-0.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 22.2 kB

Release files / pipecat_finesse-0.1.1.tar.gz

Download URL pipecat_finesse-0.1.1.tar.gz
Size 10.7 kB
Tags Source
SHA-256 checksum
How to use checksums
c98d52b19d3f2f5fe7248fb9eed515f8fa646d4f1c5faaecc74628b2d7732179
BLAKE2b-256 checksum
How to use checksums
e80f0386e6cf874dc79fa76a2dbfe54211984e2a051195c79ecbe23f2d7c48a6
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.1-py3-none-any.whl

Download URL pipecat_finesse-0.1.1-py3-none-any.whl
Size 11.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d0ac0f86009b50759d5ecb24fc6d9af6559a2a01675f5b4abe18f8607784e235
BLAKE2b-256 checksum
How to use checksums
1be641088d060c787f959663d8bef5a806dc6d684a3a472f452f6e57dad45fda
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.1

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.1 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