Precentor

Sing the 1650 Scottish Psalter, the Psalms of David in Metre. The app has all 150 psalms and the second versions of 13 psalms. Each psalm has a choice of tunes. The player plays the tune in four parts and lights each syllable when you must sing it.

In Scottish churches the precentor led the psalm singing, one line at a time. This app does the same.

Use the app at precentor.app.

If Precentor helps you, you can support it on Ko-fi.

One app for three platforms

Precentor is one Expo app (SDK 58, React Native 0.88, Expo Router). The same code runs on the web, on iOS and on Android. On the web, react-native-web renders the app.

Part	Web	iOS and Android
Screens	src/app/, rendered by react-native-web	src/app/, native views
Sound	The Web Audio API of the browser	react-native-audio-api, a native Web Audio engine
Sheet music	abcjs draws SVG in the page	abcjs draws SVG in an Expo DOM component, in a web view
Psalm data	The app gets corpus/ from the server	The app reads corpus/ from its own bundle
Settings	localStorage	AsyncStorage

A file that ends in .native.ts replaces the file of the same name on iOS and Android.

Run

The app needs Node 24 or later.

npm install
npm run dev        # the web app at http://localhost:5180
npm run build      # the static web app in dist/
npm test           # the tests of the engine, the music, the routes and the analytics

npm install also runs scripts/link-corpus.mjs. See Psalm data on iOS and Android.

Run on an iPhone

The sound engine is a native module. Expo Go does not contain it, so you need a development build.

To make a development build in the cloud, do these steps:

1. Create an Expo account.
2. Run npx eas-cli@latest login.
3. Run npx eas-cli@latest init. This command writes the project id into app.json.
4. To register the iPhone, run npx eas-cli@latest device:create.
5. Run npx eas-cli@latest build --profile development --platform ios.
6. Install the build on the iPhone from the link that the build shows.
7. Run npx expo start.
8. Scan the QR code with the camera of the iPhone.

To make the build on a Mac with Xcode, connect the iPhone and run npx expo run:ios --device. For the iOS Simulator, run npx expo run:ios. For Android, run npx expo run:android.

The app opens in Expo Go, but Expo Go plays no sound. The words and the notes still follow the beat, and the player shows a note about the development build.

On iOS, the app sets the category of the audio session to playback. So when the iPhone is on silent, the tune plays, as in a music app.

Checks before a release

npx tsc --noEmit
npx expo lint
npx expo-doctor
npx expo export --platform ios --platform android   # the native bundles must compile
npm run build                                       # the web app

Paths and links

Path	Screen
/	The psalms
/psalm/023	Psalm 23. 023b is the second version.
/psalm/023?tune=dundee	Psalm 23 on the tune Dundee
/about, /about/metre	The About page

The deep link precentor://psalm/023 opens the same screen in the native app.

The Vite app used hash routes, for example https://precentor.app/#/psalm/023?tune=dundee. Other apps, for example Covenant Household and Hearers, link to these addresses. Before the router starts, src/lib/legacyHash.ts changes an old hash route to its path. So each old link opens the same psalm and the same tune.

Psalm data on iOS and Android

The native app carries all of the psalm data in its bundle. It does not get the data from precentor.app. These are the reasons:

• Each psalm plays with no network, from the first start. Singing offline is important, for example in a church with no signal.
• The data is 22 MB, but it compresses to 1.5 MB. The stores compress the app. So the data makes the download only a little larger.
• The app has no cache to fill, to check or to clear, and no code for a failed download.

To change the data, release a new version of the app.

Metro bundles a .json file as code. For this reason, scripts/link-corpus.mjs links each file of public/corpus/ to assets/corpus/ with the extension .corpus, and metro.config.js treats that extension as an asset. The script also writes src/data/corpusAssets.native.ts. The postinstall script and the eas-build-post-install script run it. Git does not keep assets/corpus/.

Deployment

CI owns the deployment to Cloudflare Pages. Do not deploy from a workstation.

1. A push to main starts the Website workflow. It runs the tests and builds dist/.
2. When Website passes, the Deploy to Cloudflare Pages workflow starts.
3. That workflow downloads the dist/ artifact. It does not build again.
4. It makes the Pages project precentor if the project does not exist.
5. It deploys the artifact and the Pages Functions to the production branch main.
6. It checks the app, the psalm data and /a/boot.js on the live site.

Each pull request from this repository also gets a preview. The job summary of the Website run shows the preview address.

The workflows need two repository secrets:

Secret	Value
CLOUDFLARE_API_TOKEN	An API token with the permission Account, Cloudflare Pages, Edit
CLOUDFLARE_ACCOUNT_ID	The account ID from the Cloudflare dashboard

npm run build runs expo export --platform web, then scripts/web-postbuild.mjs. The export copies public/ into dist/, with the psalm data, _headers, the icon and the web manifest. public/index.html is the page template. scripts/web-postbuild.mjs writes the service worker dist/sw.js, and copies the app icon to dist/apple-touch-icon.png.

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