DEV Community: Rehan Sanjay Venkatesan

I measured what jambonz actually sends on a websocket, instead of reading the docs

Rehan Sanjay Venkatesan — Tue, 20 Oct 2026 13:42:10 +0000

Pipecat ships transport serializers for Twilio, Telnyx, Plivo, Exotel, Vonage and Genesys. A developer choosing a phone layer has six options, and jambonz — open source, self-hostable, already capable of forking call audio to a websocket — isn't one of them.

So I wrote it. This post is about the part before the code: finding out what the socket actually does.

Three things I couldn't look up

A FrameSerializer in Pipecat is two methods. serialize turns a Pipecat frame into something to write to the socket; deserialize turns a socket message into a frame. To write either I needed to know:

What sample rate does jambonz actually send? The listen verb takes a sampleRate. Does it honour it?
Is the framing stable? That decides whether deserialize needs a variable-length path.
Does control data share the socket with audio? This is the one that changes the shape of the class. Exotel base64s audio into JSON events, so everything is one stream of JSON. If jambonz interleaves JSON control frames with raw binary audio, deserialize has to branch on every message.

None of these are in jambonz's docs or Pipecat's. I had an assumption about the first one and I'd already written it into a public README. It was wrong.

The probe

Rather than reason about it, I wrote about 120 lines of aiohttp with two endpoints.

POST / is the call hook — jambonz asks it what to do, and it answers with a single listen verb pointing back at the websocket:

verbs = [{
    "verb": "listen",
    "url": ws_url,
    "mixType": "mono",
    "sampleRate": SAMPLE_RATE,
    "bidirectionalAudio": {"enabled": True, "streaming": True, "sampleRate": SAMPLE_RATE},
}]

GET /ws receives the forked audio and, crucially, describes it rather than interprets it: how big each frame is, whether the size is stable, whether any TEXT frames arrive, and the byte total divided by the rate we asked for, against wall clock.

That last ratio is the whole point. If I ask for 16 kHz and 30 seconds of wall clock produces 30 seconds of implied audio, the rate is right. If it produces 15, the real rate is half what I asked for.

Then: ngrok, point a jambonz application at it, dial from a softphone, talk for thirty seconds, hang up.

What came back

binary frames : 1514
total bytes   : 968960
frame sizes   : [640]
text frames   : 1
wall clock    : 30.03s
audio implied : 30.28s at 16000 Hz, 16-bit mono
ratio         : 1.01

The rate the verb asks for is the rate that arrives. Ratio 1.01 across thirty seconds. My assumption had been that jambonz forks at 8 kHz — I'd written that in a public README and it was wrong by a factor of two. It forks at whatever sampleRate the verb set, and the default is 16 kHz.

Framing is fixed at 20 ms. One distinct frame size across 1514 frames: 640 bytes, which is 320 samples of 16-bit mono, which is exactly 20 ms at 16 kHz. No variable-length path needed.

And the third question had a better answer than I expected. Exactly one TEXT frame arrives, before any audio, and then the socket is pure binary for the rest of the call:

{"sampleRate":16000,"mixType":"mono","callSid":"3e5d869a-…",
 "direction":"inbound","from":"…","to":"…","sipStatus":200,
 "callStatus":"in-progress","traceId":"…"}

It's a preamble, not a channel. So deserialize doesn't branch per frame. It reads one metadata frame at the start and treats everything after it as L16 PCM.

What that does to the design

The sample rate should be read from the wire, not configured. My first spec said the verb and the serializer "have to agree" on a rate. They don't have to — the socket states it. A params field can still override for a narrowband carrier, but the default is to believe the connection. A narrowband call at 8 kHz then needs no code change at all.

I also left it deliberately unset until the preamble arrives, rather than defaulting to 16000. A connection with no preamble then drops audio with a warning, instead of resampling from a rate that was never negotiated — which on a narrowband call produces audio that sounds almost right, and that is the worst kind of wrong.

The preamble carries callSid and traceId for free. That's enough to correlate a Pipecat session with a jambonz call in logs, without threading identifiers through the verb's URL.

And interruptions can't just stop. jambonz has killAudio, which flushes playing and buffered audio. But I asked about the race in the jambonz community Slack and got this from Sam Machin:

the ordering of messages on the socket isn't 100% we've seen clients that sometimes prioritise smaller messages so its best to have a small break after a killAudio before you send the next stream, 50-100ms should be plenty

