Vonage WebRTC Transport Integration

[asilvestre]

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

This pull request introduces a new transport integration for Vonage WebRTC sessions using the Vonage Video Connector library.

These are some documentation references:

• Video Connector library docs: https://developer.vonage.com/en/video/guides/vonage-video-connector.
• Pipecat integration of Vonage Video Connector docs: https://developer.vonage.com/en/video/guides/vonage-video-connector-pipecat-transport

Overview of changes in this PR:

• Transport files are included insrc/pipecat/transports/vonage
• Extensive unit test coverage is added in tests/test_vonage_video_connector.py
• A new foundational example is added in the file 04c-transports-vonage-video-connector.py
• There are some modifications in the src/pipecat/runner module to allow using this new transport in other examples.

[jamsea]

I'm going to try this out locally 👀

[jamsea]

Hi @asilvestre is there anyway to run this on macOS? The vonage-video-connector package is gated to Python 3.13 on Linux only. 🤔

[Copilot]

Pull request overview

Adds a new Vonage WebRTC transport integration (via the Vonage Video Connector SDK) so Pipecat pipelines can join Vonage sessions, publish audio/video, subscribe to participant streams, and surface session/participant lifecycle events through the runner and examples.

Changes:

• Introduces pipecat.transports.vonage implementation (VonageClient, input/output transports, utilities for audio + colorspace conversion).
• Extends the runner to support -t vonage and adds Vonage env configuration helpers.
• Adds a comprehensive Vonage-focused unit test suite and a new foundational example.

Reviewed changes

Copilot reviewed 11 out of 13 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/pipecat/transports/vonage/client.py	Core Vonage SDK client wrapper: connect/disconnect/publish/subscribe, callback plumbing, audio/video processing.
src/pipecat/transports/vonage/video_connector.py	Pipecat BaseTransport implementation exposing input/output processors + event handlers.
src/pipecat/transports/vonage/utils.py	Audio normalization helpers and image colorspace conversion utilities.
src/pipecat/transports/vonage/__init__.py	Package marker for the new transport module.
src/pipecat/runner/vonage.py	Loads Vonage session config from environment variables.
src/pipecat/runner/types.py	Adds VonageRunnerArguments for runner integration.
src/pipecat/runner/utils.py	Adds Vonage-aware client-id extraction, camera capture subscription, and transport creation support.
src/pipecat/runner/run.py	Adds CLI transport choice vonage and direct-run entrypoint.
tests/test_vonage_video_connector.py	New unit tests for the Vonage client, transports, and utility functions (with SDK mocking).
examples/foundational/04c-transports-vonage-video-connector.py	Foundational example showing Vonage transport usage with AWS Nova Sonic.
examples/foundational/README.md	Documents running foundational examples with Vonage env vars and -t vonage.
env.example	Adds Vonage environment variables to the example env file.
pyproject.toml	Adds optional dependency group vonage-video-connector.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[asilvestre]

Hi @asilvestre is there anyway to run this on macOS? The vonage-video-connector package is gated to Python 3.13 on Linux only. 🤔

Thanks a lot @jamsea for looking into this. Indeed this transport only works on Linux.

I'll share my macOS setup to run the vonage transport foundational example using docker in case it's useful:

Dockerfile

FROM python:3.13-slim-bookworm AS base

# Dependencies
RUN apt-get update \
  && apt-get upgrade -y \
  && apt-get install -y \
     libexpat1 \
     libglib2.0-0 \
  && apt-get clean \
  && rm -rf /var/lib/apt/lists/*

RUN pip install uv

$> docker build -f Dockerfile-minimal -t pipecat-test .

From a pipecat checkout

$> docker run --rm -ti -v $PWD:/pipecat pipecat-test bash -c 'cd /pipecat && uv sync --group dev --all-extras --no-extra gstreamer --no-extra krisp --no-extra local && cd examples/foundational/ &&  uv run 04c-transports-vonage-video-connector.py -t vonage'

[jamsea]

Hi @asilvestre!

I'm having trouble getting this working, is the way I'm testing this wrong? I checked the chrome console and I can see I'm publishing audio, but it looks like the vonage agent doesn't see it:

Video: https://www.loom.com/share/e37a2076909043ba94853025fdde8174

vonage-logs.txt

[asilvestre]

Hi @asilvestre!

I'm having trouble getting this working, is the way I'm testing this wrong? I checked the chrome console and I can see I'm publishing audio, but it looks like the vonage agent doesn't see it:

Video: https://www.loom.com/share/e37a2076909043ba94853025fdde8174 vonage-logs.txt

Hi @jamsea! Thanks again.

I think the issue here were the AWS credentials, for some reason the AWS nova sonic service is very silent when there is an authentication issue. One tell we found when this is the issue are these logs when shutting down Pipecat:

2026-04-24 06:32:10.853 | DEBUG    | pipecat.pipeline.runner:run:95 - Runner PipelineRunner#0 finished running PipelineTask#0
Exception ignored in: <class 'concurrent.futures._base.InvalidStateError'>
Traceback (most recent call last):
  File "/pipecat/.venv/lib/python3.13/site-packages/awscrt/aio/http.py", line 312, in _on_complete
    future.set_result("")
  File "/usr/local/lib/python3.13/concurrent/futures/_base.py", line 544, in set_result
    raise InvalidStateError('{}: {!r}'.format(self._state, self))
concurrent.futures._base.InvalidStateError: CANCELLED: <Future at 0xffff2066a550 state=cancelled>

If you want an example that doesn't have the AWS nova sonic dependency here is the example modified to just be an audio echo server:
04c-transports-vonage-video-connector.py

Let me know if you want more examples showing different capabilities.

Finally, even though not related to the root cause, we see there's some occasional CPU usage contention (the audio thread complains about long ticks), it would be good to ensure your docker system has at least 2 cores and 1-2 GiB of memory available for containers.

[asilvestre]

btw @jamsea I have ready a commit to bring this PR in sync with main, I haven't pushed it yet to avoid disrupting your current setup testing this branch but let me know if you want me to push it

[jamsea]

@asilvestre i think you're right, I made a note to have the AWS processor throw an error or something in this case. Push your commit when you get a chance and I'll wrap this up Monday 🙏