gencon-audiobook 0.1.8rc1

Download General Conference talks as a complete audiobook (m4b) and epub with full transcripts

gencon-audiobook

Download General Conference talks from churchofjesuschrist.org and produce:

• A chaptered .m4b audiobook — one chapter per talk, with speaker name in the chapter title, cover art, and full metadata
• An .epub companion — full transcripts, speaker photos, nested session/talk table of contents, and theme-safe CSS (dark mode, sepia, and accessibility modes all work)

Single pip install, no prerequisites beyond Python 3.10+. ffmpeg is located automatically — on your PATH if present, otherwise downloaded once via static-ffmpeg.

Inspired by General-Conference-to-Audiobook.

Disclaimer: This is an unofficial tool not affiliated with The Church of Jesus Christ of Latter-day Saints. General Conference content is copyright Intellectual Reserve, Inc. All rights reserved. This tool downloads content for personal, noncommercial use as permitted by the Church's Terms of Use.

---

Installation

pip install gencon-audiobook

Python 3.10 or newer is required. All other dependencies, including ffmpeg, are handled automatically. ffmpeg 1.0+ is required for per-file progress display during conversion; any ffmpeg from a package manager or the static-ffmpeg fallback exceeds this.

New to the terminal or Python? See the User Guide for step-by-step instructions.

---

Usage

# Download the most recent conference (both audiobook and epub)
gencon-audiobook

# Select a specific conference
gencon-audiobook --conference "April 2024"

# Audiobook only (skip epub)
gencon-audiobook --audiobook-only

# EPUB only (skip audiobook and audio download)
gencon-audiobook --epub-only

# Custom output directory
gencon-audiobook --output ~/Books

# Rebuild existing output files
gencon-audiobook --overwrite

# Re-scrape fresh data from the Church website (bypass local cache)
gencon-audiobook --force-scrape

# Reduce file size (lower bitrate and sample rate)
gencon-audiobook --bitrate 32k --sample-rate 22050

# Show detailed progress in the terminal
gencon-audiobook --verbose

# Add paragraph numbers to EPUB transcripts (useful for study groups and citations)
gencon-audiobook --epub-paragraph-numbers

For the full options reference, file size guide, and platform compatibility notes, see the User Guide.

---

Output structure

~/gencon-audiobook/
  April 2024 General Conference/
    April 2024 General Conference.m4b    # Chaptered audiobook
    April 2024 General Conference.epub   # Transcript companion
    cover.jpg                            # Conference cover image
    conference.json                      # Cached conference metadata (skip re-scraping)
    audio/                               # Downloaded MP3 files
    speakers/                            # Speaker photos
    inline/                              # Inline body images embedded in the EPUB
    gencon-audiobook.log                 # Full DEBUG log for troubleshooting

Running the tool a second time skips files that already exist and loads conference metadata from conference.json instead of re-scraping the Church website. Use --overwrite to rebuild output files. Use --force-scrape to bypass the metadata cache and fetch fresh data from the Church website.

---

Documentation

• User Guide — full options reference, file size guide, platform support, troubleshooting
• Listening/Reading Guide — how to open the output files on every platform
• Architecture — codebase structure for contributors
• Technical Decisions — design choices with rationale

---

Development

git clone https://github.com/XeroIP/gencon-audiobook.git
cd gencon-audiobook
pip install -e ".[dev]"

# Run unit tests (no network required)
pytest tests/ --ignore=tests/test_scraper_live.py --ignore=tests/test_integration.py

# Run live smoke tests (hits the real website)
pytest tests/test_scraper_live.py -v -m live

# Run full end-to-end integration test (requires ffmpeg)
pytest tests/test_integration.py -v -m integration

Project layout

src/gencon_audiobook/
  cli.py            Click entry point
  scraper.py        Fetch and parse conference listings and talk pages
  downloader.py     Download MP3s, cover, speaker photos, and inline images (parallel)
  audio.py          Convert MP3 to AAC, assemble chaptered m4b
  epub_builder.py   Build EPUB 3 ZIP from transcripts and images
  ffmpeg_manager.py Locate ffmpeg/ffprobe (PATH first, static-ffmpeg fallback)
  cache.py          Save/load Conference metadata to conference.json (skip re-scraping)
  models.py         Conference / Session / Talk / InlineImage dataclasses
  progress.py       Custom Rich progress column (TimeRemainingWithLabel)
  utils.py          sanitize_filename(), validate_url()

tests/
  conftest.py             Shared helpers (ffmpeg discovery, silent MP3, JPEG)
  test_scraper.py         Unit tests against saved HTML fixtures
  test_downloader.py      Mocked HTTP tests
  test_audio.py           Audio pipeline with generated silent fixtures
  test_epub.py            EPUB structure and content validation
  test_cache.py           Cache serialization and version compatibility
  test_cli.py             CLI behavior (all external calls mocked)
  test_utils.py           Filename sanitization and URL validation
  test_ffmpeg_manager.py  ffmpeg/ffprobe discovery and caching
  test_scraper_live.py    Live smoke tests (@pytest.mark.live)
  test_integration.py     End-to-end test (@pytest.mark.integration)
  fixtures/               Saved HTML snapshots for scraper unit tests

---

Contributing

See CONTRIBUTING.md.

---

Legal

• Tool license: MIT — see LICENSE
• Downloaded content: Copyright Intellectual Reserve, Inc. — see LICENSE-CONTENT.md

This tool accesses publicly available content using a transparent User-Agent string, respects robots.txt, and applies a rate-limiting delay between requests. It is intended for personal, noncommercial use only.