So a frame written in the same instant as the flush can land after it and play over the caller. Pipecat's interruption model lets a processor stop; over jambonz it has to stop and wait. There's nowhere upstream to put that, so the serializer holds the frames itself for 100 ms — and discards them rather than queueing, because they belong to the turn the caller just interrupted and arriving late is worse than not arriving.

A gotcha worth the whole post

I wrote the tests before the serializer, from the measurements. Three of them failed against correct code.

Pipecat's create_stream_resampler does not emit one chunk per chunk. It buffers and flushes in bursts:

chunk 1: in 640 -> out 0
chunk 2: in 640 -> out 0
chunk 3: in 640 -> out 0
chunk 4: in 640 -> out 3300

Three empty returns, then everything at once. My tests assumed one frame in, one frame out — so serialize returning None looked like a bug when it was the correct answer. Over twenty frames the throughput settles to about 86% of the arithmetic ideal, the rest being the tail still held in the buffer.

If you write a serializer for any transport, don't assert a byte count per call. Pump a run of frames and assert on the total, which is what a real call does anyway.

The thing I'd take away

I got the sample rate wrong by assuming, and it reached a public README. I got the test shape wrong by assuming, and it failed against working code. The protocol questions that mattered were all answered in thirty seconds of one phone call and about 120 lines of throwaway code.

Writing the probe felt like a detour from writing the serializer. It wasn't — it was the serializer. Everything after it was transcription.

The probe, the measurements and the spec:
https://github.com/Rehansanjay/jambonz-bridge

The serializer, in review upstream:
https://github.com/pipecat-ai/pipecat/pull/6112

My tool called a maintainer's plugin broken. They had fixed it two weeks earlier.

Rehan Sanjay Venkatesan — Tue, 20 Oct 2026 13:30:47 +0000

For about a month I've had a nightly job that installs every community-maintained plugin listed in Pipecat's docs into a fresh environment, imports it, and checks that every service class it defines can still be constructed. It publishes a table: works, broken, pinned to an old version, can't install.

It installs from PyPI, because that's what a user gets.

In late September I opened a pull request against one of the red ones — pipecat-boson, failing on an import that pipecat moved in 1.8. It sat for a fortnight, and by the time anyone looked at it the maintainer had landed their own fix, so mine was closed. Fair enough; theirs is better than mine was:

try:
    from pipecat.utils.types import assert_given, is_given
except ImportError:  # pipecat-ai < 1.8.0
    from pipecat.services.settings import assert_given, is_given

That landed on 30 September. PyPI still serves the version published before it. So for more than two weeks my dashboard printed a red row, with their project's name on it, for code that was already correct.

The check wasn't buggy. It answered exactly the question I wrote it to answer. The question was wrong.

"Broken" was doing two jobs

There are two different sentences hiding in one red row:

Your users are getting a package that doesn't work. True for Boson. Still true today.
Your code is broken. False for Boson, and false for two weeks.

The first is the user's question and the wheel answers it. The second is the maintainer's question, and the wheel cannot answer it at all — a wheel is a snapshot of a repository at some past moment, and nothing says how far behind that moment is.

This matters more than tidiness, because the two sentences imply different actions. "Your code is broken" asks for a patch. "Your users are getting a broken package" asks for a release. If you only ever send the first one, you're asking people to redo work they've already done, and the thing that would actually help their users never gets mentioned.

So the checker now asks both. When the released version fails, it installs the plugin's own source from its repository, pinned to the commit under test, and probes that too. A plugin whose source imports and constructs gets a new status — fixed, not released — which keeps the released failure alongside it and names the commit that passed.

Finding the repository is the hard part

I assumed this would be a lookup. PyPI has project_urls. You read Repository, you clone it, done.

pipecat-boson declares nothing. No Homepage, no Repository, no project_urls at all. Its repository appears in exactly one place in the entire package metadata: a git clone line in the README body.

And then there's this one, which is worse:

Homepage      https://github.com/your-username/pipecat-firered-vad
Repository    https://github.com/your-username/pipecat-firered-vad
Bug Tracker   https://github.com/your-username/pipecat-firered-vad/issues
Changelog     https://github.com/your-username/pipecat-firered-vad/releases

All four published URLs are a template placeholder that was never filled in. Anyone who installs that package and hits a problem follows the Bug Tracker link to a 404. Their bug report doesn't go to the wrong place — it goes nowhere, and the maintainer never learns the report existed. There's no route from the package page back to the repository either. I only found the real one because the install error happened to name the dependency.

