finchvox 0.0.8

Voice AI observability dev tool for Pipecat

Finchvox - elevated debugging for Pipecat Voice AI

Do your eyes bleed like a Vecna victim watching Pipecat logs fly by? Does flipping between audio recordings, transcripts, and logs damage your ⌘+tab keys from frequent use? If so, meet Finchvox, a local debugger purpose-built for Voice AI apps.

Finchvox unifies conversation audio, logs, traces, and metrics in a single UI, highlighting voice-specific problems like interruptions and high user <-> bot latency.

👇 Click the image for a short video:

Table of Contents

• Prerequisites
• Installation
• Setup
• Configuration
• Usage
• Troubleshooting
• Telemetry

Prerequisites

• Python 3.10 or higher
• A Pipecat Voice AI application

Installation

# uv
uv add finchvox "pipecat-ai[tracing]"

# Or with pip
pip install finchvox "pipecat-ai[tracing]"

Setup

1. Add the following to the top of your bot (e.g., bot.py):

import finchvox
from finchvox import FinchvoxProcessor

finchvox.init(service_name="my-voice-app")

2. Add FinchvoxProcessor to your pipeline, ensuring it comes after transport.output():

pipeline = Pipeline([
    # SST, LLM, TTS, etc. processors
    transport.output(),
    FinchvoxProcessor(), # Must come after transport.output()
    context_aggregator.assistant(),
])

3. Initialize your PipelineTask with metrics, tracing and turn tracking enabled:

task = PipelineTask(
    pipeline,
    params=PipelineParams(enable_metrics=True),
    enable_tracing=True,
    enable_turn_tracking=True,
)

Configuration

The finchvox.init() function accepts the following optional parameters:

Parameter	Default	Description
endpoint	"http://localhost:4317"	Finchvox collector endpoint
insecure	True	Use insecure gRPC connection (no TLS)
capture_logs	True	Send logs to collector alongside traces
log_modules	None	Additional module prefixes to capture (e.g., ["myapp"])

By default, logs from pipecat.*, finchvox.*, __main__, and any source files in your project directory are captured. Use log_modules to include additional third-party modules.

Usage - Finchvox server

uv run finchvox start

For the list of available options, run:

uv run finchvox --help

Troubleshooting

No spans being written

1. Check collector is running: Look for "OTLP collector listening on port 4317" log message
2. Verify client endpoint: Ensure Pipecat is configured to send to http://localhost:4317

Telemetry

FinchVox collects minimal, anonymous usage telemetry to help improve the project. No personal data, IP addresses, or session content is collected.

What's collected:

• Event type (server_start, session_ingest, session_view)
• FinchVox version
• Operating system (macOS, Linux, or Windows)
• Timestamp

Disable telemetry:

finchvox start --telemetry false

Or set the environment variable:

export FINCHVOX_TELEMETRY=false