VonageVideoConnectorTransport

WebRTC transport implementation using Vonage Video API for real-time audio/video communication

Overview

VonageVideoConnectorTransport provides real-time WebRTC audio and video communication using the Vonage Video API. It handles bidirectional media streams, participant management, and session lifecycle events, enabling you to build AI-powered applications that participate in Vonage Video sessions.

The Vonage Video Connector library runs on Linux AMD64 and ARM64 platforms only (Python 3.13+).

VonageVideoConnectorTransport API Reference

Pipecat’s API methods for Vonage Video Connector integration

Example Implementation

Complete Vonage Video Connector voice agent example

Vonage Video API Documentation

Official Vonage Video API documentation and guides

Vonage Dashboard

Sign up for Vonage API access and application management

Installation

To use VonageVideoConnectorTransport, install the required dependencies:

uv add "pipecat-ai[vonage-video-connector]"

The vonage-video-connector extra installs the Vonage Video Connector native library, which is only available on Linux AMD64 and ARM64 with Python 3.13.

Prerequisites

Vonage Account Setup

Before using VonageVideoConnectorTransport, you need:

1. Vonage Account: Sign up at Vonage Dashboard
2. Application: Create a Vonage Video API application in the dashboard
3. Session: Create a Vonage Video session (via the server SDK or REST API)
4. Token: Generate a participant token for the session

The Vonage Video Playground is an easy way to create a session and generate a token for testing — no code required.

Required Environment Variables

• VONAGE_APPLICATION_ID: Your Vonage Video application ID
• VONAGE_SESSION_ID: The ID of the Video API session to join
• VONAGE_TOKEN: A valid participant token for the session

Key Features

• Vonage Video API: Integrate with Vonage’s managed WebRTC infrastructure
• Audio and Video I/O: Bidirectional audio and video streaming
• Participant Management: Stream subscription and participant lifecycle events
• Auto-subscription: Optionally auto-subscribe to incoming audio and video streams
• Interruption Handling: Automatic media buffer clearing on pipeline interruptions

Configuration

VonageVideoConnectorTransport

application_id · str · required

Your Vonage Video API application identifier.

session_id · str · required

The ID of the Vonage Video session to connect to.

token · str · required

A valid participant token for the session.

params · VonageVideoConnectorTransportParams · default: "VonageVideoConnectorTransportParams()"

Transport configuration parameters. See VonageVideoConnectorTransportParams below and TransportParams for inherited base parameters.

VonageVideoConnectorTransportParams

Inherits all parameters from TransportParams (audio, video settings) with these additional fields:

publisher_name · str · default: "\"Bot\""

Display name for the bot’s published stream in the session.

publisher_enable_opus_dtx · bool · default: "False"

Whether to enable Opus Discontinuous Transmission (DTX) for the publisher audio, which reduces bandwidth when no audio is being sent.

session_enable_migration · bool · default: "False"

Whether to enable session migration, allowing the connection to survive network changes.

audio_in_auto_subscribe · bool · default: "True"

Whether to automatically subscribe to incoming audio streams from session participants.

video_in_auto_subscribe · bool · default: "False"

Whether to automatically subscribe to incoming video streams from session participants.

video_in_preferred_resolution · tuple[int, int] · default: "None"

Preferred (width, height) resolution for auto-subscribed video input streams.

video_in_preferred_framerate · int · default: "None"

Preferred framerate for auto-subscribed video input streams.

clear_buffers_on_interruption · bool · default: "True"

Whether to clear media buffers in the Vonage Video Connector when an InterruptionFrame is received. Enable this for conversational AI applications that need to stop playback immediately when the user interrupts; disable it for recording or streaming scenarios where all media should be preserved.

video_connector_log_level · str · default: "\"INFO\""

Log level for the Vonage Video Connector native library. Accepted values: "DEBUG", "INFO", "WARNING", "ERROR".

SubscribeSettings

Used with subscribe_to_stream() to control per-stream subscription quality when audio_in_auto_subscribe or video_in_auto_subscribe are disabled.

subscribe_to_audio · bool · default: "True"

Whether to subscribe to the stream’s audio track.

subscribe_to_video · bool · default: "False"

Whether to subscribe to the stream’s video track.

preferred_resolution · tuple[int, int] · default: "None"

Preferred (width, height) resolution for the subscribed video track. The server provides the closest available quality if the exact resolution is unavailable.

preferred_framerate · int · default: "None"

Preferred framerate for the subscribed video track.

Usage

VonageVideoConnectorTransport connects your Pipecat bot to a Vonage Video session where it can communicate with participants through audio and video streams. The transport handles session joining, stream subscription, and media conversion automatically.

Use pipecat.runner.vonage.configure() to read credentials from environment variables:

from pipecat.runner.vonage import configure
from pipecat.transports.vonage.video_connector import (
    VonageVideoConnectorTransport,
    VonageVideoConnectorTransportParams,
)

(application_id, session_id, token) = await configure()

transport = VonageVideoConnectorTransport(
    application_id,
    session_id,
    token,
    VonageVideoConnectorTransportParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        publisher_name="Bot",
    ),
)