So resolution reads the metadata first and falls back to scanning the README. That gets 58 of 67, and every plugin that's currently failing.

If you maintain a published package: go and look at your own project_urls right now. It takes ten seconds and the failure mode is silent.

The guard matters more than the feature

Here's the part I'd want to read if someone else wrote this.

pipecat-supertonic resolves to supertone-inc/supertonic — the vendor's own text-to-speech model repository, thirteen thousand stars — because the two names share a word. The plugin actually lives somewhere else entirely.

That particular one fails to install, so it reports unknown either way and I got lucky. But a wrong repository that happened to be pip-installable and to import cleanly would have promoted the plugin to "fixed, not released" on the strength of a completely unrelated codebase, and published that claim under a maintainer's name.

The fix is that the source build has to produce the distribution the plugin actually is, normalised per PEP 503, or the answer is unknown:

expected = {_canonical(project_name(spec)) for spec in plugin.specs if project_name(spec)}
built = {_canonical(dist.split("==")[0]) for dist in probe.get("distributions") or []}
if expected and not expected & built:
    return {"source": "unknown", "source_reason": "that repository does not build " + ...}

Measuring something in public means you can be wrong about it in public. The guards are the work, not the measurement.

What it found, versus what I expected

I expected a pile of these. My assumption going in was that several vendors had quietly merged fixes without cutting releases, which would have given me a stack of genuinely welcome messages to send — your fix is merged, your users still get the broken wheel, a release closes it. Nobody minds receiving that.

Thirteen plugins currently fail. Rebuilt from their own source:

	count
Still broken when built from source	8
Fixed in source, stale on PyPI	1
Couldn't be read, reported `unknown`	4

One. Not a stack.

And the harder number: zero of the nine vendors has fixed their own plugin. I read the HEAD of each repository to check. Two of them looked fixed and were my own false positives — one still imports the removed name from the old path, and the other still uses a frame class that was renamed, which my first grep matched as a substring of the new name.

So the thing I built to find a pile of easy wins found one, and mostly confirmed that the plugins are broken in source too. That's a worse story and a more useful tool.

The one that gained something real

One plugin isn't on PyPI at all under the name its documentation publishes. For a month its row said can't install, with no diagnosis, because there was nothing to install and therefore nothing to diagnose.

Built from source, it produces a real one — the same import failure as the others.

That's the part I'd keep if I could only keep one thing. For a package that was never published, the source isn't a second opinion. It's the only place its state exists at all.

The checker, the full table and the nightly results:
https://github.com/Rehansanjay/pipecat-plugin-health

If you maintain a plugin for a fast-moving framework, I'd genuinely like to know whether you run CI against its main — and if not, whether it's because nobody asked.

I sent the fixes. A month later, none of them have merged.

Rehan Sanjay Venkatesan — Sat, 17 Oct 2026 12:41:53 +0000

A few weeks ago I published a count: of the community plugins listed in Pipecat's docs, 18 of 56 didn't work. Broken imports, missing dependencies, version pins dragging Pipecat backwards a year.

I also said I'd send PRs for the ones I could fix from outside, and I did — eleven of them, across eleven repositories.

Here is what has happened since. It is not the post I expected to write, and the most useful part came from a reader rather than from me.

The eleven PRs

Every one is still open. Every one is mergeable, not a draft, with no conflicts and nothing red.

29d  ImportError on pipecat >= 1.8        no response
29d  ImportError on pipecat >= 1.8        no response
28d  ImportError on pipecat >= 1.8        1 comment
28d  ImportError on pipecat >= 1.8        no response
28d  ImportError on pipecat >= 1.8        no response
28d  ImportError on pipecat >= 1.8        no response
28d  accept 1.11 patch releases           no response
28d  ImportError on pipecat >= 1.8        no response
22d  InterruptionFrame rename             1 review
22d  LLM context frames removed in 1.8    no response
16d  allow 1.11 and 1.12                  no response

Nine of eleven have had no human response at all. Nothing has merged.

I want to be careful about what that does and doesn't mean. A community plugin is usually one engineer inside a vendor, with a roadmap that isn't this. An unreviewed PR from a stranger is one of the easiest things in the world to not get to, and none of these repositories owes me anything. I'm reporting the number because the number is the finding, not because anybody behaved badly.

Then a reader checked my arithmetic

Arhan Canli commented on the first post within a few hours, and he was right about something I'd got wrong:

The pinned five are the only group where nothing has been shown to be broken. A plugin pinned to ==1.8.1 fails to resolve, but it may run fine on 1.12.

