Bible XML Manager

A modern desktop Tkinter app designed to search, discover, download, and convert Bible translations into standard OpenSong XML files ready for instant import into FreeShow, Lyric Display, OpenSong, and other lyrics & scripture projection software.

Powered by bible_translation_finder (btf / btm, currently pinned to ==0.3.1 in requirements.txt).

---

Downloads

• Windows (recommended): download bible-xml-manager.exe from the latest Release (built by GitHub Actions on every v* tag), double-click to run. No Python needed. Alternatively run from source with run.bat.
• macOS / Linux: automated PyInstaller binaries are built as best-effort CI artifacts on every push (see the Build workflow run), but the supported path is running from source via the script — Tk theming, file dialogs, and xdg-open/open folder integration behave better that way. Nothing personal, native packaging for Tk is just fragile.

---

Features

• Multi-Source Translation Search:
  • 📁 Local on Laptop: Automatically discovers Bible XML files stored on your laptop (such as in ~/Downloads, ~/.local/share/bible-translation-finder, and ~/projects/bible-translations).
  • 📚 Curated Catalog: 98 popular translations (KJV, WEB, ASV, BBE, etc.) with instant offline metadata and download URLs.
  • ☁ eBible.org Live Catalog: Real-time access to 1,500+ global translations across hundreds of languages.
• One-Click Format Conversion:
  • Automatically converts local Zefania XML Bibles (e.g. esv.xml, NASB.xml, NKJV.xml, NLT.xml, MSG.xml, AMP_2001.xml) into clean, compliant OpenSong XML (<bible><b n="Genesis"><c n="1"><v n="1">...).
• FreeShow & Lyric Display Compatibility:
  • Ensures proper <b n="BookName"> naming convention required by FreeShow's scripture detector.
• Logical File Management:
  • Shows the exact filesystem path where the XML file is saved (default: ~/.local/share/bible-translation-finder).
  • 📋 Copy Path: Instantly copy the XML path to clipboard to paste into presentation software.
  • 📂 Reveal in Folder: Directly open the folder in your system file manager (xdg-open on Linux, open on macOS, Explorer on Windows).
  • 💾 Export As: Save an OpenSong XML copy directly to any folder of your choice.
• Integrated Scripture Previewer:
  • Read and verify verses and chapters (e.g., John 3:16, Genesis 1:1-5, Psalm 23) directly inside the app before importing.

---

Quick Start (from source)

Requires Python 3.10+ with Tkinter.

pip install -r requirements.txt

Launch the app:

Linux / macOS (preferred method):

./run.sh

Or using python:

python3 main.py

Windows:

run.bat

Or:

py main.py

run.sh / run.bat just launch main.py with the nearest Python — no build step required.

---

Backend dependency: bible_translation_finder

All Bible search, download, conversion, and passage-parsing logic lives in the bible_translation_finder PyPI package (import btf / import btm). This repo contains only the Tkinter GUI (main.py, ui_theme.py, bible_manager.py thin wrapper).

Update policy:

1. The GUI pins the backend in requirements.txt (bible-translation-finder==0.3.1) so CI builds and user installs are reproducible.
2. To pick up a new backend release: bump the pin, then smoke-test passage preview (John 3:16), a curated download, and a local Zefania conversion before tagging a GUI release.
3. The smoke job in .github/workflows/build.yml installs requirements.txt fresh and verifies bible_manager still imports against the pinned backend — so a breaking backend change fails fast in CI, not on a user's laptop.
4. Deliberately not vendored or git-submoduled: the backend ships on PyPI and evolves independently; the GUI just consumes it.

---

Importing into Presentation Apps

FreeShow

1. In FreeShow, click the Bibles / Scripture icon on the left navigation bar.
2. Click + or Import.
3. Select OpenSong format.
4. Select the .xml file path provided by this app (or paste the copied path).

Lyric Display / OpenSong

1. Open Lyric Display or OpenSong.
2. Select Import Bibles -> OpenSong XML.
3. Choose the generated .xml file.

---

License

MIT — see LICENSE.