> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Finchvox

> Voice AI observability dev tool that unifies conversation audio, logs, traces, and metrics for Pipecat agents

export const CommunityMaintained = ({maintainer, maintainerUrl, repo}) => <Note>
    <strong>Community-maintained integration.</strong> This service is built and
    maintained by{" "}
    <a href={maintainerUrl} target="_blank" rel="noreferrer">
      {maintainer}
    </a>
    . Pipecat does not test or officially support it. Please report issues and
    request changes on the{" "}
    <a href={repo} target="_blank" rel="noreferrer">
      source repository
    </a>
    . Learn more about{" "}
    <a href="/api-reference/server/services/community-integrations">
      community integrations
    </a>
    .
  </Note>;

<CommunityMaintained maintainer="finchvox" maintainerUrl="https://github.com/finchvox" repo="https://github.com/finchvox/finchvox" />

## 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`.

<CardGroup cols={2}>
  <Card title="Source Repository" icon="github" href="https://github.com/finchvox/finchvox">
    Source code, examples, and issues for the Finchvox integration
  </Card>

  <Card title="PyPI Package" icon="cube" href="https://pypi.org/project/finchvox/">
    The `finchvox` package on PyPI
  </Card>

  <Card title="Finchvox Website" icon="book" href="https://finchvox.dev/">
    Sign up for the production-ready self-hosted option
  </Card>
</CardGroup>

## 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:

```bash theme={null}
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](https://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`):

```python theme={null}
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()`:

```python theme={null}
pipeline = Pipeline([
    # STT, 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:

```python theme={null}
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:

```bash theme={null}
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:

| Parameter      | Type   | Default                   | Description                                                |
| -------------- | ------ | ------------------------- | ---------------------------------------------------------- |
| `service_name` | `str`  | `"pipecat-app"`           | Name identifying this application in traces.               |
| `endpoint`     | `str`  | `"http://localhost:4317"` | Finchvox collector gRPC endpoint.                          |
| `insecure`     | `bool` | `True`                    | Use an insecure (non-TLS) gRPC connection.                 |
| `capture_logs` | `bool` | `True`                    | Send logs to the collector alongside traces.               |
| `log_modules`  | `list` | `None`                    | Additional module prefixes to capture (e.g., `["myapp"]`). |
| `app_root`     | `str`  | `None`                    | Root 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:

<ParamField path="endpoint" type="str" default="http://localhost:3000">
  URL of the Finchvox HTTP server used to upload conversation audio.
</ParamField>

<ParamField path="chunk_duration_seconds" type="int" default="5">
  Duration of each audio chunk uploaded.
</ParamField>

<ParamField path="sample_rate" type="int" default="16000">
  Audio sample rate in Hz.
</ParamField>

<Note>
  Available parameters and defaults are defined by the integration. See the
  [source repository](https://github.com/finchvox/finchvox) for the
  authoritative, up-to-date list.
</Note>

## Compatibility

Requires Pipecat 0.0.68 or higher. Check the [source
repository](https://github.com/finchvox/finchvox) for the latest tested version
and changelog.