VIDX — Scripture Video Generator

Repository: https://github.com/beniza/vidx

🌟 NEW USERS & TEAM MEMBERS: Please read our Complete Getting Started & Distribution Guide for simple, non-technical instructions on generating Scripture videos and publishing them to YouTube!

vidx is a powerful, CLI-first, configuration-driven automation engine designed for Bible translation teams. If your team has already built a Scripture App in Scripture App Builder (SAB), VIDX reuses those same assets — no re-work required. It combines three core Bible translation assets into broadcast-quality lyric videos and standalone subtitle files:

1. USFM Scripture Files (e.g., src/snd/42MRKsnd.SFM)
2. Audio Recordings (e.g., src/snd/42MRKSND.mpeg, your studio-recorded narration audio)
3. Verse-Level Timing Maps (e.g., src/snd/C01-01-MRK-05-timing.txt generated by Scripture App Builder)

vidx is a fully self-contained, high-performance video and subtitle engine. It integrates a native USFM 3.0 syntax parser (vidx.usfm_parser) directly into its rendering pipeline, transforming static text and timestamp data into dynamically styled video streams or SRT/ASS subtitles:

┌──────────────────────────────────────────────────────────────┐
│                    VIDX Automation Engine                    │
├──────────────────┬──────────────────┬────────────────────────┤
│  Config Module   │  ASS Generator   │     FFmpeg Builder     │
│  (YAML / Rules)  │  (Styles/Events) │    (Filter/Render)     │
└────────┬─────────┴────────┬─────────┴───────────┬────────────┘
         │                  │                     │
         ▼                  ▼                     ▼
  [examples/*.yaml]  [vidx.usfm_parser]   [FFmpeg + libass]
                      (Internal Core)     (Hardware / Multi-core)

• usfm_parser (Internal Core): Native USFM 3.0 syntax parser that removes formatting noise (footnotes \f, cross-references \x, and figure tags \fig) while dynamically aligning text segments with audio timestamps. Enables whole-book processing where multiple chapters share a single .SFM source file!
• ASSGenerator: Compiles USFM verses and timing entries into Advanced SubStation Alpha (.ass) and SubRip (.srt) subtitle files. Handles complex Indic/Devanagari text shaping, section headings (\s1, \s2), and customizable verse numbering (5:1).
• FFmpegBuilder: Dynamically builds hardware-accelerated FFmpeg command pipelines. Loops static image backgrounds or video loops, pads/crops to any aspect ratio, and composites subtitles via libass + HarfBuzz.
• BatchRunner: Orchestrates multi-chapter rendering jobs sequentially or in parallel across multi-core CPU workers (-w 4), supporting dual-purpose subtitle-only extraction (--generate-only).

• Python: 3.10 or higher
• FFmpeg: Version 4.3+ compiled with --enable-libass and --enable-libharfbuzz (standard on modern Linux/Windows/macOS builds).
• Fonts: Target fonts (e.g., Nirmala UI, Bailey, Mangal, Noto Sans Devanagari) must be installed on your operating system.

Since all USFM parsing dependencies are built directly into vidx, installation is a clean, single-step process:

# Clone the repository and install in editable mode
git clone https://github.com/beniza/vidx.git
cd vidx
pip install -e .

Verify the CLI installation:

vidx --help

Rendering and subtitle generation need nothing beyond the base install. Two features ship as optional extras because they pull in large dependencies — install them only if you need them:

⚠️ If you plan to upload to YouTube, install the youtube extra now. Without it, vidx --manifest ... fails with No module named 'google' — the Google Cloud credentials setup is entirely separate and will not fix this. Verify with:

python -c "import google.oauth2, googleapiclient; print('youtube extra OK')"

Quote the brackets (".[youtube]") — some shells, notably zsh, treat [ and ] as glob characters and will otherwise report "no matches found".

To compile a portable, self-contained executable for distribution to team members without requiring Python:

# Install PyInstaller and the extras you want baked into the .exe
pip install pyinstaller
pip install -e ".[youtube]"

# Compile standalone binary using the project specification
pyinstaller --clean vidx.spec

The compiled binary will be generated at dist/vidx.exe. You can distribute this single file along with your project assets to any Windows machine.

⚠️ Install the youtube extra before building. vidx.spec pulls the Google API modules in via collect_submodules('google.auth') and friends, which return an empty list without error if those packages aren't present in the build environment. The build succeeds, and the resulting .exe then fails at runtime with No module named 'google'. Always test the artifact before distributing it:

dist/vidx.exe --manifest path/to/publish_manifest.json

The align extra is deliberately not bundled — the speech model is downloaded at runtime, so use the Python install for --align.

VIDX includes pre-built sample configurations in the examples/ directory for multiple languages and aspect ratios:

# Render all chapters in a sample configuration
vidx -c examples/sindhi_mark_16x9.yaml

# Execute with 4 parallel CPU workers for rapid processing
vidx -c examples/malayalam_philemon_16x9.yaml -w 4

# Shakedown Test: Render only the first 15 seconds of each job to verify styling
vidx -c examples/sindhi_mark_16x9.yaml -t 15

# Production pattern validated on real multi-book batches: GPU encoding, 4 parallel
# workers, and -y to auto-confirm the one-time 4K-background-to-1080p downscale prompt
vidx -c examples/whole_book_batch.yaml --gpu -y -w 4

# Or, using the standalone packaged executable (no Python install required)
dist\vidx.exe -c examples\whole_book_batch.yaml --gpu -y -w 4

Convert a single chapter directly from the command line without creating a YAML file:

vidx \
  --usfm src/snd/42MRKsnd.SFM \
  --timing src/snd/C01-01-MRK-05-timing.txt \
  --audio src/snd/42MRKSND.mpeg \
  --bg src/snd/bg.mp4 \
  -o output/Mark_Ch05_16x9.mp4

Use vidx as a pure batch subtitle generator to extract .srt or .ass subtitle files in milliseconds without rendering MP4 video:

# Extract both SubRip (.srt) and Aegisub (.ass) subtitles for an entire batch YAML project
vidx -c examples/sindhi_mark_16x9.yaml --generate-only --format both

# Or generate a standalone SRT subtitle file directly from command line
vidx --generate-only --format srt \
  --usfm src/snd/42MRKsnd.SFM \
  --timing src/snd/C01-01-MRK-05-timing.txt \
  -o output/Mark_05.srt

Every batch render writes a publish_manifest.json "outbox" alongside its output. Publishing is a separate, resumable step — run it any time after rendering, including the next day if YouTube's daily upload quota pauses it partway through:

vidx --manifest output/mark_video_book/publish_manifest.json

Re-running the exact same command resumes from wherever it left off, without re-uploading or re-rendering anything already done. See docs/publishing_guide.md for the full OAuth setup walkthrough.

If you don't already have timing files from Scripture App Builder, VIDX can generate them directly from your audio and USFM text. This is an optional extra because it downloads a speech model:

pip install vidx[align]

vidx --align --usfm src/mal/42MRKMAL10RO.SFM --audio src/mal/mrk/audio/01.mp3 \
     --lang mal --book MRK -o timing/

The chapter number is inferred from the audio filename when possible; pass --chapter to be explicit. Use --level phrase to split verses at punctuation into 1a/1b/1c segments the way SAB's phrase-level timings do. The output is an ordinary SAB-compatible timing file, so everything downstream of it is unchanged.

\s section headings are timed as s1/s2/... segments, matching SAB, because narrators normally read them aloud — leaving them out makes the following verse absorb the heading audio. If your recording skips them, pass --no-headings.

Under the hood this uses Meta's MMS-300M-1130 forced aligner (Wav2Vec2 CTC, 1130+ languages) through ONNX Runtime — no PyTorch. Text is romanized with uroman first, which is why it works on Malayalam, Sindhi, Devanagari and Arabic scripts alike rather than being limited to a fixed language list. The model (~340MB, INT8) downloads once to ~/.vidx/mms-aligner/.

Note: the MMS model is licensed CC-BY-NC 4.0 (non-commercial), unlike VIDX itself (MIT). It is downloaded at runtime rather than bundled, so nothing NC-licensed ships inside VIDX.

A timing file's body is byte-for-byte an Audacity label track, so no special editor is needed — export, drag the boundaries against the waveform, and merge back:

vidx --timing timing/MRK-01-timing.txt --to-labels labels.txt
#   Audacity: File > Import > Labels ... drag ... File > Export > Export Labels
vidx --timing timing/MRK-01-timing.txt --from-labels labels.txt

Editing a boundary moves the end of one segment and the start of the next together, so the file stays contiguous.

Generated timing files are saved inside your project, beside the audio they describe — if your audio lives in audio/, the timing file goes to a sibling timing/ folder, matching the SAB layout. Existing files are never overwritten without asking (-y to skip the prompt). See docs/alignment_guide.md for the full walkthrough, accuracy figures, and troubleshooting.

Below is an overview of standard project configuration options (see examples/ for ready-to-use templates):

project:
  name: "Sindhi Mark Video Project"
  output_dir: "output"
  generate_only: false          # Set true to bypass video rendering and only output subtitles
  subtitle_format: "both"       # Subtitle format: "ass", "srt", or "both"

video:
  resolution: "1920x1080"       # "1920x1080" (Landscape), "1080x1920" (Vertical Shorts), "1080x1080" (Square)
  fps: 24
  codec: "libx264"
  preset: "fast"
  crf: 23                       # Quality: 18 (near lossless) to 28 (compressed)
  background_media: "src/snd/bg.mp4" # Video clip or static image (.jpg/.png)
  loop_background: true         # Loop background video to match audio length
  scaling_mode: "pad"           # Aspect ratio handling: 'pad' (black bars), 'crop', or 'stretch'

style:
  verse:
    font: "Bailey"              # Target font family
    size: 48
    color: "#FFFFFF"            # Primary lyric text color (#RRGGBB)
    outline_color: "#000000"
    outline_width: 3
    shadow: 1
    alignment: 2                # 2 = Bottom-Center (standard subtitle positioning)
    margin_bottom: 60           # Set to 140+ for Vertical Shorts/Reels to avoid UI overlay
    margin_lr: 60
    background_box: true        # Enable semi-transparent bounding box for legibility
    background_color: "#000000" # Base color for background box
    background_opacity: 0.60    # Explicit opacity (0.0 to 1.0) or transparency (0 to 100)

  heading:
    font: "Bailey"
    size: 56
    color: "#FFD400"            # Gold color for section titles (\s1, \s2)
    alignment: 8                # 8 = Top-Center
    margin_vertical: 80
    bold: true

  verse_number:
    show: true                  # Display reference prefix (e.g., "Mark 5:1")
    color: "#FFC080"            # Accent emphasis color
    size: 36
    on_every_segment: false     # If false, displays reference only on first fragment (a) of a split verse

  overlay:
    enabled: true
    title: true                 # Derive chapter title automatically
    title_position: 5           # ASS alignment (5=Middle-Center, 8=Top-Center)
    watermark_text: "BRAND"     # Text watermark on video
    watermark_position: 4       # Watermark alignment (4=Middle-Left, 7=Top-Left)
    watermark_opacity: 0.50     # Watermark transparency level

jobs:
  - usfm: "src/snd/42MRKsnd.SFM"
    timing: "src/snd/C01-01-MRK-05-timing.txt"
    audio: "src/snd/42MRKSND.mpeg"
    output: "output/Mark_Chapter_05_16x9.mp4"
    background: "src/snd/bg.mp4"              # Per-job background override
    background_music: "src/snd/music.mp3"     # Per-job music override ("none" disables)
    background_music_volume: 0.15

• Configuration & Bulk Processing Guide: Exhaustive reference for YAML configuration, typography, transparency, bulk book/NT jobs, and dual-purpose subtitle generation.
• User Guide & Tutorials: Step-by-step walkthroughs for field coordinators and technicians.
• Timing File Guide: How to generate verse timing maps from your audio with --align, and fine-tune them in Audacity.
• YouTube & Video Publishing Guide: Google Cloud key setup, choosing which YouTube channel you upload to, quota handling, and offline Studio packages.
• Project Brief & Advisory Council Decisions: Historical background and engineering decisions.
• Project Roadmap & TODOs: Active milestones, Test-Driven Development (TDD) rules, CI/CD pipelines, and future feature enhancements.