Magnify Documentation

1. Getting Started

1.1 Installation as PWA

Magnify is a Progressive Web Application (PWA) — it installs like a native app but runs securely in your browser.

Desktop (Chrome / Edge / Firefox): Navigate to the Magnify URL → click the Install icon in the address bar → click Install. A desktop shortcut is created, and Magnify opens in its own window with no browser chrome.

Android (Chrome): Open the URL → tap the browser menu (three dots) → Add to Home screen → Add.

iOS (Safari): Tap the Share button → scroll down → Add to Home Screen → Add.

1.2 Running in Browser

No installation required. Open the URL in any modern browser and all features work identically. The only difference: the update-available modal is suppressed in browser tab mode since you can manually refresh to get updates.

1.3 System Requirements

Note: If the window is narrower than 960px, a blocker overlay appears: "For accurate live services, Magnify requires a screen at least 960px wide."

1.4 First Launch

A splash screen displays the Magnify logo with a ~1 second loading animation. The app initializes with demo data (two sample songs: "Way Maker" and "Amazing Grace") so you can explore the interface immediately.

2. Application Layout

Magnify is divided into three main sections:

┌──────────────────────────────────────────────────────────┐
│  ┌──────────────┐  ┌──────────────────────────────────┐  │
│  │   SIDEBAR    │  │  Stage Header (Song Title + Ctrl) │  │
│  │   (320px)    │  ├──────────────────────────────────┤  │
│  │              │  │          STAGE / MAIN AREA        │  │
│  │  Library /   │  │    (Filmstrip | Bible | Media)    │  │
│  │  Playlist    │  │                                   │  │
│  │              │  ├──────────────────────────────────┤  │
│  │              │  │   LIVE PREVIEW (Bottom Panel)     │  │
│  └──────────────┘  └──────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

Sidebar (Left Panel)

Contains the logo, a search bar, Library/Playlist tabs, the song list, and an Add Song floating action button.

Stage / Main Area (Center Panel)

The stage header shows the current song title and action buttons (Open Projector, Clear, Blackout, Settings, Fullscreen). Below it, a tab bar switches between Filmstrip (slide deck), Bible (navigation & projection), Media (image/video/PDF management), and Overlays.

Live Preview (Bottom Panel)

A miniature view of exactly what is being projected. Can be collapsed/expanded via the toggle handle or the P keyboard shortcut. Shows a pulsing red "LIVE" indicator when a projector window is connected.

3. Songs & Lyrics System

3.1 Adding Songs

Manual entry: Click the + button at the bottom of the sidebar, enter a title, type or paste your lyrics, then click Save.

Typing/Pasting: Paste lyrics from any source. The app automatically splits lyrics into slides based on blank lines (see below).

3.2 Editing Songs

Click the three-dot menu (⋮) next to a song → Edit. Modify the title or lyrics, then click Save. To delete, click the ✕ button or use the Edit menu.

3.3 Slide Formatting

Each physical line of text = one line on screen. A blank line separates slides. Empty lines at the start or end are automatically trimmed.

You are here, moving in my heart
I worship You, I worship You

You are here, working in this place
I worship You, I worship You

Way maker, miracle worker, promise keeper
Light in the darkness
My God, that is who You are

This creates 3 slides, each with multiple lines.

3.4 Tags

Comma-separated labels (e.g. "worship, praise, contemporary") displayed as badges below the song title. The search bar filters by both title and tags.

3.5 Searching

Live filtering with 300ms debounce — searches both song titles and tags as you type.

4. Playlist / Service Order

4.1 Library vs Playlist Mode

Library — shows all songs. Click any song to view and project it.
Playlist — an ordered list of songs for your service. Navigate through them in sequence.

4.2 Creating & Managing Playlists

By default a "Default Playlist" is created. You can add new playlists, rename them, or delete them (deleting a playlist does not delete the songs). The app remembers the last active playlist.

4.3 Adding to Playlist

In Library mode, each song has a + button. Clicking it adds the song to the end of the active playlist.

4.4 Reordering

In Playlist mode, use the ↑ and ↓ buttons next to each song to reorder.

4.5 Navigating During Service

Clicking a song loads its slides. Auto-advance: reaching the last slide of a song automatically loads the next playlist item. Ghost entries (deleted songs) are skipped automatically.

5. Slide Navigation & Projection

5.1 Selecting a Song

Click any song in the sidebar to load it into the stage, render its slides as a filmstrip, and switch to the Filmstrip tab.

5.2 Filmstrip

A horizontal, scrollable row of slide cards. Each shows a preview of the text and slide number. The live slide has a highlighted border. Click any card to jump directly to that slide.

5.3 Firing a Slide

