soundflare 1.0.2

Soundflare Observe SDK - Voice Analytics for AI Agents

Soundflare – Voice AI Observability Platform

Professional voice analytics and observability for AI agents. Monitor, analyze, and improve your voice AI applications with comprehensive tracking and actionable insights.

🚀 Get Started • Documentation • ✨ Features

---

Features

• 🔍 Real-time Session Monitoring - Track every voice interaction with comprehensive analytics
• 💰 Cost Tracking - Monitor STT, TTS, and LLM costs across all providers
• ⚡ Performance Metrics - Analyze latency, response times, and quality scores
• 🎯 Turn-by-Turn Analytics - Detailed conversation turn tracking with full context
• 📊 OpenTelemetry Integration - Native OTEL support for distributed tracing
• 🐛 Bug Reporting System - Built-in user feedback collection during sessions
• 🔧 Easy Integration - One-line SDK integration with LiveKit agents
• 📈 Usage Metrics - Track token usage, API calls, and session duration
• 🎙️ Voice Analytics - STT, TTS, LLM, and VAD metrics tracking

Quick Start

Installation

pip install soundflare

Environment Setup

Create a .env file in your project root:

# Soundflare Configuration
SOUNDFLARE_API_KEY=your_api_key_here
SOUNDFLARE_HOST_URL=your_host_url_here

Basic Integration

from dotenv import load_dotenv
import os
from soundflare import LivekitObserve

# Load environment variables
load_dotenv()

# Initialize observability
soundflare = LivekitObserve(
    agent_id="your-agent-id",
    apikey=os.getenv("SOUNDFLARE_API_KEY"),
    host_url=os.getenv("SOUNDFLARE_HOST_URL"),
    enable_otel=True  # Enable OpenTelemetry integration
)

# Wrap your LiveKit session
session = AgentSession(...)
session_id = soundflare.start_session(session, phone_number="[phone]")

# Ensure data is exported on shutdown
async def soundflare_shutdown():
    await soundflare.export(session_id)

ctx.add_shutdown_callback(soundflare_shutdown)
await session.start(...)

Advanced Features

Bug Reporting

Enable built-in bug reporting to collect user feedback during sessions:

soundflare = LivekitObserve(
    agent_id="your-agent-id",
    apikey=os.getenv("SOUNDFLARE_API_KEY"),
    host_url=os.getenv("SOUNDFLARE_HOST_URL"),
    bug_reports_enable=True,
    bug_reports_config={
        'bug_start_command': ['feedback start', 'report issue'],
        'bug_end_command': ['feedback over', 'done reporting'],
        'response': 'Please tell me the issue?',
        'continuation_prefix': 'So, as I was saying, ',
        'debug': False
    }
)

OpenTelemetry Integration

Soundflare automatically integrates with OpenTelemetry for distributed tracing:

from opentelemetry import trace

# SDK automatically creates spans for:
# - Session lifecycle
# - STT operations
# - LLM calls
# - TTS generation
# - User turns and agent responses

# Access spans data
soundflare = LivekitObserve(
    agent_id="your-agent-id",
    apikey=os.getenv("SOUNDFLARE_API_KEY"),
    host_url=os.getenv("SOUNDFLARE_HOST_URL"),
    enable_otel=True
)

What You Can Track

Metric	Description	Details
Latency	Response times for each component	STT, TTS, LLM processing times
Costs	Token usage and billing	Automatic cost calculation for major providers
Transcripts	Full conversation history	User input and agent responses
Quality	Transcription accuracy	Audio duration, confidence scores
Sessions	Call metadata	Duration, timestamps, phone numbers
Turns	Conversation flow	Turn-by-turn analysis with context
Tool Calls	Agent function executions	Track agent tool usage and results

Use Cases

• Production Monitoring - Keep voice AI applications running smoothly
• Cost Optimization - Identify expensive operations and optimize spending
• Quality Assurance - Review call transcripts and agent responses
• Performance Debugging - Diagnose latency issues and bottlenecks
• User Feedback - Collect and analyze bug reports during calls
• Distributed Tracing - Track requests across microservices

Architecture

Soundflare SDK provides:

• Lightweight Python SDK - Minimal overhead data collection
• Async Support - Non-blocking data transmission
• Event-Driven - Hooks into LiveKit agent lifecycle
• Metric Collection - Comprehensive STT/TTS/LLM metrics
• Session Management - Automatic session tracking and cleanup

Technology Stack

• Core: Python 3.9+, asyncio
• Dependencies:
  • livekit-agents - Voice agent framework
  • requests - HTTP client for data transmission
  • python-dotenv - Environment configuration
• Integrations: OpenTelemetry, LiveKit

Documentation

Core Components

LivekitObserve

Main class for observability integration.

Parameters:

• agent_id (str): Unique identifier for your agent
• apikey (str, optional): API key for authentication
• host_url (str, optional): Host URL for data export
• bug_reports_enable (bool): Enable bug reporting feature
• bug_reports_config (dict): Configuration for bug reporting
• enable_otel (bool): Enable OpenTelemetry integration

Methods:

• start_session(session, phone_number=None): Initialize session tracking
• export(session_id): Export session data
• handle_bug_report(user_input, session): Process user feedback

Session Tracking

The SDK automatically tracks:

• Session start/end times
• Conversation turns
• STT/TTS/LLM metrics
• Cost calculations
• OpenTelemetry spans
• Tool calls and executions

Metrics Collected

STT Metrics:

• Audio duration
• Latency
• Model name
• Streaming status
• Cost per request

LLM Metrics:

• Prompt tokens
• Completion tokens
• Latency
• Model name
• Cost per request

TTS Metrics:

• Characters generated
• Audio duration
• Latency
• Model name
• Cost per request

Configuration

Environment Variables

# Required
SOUNDFLARE_API_KEY=your_api_key

# Optional
SOUNDFLARE_HOST_URL=https://your-host.com

Bug Report Configuration

bug_reports_config = {
    'bug_start_command': ['feedback start'],  # Trigger phrases
    'bug_end_command': ['feedback over'],      # End phrases
    'response': 'Please tell me the issue?',   # Agent response
    'continuation_prefix': 'So, as I was saying, ',  # Resume prefix
    'fallback_message': 'So, as I was saying,',      # Fallback text
    'collection_prompt': '',                   # Custom prompt
    'debug': False                             # Debug logging
}

Support

• 📧 Email: [e-mail]
• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions

Enterprise

Need enterprise features like custom deployments or dedicated support?

Contact us: [e-mail]

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with ❤️ by the Trillet AI team
• Powered by LiveKit for real-time voice infrastructure
• Inspired by modern observability platforms

---

⭐ If Soundflare helps your voice AI applications, consider giving us a star!