My headline number lumped together plugins that fail and plugins that merely won't resolve. Those are completely different messages to send a maintainer: one says "your plugin is broken", the other says "loosen a version range."

He also handed me the test:

Install the five with --no-deps next to the current pipecat-ai, then run the same import and construct step. Any that pass are "pin too tight". Any that fail are real API breaks hiding behind the pin.

So I ran it.

All five were fine

Deepdub   pinned >=0.0.97,<0.1.0   ->  compatible
Maya      pinned ==1.8.1           ->  compatible
Memcode   pinned >=1.10,<1.11      ->  compatible
Oruk      pinned >=1.8.1,<1.9      ->  compatible
Wavix     pinned ==0.0.105         ->  compatible

Every one imports and constructs against pipecat 1.12. Zero are broken. Five one-line edits to a version range would turn five red rows green, and not one of them needs a code change.

His method needed one adjustment, which is worth passing on. --no-deps also skips the plugin's own SDK, so two of the five came back unknown — not because of pipecat, but because their vendor package wasn't installed either. uv's --overrides is the sharper tool: the plugin resolves with all its real dependencies and only pipecat-ai is forced to the version under test. That's the question actually being asked, and it turned both unknowns into answers.

And a second thing I was getting wrong

Once I was looking properly, one more row didn't belong.

One plugin imports a vendor SDK that its own README says is not published to PyPI — you contact the company, get a wheel and an API key. Its packaging correctly omits the dependency, because you can't declare one that's on no index.

That plugin isn't broken. It works for that vendor's customers. It just can't be verified by a checker standing outside the licence — and listing it as "broken" next to nine plugins genuinely broken by an upstream rename put the blame in the wrong place.

It has its own status now. The checker asks PyPI whether the missing module exists at all, and only calls it gated when the answer is a definite no — a network failure leaves it broken, because reading "I couldn't ask" as "it doesn't exist" would quietly reclassify real breakage as licensing.

So the honest number

	First post	Today
Plugins listed	56	67
Genuinely broken	"18"	13
— failing on import	10	9
— can't be installed	3	3
— partially broken	1	1
Works, but pin blocks it	counted as broken	5
Works, needs a licensed SDK	counted as broken	1

I published 18 of 56. The defensible figure was never that. Six of the plugins I called broken were working the whole time, and it took a stranger five hours to notice something I'd had weeks to check.

What I got wrong, twice

The first write-up assumed the problem was that nobody was looking. Build the checker, publish the list, send the patches, and the table should start going green.

It didn't. The information existed, the fixes sat one click away, and the count stayed flat. So the gap isn't detection and it isn't authorship — it's that a community plugin has no owner whose job it is to notice. Upstream has correctly delegated it. The vendor shipped it and moved on. The user who hits the ImportError silently picks a different vendor, which is the one signal that would prompt a fix and the one signal nobody receives.

The second thing I got wrong was subtler and more embarrassing: I built a tool to measure an ecosystem and then didn't interrogate my own categories. "Broken" was doing three jobs — actually broken, won't resolve, and licensed — and I shipped a headline number built on all three.

If you publish a measurement, someone will check it. That's the best thing that can happen to it.

Things that might close the loop

I'd rather end with open questions than a fake conclusion.

CI against upstream main in the plugin repo. One scheduled workflow, and the break shows up as a red build where it can be fixed. The obvious answer, and almost nobody does it.
A health badge on the docs page. Puts the signal where the user actually looks, at the cost of whoever maintains the page.
Nothing. It's genuinely possible that a long tail of half-maintained integrations is the normal cost of a fast-moving framework, and users routing around it is the system working rather than failing.

If you maintain a plugin for any fast-moving framework, I'd like to know whether you run CI against its main, and if not, why not. My guess is "nobody asked and it wasn't obvious", which would be a very fixable reason.

The checker, the full table and the nightly results:
https://github.com/Rehansanjay/pipecat-plugin-health

I installed all 67 Pipecat community plugins. 19 of them don't work.

Rehan Sanjay Venkatesan — Tue, 13 Oct 2026 20:23:15 +0000

Pipecat's docs list every community-maintained plugin on one page: speech-to-text, text-to-speech, serializers, VAD, analytics, transports. Pick a vendor, pip install, follow the snippet.

For 19 of the 67 listed this morning, that doesn't work. The install fails, or the import raises, or the package pins a version of Pipecat from a year ago and quietly drags your whole environment backwards.

Nobody is hiding this. It's just that nothing was checking.

