VerseListener 🎙⛪

Real-time speech-to-text with automatic Bible verse detection and EasyWorship integration.

Built for church AV operators: listen to a sermon in real time, instantly detect any Bible verse reference spoken aloud, and send it directly to EasyWorship with one click (or a hotkey).

---

Features

• 🎙 Real-time audio capture via JACK (primary) or sounddevice (fallback)
• 〰️ Live audio waveform monitor so you can verify the mic is flowing before text appears
• 🧠 Speech-to-text backends using OpenAI Realtime, faster-whisper, or Vosk
• 📖 Bible verse detection – all 66 books, dozens of abbreviations, natural-language patterns
  • "Genesis 5:2", "Gen 5 v 2", "chapter 8 verse 28", "Romans 8:28 through 30"
• ⭐ Verse queue with timestamps, confidence scores, and editable references
• 🪟 Local verse preview card above the queue, powered by offline canon files in canons/<EDITION>/verses.json
• 🧭 Likely passage suggestions from a rolling sermon context window, even when no explicit verse reference is spoken
• ⛪ EasyWorship automation via PyAutoGUI – clicks the search box, types the reference, presses Enter
• 🌗 Dark and light themes, church-friendly design
• ⌨ Hotkey: Ctrl+Shift+S sends the top queued verse to EasyWorship

---

Requirements

• Python 3.10 or newer
• Linux (JACK/ALSA/PulseAudio) – primary platform
• Windows/macOS: supported via sounddevice + PyAutoGUI (JACK not required)

---

Installation

1 – Clone / download the project

git clone https://github.com/anclatechs/verse-listener.git
cd verse-listener

2 – Create a virtual environment (recommended)

python3 -m venv .venv
source .venv/bin/activate

3 – Install Python dependencies

pip install -r requirements.txt

Windows note:

• use the repo's checked-in requirements.txt
• do not use a Linux-generated pip freeze file for Windows installs
• Linux-only CUDA packages such as nvidia-cufile are not needed for this app on Windows

3.1 – Configure .env

The project includes a ready-to-edit .env file.

Set at least:

OPENAI_API_KEY=your_key_here
VERSE_LISTENER_STT_BACKEND=openai_realtime

3.2 – Add local Bible preview text

For the queue preview card, place canon files like this:

canons/
└── KJV/
    └── verses.json

The file should map references to verse text, for example:

{
  "John 3:16": "For God so loved the world...",
  "John 3:17": "For God sent not his Son..."
}

4 – (Linux) Install system packages

sudo apt install python3-xlib wmctrl jackd2 qjackctl libportaudio2 portaudio19-dev

Optional Python backends for Linux window focus:

pip install PyWinCtl python-xlib

5 – (Optional) Download a Vosk model

If you prefer Vosk over faster-whisper:

mkdir -p ~/.vosk
cd ~/.vosk
# Download model from https://alphacephei.com/vosk/models
# Example: English small model
wget https://alphacephei.com/vosk/models/vosk-model-small-en-us-0.15.zip
unzip vosk-model-small-en-us-0.15.zip
mv vosk-model-small-en-us-0.15 model-en-us

---

JACK Setup (Linux)

Start JACK with QJackCtl or via command line:

jackd -d alsa -r 44100 &

Or use QJackCtl (GUI) to configure and start JACK.

VerseListener will auto-connect to the first available physical capture port.
You can also set the exact JACK port name in Settings → Audio.

If JACK is not running, VerseListener automatically falls back to sounddevice (PulseAudio/ALSA).

---

Running the app

python main.py

On first launch, VerseListener now opens a welcome screen with these paths:

• Quick Setup → OpenAI-first setup with API key entry
• Install Offline → in-app add-on manager for optional offline packages
• Developer Mode → advanced-friendly startup path
• Skip for now

Recommended Speech-to-Text Setup

For this project, the best default setup is:

• Audio backend: sounddevice on Windows, auto or jack on Linux
• STT backend: openai_realtime
• OpenAI model: gpt-4o-transcribe

Why this is the best starting point:

• you get streaming partial transcripts instead of waiting on local chunked inference
• the .env prompt can bias the model toward Bible book names and verse notation
• you avoid CPU-heavy local Whisper inference

If you need a fully offline fallback:

• use backend whisper with model small.en or base.en

OpenAI Realtime Setup

The app can read these values from .env, but the API key can also be entered directly in Settings → Speech Model:

OPENAI_API_KEY=your_key_here
VERSE_LISTENER_STT_BACKEND=openai_realtime
OPENAI_REALTIME_TRANSCRIBE_MODEL=gpt-4o-transcribe
OPENAI_REALTIME_LANGUAGE=en
OPENAI_REALTIME_PROMPT=...

Notes:

• OPENAI_API_KEY is required for the OpenAI backend
• the Settings dialog stores the key locally on the machine and applies it to the running app
• OPENAI_REALTIME_PROMPT is a good place to bias scripture names, sermon terms, and punctuation style
• OpenAI Realtime transcription expects 24 kHz PCM; the app handles resampling before streaming audio

Optional Add-ons

VerseListener keeps the bundled app lean and lets users install heavier offline tools later from Settings → Add-ons.

Optional in-app installs:

• Vosk for offline STT
• faster-whisper for offline Whisper fallback
• sentence-transformers for stronger semantic passage matching

Notes:

