Skip to content

README.md

Latest commit

 

History

History
219 lines (156 loc) · 6.98 KB

README.md

File metadata and controls

219 lines (156 loc) · 6.98 KB
Raw

Firetell Audio Stream — Python Examples

Official sample code for the Firetell stream call action.
Connect live call audio to your own WebSocket server for real-time transcription, compliance monitoring, or a fully custom AI voice bot.

📚 Documentation: developers.firetell.com/docs/rest-api/workspace-api/call

Overview

When you use the stream action in a Firetell call flow or outbound call, Firetell establishes a WebSocket connection to your server and streams raw 16-bit signed PCM audio in real-time. With bidirectional: true, your server can also send audio back to be played to the caller.

[Caller] ◄──► [Firetell] ◄──► Your WebSocket Server
                                       │
                         One-way:  STT / Analytics / Recording
                         Full-duplex:  STT → LLM → TTS (AI Voice Bot)

Examples

Example 1 — One-Way Monitoring (one_way_monitor.py)

Receive the caller's live audio stream without affecting the call. Suitable for:

  • Real-time speech-to-text (STT) transcription
  • Keyword detection & compliance monitoring
  • Call analytics and sentiment analysis
  • Audio recording / archiving

Example 2 — Full-Duplex AI Voice Bot (full_duplex_bot.py)

Receive audio and send audio back — build a fully custom AI voice bot using any STT, LLM, and TTS provider of your choice. Suitable for:

  • Custom voice assistants with any AI model (GPT-4, Gemini, Claude, etc.)
  • Virtual agents with proprietary business logic
  • Real-time translation and interpretation services

Prerequisites

  • Python 3.10+
  • A Firetell workspace with API access — firetell.com
  • A publicly accessible HTTPS/WSS endpoint (use ngrok for local testing)

Setup

git clone https://github.com/firetellcom/audio-stream-python-example.git
cd audio-stream-python-example
pip install -r requirements.txt

Run the Examples

One-Way Monitoring

PORT=3000 AUTH_TOKEN=your-secret-token python examples/one_way_monitor.py

Full-Duplex AI Voice Bot

PORT=3001 AUTH_TOKEN=your-secret-token SAMPLE_RATE=8000 python examples/full_duplex_bot.py
Environment Variable Default Description
PORT 3000 / 3001 WebSocket server port
AUTH_TOKEN (empty) If set, validates Authorization: Bearer <token> header
SAMPLE_RATE 8000 PCM sample rate — must match your stream action sample_rate param

Configure Your Firetell Call Flow

In your JCA webhook response or outbound Make Call API request, include the stream action:

One-Way Monitoring

{
  "actions": [
    {
      "action": "stream",
      "params": {
        "ws_url": "wss://your-server.example.com/stream",
        "track": "both",
        "bidirectional": false,
        "headers": {
          "Authorization": "Bearer your-secret-token"
        }
      }
    }
  ]
}

Full-Duplex AI Voice Bot

{
  "actions": [
    {
      "action": "stream",
      "params": {
        "ws_url": "wss://your-server.example.com/bot",
        "track": "both",
        "sample_rate": 8000,
        "bidirectional": true,
        "headers": {
          "Authorization": "Bearer your-secret-token"
        }
      }
    }
  ]
}

Audio Format

Property Value
Encoding 16-bit signed PCM, little-endian
Sample rate 8000 Hz (default) or 16000 Hz
Channels (incoming, track=both) Stereo — left = caller, right = callee
Channels (incoming, track=inbound/outbound) Mono
Channels (outgoing to Firetell) Mono

WebSocket Protocol

Direction Frame type Content
Firetell → Your server Binary Raw PCM audio (caller's speech)
Your server → Firetell Binary Raw PCM audio (bot speech — requires bidirectional: true)
Your server → Firetell Text (JSON) {"type":"killAudio"} — stop queued playback (barge-in)

Query Parameters (Auto-Appended by Firetell)

Firetell automatically appends the following to your ws_url so you can identify the call without custom headers:

Parameter Description
call_id Unique Firetell call identifier
workspace_id Your Firetell workspace ID
caller_number Caller's phone number (E.164)
caller_name Caller's display name (if available)
destination_number The dialed number
stream_type Always firetell_stream

Local Development with ngrok

If you don't have a public server, use ngrok to expose your local server:

# Terminal 1 — start your server
python examples/full_duplex_bot.py

# Terminal 2 — expose it publicly
ngrok http 3001

Use the wss:// ngrok URL in your ws_url param.

Build Your AI Pipeline

Replace the placeholder logic in full_duplex_bot.py with your actual pipeline:

async for message in websocket:
    if isinstance(message, str):
        continue
    caller_audio: bytes = message

    # 1. Voice Activity Detection (barge-in)
    if vad.is_speaking(caller_audio):
        await send_kill_audio()

    # 2. Stream to STT (e.g. Deepgram, Google, OpenAI Whisper)
    await stt_stream.send(caller_audio)

# When STT returns a final transcript:
async def on_transcript(text: str) -> None:
    # 3. LLM (e.g. OpenAI GPT-4, Google Gemini)
    reply = await llm.chat(text)

    # 4. TTS → PCM (must be mono, 16-bit, at SAMPLE_RATE Hz)
    audio_pcm = await tts.synthesize(reply, sample_rate=SAMPLE_RATE)
    await send_audio(audio_pcm)

License

MIT — see LICENSE

Contributing

Issues and PRs are welcome at github.com/firetellcom/audio-stream-python-example.