Skip to content

Commit 366add2

Browse files
markbackmanmarkbackman
authored
Merge pull request pipecat-ai#1878 from pipecat-ai/mb/add-plivo-serializer
Add PlivoFrameSerializer
2 parents 2a6c01f + e13c9fd commit 366add2

File tree

10 files changed

+761
-12
lines changed

10 files changed

+761
-12
lines changed

‎CHANGELOG.md‎

Lines changed: 16 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1111

1212
- Added `GoogleHttpTTSService` which uses Google's HTTP TTS API.
1313

14-
- Added `TavusTransport`, a new transport implementation compatible with any
15-
Pipecat pipeline. When using the `TavusTransport`the Pipecat bot will
14+
- Added `TavusTransport`, a new transport implementation compatible with any
15+
Pipecat pipeline. When using the `TavusTransport`the Pipecat bot will
1616
connect in the same room as the Tavus Avatar and the user.
1717

18+
- Added `PlivoFrameSerializer` to support Plivo calls. A full running example
19+
has also been added to `examples/plivo-chatbot`.
20+
1821
- Added `UserBotLatencyLogObserver`. This is an observer that logs the latency
1922
between when the user stops speaking and when the bot starts speaking. This
2023
gives you an initial idea on how quickly the AI services respond.
@@ -36,8 +39,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
3639
correspond to the `StartFrame`, `StopFrame`, `EndFrame` and `CancelFrame`
3740
respectively.
3841

39-
- Added additional languages to `LmntTTSService`. Languages include: `hi`, `id`,
40-
`it`, `ja`, `nl`, `pl`, `ru`, `sv`, `th`, `tr`, `uk`, `vi`.
42+
- Added additional languages to `LmntTTSService`. Languages include: `hi`,
43+
`id`, `it`, `ja`, `nl`, `pl`, `ru`, `sv`, `th`, `tr`, `uk`, `vi`.
4144

