PTS/Church-Music
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d367261867f555324c071d2d2a1ff220d91d93ae
Church-Music/legacy-site/documentation/md-files/README.md

9.6 KiB
Raw Blame History

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)

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):

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

Frontend (React)

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:

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:

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:
    cd "E:\Documents\Website Projects\Church_SongLyric\backend"
.\venv\Scripts\python.exe app.py
    • Frontend:
    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:
    cd "E:\Documents\Website Projects\Church_SongLyric\backend"
.\venv\Scripts\python.exe app.py
    • Tunnel:
    & "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):

  2. Chocolatey:


```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:
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:

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
Reference in New Issue View Git Blame Copy Permalink