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

# Behavioral Signals

> A perception producer that adds emotion and behavior sensing from the Behavioral Signals API, and tells the LLM how each user turn sounded.

> [!NOTE]
>
> **Community-maintained integration.** This service is built and
> maintained by
> [Behavioral Signals](https://github.com/BehavioralSignalTechnologies)
> . Pipecat does not test or officially support it. Please report issues and
> request changes on the
> [source repository](https://github.com/BehavioralSignalTechnologies/pipecat-behavioralsignals)
> . Learn more about
> [community integrations](https://docs.pipecat.ai/api-reference/server/services/community-integrations.md)
> .

## Overview

`BehavioralSignalsPerceptionService` is a perception producer for [expressive conversation](https://docs.pipecat.ai/api-reference/server/expressive/overview.md). It streams the user's voice to the [Behavioral Signals](https://behavioralsignals.com/) API and adds per-utterance estimates of expressed emotion, strength, positivity, hesitation, engagement and speaking rate, each with a probability for every class, to the `perception` of each user turn's transcriptions. The LLM reads it with the user's words. Outputs are probabilistic estimates of signals expressed in speech, not determinations of what a person feels, intends or believes.

It can run with [`PipecatToneReader`](https://docs.pipecat.ai/api-reference/server/expressive/pipecat-tone#pipecattonereader), which reads the words: the service adds its reading to the one a transcription already carries.

> [card] [Source Repository](https://github.com/BehavioralSignalTechnologies/pipecat-behavioralsignals)
>
> Code, an example voice agent, and the changelog

> [card] [PyPI Package](https://pypi.org/project/pipecat-behavioralsignals/)
>
> The `pipecat-behavioralsignals` package on PyPI

## Installation

This is a community-maintained package distributed separately from `pipecat-ai`:

```bash theme={null}
uv add pipecat-behavioralsignals
```

Requires Python 3.12 or later and Pipecat 1.16.

## Prerequisites

* A Behavioral Signals account, with a client ID (CID) and an API key from the [Behavioral Signals portal](https://portal.behavioralsignals.com/).
* Set them as environment variables, or pass them to the service:

```bash theme={null}
export BEHAVIORALSIGNALS_CID=...
export BEHAVIORALSIGNALS_API_KEY=...
```

The service streams all of the user's input audio for the whole call, and streaming is billed by the minute. Behavioral Signals saves a stream's results, which can be fetched later: tell your users, and check that this fits your privacy terms (see [Your users' audio](https://github.com/BehavioralSignalTechnologies/pipecat-behavioralsignals#your-users-audio)).

## Configuration

**cid** `str | None` (default: None)

Your Behavioral Signals client ID. `None` uses the `BEHAVIORALSIGNALS_CID`
environment variable.

**api\_key** `str | None` (default: None)

Your Behavioral Signals API key. `None` uses the `BEHAVIORALSIGNALS_API_KEY`
environment variable.

## Usage

Put the service right after your STT service, and turn on expressive conversation:

```python theme={null}
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.worker import PipelineParams, PipelineWorker

from pipecat_behavioralsignals import BehavioralSignalsPerceptionService

pipeline = Pipeline([
    transport.input(),
    stt,
    BehavioralSignalsPerceptionService(),
    user_aggregator,
    llm,
    tts,
    transport.output(),
    assistant_aggregator,
])

worker = PipelineWorker(pipeline, params=PipelineParams(enable_expressive_conversation=True))
```

The service reads the audio the STT service passes on, so keep the STT service's default `audio_passthrough=True`. It reads mono audio, which Pipecat transports give by default; on audio with more channels it reports an error and stops reading.

Each user message then starts with the reading:

```
([voice_emotion angry=0.71, neutral=0.20, sad=0.06, happy=0.03],[positivity negative=0.72, neutral=0.20, positive=0.08],[strength strong=0.64, neutral=0.30, weak=0.06],[speaking_rate fast=0.50, normal=0.40, slow=0.10],[hesitation no=0.80, yes=0.20],[engagement engaged=0.55, neutral=0.35, withdrawn=0.10],[intensity value=0.61]) I already told you, I was charged twice.
```

A reading covers a recent part of the turn, often not its last words, and a very short turn may have none.

The signals are `voice_emotion`, `strength`, `positivity`, `speaking_rate`, `hesitation`, `engagement` and `intensity`. See the [repository](https://github.com/BehavioralSignalTechnologies/pipecat-behavioralsignals#what-the-llm-sees) for what each reads and how a reading is matched to a turn.

## Compatibility

Version 0.2.0 requires Pipecat 1.16 (`pipecat-ai>=1.16.0,<1.17`) and is tested with 1.16.0. On Pipecat 1.15, use 0.1.0. See the [changelog](https://github.com/BehavioralSignalTechnologies/pipecat-behavioralsignals/blob/main/CHANGELOG.md) for the versions each release requires.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.