Professional real-time lyric display application for live events, church services, and multimedia presentations.
Version: 6.2.10 Author: Peter Alakembi Co-Contributor: David Okaliwe
LyricDisplay is a comprehensive Electron-based application designed for use in professional live production environments alongside streaming/recording software. It provides real-time lyric synchronization across multiple transparent output displays, making it ideal for church services, concerts, and live streaming setups where lyrics need to be displayed in distinct display points.
- Dual Independent Outputs: Two separate output pages plus stage output page with individual styling controls
- Transparent Backgrounds: Perfect for OBS/VMIX browser source capture
- Real-time Synchronization: Instant updates across all connected displays
- Browser Source Compatible: Works seamlessly with popular streaming software
- Smart Text Processing: Automatic formatting for cleaning up lyric files
- Translation Support: Displays translation lines where available (lines wrapped in brackets below main lyric line)
- Live Editing Canvas: Built-in editor with formatting tools and auto-cleanup
- Search & Navigation: Advanced search with match highlighting and keyboard navigation
- 10 Professional Featured Fonts: 10 pro fonts from Google Fonts in addition to locally installed fonts
- Typography Controls: Bold, italic, underline, and all-caps options
- Color Customization: Independent font and drop shadow colors
- Background Controls: Adjustable opacity and color settings
- Padding Adjustments: X/Y margin controls for proper padding control
- Full Screen Mode: Fill colour/media background options for full screen lyrics display
- NDI® Output: Broadcast lyrics over NDI for use in OBS, vMix, and other production software — with transparency and per-output resolution control
- Auto-Updates: Seamless background updates via GitHub releases
- Dark Mode: System-integrated dark/light theme switching
- Keyboard Shortcuts: Full menu-driven workflow
- Secondary Controllers: Authorize mobile/web devices with a 6-digit join code so remote operators can trigger lines and submit lyric drafts (desktop approval required)
- Cross-Platform: Windows, macOS, and Linux support
- Socket.io Backend: Secure and reliable real-time communication
- Download the latest release from the releases page
- Run the installer for your platform
- Launch LyricDisplay
macOS Users: Because the app is not code-signed, macOS will show a "damaged" error. Before opening, run
xattr -cr /Applications/LyricDisplay.appin Terminal. See the Installation Guide for detailed instructions.
# Clone the repository
git clone https://github.com/PeterAlaks/lyric-display-app.git
cd lyric-display-app
# Install client dependencies
npm install
# Install server dependencies
cd server
npm install
# Development mode
npm run electron-dev
# Build for production
npm run electron-pack- File Menu → Load Lyrics File (Ctrl/Cmd+O)
- Drag & Drop: Drop .txt files directly into the main panel
- New Song Canvas: Create and format lyrics from scratch (Ctrl/Cmd+N)
- Online Lyrics Search: Quickly search for and load lyrics from featured online providers (Icon in top bar)
- Configure Output 1 and Output 2 settings independently
- Use File Menu → Preview Output 1/2 (Ctrl/Cmd+1/2) to open and preview display outputs in windows
- Toggle Display Output switch to control visibility
- Click lyric lines to select and display them
- Use search bar to quickly find specific lyrics
- Navigate matches with Shift+Up/Down arrows
- Toggle output on/off with the main switch
- In the desktop app, open
File > Connect Mobile Controlleror tap the shield icon to view the QR code and current 6-digit join code (the code refreshes when the app restarts) - On a phone or tablet on the same network, scan the QR code or visit
http://<control-pc-ip>:4000/?client=mobile, then enter the join code to pair - Paired controllers load the mobile layout where they can trigger lyric lines, toggle outputs, run manual sync, and submit lyric drafts for approval
LyricDisplay accepts plain text (.txt) and lyrics (.lrc) files
Formatting Rules:
- Bracketed lines
[like this],(this)or{this}are treated as translation lines - Two consecutive lines where the second is bracketed will be grouped
- Auto cleanup removes periods and other special characters, capitalizes first letter of words like God, Jesus, etc.
- React with Hash Router for SPA navigation
- Tailwind CSS for responsive styling
- Radix/ShadCN UI components for accessibility
- Zustand for state management with persistence
- Lucide React for modern iconography
- Express.js server for static file serving
- Socket.io for real-time WebSocket communication
- Node.js child processes for backend management
- Electron for cross-platform desktop application
- Auto-updater with GitHub releases integration
- Native menus with keyboard shortcuts
- System theme synchronization
- Settings automatically saved using Zustand persistence
- Cross-session state restoration
- Electron-store integration for native preferences
- Display hymns and worship songs simultaneously in-house and online
- Support for multiple languages with translation grouping
- Quick song switching during live services
- OBS/VMIX browser source integration
- Transparent overlays for professional broadcasts
- Real-time lyric synchronization for worship leaders
- Multi-screen lyric coordination
- Custom styling to match event branding
- Reliable real-time performance
- Add Browser Source to your scene
- Set URL to:
http://localhost:4000/#/output1orhttp://localhost:4000/#/output2 - Replace
localhostwith the control panel PC's local IP if capturing display from another system across a network - Set dimensions of browser source to match your canvas (for example, 1920 x 1080 pixels)
- Enable Shutdown source when not visible for performance
- Refresh browser when scene becomes active for reliability
- Add Web Browser input
- Use same URL format as OBS
- Configure as overlay for professional broadcast mixing
lyric-display-app/
├── lyricdisplay-ndi/ # LyricDisplay NDI Companion (Separate repo but needed here for development)
├── main/ # Electron main script modules
| ├── ipc/ # IPC handlers
| | ├── index.js # Main registration point
| | ├── app.js # App-level handlers (version, dark mode)
| | ├── window.js # Window controls (minimize, maximize, close, etc.)
| | ├── files.js # File operations (load, save, parse lyrics)
| | ├── recents.js # Recent files management
| | ├── auth.js # Authentication (admin key, JWT, join code, tokens)
| | ├── lyrics.js # Lyrics providers (search, fetch, API keys)
| | ├── easyworship.js # EasyWorship import handlers
| | ├── setlist.js # Setlist operations (save, load, browse, export)
| | ├── display.js # Display management (assignments, output windows)
| | ├── updater.js # App updater controls
| | ├── templates.js # User templates handlers
| | ├── preferences.js # User preferences handlers
| | └── misc.js # Miscellaneous (fonts, IP address, browser)
│ ├── lyricsProviders/
| | ├── providers/
| | | ├── chartlyrics.js # ChartLyrics lyrics provider definitions
| | | ├── hymnary.js # Hymnary.org lyrics provider definitions
| | | ├── lrclib.js # LRCLIB lyrics provider definitions
| | | ├── lyricsOvh.js # Lyrics.ovh lyrics provider definitions
| | | ├── openHymnal.js # Open Hymnal lyrics provider definitions
| | | └── vagalume.js # Vagalume lyrics provider definitions
| | ├── cache.js # Online lyrics search data cache
| | ├── fetchWithTimeout.js # Fetch lyric data timeout moderator for providers
| | ├── index.js # Main online lyrics search initializer and aggregator
| | └── searchAlgorithm.js # Online lyrics search algorithm
| ├── adminKey.js # Admin access key module
| ├── backend.js # Backend server starter
| ├── cleanup.js # Cleanup utility for windows and other processes upon exit
| ├── displayDetection.js # External display detection in main process
| ├── displayManager.js # External assignment and management module
| ├── easyWorship.js # EasyWorship song lyric files conversion module
| ├── externalControl.js # External control module for MIDI and OSC
| ├── fileHandler.js # Main process file processing handler
| ├── inAppBrowser.js # In-App browser window configuration and styling
| ├── ipc.js # IPC handlers import (Backward compatibility)
| ├── loadingWindow.js # Loading process window
| ├── menuBridge.js # Renderer/menu bridge (dark mode, undo/redo state)
| ├── midiController.js # MIDI main controller module
| ├── modalBridge.js # Global modal bridge for electron main process
| ├── modalBridge.js # Global modal bridge for electron main process
| ├── ndiManager.js # Main NDI manager module for main app
| ├── paths.js # Production paths resolver
| ├── presentation.js # Presentation file import and conversion engine
| ├── progressWindow.js # App updater dialog window configuration and styling
| ├── providerCredentials.js # Secure storage utility for online lyrics provider credentials
| ├── recents.js # Module for token storage
| ├── secureTokenStore.js # Main token storage for desktop
| ├── setlistExport.js # Backend process for setlist export operations
| ├── singleInstance.js # Single app instance lock process
| ├── startup.js # Main app startup processes
| ├── systemFonts.js # Helper module for loading system installed fonts
| ├── themePreferences.js # Theme manager for main process dark mode sync
| ├── updater.js # Module to manage app updates
| ├── userPreferences.js # User preferences and app settings manager
| ├── userTemplates.js # Backend manager for user-stored output settings template system
| ├── utils.js # Utility file to get local IP address
| └── windows.js # Main window builder
├── public/ # Static assets
├── scripts/ # Custom npm scripts
| ├── release.js # Release assistant main script
| └── update-version.js # Helper script for updating current version in readme and install guide
├── server/ # Express.js backend
| ├── events.js # Backend communication events
| ├── index.js # Main backend server
| ├── joinCodeGuard.js # Guard/limiter for join code attempts by secondary controllers
| ├── package.json # Backend dependencies
| └── secretManager.js # Module handling the secure management of app secrets
├── shared/
│ ├── data/
| | ├── knownArtists.json # Popular artists name database for enhanced lyric search logic
| | ├── openhymnal-bundle.json # Open Hymnal hymn lyrics bundle from public website
| | └── openhymnal-sample.json # Open Hymnal hymn lyrics sample format for search discoverability
| ├── lineSplitting.js # Intelligent line splitting utility for smarter lyrics parsing
| └── lyricsParsing.js # Shared TXT/LRC parsing helpers.
├── src/ # React frontend source
│ ├── assets/ # Fonts, etc.
│ ├── components/
| | ├── modal/
| | | └── ModalProvider.jsx # Global modal component
| | ├── toast/
| | | └── ToastProvider.jsx # Toast notifications component
| | ├── ui/ # Reusable UI components
| | ├── WindowChrome/
| | | ├── DesktopShell.jsx # Desktop app wrapper component
| | | └── TopMenuBar.jsx # Custom renderer-based native top menu bar
| | ├── AboutAppModal.jsx # About the app modal
| | ├── AuthStatusIndicator.jsx # Authentication status component
| | ├── AutoplaySettings.jsx # Autoplay settings modal
| | ├── ConnectionBackoffBanner.jsx # Global connection backoff modal component
| | ├── ConnectionDiagnosticsModal.jsx # Connection diagnostics modal component
| | ├── DisplayDetectionModal.jsx # Display detection modal component
| | ├── DraftApprovalModal.jsx # Approval modal component for lyric drafts submitted from secondary controllers
| | ├── EasyWorshipImportModal.jsx # Song import from local EasyWorship store wizard
| | ├── ElectronModalBridge.jsx # In-app listener for global modal usage in Electron
| | ├── FontSelect.jsx # Custom font selection overlay
| | ├── HelpContent.jsx # Help and operation tips modal
| | ├── IntegrationInstructions.jsx # Integration help modal for OBS, VMix and Wirecast
| | ├── IntelligentAutoplayInfo.jsx # Intelligent Autoplay info modal
| | ├── JoinCodePromptBridge.jsx # Bridge and component for join code user flow
| | ├── LyricDisplayApp.jsx # Main control panel UI
| | ├── LyricsList.jsx # Control panel lyrics list UI
| | ├── MobileLayout.jsx # Minified control panel UI for secondary connected clients
| | ├── NdiBridge.jsx # Global NDI store initiator and main-process NDI events sync
| | ├── NdiOutputSettingsModal.jsx # NDI output settings modal for each output
| | ├── NewSongCanvas.jsx # New/edit song text editor
| | ├── OnlineLyricsSearchModal.jsx # Online Lyrics Search modal
| | ├── OnlineLyricsWelcomeSplash.jsx # Online Lyrics Search welcome and help modal component
| | ├── OutputSettingsPanel.jsx # Settings panel interface
| | ├── OutputSettingsShared.jsx # Shared UI components for output and stage settings panel
| | ├── OutputTemplatesModal.jsx # Output settings templates modal
| | ├── PresentationImportModal.jsx # Presentation file import/conversion modal
| | ├── PreviewOutputsModal.jsx # Display outputs preview modal
| | ├── QRCodeDialog.jsx # QR Code Dialog UI for mobile controller connection
| | ├── QRCodeDialogBridge.jsx # Bridge component for QR Code Dialog
| | ├── SaveTemplateModal.jsx # Save settings combo as template modal
| | ├── SearchBar.jsx # Search bar component for control panel
| | ├── SetlistExportModal.jsx # Setlist export modal
| | ├── SetlistModal.jsx # Setlist modal
| | ├── ShortcutsHelpBridge.jsx # Shortcuts help modal and bridge
| | ├── SongInfoModal.jsx # Info modal for loaded lyrics
| | ├── StageSettingsPanel.jsx # Stage settings interface
| | ├── StageTemplatesModal.jsx # Stage settings templates modal
| | ├── SupportDevelopmentBridge.jsx # Support development modal bridge
| | ├── SupportDevelopmentModal.jsx # Support development modal
| | └── UserPreferencesModal.jsx # User preferences UI
| | └── WelcomeSplash.jsx # Welcome splash modal for first time install
│ ├── constants/
| | ├── easyWorship.js # Some EasyWorship constants
| | ├── fonts.js # Featured fonts dropdown store
| | ├── lyricsFormat.js # Constants used in lyrics formatting/cleanup utility
| | ├── presentationImport.js # Presentation file import constants
| | ├── shortcuts.js # Keyboard shortcut definitions used for shortcuts help modal
| | └── songCanvas.js # Some constants used in canvas editor
│ ├── context/
| | ├── ControlSocketProvider.jsx # Control socket provider
| | ├── LyricsStore.js # Global Zustand store definitions
| | └── NdiStore.js # NDI Zustand store definitions
│ ├── hooks/
| | ├── LyricDisplayApp/
| | | ├── useDragAndDrop.js # Drag and drop operations for control panel
| | | ├── useElectronListeners.js # Hook for listening to main process events and broadcasts for control panel
| | | ├── useKeyboardShortcuts.js # Keyboard entry listener for control panel
| | | ├── useLyricsLoader.js # Multi-source lyrics load processor for control panel
| | | ├── useMenuShortcuts.js # Hook for handling menu navigation/shortcuts
| | | ├── useOutputSettings.js # Hook for output settings tab switcher
| | | ├── useResponsiveWidth.js # Window resize observer hook for control panel button responsiveness
| | | ├── useSetlistActions.js # Hook for setlist action functionality
| | | └── useSupportDevModal.js # Hook for processing show time and parameters for support development modal
| | ├── LyricsList/
| | | └── useElectronListeners.js # Hook for listening to main process events and broadcasts for lyrics list
| | ├── NewSongCanvas/
| | | ├── useCanvasSearch.js # Content search hook for editing area/canvas
| | | ├── useEditorClipboard.js # Hook for cut, copy and paste handlers
| | | ├── useEditorHistory.js # Hook for history state management of lyrics editor canvas
| | | ├── useElectronListeners.js # Hook for listening to main process events and broadcasts for new song canvas
| | | ├── useFileSave.js # Canvas file operations hook
| | | ├── useKeyboardShortcuts.js # Keyboard entry listener for canvas
| | | ├── useLineMeasurements.js # Hook for measuring and calculating line dimensions in canvas
| | | ├── useLineOperations.js # Hook for line manipulation operations in canvas
| | | ├── useLrcEligibility.js # Hook for determining LRC format eligibility
| | | ├── useTimestampOperations.js # Hook for timestamp handling and operations
| | | └── useTitlePrefill.js # Hook for auto-prefilling song title in canvas
| | ├── OnlineLyricsSearchModal/
| | | ├── useKeyboardShortcuts.js # Keyboard entry listener for online lyrics search modal
| | | └── useNetworkStatus.js # Internet connection status hook
| | ├── OutputSettingsPanel/
| | | ├── useAdvancedSectio....js # Hook for advanced sections visibility states
| | | ├── useFullscreenBackground.js # Hook for handling fullscreen background controls
| | | ├── useFullscreenModeState.js # Fullscreen mode and settings visibility state hook
| | | ├── useOutputToggle.js # Individual output switch manager
| | | ├── useStageDisplayControls.js # Hook for stage display controls
| | | └── useTypographyAndBands.js # Background band and related logic hook
| | ├── SetlistModal/
| | | └── useSetlistLoader.js # Hook for setlist file loading functionality
| | ├── WindowChrome/
| | | ├── useMenuHandlers.js # Menu operations hook for top menu bar
| | | ├── useSubMenuListNav.js # Hook for handling top menu bar sub-menu navigation
| | | └── useTopMenuState.js # Top menu bar state definitions
| | ├── useAuth.js # Authenticator hook for socket connections
| | ├── useAutoplayManager.js # Autoplay engine and logic
| | ├── useContextMenuPosition.js # Hook for space-aware context menu positioning
| | ├── useContextSubmenus.js # Context submenus definitions and logic
| | ├── useDarkModeSync.js # Hook for global dark mode sync
| | ├── useExternalControl.js # Hook for external control (MIDI, OSC, etc.)
| | ├── useFileUpload.js # Custom React hook for file uploads
| | ├── useModal.js # Global modal hook
| | ├── useMultipleFileUpload.js # Multiple file upload handler
| | ├── useSearch.js # Hook for search bar functionality
| | ├── useSocket.js # Main React hook for Socket.IO client
| | ├── useSocketEvents.js # Socket events hook
| | ├── useStoreSelectors.js # Centralized collection of Zustand selectors
| | ├── useSyncOutputs.js # Outputs sync manager for control panel
| | ├── useSyncTimer.js # Last synced timer hook
| | └── useToast.js # Toast notifications hook
│ ├── lib/
| | └── utils.js # UI library utility functions
│ ├── pages/ # Route-based page components
| | ├── ControlPanel.jsx # Control panel page wrapper
| | ├── Output1.jsx # Output 1 display
| | ├── Output2.jsx # Output 2 display
| | └── Stage.jsx # Stage output display
│ ├── styles/
| | └── fonts.css # Display font styles import and definitions
│ ├── utils/
| | ├── artistDetection.js # Scans Known Artists database for various uses around the app
| | ├── asyncLyricsParser.js # Picks worker/IPC/sync parsing strategy
| | ├── connectionManager.js # Socket connection management utility
| | ├── errorClassification.js # Network error detection and description utility
| | ├── logger.js # Simple event and error logger utility
| | ├── lyricsFormat.js # Format lyrics utility for new/edit song canvas
| | ├── markdownParser.js # Helper utility for converting markdown to HTML
| | ├── maxLinesCalculator.js # Calculator for maximum lines feature in outputs display
| | ├── network.js # Network utility for backend URL resolution
| | ├── numberInput.js # Integer value sanitization utility for settings panel
| | ├── outputTemplates.js # Output templates for settings panel
| | ├── parseLrc.js # LRC file parser
| | ├── parseLyrics.js # Text file parser
| | ├── secureTokenStore.js # Secure token storage utility
| | ├── timestampHelpers.js # Timestamp helper utility for intelligent autoplay feature
| | ├── titlePrefill.js # Title prefill utility for song canvas
| | └── toastSounds.js # Toast notifications tones utility
│ ├── workers/
| | └── lyricsParser.worker.js # Web worker that parses lyrics off the UI thread.
| ├── App.jsx # React app main component
| ├── index.css # Global CSS and custom style definitions
| └── main.jsx # App entry point
├── components.json # Shadcn UI config
├── CONTRIBUTING.md # Contribution guides for project
├── index.html # Web app entry point
├── jsconfig.json # Path and settings configurations for JS
├── main.js # Electron main process
├── package.json # Dependencies and scripts
├── postcss.config.js # PostCSS configurations
├── preload.js # Electron preload script
├── README.md # App documentation
├── tailwind.config.js # Tailwind configurations
└── vite.config.js # Vite configurations
npm run dev # Vite development server
npm run server # Backend server only
npm run electron-dev # Full Electron development
npm run build # Production build
npm run electron-pack # Package Electron app- Fork the repository
- Create a feature branch
- Implement changes with proper testing
- Submit pull request with detailed description
Output windows not displaying:
- Verify backend server is running (Port 4000 active)
- Ensure Socket.io connection is established (Connected status in top bar)
- Try refreshing browser sources in OBS/vMix/Wirecast
LyricDisplay integrates optional online lyrics search features powered by free and publicly available lyrics providers.
All lyrics, metadata, and related content displayed through these services remain the property of their respective copyright holders.
- LRCLIB — Free synced lyrics database with nearly 3 million lyrics. No API key required. Provides both plain and timestamped (LRC format) lyrics.
- ChartLyrics — Free public lyrics API with good coverage of popular songs. No API key required.
- Lyrics.ovh — Free lyrics API (public domain and licensed material) provided for educational and non-commercial use.
- Vagalume — © Vagalume Media Group. Lyrics and artist data are provided through the official Vagalume API.
- Hymnary.org — © Hymnary.org / Christian Classics Ethereal Library (CCEL). Content is provided for educational and liturgical purposes.
- Open Hymnal Project — Public domain hymn texts and music as compiled by the Open Hymnal Project.
NDI® is a registered trademark of Vizrt NDI AB. LyricDisplay uses the NDI SDK via the open-source grandi module for video output over IP networks. This project is not affiliated with or endorsed by Vizrt NDI AB. For more information about NDI, visit ndi.video.
Logos and brand marks of the above providers are displayed in LyricDisplay for identification and attribution purposes only.
All trademarks, service marks, and logos are the property of their respective owners.
Their inclusion does not imply endorsement, partnership, or affiliation with LyricDisplay or its developers.
- LyricDisplay does not store, redistribute, or claim ownership of any lyrics obtained through these sources.
- Lyrics are fetched on demand from publicly accessible APIs and displayed solely for personal, church, and non-commercial use.
- If you are a copyright holder and wish to request content removal or modification, please contact the original provider directly.
Disclaimer: LyricDisplay and its developers are not affiliated with or endorsed by any of the above content providers.
This feature is offered “as is” for convenience and educational purposes only.
Copyright © 2026. All Rights Reserved.
Developers:
- Peter Alakembi (Lead Designer and Developer)
- David Okaliwe (Co-Developer)
Links:
For technical support, feature requests, or bug reports:
- Open an issue on the issues tab
- Check existing documentation
- Review troubleshooting section
LyricDisplay - Powering worship experiences worldwide