# House of Prayer Song Lyrics System

A full-stack React + Flask platform for worship teams to search, collect, organize, edit, and prepare song lyrics with chords.

## Features

- Modern React frontend (navigation, search, pop-ups, profile management)
- Flask REST API backend
- SQLite database for songs, profiles, and planning
- External & local lyric search (ChartLyrics + Lifeway link + EssentialWorship metadata)
- Upload & extract lyrics from .txt, .docx, .pdf, and images (OCR)
- **Smart Chord Assignment**: Automatically detects and excludes section headers (Verse, Chorus, Bridge, etc.) when assigning or transposing chords
- **Cross-Device Sync**: Frontend polling (~5s) propagates changes across devices
- Minimalist, elegant UI

## Getting Started

### Backend (Flask)

```bash
cd backend
python -m venv venv
venv\Scripts\activate  # On Windows
pip install -r requirements.txt
python app.py
```

### Alternative/Convenience Starts (Windows PowerShell)

If you already created a virtual environment and installed packages, you can use these commands to start both services and optionally expose the backend publicly for mobile testing.

Backend (using venv Python and explicit port 5000):

```powershell
cd "E:\Documents\Website Projects\Church_SongLyric\backend"
.\venv\Scripts\python.exe app.py
```

### Frontend (React)

```powershell
cd "E:\Documents\Website Projects\Church_SongLyric\frontend"
& "C:\Program Files\nodejs\npm.cmd" install
& "C:\Program Files\nodejs\npm.cmd" start
```

Expose backend to the internet (LocalTunnel) for phones on cellular/Wi‑Fi outside your LAN:

```powershell
cd "E:\Documents\Website Projects\Church_SongLyric\backend"
& "C:\Program Files\nodejs\npx.cmd" localtunnel --port 5000
```

In the app Settings on your phone:

- Protocol: `https`
- Hostname: `<your-generated>.loca.lt`
- Port: blank (or `443`)

### One‑shot helper script

You can also use the included script to start the backend and create a tunnel in one go:

```powershell
cd "E:\Documents\Website Projects\Church_SongLyric"
./start-server-with-tunnel.ps1
```

The React app runs on port 3000, Flask API on port 5000.

---
There are three reliable ways to run the backend so phones/tablets sync with your data:

- LAN IP (same Wi‑Fi)
  - Backend:

  ```powershell
  cd "E:\Documents\Website Projects\Church_SongLyric\backend"
  .\venv\Scripts\python.exe app.py
  ```

  - Frontend:

  ```powershell
  cd "E:\Documents\Website Projects\Church_SongLyric\frontend"
  & "C:\Program Files\nodejs\npm.cmd" start
  ```

  - App Settings (phone): protocol `http`, hostname = your PC LAN IP (e.g., `192.168.1.50`), port `5000`.

- LocalTunnel (off‑LAN via HTTPS)
  - Backend:

  ```powershell
  cd "E:\Documents\Website Projects\Church_SongLyric\backend"
  .\venv\Scripts\python.exe app.py
  ```

  - Tunnel:

  ```powershell
  & "C:\Program Files\nodejs\npx.cmd" localtunnel --port 5000
  ```

  - App Settings (phone): protocol `https`, hostname `your-subdomain.loca.lt`, port blank (or `443`).

- Router Port Forwarding (public access)
  - Backend binds to all interfaces (default in `app.py`).
  - Router forwards external TCP `5000` → `PC_LAN_IP:5000`.
  - App Settings (phone): protocol `http` (or `https` if using TLS proxy), hostname = your public IP/DNS, port `5000`.

After configuring Settings, open the app’s Settings → Data Synchronization and tap "Full Sync". Check browser console for API base logs to confirm connectivity.

## Folder Structure

- `backend/` — Flask API and database
- `frontend/` — React app

---

## Lyric File Upload & OCR

The Home page includes an "Upload Lyric File" section.

Supported formats:

- Text: `.txt`
- Documents: `.docx`, `.pdf` (first ~20 pages parsed; scanned PDFs use OCR fallback)
- Images: `.png`, `.jpg`, `.jpeg`, `.tif`, `.tiff` (requires Tesseract OCR)

After upload the extracted lyrics open in a modal for review & editing. Click `Save` in the modal to create a Song record.

1. Winget (recommended):

1. Chocolatey:

