# 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.