4245
- Added a `model` parameter to the `LmntTTSService` constructor, allowing
4346
switching between LMNT models.
@@ -75,8 +78,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7578
```
7679

7780
By default, Pipecat has implemented service decorators to trace execution of
78-
STT, LLM, and TTS services. You can enable tracing by setting `enable_tracing`
79-
to `True` in the PipelineTask.
81+
STT, LLM, and TTS services. You can enable tracing by setting
82+
`enable_tracing` to `True` in the PipelineTask.
8083

8184
- Added `TurnTrackingObserver`, which tracks the start and end of a user/bot
8285
turn pair and emits events `on_turn_started` and `on_turn_stopped`
@@ -86,13 +89,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
8689

8790
### Changed
8891

89-
- Updated `GoogleTTSService` to use Google's streaming TTS API. The default voice also updated to `en-US-Chirp3-HD-Charon`.
92+
- Updated `GoogleTTSService` to use Google's streaming TTS API. The default
93+
voice also updated to `en-US-Chirp3-HD-Charon`.
9094

91-
- ⚠️Refactored the `TavusVideoService`, so it acts like a proxy, sending audio to
92-
Tavus and receiving both audio and video. This will make `TavusVideoService` usable
93-
with any Pipecat pipeline and with any transport. This is a **breaking change**,
94-
check the `examples/foundational/21a-tavus-layer-small-webrtc.py` to see how to
95-
use it.
95+
- ⚠️ Refactored the `TavusVideoService`, so it acts like a proxy, sending audio
96+
to Tavus and receiving both audio and video. This will make
97+
`TavusVideoService` usable with any Pipecat pipeline and with any transport.
98+
This is a **breaking change**, check the
99+
`examples/foundational/21a-tavus-layer-small-webrtc.py` to see how to use it.
96100

97101
- `DailyTransport` now uses custom microphone audio tracks instead of virtual
98102
microphones. Now, multiple Daily transports can be used in the same process.

‎examples/plivo-chatbot/.gitignore‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# Byte-compiled / optimized / DLL files
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
6+
# C extensions
7+
*.so
8+
9+
# Distribution / packaging
10+
.Python
11+
build/
12+
develop-eggs/
13+
dist/
14+
downloads/
15+
eggs/
16+
.eggs/
17+
lib/
18+
lib64/
19+
parts/
20+
sdist/
21+
var/
22+
wheels/
23+
share/python-wheels/
24+
*.egg-info/
25+
.installed.cfg
26+
*.egg
27+
MANIFEST
28+
29+
# PyInstaller
30+
# Usually these files are written by a python script from a template
31+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
32+
*.manifest
33+
*.spec
34+
35+
# Installer logs
36+
pip-log.txt
37+
pip-delete-this-directory.txt
38+
39+
# Unit test / coverage reports
40+
htmlcov/
41+
.tox/
42+
.nox/
43+
.coverage
44+
.coverage.*
45+
.cache
46+
nosetests.xml
47+
coverage.xml
48+
*.cover
49+
*.py,cover
50+
.hypothesis/
51+
.pytest_cache/
52+
cover/
53+
54+
# Translations
55+
*.mo
56+
*.pot
57+
58+
# Django stuff:
59+
*.log
60+
local_settings.py
61+
db.sqlite3
62+
db.sqlite3-journal
63+
64+
# Flask stuff:
65+
instance/
66+
.webassets-cache
67+
68+
# Scrapy stuff:
69+
.scrapy
70+
71+
# Sphinx documentation
72+
docs/_build/
73+
74+
# PyBuilder
75+
.pybuilder/
76+
target/
77+
78+
# Jupyter Notebook
79+
.ipynb_checkpoints
80+
81+
# IPython
82+
profile_default/
83+
ipython_config.py
84+
85+
# pyenv
86+
# For a library or package, you might want to ignore these files since the code is
87+
# intended to run in multiple environments; otherwise, check them in:
88+
# .python-version
89+
90+
# pipenv
91+
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
92+
# However, in case of collaboration, if having platform-specific dependencies or dependencies
93+
# having no cross-platform support, pipenv may install dependencies that don't work, or not
94+
# install all needed dependencies.
95+
#Pipfile.lock
96+
97+
# poetry
98+
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
99+
# This is especially recommended for binary packages to ensure reproducibility, and is more
100+
# commonly ignored for libraries.
101+
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
102+
#poetry.lock
103+
104+
# pdm
105+
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
106+
#pdm.lock
107+
# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
108+
# in version control.
109+
# https://pdm.fming.dev/#use-with-ide
110+
.pdm.toml
111+
112+
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
113+
__pypackages__/
114+
115+
# Celery stuff
116+
celerybeat-schedule
117+
celerybeat.pid
118+
119+
# SageMath parsed files
120+
*.sage.py
121+
122+
# Environments
123+
.env
124+
.venv
125+
env/
126+
venv/
127+
ENV/
128+
env.bak/
129+
venv.bak/
130+
131+
# Spyder project settings
132+
.spyderproject
133+
.spyproject
134+
135+
# Rope project settings
136+
.ropeproject
137+
138+
# mkdocs documentation
139+
/site
140+
141+
# mypy
142+
.mypy_cache/
143+
.dmypy.json
144+
dmypy.json
145+
146+
# Pyre type checker
147+
.pyre/
148+
149+
# pytype static type analyzer
150+
.pytype/
151+
152+
# Cython debug symbols
153+
cython_debug/
154+
155+
# PyCharm
156+
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
157+
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
158+
# and can be added to the global gitignore or merged into this file. For a more nuclear
159+
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
160+
#.idea/
161+
runpod.toml

‎examples/plivo-chatbot/Dockerfile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Use an official Python runtime as a parent image
2+
FROM python:3.10-bullseye
3+
4+
# Set the working directory in the container
5+
WORKDIR /plivo-chatbot
6+
7+
# Copy the requirements file into the container
8+
COPY requirements.txt .
9+
10+
# Install any needed packages specified in requirements.txt
11+
RUN pip install --no-cache-dir -r requirements.txt
12+
13+
# Copy the current directory contents into the container
14+
COPY . .
15+
16+
# Expose the desired port
17+
EXPOSE 8765
18+
19+
# Run the application
20+
CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8765"]

‎examples/plivo-chatbot/README.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Plivo Chatbot
2+
3+
This project is a FastAPI-based chatbot that integrates with Plivo to handle WebSocket connections and provide real-time communication. The project includes endpoints for starting a call and handling WebSocket connections.
4+
5+
## Table of Contents
6+
7+
- [Features](#features)
8+
- [Requirements](#requirements)
9+
- [Installation](#installation)
10+
- [Configure Plivo URLs](#configure-plivo-urls)
11+
- [Running the Application](#running-the-application)
12+
- [Usage](#usage)
13+
14+
## Features
15+
16+
- **FastAPI**: A modern, fast (high-performance), web framework for building APIs with Python 3.6+.
17+
- **WebSocket Support**: Real-time communication using WebSockets.
18+
- **CORS Middleware**: Allowing cross-origin requests for testing.
19+
- **Dockerized**: Easily deployable using Docker.
20+
21+
## Requirements
22+
23+
- Python 3.10
24+
- Docker (for containerized deployment)
25+
- ngrok (for tunneling)
26+
- Plivo Account
27+
28+
## Installation
29+
30+
1. **Set up a virtual environment** (optional but recommended):
31+
32+
```sh
33+
python -m venv venv
34+
source venv/bin/activate # On Windows, use `venv\Scripts\activate`
35+
```
36+
37+
2. **Install dependencies**:
38+
39+
```sh
40+
pip install -r requirements.txt
41+
```
42+
43+
3. **Create .env**:
44+
Copy the example environment file and update with your settings:
45+
46+
```sh
47+
cp env.example .env
48+
```
49+
50+
4. **Install ngrok**:
51+
Follow the instructions on the [ngrok website](https://ngrok.com/download) to download and install ngrok.
52+
53+
## Configure Plivo URLs
54+
55+
1. **Start ngrok**:
56+
In a new terminal, start ngrok to tunnel the local server:
57+
58+
```sh
59+
ngrok http 8765
60+
```
61+
62+
2. **Update the Plivo Application**:
63+
64+
- Go to your Plivo console and navigate to Voice > Applications > XML
65+
- Select "Add New Application" or edit an existing one
66+
- Set the Primary Answer URL to your ngrok URL (e.g., https://<ngrok_url>/)
67+
- Ensure the Answer Method is set to POST
68+
- Save the application
69+
- Configure your number to use the newly created (or updated) application
70+
- Phone Numbers > Active > Your number
71+
- Select Application Type: XML Application
72+
- Plivo Application: Your application
73+
- Click "Update" to save
74+
75+
3. **Configure streams.xml**:
76+
77+
- Copy the template file to create your local version:
78+
```sh
79+
cp templates/streams.xml.template templates/streams.xml
80+
```
81+
- In `templates/streams.xml`, replace `<your server url>` with your ngrok URL (without `https://`)
82+
- The final URL should look like: `wss://abc123.ngrok.io/ws`
83+
84+
4. **Assign the Application to a Plivo Number**:
85+
- Go to Phone Numbers > Your Numbers in the Plivo console
86+
- Edit your Plivo number
87+
- Select the application you created/updated in the previous step
88+
- Save the configuration
89+
90+
## Running the Application
91+
92+
Choose one of these two methods to run the application:
93+
94+
### Using Python (Option 1)
95+
96+
**Run the FastAPI application**:
97+
98+
```sh
99+
# Make sure you're in the project directory and your virtual environment is activated
100+
python server.py
101+
```
102+
103+
### Using Docker (Option 2)
104+
105+
1. **Build the Docker image**:
106+
107+
```sh
108+
docker build -t plivo-chatbot .
109+
```
110+
111+
2. **Run the Docker container**:
112+
```sh
113+
docker run -it --rm -p 8765:8765 plivo-chatbot
114+
```
115+
116+
The server will start on port 8765. Keep this running while you test with Plivo.
117+
118+
## Usage
119+
120+
To start a call, simply make a call to your configured Plivo phone number. The Answer URL will direct the call to your FastAPI application, which will handle it accordingly.
121+
122+
## Key Differences from Twilio
123+
124+
- Plivo uses `streamId` instead of `streamSid`
125+
- Plivo uses `callId` instead of `callSid`
126+
- Plivo uses `<Stream>` element instead of `<Connect><Stream>`
127+
- Plivo's Stream element has `bidirectional`, `keepCallAlive`, and `contentType` attributes
128+
- Plivo API authentication uses Auth ID and Auth Token (similar to Twilio's Account SID and Auth Token)

0 commit comments

Comments
 (0)