See the complete example for a full implementation including:

• Session credential configuration via environment variables
• Transport setup with audio input and output
• Pipeline integration with an LLM service
• Event handling to trigger the bot when a participant connects

Subscribing to streams manually

When audio_in_auto_subscribe or video_in_auto_subscribe is disabled, subscribe to a specific participant’s stream with subscribe_to_stream(), passing SubscribeSettings to control which tracks are received and at what quality. The streamId is available from the on_participant_joined event data.

from pipecat.transports.vonage.video_connector import SubscribeSettings

await transport.subscribe_to_stream(
    stream_id="participant_stream_id",
    params=SubscribeSettings(
        subscribe_to_audio=True,
        subscribe_to_video=True,
        preferred_resolution=(1280, 720),
        preferred_framerate=30,
    ),
)

Event Handlers

VonageVideoConnectorTransport provides event handlers for session lifecycle, participant stream management, and subscriber connectivity. Register handlers using the @event_handler decorator on the transport instance.

Events Summary

Event	Description
on_joined	Bot joined the Vonage session
on_left	Bot left the Vonage session
on_error	Transport error occurred
on_first_participant_joined	First participant stream joined the session (sync)
on_participant_joined	A participant stream joined the session (sync)
on_participant_left	A participant stream left the session
on_client_connected	Transport connected to a participant’s stream (sync)
on_client_disconnected	Transport disconnected from a participant’s stream

Session Lifecycle

on_joined

Fired when the bot successfully connects to the Vonage Video session.

@transport.event_handler("on_joined")
async def on_joined(transport, data):
    print(f"Joined session: {data['sessionId']}")

Parameters:

Parameter	Type	Description
transport	VonageVideoConnectorTransport	The transport instance
data	dict	Event data containing sessionId

on_left

Fired when the bot disconnects from the Vonage Video session.

@transport.event_handler("on_left")
async def on_left(transport, data):
    print(f"Left session: {data['sessionId']}")

Parameters:

Parameter	Type	Description
transport	VonageVideoConnectorTransport	The transport instance
data	dict	Event data containing sessionId

on_error

Fired when a transport-level error occurs.

@transport.event_handler("on_error")
async def on_error(transport, error):
    print(f"Transport error: {error}")

Parameters:

Parameter	Type	Description
transport	VonageVideoConnectorTransport	The transport instance
error	str	Error description

Participants

on_first_participant_joined

Fired when the first participant stream is received in the session. Commonly used to trigger the bot’s initial response.

@transport.event_handler("on_first_participant_joined")
async def on_first_participant_joined(transport, data):
    print(f"First participant joined stream: {data['streamId']}")
    await task.queue_frames([LLMRunFrame()])

Parameters:

Parameter	Type	Description
transport	VonageVideoConnectorTransport	The transport instance
data	dict	Event data containing sessionId, streamId, and connectionData

This is a synchronous event — the session will not proceed until all handlers complete. Keep handlers fast.

on_participant_joined

Fired when any participant stream is received in the session.

@transport.event_handler("on_participant_joined")
async def on_participant_joined(transport, data):
    print(f"Participant joined stream: {data['streamId']}")

Parameters:

Parameter	Type	Description
transport	VonageVideoConnectorTransport	The transport instance
data	dict	Event data containing sessionId, streamId, and connectionData

This is a synchronous event — the session will not proceed until all handlers complete. Keep handlers fast.

Both on_first_participant_joined and on_participant_joined fire for the first stream. Use on_first_participant_joined if you only need to react once.

on_participant_left

Fired when a participant’s stream is dropped from the session.

@transport.event_handler("on_participant_left")
async def on_participant_left(transport, data):
    print(f"Participant left stream: {data['streamId']}")

Parameters:

Parameter	Type	Description
transport	VonageVideoConnectorTransport	The transport instance
data	dict	Event data containing sessionId, streamId, and connectionData

Subscribers

on_client_connected

Fired when the transport successfully connects to a participant’s stream — at this point the subscription is established and media is flowing.

@transport.event_handler("on_client_connected")
async def on_client_connected(transport, data):
    print(f"Client connected to stream: {data['streamId']}")
    await task.queue_frames([LLMRunFrame()])

Parameters:

Parameter	Type	Description
transport	VonageVideoConnectorTransport	The transport instance
data	dict	Event data containing subscriberId, streamId, and connectionData

This is a synchronous event — the session will not proceed until all handlers complete. Keep handlers fast.

on_client_disconnected

Fired when the transport disconnects from a participant’s stream, either due to an explicit unsubscription or a connection drop.

@transport.event_handler("on_client_disconnected")
async def on_client_disconnected(transport, data):
    print(f"Client disconnected from stream: {data['streamId']}")

Parameters:

Parameter	Type	Description
transport	VonageVideoConnectorTransport	The transport instance
data	dict	Event data containing subscriberId, streamId, and connectionData

Additional Resources

• Events Overview - Overview of all events in Pipecat
• TransportParams - Base transport parameters reference