Click a slide card to project it. Active line mode resets to line 0. Any active Bible projection is cleared.

5.4 Next / Previous

Press → (ArrowRight) or Space for the next slide. Press ← (ArrowLeft) for the previous slide. These also advance Bible verses when on the Bible tab.

5.5 Active Line Mode

A cinematic text reveal (toggled in Settings → Controls):

• One line is fully highlighted at a time
• Past lines are dimmed (opacity 0.5, blur 0.5px)
• The active line has full opacity, a floating animation, and a purple glow
• ↓ / ↑ navigates lines; 1–9 jumps directly to a line
• Reaching the last line auto-advances to the next slide

5.6 Auto-Advance Through Playlist

When Active Line Mode is on and you're in Playlist mode, the app seamlessly loads the next/previous song as you navigate through the last/first line of each song.

6. Bible Projection System

6.1 Uploading Bible Versions

Go to the Bible tab. Drag & drop a .json file onto the upload area, or click to browse. The app validates the JSON structure and displays an error if invalid. Multiple versions can be uploaded.

6.2 JSON Format

Your Bible JSON must follow this structure:

{
  "metadata": {
    "name": "King James Version",
    "language": "en",
    "description": "The Authorized Version"
  },
  "verses": [
    {
      "book_name": "Genesis",
      "chapter": 1,
      "verse": 1,
      "text": "In the beginning God created the heaven and the earth."
    }
  ]
}

6.3 Selecting & Parallel Display

Use the Version dropdown to switch versions. Select a Parallel version to display two translations side by side. To disable parallel mode, select "None".

6.4 Navigating

Five cascading custom dropdowns: Version → Parallel → Book → Chapter → Verse. Selecting a book populates the chapter list; selecting a chapter populates the verse list.

6.5 Custom Dropdown Keyboard Navigation

Tab cycles through dropdowns. Enter/Space opens. ↑/↓ navigates options. Enter selects. Esc closes. Type a letter to jump to that option.

6.6 Verse Selection & Projection

Click verses to select/deselect (highlighted with a left border). Click Send to Projector to project with book/chapter/verse reference displayed above the text.

6.7 Bible Search

The search box searches verse text across the active version. Results show reference and snippet. Click a result to navigate directly to that verse.

6.8 Bible Playlist

Save selected verses to a persistent Bible Playlist. Navigate through it using Next/Prev buttons.

7. Media Library & PDF Decks

7.1 Supported Formats

7.2 Uploading & Grid

Drag & drop files onto the upload zone in the Media tab. Files appear in a responsive grid. Videos show a ▶ overlay; PDFs show a 📄 icon with page count.

7.3 Projecting

Double-click an item to project it full-screen. Videos auto-play (muted). The background layer is automatically hidden for clean projection.

7.4 PDF Filmstrip

Click a PDF to open a smooth-scrolling filmstrip with thumbnail cards for each page. Click any page to project it. Navigate with Next/Prev buttons or arrow keys.

8. Background Gallery

8.1 Uploading

Go to Settings → Visuals → Background Gallery. Drag & drop images/videos or click to browse. Backgrounds persist across sessions.

8.2 Applying

Double-click a background card to apply it. Click Reset to Black to clear it. The active background is remembered across sessions.

8.3 Settings

• Dimmer — opacity overlay (0-100%) to darken backgrounds
• Background Color — solid color fallback
• Background Blur — blur effect (0-20px)

9. Overlays System

9.1 What Are Overlays?

Visual media files (textures, light leaks, smoke, bokeh, logos) that blend onto the projector output to add depth and atmosphere.

9.2 Layer Stack

┌─────────────────────────────────────┐
│  Foreground Layer (z-index: 20)     │  ← Overlays on TOP of text
│  Content Layer (z-index: 10)        │  ← Lyrics, Bible, Media
│  Background Layer (z-index: 0)      │  ← Color, Image, Video BG
└─────────────────────────────────────┘

9.3 Foreground vs Background

Foreground sits above lyrics/scriptures — best for light leaks, dust/scratches, gold textures.
Background sits behind text — best for moving fog, bokeh, abstract patterns that don't interfere with readability.

9.4 Blend Modes

9.5 Opacity & Application

The opacity slider (0-100%, default 30%) controls transparency. Double-click an overlay to project it. Select target layer (Foreground/Background) using radio buttons.

10. Scrolling Banner

10.1 Enabling

Open Settings → Controls and toggle Banner on. The banner scrolls horizontally across the top or bottom of the projector.

10.2 Customization

• Text — any scrolling message (e.g. "Welcome to Our Service! 🙏")
• Text Color — pick any color
• Background Color — pick any color for the banner bar
• Position — Top or Bottom (12% screen height)
• Speed — slider (1-100) controlling scroll velocity

