Releases: ebena107/HymnFlow
π΅ HymnFlow v2.3.1 - Global Worship Enhanced
Release Date: January 14, 2026
Release Type: Feature + Documentation Release
Download:hymnflow-v2.3.1-plugin.zip
β¨ What's New
HymnFlow v2.3.1 combines the powerful internationalization features of v2.3.0 with enhanced documentation to make setup crystal clear. This release represents a major leap forward in accessibility and usability for worship teams worldwide.
π Major Features (v2.3.0 + v2.3.1)
1οΈβ£ Multi-Language Support (v2.3.0)
The HymnFlow interface now supports 9 languages, allowing operators to work in their native tongue!
Supported Languages:
- π¬π§ English (Default)
- πͺπΈ EspaΓ±ol (Spanish)
- π«π· FranΓ§ais (French)
- π΅πΉ PortuguΓͺs (Portuguese)
- πΉπΏ Kiswahili (Swahili)
- π΅π Tagalog
- π³π¬ YorΓΉbΓ‘ (Yoruba)
- π¨π³ δΈζ (Mandarin Chinese)
- π°π· νκ΅μ΄ (Korean)
How to change language:
- Open HymnFlow Dock in OBS
- Scroll to the Settings section
- Select your language from the Interface Language dropdown
- The UI updates immediately!
2οΈβ£ Official CAC Hymn Collections (v2.3.0)
Complete, verified hymn books from Christ Apostolic Church:
- CAC Gospel Hymn Book (English): 1,001 hymns - 1.18 MB
- CAC Yoruba Hymn Book (Iwe Orin CAC): 997 hymns - 969 KB
Plus standard collections:
- Faith We Sing: 46 hymns - 44 KB
- Baptist Hymnal (2008): 325 hymns - 352 KB
- United Methodist Hymnal: 296 hymns - 337 KB
- Yoruba Baptist Hymnal: 650 hymns - 582 KB
Total: 2,315 hymns across 6 collections!
3οΈβ£ Optimized "Hymn Bundle" Architecture (v2.3.0)
To keep the core application small and fast, large hymn collections have been moved into an optional Hymn Bundle available as a separate download.
Benefits:
- β Reduced Size: Core plugin download reduced from ~3MB to ~150KB (95% smaller!)
- β Faster Downloads: Get started quickly, download only the hymns you need
- β Separate Management: Update your hymn library without re-downloading the plugin
- β Community Ready: Easier to share and contribute new hymn books in JSON format
- β Individual Downloads: Each hymn collection available as a separate file
4οΈβ£ Crystal-Clear Documentation (v2.3.1)
Enhanced documentation to eliminate confusion about hymn file downloads:
- π Prominent notices explaining hymn files are a separate download
- π Step-by-step instructions for downloading hymn files from GitHub
- π Multiple download options (individual files or bulk download)
- π Updated setup wizard with clear separation messaging
- π Comprehensive guides in README, SETUP, and interactive HTML wizard
π Complete Change Log
v2.3.1 (January 14, 2026) - Documentation Improvements
Changed:
- π Updated
README.mdwith explicit hymn bundle download instructions - π Updated
doc/SETUP.mdwith detailed download options (GitHub folder or Releases) - π Updated
public/obs-setup.htmlwith prominent notice that hymn files are separate downloads - π’ Bumped version to 2.3.1 in
package.jsonand all HTML files - π Created comprehensive release notes and OBS Project release documentation
Notes:
- No functional changes to the application
- Plugin download remains ~150KB (hymn files not included)
v2.3.0 (January 14, 2026) - Internationalization & Optimization
Added:
- π Multi-language support for 9 languages
- βοΈ Interface Language selector in Settings
- πΎ Persistent language preference (saved in localStorage)
- π§© New i18n module for dynamic translation management
- π JSON-based translation files for easy community contribution
- π CAC Gospel Hymn Book (English) - 1,001 hymns
- π CAC Yoruba Hymn Book (Iwe Orin CAC) - 997 hymns
- π¦ Optimized "Hymn Bundle" architecture (separate download)
Changed:
- π― Reduced core plugin size from ~3MB to ~150KB
- π Updated setup documentation for external data import
π₯ How to Get Hymn Files
Important
Hymn files are NOT included in the main plugin download to keep it lightweight.
Option 1: Download Individual Files from GitHub
- Visit the hymn-bundle folder on GitHub
- Click on the hymn file you want (e.g.,
cac_ghb.json) - Click the "Download raw file" button or right-click "Raw" and select "Save link as..."
- Save to your computer (e.g.,
C:\HymnFlow\hymn-bundle\)
Option 2: Download from Releases
- Visit the Releases page
- Download the
hymn-bundle.zipfile (if available) - Extract to your preferred location
Import into HymnFlow
- Open the HymnFlow Dock in OBS
- Click the Import button in the Hymns section
- Navigate to where you saved the
.jsonfile - Select the hymn file (e.g.,
cac_ghb.json) - Your hymns will be imported and ready to use!
π Available Hymn Collections
All available as separate downloads from the hymn-bundle folder:
| Collection | Language | Hymns | Size |
|---|---|---|---|
| CAC Gospel Hymn Book | English | 1,001 | 1.18 MB |
| CAC Yoruba Hymn Book | Yoruba | 997 | 969 KB |
| Faith We Sing | English | 46 | 44 KB |
| Baptist Hymnal (2008) | English | 325 | 352 KB |
| United Methodist Hymnal | English | 296 | 337 KB |
| Yoruba Baptist Hymnal | Yoruba | 650 | 582 KB |
Total: 3,315 hymns available for download!
π Migration from v2.2.x
No breaking changes! All existing hymns and styling settings are fully compatible.
If Upgrading from v2.2.x:
- Download and extract the new plugin
- Your existing hymns in localStorage will remain
- Select your preferred language in Settings
- Optionally download additional hymn collections
If Upgrading from v2.3.0:
- No changes required! This is purely a documentation update
- You don't need to update unless you want the latest documentation
π¦ What's Included in the Plugin Download
The hymnflow-v2.3.1-plugin.zip (~150KB) contains:
- β OBS Dock - Control panel for managing hymns
- β OBS Overlay - Lower-third display for streaming
- β i18n Translations - 9 language support files
- β Setup Guide - Interactive HTML setup wizard
- β Documentation - README, SETUP, TROUBLESHOOTING guides
- β Parsers - Support for .txt and .json import
- β Default Data - Sample hymns to get started
NOT Included:
- β Hymn Collections - Download separately (see above)
π¬ Quick Start
1. Download Plugin
- Get hymnflow-v2.3.1-plugin.zip
- Extract to
C:\HymnFlow\(or your preferred location)
2. Setup in OBS
- Add Custom Dock: View β Docks β Custom Browser Docks
- Name:
HymnFlow Control - URL:
file:///C:/HymnFlow/obs-dock/index.html
- Name:
- Add Browser Source: Add Source β Browser Source
- Name:
Hymn Lower-Third - URL:
file:///C:/HymnFlow/obs-overlay/index.html - Size: 1920x1080
- Name:
3. Download Hymn Files
- Visit hymn-bundle folder
- Download the collections you need
4. Import and Use
- Click Import in the dock
- Select your downloaded
.jsonfile - Start displaying hymns!
π¨ Core Features
- π― Zero-Latency - Pure browser localStorage communication (no server required)
- π International - UI in 9 languages and growing
- π¨ Customizable - Control fonts, colors, outlines, shadows, and animations
- β¨οΈ Keyboard-Driven - Arrow keys for seamless verse/line navigation
- π Smart Chorus - Automatic chorus display after every verse
- π Service Scheduling - Pre-plan your hymn order before services start
- πΎ Persistent Storage - Hymns saved in browser localStorage
- π± Responsive - Works on any screen size
- π₯ Import/Export - Support for .txt and .json hymn files
π Credits
Internationalization: Community Contributors & Media Team
CAC Hymn Collections: Christ Apostolic Church
Implementation: HymnFlow Development Team
Built by: Gloryland Baptist Church, Owode-Ede (@gbcowode), Media Team
π Resources
- Repository: HymnFlow on GitHub
- Latest Release: v2.3.1
- Documentation: Setup Guide
- Troubleshooting: Common Issues
- Hymn Bundle: Download Hymns
- Full Changelog: CHANGELOG.md
π€ Community
Help Us Grow
- π Translations: Can you help translate HymnFlow to a new language? Join our GitHub discussions!
- π Hymn Collections: Have a hymn book you'd like to contribute? We'd love to include it!
- π Report Issues: Found a bug? Open an issue
- π‘ Suggest Features: Have an idea? Share it in Discussions
π License
GPL-2.0 License - Same as OBS Studio. Free to use and modify for your worship services!
Empowering worship teams worldwide with seamless hymn display! π΅πβ¨
HymnFlow v2.2.0 - Chorus Display Release
π΅ HymnFlow v2.2.0 - Chorus Display Release
Release Date: January 8, 2026
Release Type: Feature Release
β¨ What's New
HymnFlow v2.2.0 introduces a highly requested feature: Automatic Chorus Display. This update transforms the navigation experience, ensuring that hymns with choruses are displayed correctly and efficiently during live worship services.
π― Major Features
1οΈβ£ Automatic Chorus Sequencing (NEW)
HymnFlow now understands the natural flow of a hymn. When a hymn has a chorus, the system automatically inserts it into the navigation sequence after every verse.
Features:
- β
Smart Sequencing: Navigating "Next" now follows the logical order:
Verse 1βChorusβVerse 2βChorus... - β Dynamic Labeling: The OBS Overlay now displays a clear "Chorus" label instead of a verse number when the chorus is active.
- β Seamless Reversion: "Previous" navigation correctly steps back through the sequence, allowing you to return to the preceding verse or chorus perfectly.
- β Boundary Awareness: Line-by-line navigation (Up/Down arrows) automatically transitions between verses and choruses without manual intervention.
2οΈβ£ Functional "Jump to Chorus" (ENHANCED)
The "Jump to Chorus" button has been fully implemented.
Features:
- β Instant transition to the chorus from any verse.
- β Auto-updates both the preview and the live OBS overlay.
- β Smart state management: The system knows you are now in the "Chorus" state for subsequent navigation.
π΅ HymnFlow v2.1.0 - Major Enhancement Release
π΅ HymnFlow v2.1.0 - Major Enhancement Release
Release Date: January 5, 2026
Release Type: Feature Release
Download: hymnflow-v2.1.0-plugin.zip
β¨ What's New
HymnFlow v2.1.0 brings three significant enhancements to the dock interface, making it more powerful for professional worship leaders and A/V operators. All features requested by Michael Fasina community feedback.
π― Major Features
1οΈβ£ Text Outline Styling (NEW)
Add crisp text outlines (strokes) for better readability over complex backgrounds.
Features:
- β Toggle outline on/off with checkbox
- β Customizable outline color picker
- β Adjustable outline width (1-5px)
- β Real-time preview
- β Settings persist across sessions
Why? When displaying hymns over video, images, or live camera feeds, text outlines provide critical contrast for readability. Shadow and glow effects work well, but outlines give the sharpest, most professional appearance.
How to Use:
- Open Styles section in dock
- Check "Outline" checkbox
- Select outline color with color picker
- Adjust width with slider (1-5px recommended)
- Settings apply immediately to overlay
Technical: Uses -webkit-text-stroke for broad browser compatibility (Chrome, Edge, Firefox).
2οΈβ£ Hymn Editing (NEW)
Edit hymns directly in the dock to fix typos and make corrections without re-importing.
Features:
- β Edit button in Hymns section (next to + Add, - Remove)
- β
Modal form with all hymn fields:
- Hymn Number (optional metadata)
- Title (required)
- Author
- Verses (textarea with blank-line separation)
- Chorus (optional)
- β Full validation (title and verses required)
- β Preserves hymn ID (references maintained)
- β Immediate UI refresh
Why? Typos happen. Previously, users had to:
- Delete and re-import (losing metadata)
- Manually edit localStorage JSON (error-prone)
- Live with the error
Now: One click β Edit β Save β Done!
How to Use:
- Select hymn from list
- Click "βοΈ Edit" button
- Make corrections in modal
- Click "Save Changes"
- Hymn updates in list and preview
Technical: Modal form with client-side validation, updates hymn object while preserving ID.
3οΈβ£ Service/Program Scheduling (NEW)
Pre-organize hymns for services, programs, and events. Perfect for:
- Sunday morning/evening services
- Bible study sessions
- Special events (Easter, Christmas, weddings, funerals)
- Multi-language services
Features:
- β Create named services ("Sunday Morning - Jan 5", "New Year Service", etc.)
- β Add hymns to services in sequence
- β Reorder hymns with up/down buttons
- β Load service to display only those hymns
- β Navigate through service hymns with Previous/Next verse buttons
- β All services saved to localStorage
- β Delete services anytime
Workflow:
1. Click "+ New" in Services section
2. Enter service name (e.g., "Sunday Morning")
3. Click "+ Add Hymn" to add hymns in order
4. Reorder with ββ buttons if needed
5. Click "Save Service"
6. Later: Click "Load" to activate service
7. Navigate through hymns normally
Why? Worship services follow planned hymn orders. Scheduling:
- Reduces search time during live service
- Prevents accidentally selecting wrong hymn
- Works offline with no internet
- Allows planning before service starts
Technical: Services stored as arrays of hymn IDs in localStorage (key: hymnflow-services). Reordering is instant, no re-importing needed.
π Complete Change Log
Added
- π¨ Text outline styling with color and width control
- βοΈ Full hymn editor with modal form
- π― Service/program scheduling system
- π Service load/save functionality
βοΈ Hymn reordering in services
Enhanced
- Improved Styles section layout
- Better form validation
- Enhanced modal UI for editing
- Slim single-line color indicators in style controls (more compact UI)
Fixed
- Style setting changes (including outline color/width) now update the live overlay instantly when a hymn is displayed
π Migration from v2.0.x
No breaking changes! All existing data is compatible:
- β Hymns migrate automatically
- β Settings persist as-is
- β No re-import needed
- β Just upgrade and use
π Feature Comparison
| Feature | v2.0.0 | v2.0.1 | v2.1.0 |
|---|---|---|---|
| Hymn Management | β | β | β |
| Quick Edit | β | β | β |
| Text Outline Styling | β | β | β |
| Service Scheduling | β | β | β |
| Customizable Styling | β | β | β |
| Keyboard Navigation | β | β | β |
| Import/Export | β | β | β |
π¬ Quick Start
For v2.0.x Users
- Backup (optional): Export hymns from dock
- Replace files in your HymnFlow folder with v2.1.0 files
- Reload custom dock in OBS (no reconfiguration needed)
- No data loss - everything stays the same
Trying New Features
Text Outline
- Open OBS Dock β Styles section
- Check "Outline" checkbox
- Pick outline color
- Set width to 2-3px for best results
Hymn Editing
- Select hymn from list
- Click "βοΈ Edit" button
- Fix typos in modal
- Click "Save Changes"
Service Scheduling
- Click "+ New" in Services section
- Name your service
- Click "+ Add Hymn" to add hymns in order
- Save and load during service
π Technical Details
New Settings Keys (localStorage)
hymnflow-dock-settings.outline(boolean)hymnflow-dock-settings.outlineColor(hex color)hymnflow-dock-settings.outlineWidth(number 1-5)hymnflow-services(array of service objects)
Service Data Structure
{
id: "srv_${timestamp}",
name: "Service Name",
hymns: ["hymn_id_1", "hymn_id_2", "hymn_id_3"]
}Browser Compatibility
- β Chrome/Chromium (OBS uses Chromium)
- β Edge
- β Firefox
β οΈ Safari (limited-webkit-text-strokesupport)
π Known Issues / Limitations
- None reported in beta testing
- Modal styling optimized for dock width (420px max)
- Service names limited to ~50 characters for display
- Maximum ~1000 services before localStorage limits
π Support & Feedback
Having issues?
- Check TROUBLESHOOTING.md
- Report bugs: GitHub Issues
- Request features: GitHub Issues
Like what you see?
- Share feedback in Discussions
- Contribute improvements via Pull Requests
π Credits
Feature Requests by: Michael Fasina
Implementation: HymnFlow Development Team (Gloryland Baptist Church, Owode-Ede, Nigeria)
Community Feedback: Global worship leaders and A/V operators
π Version History
| Version | Date | Focus |
|---|---|---|
| v2.1.0 | Jan 5, 2026 | Editing, Outline, Scheduling |
| v2.0.1 | Jan 5, 2026 | Vertical Dock, Hymn Numbers |
| v2.0.0 | Jan 4, 2026 | Initial Stable Release |
| v1.0.0 | (archived) | Server-based version |
π Resources
- Setup Guide: SETUP.md
- Troubleshooting: TROUBLESHOOTING.md
- Full Documentation: docs/
- Repository: github.com/ebena107/HymnFlow
π License
HymnFlow v2.1.0 is released under the GPL-2.0 License - Same as OBS Studio.
Free to use in churches, ministries, and commercial settings.
Enjoy the enhanced HymnFlow experience! π΅β¨
Questions? Ideas? Let's build the best hymn display tool together!
HymnFlow-v2.0.0
π΅ HymnFlow v2.0.0 - Initial Stable Release
Release Date: January 4, 2026
Release Type: Major Release - Stable
Download: hymnflow-v2.0.0-plugin.zip
π What's New
HymnFlow v2.0.0 is the first stable release of a browser-based OBS Studio plugin for displaying hymns during worship services. This release focuses on simplicity, reliability, and ease of use.
β¨ Key Features
ποΈ OBS Custom Dock Control Panel
- Complete hymn library management (add, remove, search, import, export)
- Real-time preview of current hymn and verse
- Navigation controls (previous/next verse, line-by-line navigation)
- Keyboard shortcuts for fast operation during live services
- Visual display toggle with state indicators
πΊ OBS Browser Source Overlay
- Lower-third display perfect for worship presentations
- Smooth animations (fade, slide, or none)
- Customizable positioning (bottom, middle, top)
- Automatic updates as you navigate in the dock
π¨ Powerful Styling Options
- Font family selection (Inter, Segoe UI, Roboto, Georgia, Montserrat)
- Font size control (24px - 96px)
- Text effects: Bold, Italic, Shadow, Glow
- Text color picker
- Background types: Transparent, Solid, Gradient
- Custom background colors with gradient support
π₯ Import/Export System
- TXT format: Simple text-based format for easy hymn entry
- JSON format: Structured data with full metadata support
- Export: Backup your entire hymn library as JSON
- Default hymns included (English samples)
π Smart Navigation
- Auto-advance between verses when reaching line boundaries
- Configurable lines per display (2-6 lines)
- Jump to chorus functionality
- Emergency clear button for instant hide
πΎ Browser-Based Storage
- All data stored in browser localStorage (~5-10MB capacity)
- No server required - works offline
- Persistent across browser sessions
- Can handle thousands of hymns
ποΈ Architecture
Pure Client-Side Design
HymnFlow uses an innovative localStorage + storage events architecture:
OBS Custom Dock (Control) ββ localStorage ββ OBS Browser Source (Display)
Benefits:
- β No server installation or configuration
- β No network dependencies
- β
Works with
file://protocol (direct file access) - β Zero latency communication
- β Simple deployment and updates
File Structure
hymnflow-v2.0.0/
βββ obs-dock/ # Control panel HTML/CSS/JS
β βββ index.html
β βββ obs-dock.css
β βββ obs-dock.js
βββ obs-overlay/ # Display overlay HTML/CSS/JS
β βββ index.html
β βββ overlay.css
β βββ overlay.js
βββ data/ # Default hymn library
β βββ hymns-data.js
β βββ hymns.json
βββ parsers/ # Import format parsers
β βββ txtParser.js
β βββ csvParser.js
β βββ jsonParser.js
βββ Documentation files (README, SETUP, etc.)
Total Size: ~150-200 KB
π Getting Started
Quick Setup (5 Minutes)
-
Download & Extract
- Download
hymnflow-v2.0.0-plugin.zip - Extract to
C:\HymnFlow\(or any location)
- Download
-
Add Custom Dock in OBS
View β Docks β Custom Browser Docks Dock Name: HymnFlow Control URL: file:///C:/HymnFlow/public/obs-dock/index.html -
Add Browser Source
Add Source β Browser Source Name: Hymn Lower-Third URL: file:///C:/HymnFlow/public/obs-overlay/index.html Width: 1920, Height: 1080 -
Import Your Hymns
- Click Import in the dock
- Select your .txt or .json file
- Start displaying!
Detailed Instructions: See SETUP.md
π System Requirements
Minimum Requirements
- OBS Studio: v27.0 or higher (v29+ recommended)
- Operating System: Windows 10/11, macOS 10.15+, Linux (Ubuntu 20.04+)
- Browser Engine: Chromium-based (OBS uses CEF - Chromium Embedded Framework)
- Disk Space: ~1 MB for plugin files
- localStorage: ~5-10 MB available (standard browser allocation)
Recommended
- OBS Studio: v29.1+ (latest stable)
- Display Resolution: 1920x1080 or higher
- RAM: 8 GB+ (for smooth OBS operation)
π― Use Cases
Perfect For:
- βοΈ Church worship services (Sunday services, prayer meetings, special events)
- π€ Small to medium congregations
- πΊ Live streaming worship (YouTube, Facebook, Vimeo)
- πΆ Multi-language worship (import different hymn collections)
- π« Bible study groups with hymn singing
Tested Scenarios:
- β Sunday morning services with 20+ hymns
- β Live streaming with OBS Studio
- β Multiple services with different hymn sets
- β Quick hymn changes during live worship
- β Keyboard-only operation for A/V operators
β¨οΈ Keyboard Shortcuts
| Key | Action |
|---|---|
β Right Arrow |
Next verse |
β Left Arrow |
Previous verse |
β Down Arrow |
Next line window |
β Up Arrow |
Previous line window |
Space |
Toggle display (show/hide) |
π¦ What's Included
Core Files
obs-dock/- Control panel (3 files)obs-overlay/- Display overlay (3 files)parsers/- Import parsers (3 files)data/- Default hymns (2 files)
Documentation
README.md- Project overview and featuresSETUP.md- 5-minute setup guideTROUBLESHOOTING.md- Common issues and solutionsSECURITY.md- Security policyLICENSE- MIT License
Development Files
.github/- GitHub templates and workflowsscripts/- Release automation scriptsdoc/- Developer documentation
π Security & Privacy
- β No data collection - Everything stays on your computer
- β No network calls - Works completely offline
- β No tracking - No analytics or telemetry
- β No external dependencies - Pure vanilla JavaScript
- β Open source - Full code transparency (MIT License)
Data Storage: All hymns and settings stored in browser localStorage (OBS's internal Chromium instance). Data never leaves your computer.
π€ Contributing
We welcome contributions! See CONTRIBUTING.md for guidelines.
Ways to Contribute:
- π Report bugs via GitHub Issues
- π‘ Suggest features
- π Improve documentation
- π Add translations or multi-language hymn collections
- π¨ Design improvements
- π» Code contributions (PRs welcome!)
π License
HymnFlow is released under the MIT License.
Commercial Use Allowed - Free to use in churches, ministries, and commercial settings.
π Acknowledgments
- Built for the global worship community
- Inspired by the need for simple, reliable hymn display solutions
- Designed with A/V operators and worship leaders in mind
π Resources
- Documentation: SETUP.md | TROUBLESHOOTING.md
- Support: GitHub Issues
- Repository: github.com/ebena107/HymnFlow
π Release Notes
What's Included in v2.0.0
β
Complete OBS Studio integration (custom dock + browser source)
β
Hymn management (add, delete, search, import, export)
β
Real-time navigation with keyboard shortcuts
β
Customizable styling and animations
β
Smart line-by-line navigation with auto-verse advancement
β
Visual display toggle with state indicators
β
Responsive design for various screen sizes
β
Comprehensive documentation
β
Default English hymn samples included
Known Limitations
- localStorage limited to ~5-10 MB (thousands of hymns)
- OBS dock and overlay must be from same origin (same folder structure)
- Browser-specific localStorage (separate OBS profile = separate storage)
Planned for Future Releases
See GitHub Issues for planned features and enhancements.
π Support
Having issues? Check TROUBLESHOOTING.md first.
Need help? Open an issue: GitHub Issues
Happy Worshiping! π΅β¨
HymnFlow v2.0.0 - Browser-based OBS hymn display plugin
Released: January 4, 2026
License: MIT