What the checker does

Every night, for each plugin on the supported-services page:

Create a fresh environment.
Install the plugin together with the latest pipecat-ai release on PyPI — what a new user gets today.
Do it again against pipecat-ai main — what users get in the next release.
Import the plugin and construct every Pipecat service class it defines.

No API keys are used anywhere, so this doesn't test whether a provider's servers answer. It tests the part that breaks far more often: install, import, and API shape — renamed or removed Pipecat symbols, new abstract methods, version pins.

The plugin list is re-read from the docs on every run, so new plugins are picked up automatically. That matters: the page had 56 entries three weeks ago and has 67 today.

Results from this morning's run, against pipecat-ai 1.12.0:

Status	Count
Works	48
Partial	1
Broken on import	10
Pinned to an older Pipecat	5
Can't be installed at all	3

The failures cluster, and that's the interesting part

Six plugins die on the same line. In Pipecat 1.8 the settings sentinel _NotGiven was removed from pipecat.services.settings — it's NotGiven in pipecat.utils.types now. Six plugins still import the old name, so they raise before doing anything else:

ImportError: cannot import name '_NotGiven' from 'pipecat.services.settings'

Six different companies, six separate repositories, one upstream rename. Each fix is a single import line.

Three more broke on renamed frames. One imports StartInterruptionFrame, another LLMMessagesFrame, another assert_given — none of which exist under those names any more.

Two are missing their own dependency. The plugin expects a vendor SDK that isn't installable from where it looks for it.

Five pin Pipecat backwards. One requires pipecat-ai>=0.0.97,<0.1.0. Another wants ==0.0.105. A third pins ==1.8.1 exactly. These don't error — which is worse. Your resolver silently downgrades Pipecat, or refuses to solve, and the reason isn't obvious from the traceback you eventually get.

Three can't be installed at all. Two checkouts have neither a pyproject.toml nor a setup.py, so there's nothing to install. One isn't on PyPI under the name the docs use.

This is not upstream's fault

It would be easy to read the _NotGiven cluster as Pipecat breaking its ecosystem. It isn't.

The 1.8.0 changelog flagged the change with a ⚠️ and spelled out the migration:

NOT_GIVEN, NotGiven, is_given() and assert_given() now come from pipecat.utils.types and are no longer importable from pipecat.services.settings. The private pipecat.services.settings._NotGiven is now the public pipecat.utils.types.NotGiven.

They announced it, named the destination, and were right that the old name was private — plugin authors were importing an underscore-prefixed symbol out of someone else's module, which was always going to be fragile.

The supported-services page is equally clear about ownership: community plugins are distributed separately and issues go to their own repositories.

So upstream did the things you'd ask for. The breakage happened anyway.

Why it keeps happening

Community plugins live in their own repositories, usually maintained by one engineer at the vendor. Pipecat ships often and moves fast, which is a virtue. But a plugin repo has no CI that installs against Pipecat main, so an upstream rename doesn't produce a red build anywhere — it produces a broken install six weeks later, for a user who has no relationship with either party and will simply choose a different vendor.

That's the gap: the breakage is public, deterministic and cheap to detect, and there was no place where anyone looked at all of them at once.

It measures recovery too

Between two runs in September, one plugin loosened its pin and moved from "needs older Pipecat" to "works". That's the part I didn't expect to enjoy: the table isn't a wall of shame, it's a live picture. Anything on it can move, and most of these are one line away from moving.

Running against main as well as the current release is deliberate, and it's the part I'd most like vendors to use. A plugin that breaks against main today has until the next Pipecat release to fix it, rather than finding out from an issue after the fact.

If you're choosing a plugin

Check the pin before you check the features. Four of the five pinned plugins will silently downgrade Pipecat in your environment rather than fail, and you'll debug it as something else entirely.
An import test is a five-second question. python -c "import pipecat_<name>" in a fresh environment tells you more than a README.
Check when the repo last moved. All ten broken plugins have been broken since late August. That's visible from the outside before you commit.

I've been sending the fixes

Rather than just publishing a list, I opened PRs for the ones I could fix from outside — eleven of them across eleven repositories.

What happened next is its own post, and it isn't the happy ending: three weeks on, none of them have merged. I'll write that one up separately, because the result surprised me more than the original findings did.

The repo, with the full table and the nightly results:
https://github.com/Rehansanjay/pipecat-plugin-health

If your plugin is on the broken list and you'd rather have a PR than a bug report, say so and I'll send one.