11. Countdown Timer

11.1 Two Modes

Duration Mode — countdown from a set number of minutes:seconds.
Service Time Mode — automatically calculates countdown to a specific time.

11.2 Setting a Duration

Use + and - buttons (or type directly) to set minutes and seconds. Click Start.

11.3 Service Time

Enter a time like 4pm, 8:20am, or 10:00 and press Enter. The app calculates the difference from the current local time and starts counting down immediately.

11.4 Dynamic Updating

Change the target time while running — the countdown adjusts instantly. Changes to label, color, and duration are reflected in real-time.

12. Projector & Dual-Display System

12.1 Opening a Projector Window

Click Open Projector in the stage header. A new browser window opens. Drag it to your secondary display and enter fullscreen (F11). The projector URL includes ?mode=projector.

12.2 Presence Detection

The controller sends a heartbeat every second via BroadcastChannel. The projector responds with an ACK. If no response within 3 seconds, the controller shows the projector as disconnected.

12.3 Stage Controls

12.4 Live Preview

The bottom panel shows a miniature version of the projector output, including all layers. Collapse/expand with the toggle handle or P shortcut.

13. Settings Panel

Opens as a sliding drawer from the right side with six tabs:

14. Data Management

14.1 Auto-Save

Songs and settings are saved to IndexedDB automatically after any change. The app tracks unsaved changes for data integrity.

14.2 Backup

Go to Settings → Data → Backup Data. A JSON file is downloaded containing all songs, settings, playlists, and the Bible playlist. (Bible versions are not included — re-upload from source files.)

14.3 Restore

Select a previously downloaded .json backup. Songs with duplicate IDs are renamed (e.g., "Song Title (v2)"). Settings from the backup overwrite current settings.

14.4 Factory Reset

Wipes ALL data with double confirmation. After confirmation, all IndexedDB data is cleared and the app reloads.

15. Keyboard Shortcuts

16. PWA & Offline Features

16.1 PWA Installation

Magnify includes a manifest.json (app name, icons, theme color, display: standalone) and a service worker (sw.js) that caches all static assets on first load.

16.2 Updates

When a new version is deployed, the service worker is downloaded in the background. If you're running as an installed PWA, an "Update Available" modal appears. In a browser tab, just refresh to get the latest version.

16.3 Offline Capabilities

Once loaded, the following work fully offline: song lyrics, Bible versions, settings, media files, backgrounds, overlays, playlists, and the entire UI. Only first-time load requires internet.

17. Technical Architecture

IndexedDB Schema

Database: MagnifyIndexedDB (v2)
├── Object Store: general
│   ├── magnify_pro_db_v5         → Songs array
│   ├── magnify_pro_settings_v5   → Settings object
│   ├── magnify_pro_bible_data_v2 → Bible versions
│   ├── magnify_song_playlist_v1  → Playlists
│   ├── magnify_media_library_v1  → Media metadata
│   ├── magnify_overlay_library_v1 → Overlay metadata
│   └── magnify_bg_gallery_v1     → Background metadata
│
└── Object Store: files
    ├── media_{id}   → Media blobs
    ├── overlay_{id} → Overlay blobs
    ├── bg_{id}      → Background blobs
    └── pdf_{id}     → PDF data

BroadcastChannel Messages

The controller and projector communicate via 16 message types through the magnify_channel BroadcastChannel: LYRICS, BIBLE, CLEAR, BLACKOUT, BANNER, TIMER, MEDIA_PROJECT, CLEAR_MEDIA, DRAWER, VISUALS, SETTINGS, REQUEST_STATE, REMOTE_COMMAND, PRESENCE_ACK, and REQUEST_PRESENCE.

18. Troubleshooting & FAQ

Common Issues

Frequently Asked Questions

Is Magnify completely free?
Yes, 100% free under the GNU AGPLv3. No subscriptions, no data collection, no account needed.

Does it work offline during services?
Yes. Once loaded, everything works offline — songs, Bibles, media, and settings are all stored locally.

What platforms does it support?
Windows, macOS, Linux, ChromeOS, and Android — any device with a modern browser.

Can I import songs from SongSelect or CCLI?
No direct API integration. You can manually type or paste lyrics. CCLI/SongSelect do not offer free public APIs.

How do I update?
If installed as a PWA, the app notifies you. In a browser tab, just refresh the page. No manual update process needed.

Can I use this for non-church events?
Absolutely! Conferences, weddings, concerts, lectures — any presentation need.

Can I open multiple projector windows?
Currently designed for one projector at a time. Multi-projector is a planned future feature.

Is there a stage display (pastor's monitor)?
Not yet — planned for a future release.