• estimated sizes are shown in the add-ons manager before install
• installs go into the user's VerseListener add-ons folder, not into the bundled executable itself
• restart after install is recommended for the cleanest reload
• Windows onedir builds can bundle a helper Python runtime so in-app installs work even when the target PC does not have Python installed

Windows Onedir Build

For a lean Windows bundle with OpenAI as the default path:

build_windows.bat

What this does:

• installs the lean Windows runtime dependencies from requirements-windows-openai.txt
• builds VerseListener.exe with PyInstaller using VerseListener.spec
• prepares and bundles a helper Python runtime under dist\VerseListener\runtime\python

Why the helper runtime matters:

• the shipped app stays lean and OpenAI-first by default
• optional add-ons still install later from Settings → Add-ons
• the target PC does not need a separate Python install for those add-ons

The helper runtime is prepared by:

powershell -ExecutionPolicy Bypass -File .\scripts\prepare_windows_runtime.ps1 -PythonVersion 3.12.3 -Force

Use the same Python major/minor version that you build the app with on Windows. build_windows.bat will auto-prepare this runtime for you when possible.

Verse Preview

The right-hand queue panel includes a compact preview card above the detected verses list.

• Click a queued verse to load its text from canons/<EDITION>/verses.json
• Range references like Romans 8:28-30 are combined into one preview
• Chapter-only references show the first few verses as a compact preview
• In Settings → Interface, you can adjust:
  • preview canon edition
  • preview max height
  • gradient start and end colors

Contextual Passage Guessing

VerseListener can also infer a likely Bible passage from what is being preached, even if the speaker does not explicitly say the reference.

• It keeps a rolling context window from the last few transcript segments
• Exact verse detection still wins first
• If no explicit reference is found, the app searches the local canon for the closest passage match
• Suggestions appear as a separate Likely Passage card and can be queued manually

Default behavior:

• context window: 8s
• matcher: local keyword retrieval
• optional upgrade: install sentence-transformers for semantic reranking

Enable and adjust it in Settings → Speech Model.

Optional: choose the EasyWorship window backend

VerseListener reads VERSE_LISTENER_EW_WINDOW_BACKEND at startup.

export VERSE_LISTENER_EW_WINDOW_BACKEND=auto
python main.py

Supported values:

• auto → Linux tries pywinctl, then wmctrl, then xlib, then pygetwindow
• pywinctl
• wmctrl
• xlib
• pygetwindow

Examples:

export VERSE_LISTENER_EW_WINDOW_BACKEND=pywinctl
export VERSE_LISTENER_EW_WINDOW_BACKEND=xlib

---

EasyWorship Setup

1. Open EasyWorship on the same machine.
2. Click "Calibrate EW" in the VerseListener toolbar.
3. You have 3 seconds to move your mouse cursor to the Bible search field in EasyWorship.
4. VerseListener saves those coordinates.
5. From now on, clicking "Send to EasyWorship" will:
   • Focus the EasyWorship window
   • Click the search field
   • Type the verse reference (e.g. Romans 8:28)
   • Press Enter

Adjusting timing

If EasyWorship is slow to respond, open Settings → EasyWorship and increase the delay values.

---

Keyboard Shortcuts

Shortcut	Action
Ctrl+R	Start / stop listening
Ctrl+Shift+S	Send top queued verse to EasyWorship

---

Supported Verse Formats

VerseListener detects all of these (and more):

Genesis 5:2
Gen 5:2
Genesis chapter 5 verse 2
Gen ch 5 v 2
Romans 8:28-30
book of Romans chapter 8 verses 28 through 30
Psalm 23
1 Corinthians 13:4
First Corinthians 13:4

Full list of supported books and abbreviations: see core/bible_detector.py.

---

Project Structure

verse_listener/
├── main.py                  # Entry point
├── requirements.txt
├── README.md
├── core/
│   ├── bible_detector.py    # Verse pattern matching
│   ├── bible_preview.py     # Local canon loading for verse preview
│   ├── transcription.py     # Audio capture + STT threads
│   ├── easyworship.py       # PyAutoGUI EasyWorship controller
│   └── settings.py          # Persistent settings
└── ui/
    ├── main_window.py       # Main application window
    ├── transcript_panel.py  # Live transcription display
    ├── queue_panel.py       # Detected verses queue
    ├── settings_dialog.py   # Settings UI
    └── styles.py            # Dark/light QSS stylesheets

---

Troubleshooting

Problem	Solution
No audio captured	Check JACK is running; or set backend to sounddevice in Settings
OpenAI realtime does not start	Check OPENAI_API_KEY in .env and confirm websocket-client is installed
PortAudio library not found	Install libportaudio2 (and, if needed, portaudio19-dev) then restart the app
Model takes long to load	First run downloads faster-whisper model; subsequent runs are fast
EasyWorship not focused	Re-run calibration; increase Focus Delay in Settings
Verse preview is blank	Check that the selected edition exists under canons/<EDITION>/verses.json
PyGetWindow currently does not support Linux	Set VERSE_LISTENER_EW_WINDOW_BACKEND=pywinctl, wmctrl, or xlib
PyAutoGUI fails on Linux	Install python3-xlib: sudo apt install python3-xlib
JACK auto-connect fails	Manually connect ports in QJackCtl

---

License

GNU GPL v3.0 only (GPL-3.0-only) – see LICENSE.md.