User Guide & How-To

First Launch

When you first open The Better Bible, you'll be guided through a quick setup:

1. Choose your preferred Bible translation (KJV, AKJV, ASV, WEB, YLT, or GNV)
2. Optionally sign in with your Apple ID to enable CloudKit sync
3. Grant necessary permissions for features like audio playback
4. Start reading! The app opens to Genesis 1 by default

Basic Navigation

• Switch Books: Tap the book name at the top to open the book selector
• Navigate Chapters: Use the Previous/Next buttons at the bottom, or swipe left/right
• Quick Jump: Tap the chapter number to open a chapter grid for fast navigation
• Jump to Verse: Tap a chapter in the grid, then select a specific verse
• Search: Tap the search icon to find any word or phrase across the entire Bible

Interface Overview

• Top Bar: Current book and chapter, translation selector, search
• Main Area: Bible text with verse numbers
• Bottom Bar: Previous/Next navigation, bookmarks, and settings
• Sidebar: Access bookmarks, history, notes, and settings (swipe from left or tap menu)

Reading Modes

The Better Bible offers two reading layouts:

• Verse-by-Verse: Each verse appears on its own line with clear verse numbers. Perfect for study and reference lookup.
• Paragraph Mode: Verses flow together in natural paragraphs for a more traditional book reading experience.

To switch: Open Settings → Display → Toggle "Reading Mode"

Text Customization

Adjust the text to your preferences:

• Font Size: Settings → Display → Drag the font slider (12-24pt)
• Dark Mode: Automatically follows your device's system settings
• Red Letters: Some translations show Jesus' words in red (where applicable)

Translation Management

Six public domain translations are included:

• KJV - King James Version (1611)
• AKJV - American King James Version
• ASV - American Standard Version (1901)
• WEB - World English Bible
• YLT - Young's Literal Translation
• GNV - Geneva Bible (1599)

Switch translations: Tap the translation name at the top → Select a new translation

Importing Custom Bible Translations

The Better Bible supports importing your own Bible translations via JSON files. This allows you to use translations not included by default, such as NIV, ESV, NASB, or translations in other languages.

How to Import a Translation:

1. Obtain a properly formatted JSON file (see format below)
2. Save the JSON file to your device (Files app, iCloud Drive, or any accessible location)
3. Open The Better Bible → Settings → Translations
4. Tap "Import Translation"
5. Navigate to your JSON file and select it
6. The app will validate the format and import the translation
7. Your new translation will appear in the translation selector

Required JSON Format:

The Bible JSON must follow this nested structure for proper compatibility:

{
  "metadata": {
    "name": "Translation Name",
    "abbreviation": "TRN",
    "language": "English",
    "year": "2024",
    "copyright": "Public Domain",
    "description": "Optional description"
  },
  "books": {
    "Genesis": {
      "1": {
        "1": "In the beginning God created the heaven and the earth.",
        "2": "And the earth was without form, and void...",
        "3": "And God said, Let there be light: and there was light."
      },
      "2": {
        "1": "Thus the heavens and the earth were finished...",
        "2": "And on the seventh day God ended his work..."
      }
    },
    "Exodus": {
      "1": {
        "1": "Now these are the names of the children of Israel..."
      }
    }
  }
}

Format Details:

• Top Level: Must contain "metadata" and "books" objects
• Metadata Fields:
  • name: Full translation name (required)
  • abbreviation: Short code like "NIV" or "ESV" (required)
  • language: Language name (optional)
  • year: Publication year (optional)
  • copyright: Copyright information (required)
  • description: Additional info (optional)
• Books Structure: Nested 3 levels deep
  • Level 1: Book name (string key)
  • Level 2: Chapter number (string key)
  • Level 3: Verse number (string key) → Verse text (string value)
• Book Names: Must use standard English book names (see list below)
• Numbers: Chapter and verse numbers must be strings, not integers
• Text: Verse text should be plain text (no HTML or special formatting)

Required Book Names (66 Books):

Example: Minimal Valid Translation

{
  "metadata": {
    "name": "My Custom Translation",
    "abbreviation": "MCT",
    "copyright": "Public Domain"
  },
  "books": {
    "Genesis": {
      "1": {
        "1": "In the beginning...",
        "2": "And the earth..."
      }
    },
    "Matthew": {
      "1": {
        "1": "The book of the genealogy..."
      }
    }
  }
}

Finding Public Domain Translations:

Several websites offer public domain Bible translations in JSON format:

• API.Bible - Free API access to multiple translations
• Bible Gateway - Some public domain texts available
• GitHub - Many open-source Bible projects
• Internet Archive - Historical translations

Note: You may need to convert other formats (XML, CSV, TXT) to JSON following the structure above.

