Empathy Engine

A local Python service that converts text into emotionally expressive speech. It detects the emotional tone of input text, maps that tone to voice parameters, and generates a WAV audio file with modulated speech characteristics.

No API keys or cloud services are required. Everything runs locally.

---

Architecture

text input
    │
    ▼
EmotionDetector          (emotion_detector.py)
    │  VADER sentiment analysis → label: positive / negative / neutral
    ▼
VoiceMapper              (voice_mapper.py)
    │  label → VoiceParameters (rate, volume, pitch_shift)
    ▼
TTSEngine                (tts_engine.py)
    │  pyttsx3 synthesis + scipy pitch shift → WAV file
    ▼
outputs/<filename>.wav

The pipeline is orchestrated in app.py. Each module has a single responsibility and no circular dependencies.

---

File Structure

empathy_engine/
├── app.py               # CLI entry point and pipeline orchestration
├── emotion_detector.py  # VADER-based sentiment classification
├── voice_mapper.py      # Emotion label → voice parameter mapping
├── tts_engine.py        # Speech synthesis and pitch processing
├── config.py            # Thresholds, defaults, and voice profiles
├── requirements.txt
├── README.md
└── outputs/             # Generated WAV files land here

---

Emotion-to-Voice Mapping

Emotion	Rate (wpm)	Volume	Pitch Shift
positive	210	1.0	+20 semitones
negative	140	0.85	−15 semitones
neutral	175	1.0	0 semitones

The VADER compound score determines the emotion label:

• compound ≥ 0.05 → positive
• compound ≤ −0.05 → negative
• otherwise → neutral

These thresholds and profiles are configurable in config.py.

Pitch shifting is performed in the audio domain via scipy.signal.resample after synthesis, which avoids pyttsx3 engine limitations on pitch control.

---

Setup

Requires Python 3.9+.

On Linux, install the system TTS voice engine before running:

sudo apt-get install espeak

On macOS, the built-in nsss engine is used automatically. On Windows, SAPI5 is used.

Install Python dependencies:

pip install -r requirements.txt

---

Running

Single input:

python app.py "I just got the job offer — this is incredible news!"

With pipeline details printed:

python app.py -v "I just got the job offer — this is incredible news!"

Interactive mode:

python app.py --interactive

The output WAV file path is printed to stdout on success.

---

Example Usage

$ python app.py -v "Everything went wrong today. I feel completely defeated."

Detected emotion : negative
Compound score   : -0.6908
Speech rate      : 140 wpm
Volume           : 0.85
Pitch shift      : -15 semitones
/home/user/empathy_engine/outputs/output_negative_1742041823.wav

$ python app.py -v "We won the championship! Best day of my life!"

Detected emotion : positive
Compound score   : 0.8126
Speech rate      : 210 wpm
Volume           : 1.0
Pitch shift      : +20 semitones
/home/user/empathy_engine/outputs/output_positive_1742041901.wav

---

Configuration

Edit config.py to adjust:

• EMOTION_THRESHOLDS — compound score cutoffs for classification
• VOICE_PROFILES — per-emotion rate, volume, and pitch values
• VOICE_DEFAULTS — fallback values if an unknown label is encountered