```powershell

```powershell
setx TESSERACT_OCR "C:\Program Files\Tesseract-OCR\tesseract.exe"
```

You may need to restart your terminal/IDE.

### Installing Poppler (for PDF OCR)

`pdf2image` requires Poppler binaries for PDF-to-image conversion (scanned PDF OCR):

1. Download Windows binaries: <https://github.com/oschwartz10612/poppler-windows/releases/>
2. Extract to `C:\Program Files\poppler` (or other location)
3. Add to PATH:

```powershell
setx PATH "$env:PATH;C:\Program Files\poppler\Library\bin"
```

1. Restart terminal/IDE.

### Notes

- Poor quality or low-resolution images reduce OCR accuracy.
- Scanned PDFs with minimal text layer automatically trigger OCR (first 10 pages).
- Large PDFs are truncated for performance.

---

## Setlist Export

Click the **Export** button in the header to download a formatted `.txt` setlist for any plan:

- Hover over Export → select a plan date → file downloads automatically
- Includes profile info, song order, lyrics, and chords
- Filename format: `setlist_YYYY-MM-DD.txt`

---

## Next Steps

- (Completed) Profiles, songs, planning, search, upload & OCR, setlist export.
- Potential future enhancements: chord auto-detection, multi-format export (PDF, Word), cloud sync.

---

## EssentialWorship Integration (Metadata Only)

You can now toggle the Home page search source to "EssentialWorship Only" to pull worship song metadata directly from EssentialWorship.

What is retrieved:

- Title and a heuristic match to potential song pages
- Link to the original song page
- A short preview snippet (up to 500 chars) extracted from page text if available

What is NOT stored automatically:

- Full copyrighted lyric text (intentionally omitted for compliance)

Copyright & Licensing Notice:

- EssentialWorship lyrics are protected works (© Sony Music Entertainment and publishers)
- Do NOT store, redistribute, or publicly display full lyrics unless you have appropriate licensing (CCLI, direct publisher license, etc.)
- The system deliberately restricts retrieval to short snippets for internal evaluation

If you obtain proper licensing and wish to enable full lyric capture, you must adjust the backend endpoint to lift the snippet limit. Keep audit records of licensing before making that change.

Endpoint Summary:

- `GET /api/essentialworship/search?q=term` → metadata results only
- `GET /api/essentialworship/lyrics?url=...` → snippet + notice (no full lyrics)
- `GET /api/essentialworship/debug?q=term` → (debug preview of raw HTML, first 2000 chars) requires `ENABLE_EW_DEBUG=1` env var, disabled by default

Front-End Usage:

- Use the "All Sources" mode for combined local + external
- Use "EssentialWorship Only" for focused metadata from that provider
- Click "Preview & Save" to open a modal with the snippet and manual save option (stores only the snippet)

Safety Recommendations:

- Store only what is necessary for planning (title, artist, snippet)
- Maintain original source link for reference
- For projection/printing, rely on licensed sources (e.g., Planning Center + CCLI)

Fallback Behavior:

- When no direct EssentialWorship song links are detected the API returns a single metadata entry pointing to the site search URL so users can manually open results.
- This ensures the UI always shows at least one actionable external option.

Enabling Debug Mode:

```powershell
setx ENABLE_EW_DEBUG 1
```

Restart the Node backend after setting. Remove or unset to disable.

---

## Smart Chord Assignment

The system now intelligently handles song structure when assigning or transposing chords:

### Section Header Detection

- Automatically detects common section labels: Verse, Chorus, Bridge, Pre-Chorus, Intro, Outro, Tag, Interlude, Refrain, Hook, Coda, Ending
- Supports variations like "Verse 1", "Chorus 2", "Bridge:", etc.
- Section headers are preserved without chord modifications

### Chord Assignment Behavior

- Chords are only assigned to actual lyric lines
- Section headers remain clean and readable without chord symbols
- Transposition preserves section structure perfectly
- Auto-generated chord placement skips section labels

### Benefits

- Cleaner, more readable sheet music
- Proper song structure visibility
- Accurate chord transposition without corrupting section markers

---

## Cross-Device Synchronization

Data changes propagate across devices using periodic polling from the frontend:

### What Syncs Automatically

- Song edits (lyrics, chords, metadata, singer assignments)
- Profile updates (names, keys, saved songs)
- Worship list changes (creation, updates, song ordering, deletions)
- Profile-song associations (saving/removing songs from profiles)

### How It Works

- Frontend polls the backend every ~5 seconds and dispatches update events
- Devices connected to the same backend will reflect changes shortly
- If a device shows Offline, fix Settings via the diagnostic page (`/check-settings.html`)

### Supported Devices

- Desktop computers
- Tablets
- Mobile phones
- Multiple browsers simultaneously

### Technical Details

- API runs on port 5000 by default
- Polling interval is approximately 5 seconds
- Event-driven updates trigger component re-renders
- Works across local network and internet (LocalTunnel or port forwarding)

### Setup Requirements

- All devices must point to the same backend server
- Use the server's IP address instead of `localhost` for multi-device access
- Ensure port 5000 is accessible on network
- Verify and fix Settings using `http://<frontend-host>:3000/check-settings.html`