Getting Started with Audio

1. Navigate to any chapter you want to hear
2. Tap the play button (▶) at the bottom of the screen
3. Watch as each word highlights in sync with the audio
4. Tap pause at any time to stop playback

Audio Settings

• Voice Selection: Settings → Audio → Choose from multiple voice options
• Speed Control: Adjust playback speed from 0.3x to 2.0x for comfortable listening
• Skip Verse Numbers: Enable this option to skip reading verse numbers (reads only the text)
• Auto-Continue: Automatically continue to the next chapter when the current one finishes

Personal Voice (iOS 17+)

On iOS 17 and later, you can create and use Personal Voice - a synthesized voice that sounds like you or a loved one. This feature is perfect for accessibility or hearing Scripture in a familiar voice.

How to Record Your Personal Voice:

1. Open iOS Settings → Accessibility → Personal Voice
2. Tap "Create a Personal Voice" and follow the on-screen instructions
3. Read the preview text to understand what's required
4. Start recording in a quiet place with no background noise
5. Read 150 phrases clearly and naturally (takes 15-20 minutes)
   • You can pause and resume anytime
   • The phrases are randomly selected
   • Speak naturally - don't rush or over-enunciate
   • Keep your device 6-8 inches from your mouth
6. Wait for processing - iOS will process your voice overnight (while charging and connected to Wi-Fi)
7. Receive notification when your Personal Voice is ready (usually 12-24 hours)

Using Personal Voice in The Better Bible:

1. Once your Personal Voice is created in iOS Settings
2. Open The Better Bible → Settings → Audio → Voice Selection
3. Scroll to the "Personal Voice" section
4. Select your Personal Voice from the list
5. Start reading any chapter - it will now be read in your voice

Note: Personal Voice is end-to-end encrypted and never leaves your devices without your permission. It's designed for individuals who are at risk of losing their ability to speak.

Downloading Additional Voices

iOS includes many voices beyond the default. You can download premium, enhanced, and additional language voices:

How to Download More Voices:

1. Open iOS Settings → Accessibility → Spoken Content → Voices
2. Select a language (e.g., English)
3. Browse available voices - you'll see quality indicators:
   • Default Quality: Pre-installed, smaller file size (~50-100 MB)
   • Enhanced Quality: Better sound, download required (~150-300 MB)
   • Premium Quality: Most natural, largest files (~500 MB-1 GB)
4. Tap the download icon (☁️) next to any voice to download it
5. Wait for download - premium voices may take several minutes on Wi-Fi
6. Check completion - a checkmark (✓) appears when ready

Recommended Voices for Bible Reading:

• English (US):
  • Samantha (Premium) - Clear, professional female voice
  • Aaron (Premium) - Deep, authoritative male voice
  • Nicky (Enhanced) - Warm female voice
• English (UK):
  • Daniel (Premium) - Classic British male voice
  • Serena (Premium) - Elegant British female voice
• Other Languages: Available in 40+ languages with multiple voices each

Using Downloaded Voices: Once downloaded in iOS Settings, the voices automatically appear in The Better Bible's voice selection menu (Settings → Audio → Voice Selection).

How to Highlight

1. Long-press on any verse to open the highlight menu
2. Select a color: Yellow, Green, Orange, Pink, or Purple
3. The verse will now display with a colored background
4. To remove a highlight, long-press again and tap "Remove Highlight"

Organizing Your Highlights

Create your own system for organizing highlights. Many users use:

• Yellow: Key verses or general importance
• Green: Promises or encouragement
• Orange: Warnings or commands
• Pink: Verses about love or relationships
• Purple: Verses to memorize

Your system can be whatever works best for your study!

Viewing Highlights

• In Reading: Highlighted verses appear with colored backgrounds as you read
• Highlights List: Sidebar → Highlights → See all highlights grouped by color
• Filter by Color: Tap a color chip to see only those highlights
• Search Highlights: Use the search bar to find specific highlighted verses

Export & Share

Share your highlights with others:

1. Open Sidebar → Highlights
2. Tap the export button (⬆)
3. Choose format: JSON (for backup), PDF, or Text
4. Share via Messages, email, or save to Files

Creating Notes

1. Long-press on any verse
2. Tap "Add Note" from the menu
3. Type your note in the text field
4. Select one or more tags (optional): Prayer, Study, Question, Insight, Memorize
5. Tap "Save"

Verses with notes show a small note icon (📝) next to the verse number.

Smart Tags Explained

• 🙏 Prayer: Prayer requests, verses to pray, or prayer reflections
• 📚 Study: Theological insights, word studies, or research notes
• ❓ Question: Questions about the text or things to research later
• 💡 Insight: Personal revelations or "aha" moments
• ⭐ Memorize: Verses you're working on memorizing

