174 lines
5.6 KiB
Markdown
174 lines
5.6 KiB
Markdown
# Japji
|
||
|
||
1. A tutorial web-app to help students learn the approved pronunciations for reading Sikh sacred texts;
|
||
2. An experimental use of the [scittle](https://babashka.org/scittle/) dialect of [Clojure](https://clojure.org/).
|
||
|
||
## Lucy's instructions
|
||
|
||
You’ll produce either:
|
||
|
||
Two-file bundle: japji.html + japji_bindranwale.mp3 (zipped), or
|
||
|
||
Single self-contained HTML with the MP3 embedded as a Data URL.
|
||
|
||
The page is the “embed-ready” build that already supports:
|
||
|
||
per-word/per-line playback using the provided timings array
|
||
|
||
a small playback-rate control
|
||
|
||
optional “freeze” to one-file (if you choose that route)
|
||
|
||
0) Input materials (from Lucy)
|
||
|
||
MP3: japji_bindranwale.mp3 (or rename to that).
|
||
|
||
Timings JSON: the long array (save as japji_lines.json or keep handy to paste).
|
||
|
||
Attribution string (optional).
|
||
|
||
Distribution choice (two-file zip vs single HTML).
|
||
|
||
1) Create the HTML
|
||
|
||
Make a file called japji.html with the following structure. It’s the embed-ready page we discussed, with one change: paste the timings JSON into LINES_EMBEDDED = ...;.
|
||
|
||
Find this line near the top of the <script> block:
|
||
|
||
const LINES_EMBEDDED =
|
||
/* paste JSON array below */ [];
|
||
;
|
||
Replace the [] with the full JSON array.
|
||
Important: it must be valid JSON (numbers are fine; don’t include trailing commas).
|
||
|
||
Ensure this default points at the MP3 name:
|
||
|
||
const DEFAULT_AUDIO = 'japji_bindranwale.mp3';
|
||
If your MP3 has a different filename, either rename the file or change this constant.
|
||
|
||
Calibration (fine-tuning alignment) is here; leave as-is unless you need to shift globally:
|
||
|
||
const CAL = { offsetMs: -80, prerollMs: 40, earlyMs: 30, hiRes: true };
|
||
If you don’t have my last HTML, ping me and I’ll re-send. It’s the same one that:
|
||
|
||
auto-loads japji_bindranwale.mp3 if it sits next to the HTML
|
||
|
||
offers a “Paste Data URL → Download frozen one-file” path
|
||
|
||
2) Local sanity check
|
||
|
||
Put japji.html and japji_bindranwale.mp3 in the same folder.
|
||
|
||
Double-click japji.html to open in a modern browser (Chrome, Edge, or Safari).
|
||
|
||
Confirm:
|
||
|
||
Clicking a word plays just that word (highlighted).
|
||
|
||
Clicking the bullet plays the entire line.
|
||
|
||
The Rate control works.
|
||
|
||
No console errors.
|
||
|
||
If alignment feels globally late/early, adjust CAL.offsetMs by ±10–30ms and re-test.
|
||
|
||
3) Build the distribution(s)
|
||
|
||
Option A (recommended): Two-file zip
|
||
|
||
Keep both files in one folder:
|
||
|
||
dist/
|
||
japji.html
|
||
japji_bindranwale.mp3
|
||
README.txt
|
||
Create README.txt (use the template below).
|
||
|
||
Zip the dist/ contents into japji_v1_YYYYMMDD.zip.
|
||
|
||
Pros: small HTML, clean, highest audio quality, simplest for non-technical users.
|
||
Cons: they must keep the two files together (the README explains this clearly).
|
||
|
||
Option B: Single self-contained HTML
|
||
|
||
You have two easy paths:
|
||
|
||
Path 1 — Use the built-in UI (no CLI needed):
|
||
|
||
Open japji.html in a browser.
|
||
|
||
Click “Load MP3” and pick japji_bindranwale.mp3 (only to confirm it plays).
|
||
|
||
Use a Data-URL generator (or a tiny helper page) to copy a data:audio/...;base64,... string.
|
||
|
||
Paste that into the “Paste Data URL” box → click Use.
|
||
|
||
Click “Download frozen one-file” — it produces japji_bindranwale_onefile.html.
|
||
|
||
Rename to japji_onefile_v1.html.
|
||
|
||
Path 2 — CLI (Node) to generate the Data URL:
|
||
|
||
node -e "const fs=require('fs');const b64=fs.readFileSync('japji_bindranwale.mp3').toString('base64');console.log('data:audio/mpeg;base64,'+b64)"
|
||
Copy the output string.
|
||
|
||
Open japji.html → paste into the “Paste Data URL” box → Use → Download frozen one-file.
|
||
|
||
Pros: perfect for emailing a single file.
|
||
Cons: HTML can be large (several MB); some email systems may warn about size.
|
||
|
||
4) README to include (copy/paste)
|
||
|
||
README.txt
|
||
|
||
Japji Sahib — Interactive (per-word audio)
|
||
|
||
How to use
|
||
1) Unzip everything into a single folder.
|
||
2) Double-click “japji.html” to open it in your browser.
|
||
3) Click any Gurmukhi word to hear that word; click the bullet (•) to hear the whole line.
|
||
4) Use the “Rate” dropdown to slow down or speed up playback.
|
||
|
||
Important
|
||
- Keep “japji.html” and “japji_bindranwale.mp3” in the same folder. Don’t move one without the other.
|
||
- Works offline. Nothing is uploaded anywhere.
|
||
- Best in Chrome/Edge/Safari. If audio doesn’t play, try a different browser.
|
||
- For best text quality, install the free “Noto Sans Gurmukhi” font from Google Fonts.
|
||
|
||
Credits
|
||
- Audio: Bhai Jarnail Singh Ji Bindranwale. Educational use.
|
||
- Tooling and timings provided by the project team.
|
||
|
||
Troubleshooting
|
||
- No sound? Check your system volume, then try another browser.
|
||
- If the page opens but the audio doesn’t play, make sure the MP3 file name is exactly: japji_bindranwale.mp3
|
||
(For the single-file variant, replace the “Important” section’s second bullet with:
|
||
“This is a single file; no MP3 needed.”)
|
||
|
||
5) QA checklist before hand-off
|
||
|
||
✅ Words and bullets play correctly on desktop (Chrome + one other browser).
|
||
|
||
✅ Works offline (disconnect and test).
|
||
|
||
✅ Zip contains exactly: japji.html, japji_bindranwale.mp3, README.txt.
|
||
|
||
✅ File names match exactly (case-sensitive on some systems).
|
||
|
||
✅ README updated with your chosen attribution line.
|
||
|
||
(Optional) ✅ Smoke-test on iOS Safari / Android Chrome.
|
||
|
||
### Scittle framework included
|
||
|
||
**NOTE THAT** this repository includes virtually the whole of [Michiel
|
||
Borkent](https://github.com/borkdude)'s [Scittle](https://github.com/babashka/scittle) framework, which is copyright Michiel Borkent and others, and is licensed under the Eclipse Puplic License; and Scittle in turn includes a great deal of Clojurescript
|
||
|
||
This program and the accompanying materials are made available under the
|
||
terms of the Eclipse Public License 2.0 which is available at
|
||
http://www.eclipse.org/legal/epl-2.0.
|
||
|
||
### Original code and audio recordings of the Japji project
|
||
|