Skip to main content

​
Overview

Finchvox is local session replay purpose-built for Voice AI apps. It unifies conversation audio, logs, traces, and metrics in a single UI, highlighting voice-specific problems like interruptions and high user ↔ bot latency. It exports OpenTelemetry traces from your Pipecat application to a local Finchvox server and records conversation audio via the FinchvoxProcessor.

Source Repository

Source code, examples, and issues for the Finchvox integration

PyPI Package

The finchvox package on PyPI

Finchvox Website

Sign up for the production-ready self-hosted option

​
Installation

This is a community-maintained package distributed separately from pipecat-ai. Finchvox relies on Pipecat’s tracing support, so install it alongside the tracing extra: 
uv add finchvox "pipecat-ai[tracing]"

​
Prerequisites

  • Python 3.11 or higher
  • Pipecat 0.0.68 or higher
Finchvox is currently designed for local, development usage and sends telemetry to a local Finchvox server (the collector) over gRPC. No external account or API key is required for local use. Visit Finchvox.dev to sign up for the production-ready self-hosted option.

​
Setup

Enabling observability in a Pipecat app involves three steps: initialize Finchvox, add the FinchvoxProcessor to your pipeline, and enable metrics, tracing, and turn tracking on your PipelineTask.
  1. Initialize Finchvox at the top of your bot (e.g., bot.py):
import finchvox
from finchvox import FinchvoxProcessor

finchvox.init(service_name="my-voice-app")
  1. Add FinchvoxProcessor to your pipeline, ensuring it comes after transport.output():
pipeline = Pipeline([
    # STT, LLM, TTS, etc. processors
    transport.output(),
    FinchvoxProcessor(),  # Must come after transport.output()
    context_aggregator.assistant(),
])
  1. 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,
)

​
Running the Finchvox server

Start the local Finchvox server to receive and view sessions: 
uv run finchvox start
For the list of available options, run uv run finchvox --help.

​
Configuration

The finchvox.init() function accepts the following optional parameters:
ParameterTypeDefaultDescription
service_namestr"pipecat-app"Name identifying this application in traces.
endpointstr"http://localhost:4317"Finchvox collector gRPC endpoint.
insecureboolTrueUse an insecure (non-TLS) gRPC connection.
capture_logsboolTrueSend logs to the collector alongside traces.
log_moduleslistNoneAdditional module prefixes to capture (e.g., ["myapp"]).
app_rootstrNoneRoot directory of the app source. Defaults to cwd().
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. The FinchvoxProcessor constructor accepts the following optional parameters:
​
endpoint
str
default:"http://localhost:3000"
URL of the Finchvox HTTP server used to upload conversation audio.
​
chunk_duration_seconds
int
default:"5"
Duration of each audio chunk uploaded.
​
sample_rate
int
default:"16000"
Audio sample rate in Hz.
Available parameters and defaults are defined by the integration. See the source repository for the authoritative, up-to-date list.

​
Compatibility

Requires Pipecat 0.0.68 or higher. Check the source repository for the latest tested version and changelog.