You can apply multiple tags to a single note for flexible organization.

Managing Notes

• View All: Sidebar → Notes → See all your notes chronologically
• Filter by Tag: Tap a tag to see only notes with that tag
• Edit: Tap any note to edit the text or tags
• Delete: Swipe left on a note and tap Delete
• Search: Use the search bar to find notes by keyword

Rich Text Formatting

Notes support rich text formatting:

• Bold, italic, and underline text
• Bulleted and numbered lists
• Multiple paragraphs
• Links to other verses

Use the formatting toolbar above the keyboard when editing notes.

Viewing Cross-References

Verses with cross-references show a small link icon (🔗) next to the verse number.

1. Tap the link icon or the verse number
2. See a list of related verses with relationship types
3. Tap any reference to jump to that verse
4. Use the back button to return to your original location

Relationship Types

Cross-references are categorized by seven relationship types:

• Quotation: One passage directly quotes another
• Allusion: One passage alludes to or echoes another
• Parallel: Similar events or teachings
• Fulfillment: Prophecy and its fulfillment
• Theme: Verses sharing a common theme
• Contrast: Verses presenting contrasting viewpoints
• General: Other meaningful connections

Creating Custom Cross-References

1. Long-press on a verse
2. Tap "Add Cross-Reference"
3. Use the reference picker to select the related verse
4. Choose a relationship type
5. Optionally add a note explaining the connection
6. Tap "Save"

Custom cross-references appear alongside built-in ones, marked with a star (⭐).

Using Cross-References for Study

Cross-references are powerful for:

• Tracing themes throughout Scripture
• Understanding Old Testament prophecies and New Testament fulfillments
• Comparing parallel Gospel accounts
• Finding related teachings on a topic
• Building your own topical study chains

Comparing Verses

Compare any verse across multiple translations side-by-side:

1. Long-press on a verse
2. Tap "Compare Translations"
3. View the verse in all installed translations
4. Swipe to scroll through translations
5. Tap any translation to switch to it for reading

Multi-Select Comparison

Compare multiple verses at once:

1. Tap to select multiple verses
2. Tap "Compare" in the selection toolbar
3. View all selected verses across translations
4. Perfect for studying parallel passages or multiple verses on a topic

Available Translations

Basic Search

1. Tap the search icon (🔍) at the top of the screen
2. Type your search term or phrase
3. Results appear as you type, showing verse snippets
4. Tap any result to jump to that verse

Search Tips

• Exact Phrase: Use quotes: "love your neighbor"
• Multiple Words: Space-separated words find verses containing all words
• Case Insensitive: Search is not case-sensitive
• Partial Match: Search for "righteou" to find "righteous," "righteousness," etc.

Filters

Narrow your search with filters:

• Testament: Search only Old or New Testament
• Book: Limit search to a specific book
• Translation: Search in a specific translation
• My Content: Search only verses with highlights, notes, or bookmarks

Search History

Recent searches are automatically saved. Tap any past search to run it again. Clear search history in Settings → Privacy → Clear Search History.

Creating a Reading Plan

1. Open Sidebar → Reading Plans
2. Tap "Create New Plan"
3. Choose a template or start from scratch:
   • Read the Bible in a Year
   • New Testament in 90 Days
   • Gospels in 30 Days
   • Psalms & Proverbs
   • Custom Plan
4. Set your start date
5. Customize the reading schedule
6. Name your plan and tap "Create"

Following a Plan

• Today's Reading: Opens automatically when you launch the app
• Mark Complete: Tap the checkmark when finished
• Get Ahead: View and complete future readings
• Catch Up: Missed readings stay accessible
• Progress Bar: See your overall plan progress

Sharing Plans

Share reading plans with your small group or family:

1. Open the plan you want to share
2. Tap the share button (⬆)
3. Choose export format: JSON (for other app users) or PDF (for printing)
4. Share via Messages, email, or your group chat

Importing plans: Sidebar → Reading Plans → Import → Select the JSON file

Managing Multiple Plans

You can have multiple active reading plans:

• Daily devotional plan
• Long-term full Bible reading
• Topical study plan
• Group study plan

The app tracks progress for each plan independently.

Adding Bookmarks

Three ways to bookmark:

1. Single Verse: Long-press → Tap "Bookmark"
2. Multiple Verses: Select verses → Tap "Bookmark" in toolbar
3. Current Chapter: Tap the bookmark icon at the bottom

Viewing Bookmarks

• Bookmark List: Sidebar → Bookmarks
• Sort: By date added, book order, or name
• Search: Find specific bookmarked passages
• Navigate: Tap any bookmark to jump to that location

Organizing Bookmarks

Keep your bookmarks organized:

