Utility PHP/AJAX support scripts for Faithlife Proclaim projection software
Our church (Campbell United Church of Christ) began using Faithlife Proclaim projection software to produce slides for our weekly worship service in July, 2019. Previously, we had a fairly complicated and labor intensive process using MicroSoft Word™ documents to create a 'Worship Roadmap' and from that, a MicroSoft Powerpoint™ slide set for projection of worship service order with song/hymn lyrics. Faithlife Proclaim has greatly simplified the process of creating projection-ready slides, but it didn't have the ability to create a written order of worship (roadmap) for the service, nor the ability to import our existing song library (in Word documents) easily into Proclaim for projection.
As a result, several utility PHP scripts were generated to allow:
- Creation/management of songs into OpenLP/OpenLyrics XML format for easy import into Proclaim
- Query scripts to show songs in the library and show song usage in Proclaim presentations
- Creation of worship roadmap HTML page based on a Proclaim slide set (the local Backup slide set .PRS file uploaded to the website)
Our worship service preparation process is now:
- Pastor selects liturgy elements to use (generally in Word format)
- Music Director selects songs/hymns appropriate for the liturgy message
- Office Administrator copy/pastes content from the Word format liturgy into slides in Proclaim, and inserts songs based on Music Director choices.
- A/V crew adds/adjusts audio/visual instructions
- Proclaim slides are backed up to local copy, and uploaded to website where the worship roadmap is generated.
- The roadmap may be viewed directly in any browser (it is HTML5) or optionally printed via the browser for hard-copy output.
The roadmap.php script now (by default) displays the information for use by the worship participants (Pastor, Lay Reader, Song Leader, etc.) without the clutter of the A/V cues. Using roadmap.php?avtech now produces a roadmap for use by the A/V Tech with the audio and video cues highlighted and the other participant text included so the techs can follow along the service order. A roadmap.php?summary is now available to show just the slide names/order.
The roadmap.php?list now includes links for the basic, A/V tech and summary roadmaps available.
In 2021, we began using Audio and Video files embedded in the slides, so the roadmap.php script was modified to collect all the JSON files from a .prs backup and save to a corresponding ./proclaimarchive/YYYY-MM-DD_HH-alljson.txt file so the script could extract details about each Audio or Video file as needed. We also began to explore using Lighting Signals (MIDI) commands to control our OBS software scene selections. Unfortunately, Proclaim doesn't store details about Lighting Signals in the __BackupPresentation.json or other JSON files, so to correlate/display 'what' the signal does, a signals-list.txt can be used to associate the SceneSignal, SceneId with some text to display.
Given the larger .prs files when embedding Audio or Video files in the presentation, the make-roadmap process would sometimes fail due to either max POST size or max time. To fix this, we upload the large presentation to ./temp-proclaim/backup.prs using FTP or SCP copy, then run process-roadmap.php script to add it to the set for roadmap.php to display.
The author of these scripts is not affiliated with Faithlife Proclaim software developers in any way other than as a user of the Proclaim PC/Mac software.
The roadmap scripts use the local Backup Presentation file (.PRS) file for data, and specifically, the contents of the BackupPresentation.json file inside that ZIPped archive is used. Note that the format of that file is not documented and is likely subject to change as updates to Proclaim software are released. The BackupPresentation.json file is a manifest containing the order of slides with detailed content specifications for each slide in the presentation.
This script set was based on decoding by inspection the JSON data for each slide contained in the BackupPresentation.json file.
This script set is released under the GNU GPL-V3 license, and the DataTables scripts (in ./www/psongs/ directory) are under the MIT license. You are free to use/modify the scripts as allowed by the license(s).
The scripts are all located in the ./www/ directory in this distribution which contains a functional website and may be placed in any convenient directory in your website (preserving the relative directory structure/contents)
LICENSE - text of GNU GPL-V3 license for these scripts
README.md - this document
Contents of the ./www/ directory:
./css/ - CSS files for the included website structure
./psongs/ - support files for DataTables queries
./lyricsxml/ - storage for the OpenLyrics .XML files
./proclaimarchive/ - storage for the Proclaim Backup Presentation (.prs and .json) files submitted for roadmap generation. The files use YYYY-MM-DD_HH.{prs|json} as the filenames with YYYY-MM-DD_HH the date and hour of the service. A YYYY-MM-DD_HH-alljson.txt file will contain the contents of all the other .json files in the .prs. The roadmap.php script only uses the .json file and the .txt file for creating the roadmap.
./temp-proclaim/ - storage for a uploaded backup.prs file (uploaded by FTP or SCP). It would then be processed by running process-roadmap.php.
-
sample website structure scripts
- settings-common.php - overall settings for the scripts
- top-parts.php - common top of HTML page
- bottom-parts.php - common bottom/footer of HTML page
- index.php - homepage
-
Song lyrics support scripts
- make-openlp.php - driver page for make-openlp-inc.php
- make-openlp-inc.php - handle generation/editing of OpenLP/OpenLyrics format XML lyrics files
- songlist.php - list/query current .XML songs in the library (uses the DataTables capability)
- proclaim-songs-used.php - list/query songs included in the uploaded Proclaim .PRS slides in roadmaps
-
roadmap generation and display scripts
- make-roadmap.php - script to upload Proclaim .prs file and display (via roadmap.php) the roadmap.
- process-roadmap.php - script to read ./temp-proclaim/backup.prs file uploaded by FTP/SCP and create the needed .json and .txt files for roadmap.php to use.
- roadmap.php - main script to parse selected BackupPresentation.json file and generate the HTML5 roadmap display
- signals-list.txt - user-constructed associative array to convert Proclaim SceneIDs to human-readable text for printing on a roadmap
-
files automatically maintained:
- last-update.txt - modified with timestamp of last upload done through make-roadmap.php script.
- proclaim-songlist.csv - automatically updated by songs-usedcsv.php when a new lyric is downloaded by the make-openlp.php page.
- ./lyricsxml/ - contains the updated OpenLP/OpenLyrics .XML file for the song Downloaded by make-openlp.php. If a song is updated on the server, the prior copy is renamed with a timestamp and a .bak extension before storing the updated song.
- ./proclaimarchive/filelist.txt - automatically updated when a new Proclaim .prs file is uploaded by the make-roadmap.php script.
Copy the entire www/ directory to a website directory of your choice. Be sure to preserve the relative directory structure.
Edit the contents of settings-common.php for your church's data.
<?php
# ------------------------------------------------
# https://github.com/ktrue/proclaim-utility general webpage harness
# settings-common.php
# License: GNU GPLV3
# Author: Ken True
# ------------------------------------------------
# Please change the below to match your local church's information and
# website customization.
# This file is included by all scripts to provide this info uniformly throughout
# the website.
# ------------------------------------------------
#
global $SITE;
$SITE['churchName'] = 'Your Church';
$SITE['churchKeywords'] = 'Your Church, United Church of Christ';
$SITE['oneLicenceNumber'] = '999999'; // church's OneLicense.net number
$SITE['CCLILicenseNumber'] = '11111111'; // church's CCLI number for SongSelect
$SITE['timezone'] = 'America/Los_Angeles';
# list of Announcement slides titles to show contents on summary view
$SITE['summaryAnnounce'] = array('prelude','postlude','anthem');
# ------------------------------------------------
# settings for relative location of Proclaim backups (from make-roadmap)
$SITE['$JSONfilesDir'] = './proclaimarchive/';
$SITE['songlistCSVfile'] = './proclaim-songlist.csv';
# ------------------------------------------------
# settings for make-openlp
$SITE['lyricsXMLdir'] = './lyricsxml/';
$SITE['hymnalList'] = array('New Century Hymnal','The Faith We Sing','Sing! Prayer and Praise','United Methodist Hymnal');
$SITE['hymnalListAbbrev'] = array('NCH','TFWS','SPAP','UMH');
You can delete the contents of the ./proclaimarchive/ directory now.
Use make-roadmap.php to upload a Proclaim Backup presentation to the website and create a roadmap display. This will automatically create the updated support files for you.
The worship roadmap is basically the script for a single worship service that contains the liturgy, the song lyrics and stage/AV cues so the worship team can conduct the service.
The Proclaim slides have content that is projected (in the Content/Lyrics/etc. tabs), and content in the Notes tabs that appear only in the roadmap. Our convention using the Notes tab on a slide is:
- text at the top appears in the roadmap before the slide-name. It is used for AV cues (centered blue text) or participant cues (italic red text).
- text following a
****line (4 asterisks) is for liturgy - readings by the worship team. That text appears inline in the roadmap.
The text formatting of bold, italic, bold-italic, and small-caps is supported by the roadmap script for all content.
The roadmap is a pure HTML5 page that may be easily printed from the browser, or simply viewed online.
Version 1.200 of roadmap.php now supports highlighted text for participants. By default, 'Pastor:','Lay Reader:','Song Leader:', and 'Communion Assistant:' can be used as the start of a Slide title to highlight the text for that person. In a Notes part of a slide, the same string can be used to assign that text to that participant. The highlight function is invoked by a hilite=CCCC argument on the URL. Use ?list to get an index of the currently available roadmaps and links to highlighting the various ones. The names may be modified inside roadmap.php code
global $lookfor;
$lookfor = array( # service participants in open text
'lay reader:' => 'L', # Note: Scripture will generally be highlited for Lay Reader/Lay Leader
'lay leader:' => 'L',
'song leader:' => 'S', # Note: Songs will always be highlited for Song Leader
'pastor:' => 'P',
'communion assistant:' => 'C',
);
The default is to NOT highlight any of the text.
Unfortunately, Proclaim does not store the Lighting Signals in a format that can be accessed by a program. The signals-list.txt file provides a lookup from the SceneId to human-readible text to display. Our sample one is included -- you'll need to construct your own version (as SceneIds are unique per Faithlife group). If you embed your Lighting Signals in slides, then upload and view-source of the roadmap.php?avtech, near the bottom of the page in HTML comments will appear the listing of all Lighting Signals encountered in the slides. Using that, and the current signals-list.txt as a model, you can construct your custom signals-list.txt for your use.
Example: the view-source shows:
'42cb04d0-0bb4-46b5-9392-a1722e234f3f' =>
array (
0 => '13: Prelude',
1 => '21: May You Run and Not Be Weary',
2 => '25: Enter, Rejoice, and Come In',
3 => '27: We Are Your People',
4 => '36: Choir: Anthem',
5 => '45: The Power of Your Love',
6 => '51: As We Gather at Your Table',
7 => '62: Testify to Love',
),
which indicates that SceneId '42cb04d0-0bb4-46b5-9392-a1722e234f3f' was seen on slides 13, 21, 25 etc. with the corresponding slide titles shown.
Those are all for the 'Piano-Choir+Slides' scene in OBS so it should appear in the signals-list.txt file array as
'42cb04d0-0bb4-46b5-9392-a1722e234f3f' => 'signal: OBS scene change to <strong>Piano-Choir+Slides</strong>',
Fortunately, you only have to do this correspondence table once as Proclaim stores it (likely in the cloud) so all the Proclaim users in your presentation group have the same set of Lighting signals available.
I've included a PDF (and Word™) document that was used for training at our church. Feel free to modify/expand it for your church's use.
- Proclaim Utility Guide
- Sample Roadmap (original format)
- Sample Roadmaps (new format)
- Participant roadmap HTML format or browser printed PDF
- AV Tech roadmap HTML format or browser printed PDF
- Summary roadmap HTML format or browser printed PDF
Please use the GitHub Issues area to report issues or make suggestions for additions to the script set.