devar-engine 0.1.1

Reusable sermon transcription and Bible verse suggestion engine.

Devar Engine

Reusable sermon transcription and Bible verse suggestion engine.

devar-engine is the Python engine package for building sermon-assistant workflows. It can transcribe sermon audio, maintain rolling transcript files, and suggest Bible verses from a local JSON Bible file. It works as a command-line tool for local experiments and as a library that can be imported by a backend service.

Installation

Install from PyPI:

python -m pip install devar-engine

Install with local microphone support:

python -m pip install "devar-engine[audio]"

Install with local Moonshine transcription support:

python -m pip install "devar-engine[transcription]"

Install both microphone capture and transcription support:

python -m pip install "devar-engine[all]"

Install from a checked-out repository while developing:

cd /path/to/devar.engine
python -m pip install -e ".[all]"

Bible Data

Verse suggestions require a local Bible JSON file. The expected shape is a flat array of verse objects:

[
  {
    "book": "John",
    "chapter": 3,
    "verse": 16,
    "text": "For God so loved the world..."
  }
]

Required fields:

• book: Bible book name.
• chapter: Chapter number.
• verse: Verse number.
• text: Verse text.

An optional translation field is accepted, but it is not required. Bible files are runtime data and should not be committed to source control unless you have the right to distribute them.

Command-Line Usage

devar-engine installs two console commands:

• devar-engine-transcribe: transcribes audio into a transcript file.
• devar-engine-suggest: suggests Bible verses from transcript text or an ad-hoc query.

Suggest Verses From Text

devar-engine-suggest query \
  --bible data/nkjv.json \
  --text "Do not be anxious about anything" \
  --top-k 5

Suggest Verses From A Transcript

Run one suggestion cycle:

devar-engine-suggest once \
  --bible data/nkjv.json \
  --transcript-file transcripts/live.jsonl

Watch a transcript and print suggestions repeatedly:

devar-engine-suggest loop \
  --bible data/nkjv.json \
  --transcript-file transcripts/live.jsonl \
  --interval-seconds 10 \
  --last-seconds 15

Transcribe A WAV File

devar-engine-transcribe \
  --source wav-file \
  --input recordings/sermon.wav \
  --duration 3600 \
  --transcript-output transcripts/sermon.jsonl \
  --no-audio-output

For best results, use uncompressed WAV audio with:

• 16 kHz sample rate.
• 16-bit signed PCM samples.
• Mono audio.

Transcribe From A Microphone

Install the audio and transcription extras first:

python -m pip install "devar-engine[all]"

List available input devices:

devar-engine-transcribe --list-devices

Record and transcribe:

devar-engine-transcribe \
  --source microphone \
  --duration 3600 \
  --transcript-output transcripts/live.jsonl \
  --audio-output recordings/live.wav

Test Without Audio Hardware

devar-engine-transcribe \
  --source tone \
  --duration 5 \
  --transcript-output transcripts/tone.jsonl \
  --no-audio-output

Python API

Suggest Verses

from pathlib import Path

from devar_engine.suggestions import BibleIndex, keyword_suggest

bible = BibleIndex(Path("data/nkjv.json"))
results = keyword_suggest(
    bible,
    "God loved the world and gave His Son",
    top_k=3,
)

for result in results:
    print(result.reference)
    print(result.display_text)

Read Recent Transcript Context

from pathlib import Path

from devar_engine.suggestions import read_recent_context

text, timestamp_range = read_recent_context(
    Path("transcripts/live.jsonl"),
    last_seconds=15,
)

Transcribe WAV Bytes In A Backend

from devar_engine.transcription import transcribe_wav_bytes

with open("recordings/sermon.wav", "rb") as f:
    wav_bytes = f.read()

text = transcribe_wav_bytes(wav_bytes)

Convert PCM To WAV Bytes

from devar_engine.audio import AudioSettings, pcm_to_wav_bytes

settings = AudioSettings(sample_rate=16000, channels=1, sample_width=2)
wav_bytes = pcm_to_wav_bytes(raw_pcm_bytes, settings)

Transcript Format

JSONL transcript entries are written one object per line:

{"timestamp": "00:00 - 00:05", "text": "Grace and peace to you"}

The suggestion command reads the most recent timestamped entries when possible. For plain-text transcripts, it falls back to the last characters in the file.

Runtime Files

Typical local directories:

data/          Bible JSON files
recordings/    optional WAV recordings
transcripts/   generated transcript files

Treat these as local runtime directories. Generated transcripts, recordings, and licensed Bible files should normally stay out of git.

License

Devar Engine is licensed under the Apache License 2.0.

This package does not include Bible translations, recordings, transcripts, speech model weights, or other runtime data. Those assets may have their own licenses and usage restrictions.

Development

Run the package tests from this directory:

PYTHONPATH=src PYTHONDONTWRITEBYTECODE=1 python -m unittest discover -s tests -v

Run a CLI smoke test with a local Bible file:

PYTHONPATH=src python -m devar_engine.cli.suggest query \
  --bible data/nkjv.json \
  --text "The Lord is my shepherd"

Releasing

Build and verify distributions from the repository root:

python -m pip install -e ".[dev]"
python -m build
python -m twine check dist/*

Test a release on TestPyPI first:

python -m twine upload --repository testpypi dist/*
python -m pip install \
  --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple \
  devar-engine

Publish the real release to PyPI:

python -m twine upload dist/*

GitHub Actions workflows are also included for TestPyPI and PyPI publishing. They are triggered manually with workflow_dispatch or automatically when you push a tag like devar-engine-v0.1.2.

Troubleshooting

Bible file not found

Pass --bible /path/to/bible.json, or place the file where your command expects it.

No suggestions

Make sure the transcript has meaningful sermon text and the Bible file uses the required flat verse-object shape.

WAV file settings do not match

Use 16 kHz, 16-bit, mono WAV input, or convert the file before passing it to devar-engine-transcribe.