• Name: Give bookmarks custom names (tap to edit)
• Delete: Swipe left on any bookmark
• Bulk Delete: Tap "Edit" → Select multiple → Delete

Reading History

The app automatically tracks your reading:

• View History: Sidebar → Reading History
• Recent Chapters: See recently read chapters
• Reading Streaks: Track consecutive days of reading
• Statistics: View chapters read, time spent, and more

Privacy: All history stays on your devices via CloudKit. We don't see or collect it.

Setting Up Sync

1. Make sure you're signed in with your Apple ID on all devices
2. Enable iCloud Drive in Settings → [Your Name] → iCloud → iCloud Drive
3. Open The Better Bible on each device
4. The app will ask for permission to use CloudKit—tap "Allow"
5. Your data will start syncing automatically

Note: Initial sync may take a few minutes depending on how much data you have.

What Syncs?

Everything you create syncs across devices:

• Highlights (all colors)
• Notes and tags
• Bookmarks
• Cross-references (custom ones)
• Reading plans and progress
• Reading history
• Current reading location
• Settings and preferences

What doesn't sync: Bible translations (downloaded separately on each device for offline use)

Sync Status

Check sync status:

• Settings → CloudKit: View sync status
• Last Sync: See when data last synced
• Sync Now: Force an immediate sync
• Conflicts: Rare, but the app will help you resolve them

Troubleshooting Sync

If sync isn't working:

1. Check that you're signed in to iCloud on all devices
2. Verify iCloud Drive is enabled
3. Check your internet connection
4. Make sure you have iCloud storage available
5. Try forcing a sync: Settings → CloudKit → Sync Now
6. Restart the app or device

Still having issues? Contact us at support@thebetterbible.com

Using Without Sync

CloudKit sync is completely optional. The Better Bible works fully offline and can be used without any Apple ID or internet connection. Your data will stay local to each device.

💻 iPad Features

• Split View: Use The Better Bible alongside other apps. Drag it to either side of the screen for multitasking.
• Apple Pencil: Take handwritten notes directly on verses (appears as typed text after conversion)
• Keyboard Shortcuts: Connect a keyboard and use shortcuts:
  • ⌘F - Search
  • ⌘B - Bookmarks
  • ⌘N - New Note
  • ⌘[ and ⌘] - Previous/Next Chapter
  • ⌘, - Settings
• Larger Layout: Optimized reading experience with better use of screen space

🖥️ Mac Features

• Native Mac App: Optimized for macOS with native window management, toolbar, and menu bar
• Keyboard Shortcuts: Full keyboard navigation:
  • ⌘F - Search
  • ⌘B - Bookmarks
  • ⌘N - New Note
  • ⌘[ and ⌘] - Previous/Next Chapter
  • ⌘1, ⌘2, etc. - Switch translations
  • ⌘+ and ⌘- - Adjust font size
  • ⌘, - Settings
• Touch Bar: Quick access to highlights, bookmarks, and navigation on MacBook Pro
• Menu Bar: All features accessible via native macOS menus
• Window Management: Multiple windows, tabs, and full-screen support

📺 Apple TV Features

• Siri Remote Navigation: Optimized for TV remote control
  • Swipe to navigate chapters
  • Click to select verses
  • Hold to bring up menus
• Large Text: Text sized perfectly for reading across the room
• Family Devotions: Perfect for group Bible study or family worship
• Audio Focus: Enhanced audio playback experience
• Limited Features: Focus on reading and audio; no note-taking or highlighting on TV

⌚ Apple Watch Features

• Complications: Add a Bible verse to your watch face
  • Verse of the Day
  • Current reading plan verse
  • Random verse
• Standalone App: Works without iPhone nearby (with downloaded translations)
• Digital Crown: Scroll through chapters with the crown
• Quick Access: View bookmarked verses, reading plan progress
• Audio Playback: Listen via AirPods or watch speaker

Accessibility Features

• VoiceOver: Full VoiceOver support for visually impaired users
• Dynamic Type: Text scales with iOS system settings
• High Contrast: Increased contrast mode for better readability
• Reduce Motion: Respects reduce motion settings
• Personal Voice: Use your own voice or a loved one's for audio

Study Workflows

Offline Usage

The Better Bible is designed to work 100% offline:

• Download Translations: Install all translations you want while online
• No Internet Required: Reading, highlighting, notes, and all features work offline
• Sync When Available: Changes sync automatically when you connect to internet
• Perfect for Travel: Use on planes, in remote areas, or anywhere without service

Common Issues

Getting More Help

If you're still experiencing issues:

• Support Page: Visit /support for FAQs and contact info
• Email: support@thebetterbible.com (we typically respond within 24 hours)
• Include: Device model, OS version, app version, and screenshots if possible