@ugfoundation/swaralipi-js 0.1.0

package/LICENSE

@@ -0,0 +1,347 @@
+swaralipi-js
+Copyright (C) 2026 Upal & Gopa Das Foundation
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License version 2 as
+published by the Free Software Foundation.
+
+----------------------------------------------------------------------
+
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
+ <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Lesser General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                    GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+                            NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License along
+    with this program; if not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) year name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  <signature of Moe Ghoul>, 1 April 1989
+  Moe Ghoul, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.

package/README.md

@@ -0,0 +1,257 @@
+# swaralipi-js
+
+`@ugfoundation/swaralipi-js` — a JSON spec, a Unicode-Bengali viewer, a Tone.js player, and an NLTR converter for **Rabindrasangeet swaralipi** (Tagore's আকারমাত্রিক / *akarmatrik* notation).
+
+The spec is the contract: write (or generate) a swaralipi **JSON document**, then hand the same document to the viewer, the player, or the printer. Built for [gitabitan.io](https://github.com/UGFoundation), published standalone under GPL-2.0-only.
+
+```sh
+pnpm add @ugfoundation/swaralipi-js      # or npm / yarn
+```
+
+## Quick start
+
+The smallest useful program: validate a document and render it.
+
+```ts
+import { parseSwaralipi } from '@ugfoundation/swaralipi-js/spec';
+import { renderToHtml, SWARALIPI_CSS } from '@ugfoundation/swaralipi-js/viewer';
+
+const doc = parseSwaralipi({
+  version: '0.1.0',
+  meta: { title: 'অকারণে', taal: { id: 'dadra', numBeats: 6 }, tonic: 'C' },
+  parts: [{ name: 'asthayi', rows: [{ notes: [
+    { svara: ['madhyam', 'm'], lyric: 'অ' },
+    { svara: ['madhyam', 'p'], lyric: 'কা' },
+    { sustain: true, lyric: '৹' },
+    { bar: 'single' },
+  ] }] }],
+});
+
+document.head.insertAdjacentHTML('beforeend', `<style>${SWARALIPI_CSS}</style>`);
+document.body.innerHTML = renderToHtml(doc, { lang: 'bn' });
+```
+
+---
+
+# Writing a swaralipi document
+
+A document is a single JSON object: `{ version, meta, parts }`. A **part** is a section (আস্থায়ী / অন্তরা …) holding **rows** (written lines); a row holds **notes** (the tokens below). Build it by hand, generate it from a tool, or produce it with the [converter](#convert-nltr-html--json). Everything else in this package consumes this shape.
+
+```jsonc
+{
+  "version": "0.1.0",
+  "meta": { /* see below */ },
+  "parts": [
+    { "name": "asthayi", "rows": [ { "notes": [ /* tokens */ ] } ] }
+  ]
+}
+```
+
+### meta
+
+Only `title` is required. The rest is optional but drives playback and the header.
+
+```jsonc
+"meta": {
+  "title": "অকারণে অকালে মোর পড়ল যখন ডাক",
+  "taal": { "id": "dadra", "numBeats": 6, "bhaags": [3, 3], "sam": 0, "khaali": [3] },
+  "taalName": "দাদরা",        // verbatim source name (use when `taal.id` is unknown)
+  "tonic": "C",               // base pitch — "C", "C#"/"cs", "Db" all accepted
+  "bpm": 144,                 // default tempo, matra/min (player only; viewer ignores it)
+  "avartan": 2,               // আবর্তন count, when the source states it
+  "notationBy": "…", "source": "…"   // provenance
+}
+```
+
+### svara — pitched notes
+
+A pitch is a `[octave, letter]` tuple. Octaves: `ati-mandra`, `mandra`, `madhyam`, `taar`, `ati-taar`. Letters: `s r g m p d n` (`d`=ধৈবত/dha, `n`=নিষাদ/ni). Sharps/flats are **flags**, not letters:
+
+```jsonc
+{ "svara": ["madhyam", "g"] }                       // শুদ্ধ গ
+{ "svara": ["madhyam", "g"], "komal": true }        // কোমল গ (flat)
+{ "svara": ["madhyam", "m"], "tivra": true }        // কড়ি/তীব্র ম (sharp)
+{ "svara": ["taar", "s"] }                          // taar সা (high)
+{ "svara": ["mandra", "p"] }                        // mandra প (low)
+{ "svara": ["madhyam", "r"], "microtone": "atikomal" }  // sub-komal: alpakomal | atikomal
+```
+
+### duration — matra groups
+
+Default duration is **1 মাত্রা**. Use `durationMatra` for fractional or held notes; a run of fractions summing to a whole matra renders as one beamed group (`nsfa` → নর্সা):
+
+```jsonc
+{ "svara": ["madhyam", "n"], "durationMatra": 0.5 }   // half-matra
+{ "svara": ["taar", "s"],    "durationMatra": 0.5 }   // …grouped with the one above
+{ "svara": ["madhyam", "p"], "durationMatra": 2 }     // held two matras
+```
+
+### sustain (আ-কার) and melisma
+
+```jsonc
+{ "sustain": true, "lyric": "৹" }                       // hold prev pitch+vowel (আ-কার)
+{ "svara": ["taar", "s"], "sustain": true, "lyric": "৹" } // melisma: pitch moves, vowel continues
+```
+
+### rest (বিরাম)
+
+```jsonc
+{ "rest": true, "durationMatra": 1 }                    // silence for one matra
+```
+
+### bars — দাঁড়ি / দণ্ড
+
+```jsonc
+{ "bar": "dari" }     // ।   vibhag separator inside the cycle
+{ "bar": "single" }   // I   end of one taal cycle (ফেরা)
+{ "bar": "double" }   // II  section / return-to-asthayi boundary
+{ "bar": "quad" }     // IIII end of the song
+```
+
+### brackets — repeat / skip / alt
+
+A bracket spans a range; the first note carries `edge: 'open'`, the last `edge: 'close'`.
+`repeat` = `{}` গুন্ডবন্ধনী · `skip` = `()` omit on repeat · `alt` = `[]` changed-on-repeat.
+
+```jsonc
+{ "svara": ["madhyam", "s"], "brackets": [{ "kind": "repeat", "edge": "open" }] }
+{ "svara": ["madhyam", "r"], "brackets": [{ "kind": "repeat", "edge": "close" }] }
+```
+
+### kan (grace) and meend (glide)
+
+```jsonc
+{ "svara": ["madhyam", "n"], "kan": ["taar", "s"] }   // কণ grace before the note
+{ "svara": ["madhyam", "p"], "meend": "start" }       // মীড় slur start …
+{ "svara": ["madhyam", "g"], "meend": "end" }         // … and end
+```
+
+### lyrics and annotations
+
+`lyric` rides on the **note** (column-aligned, per-syllable). `above` / `below` attach recursive notes for alt-on-repeat passages, stop marks, or beat labels:
+
+```jsonc
+{ "svara": ["madhyam", "m"], "lyric": "অ",
+  "above": [{ "svara": ["madhyam", "p"] }] }           // alt note printed above
+```
+
+### raw — lossless passthrough
+
+Anything the converter can't decode is preserved verbatim in `raw` and rendered dimmed — **the spec is lossless by construction**, nothing is silently dropped. You rarely write `raw` by hand.
+
+```jsonc
+{ "raw": "w", "below": [/* … */] }
+```
+
+### Validate what you wrote
+
+```ts
+import { parseSwaralipi, safeParseSwaralipi } from '@ugfoundation/swaralipi-js/spec';
+
+parseSwaralipi(json);            // returns typed Swaralipi, throws ZodError if invalid
+safeParseSwaralipi(json);        // { success, data | error } — no throw
+```
+
+See [`fixtures/`](./fixtures) for worked documents — `octaves`, `microtones`, `matra-durations`, `repeat-brackets`, and the hand-checked `akarone` anchor.
+
+---
+
+# Deploying the document
+
+## View: `<swaralipi-sheet>`
+
+Renders the document as **Unicode Bengali + a CSS grid** — no images, no embedded font, no framework. Arcs, kan, bars, beat labels and annotations all render.
+
+```html
+<script type="module">
+  import { defineSwaralipiSheet } from '@ugfoundation/swaralipi-js/viewer';
+  defineSwaralipiSheet();
+</script>
+
+<swaralipi-sheet src="/notation/4270.json" lang="bn"></swaralipi-sheet>
+```
+
+Pass a URL via `src` or set the `doc` property directly. `lang` is `bn | hi | en` (Devanagari for `hi`, roman + octave dots for `en`); `hide-header`; `highlight('part.row.note')` for player sync. Styles are shadow-DOM-encapsulated, themeable via `--sw-font`, `--sw-size`, `--sw-cell-gap`, `--sw-hl`.
+
+**SSR / static sites (Astro etc.)** — `renderToHtml` is a pure function (string in, string out, no DOM); emit it alongside `SWARALIPI_CSS`. See [Quick start](#quick-start).
+
+### Print / PDF
+
+```ts
+import { printSwaralipi, renderPrintDocument } from '@ugfoundation/swaralipi-js/viewer';
+
+printSwaralipi(doc, { lang: 'bn', title: 'song-name' });   // hidden-iframe → print dialog
+const page = renderPrintDocument(doc);                     // full HTML string (new tab / headless)
+```
+
+`document.querySelector('swaralipi-sheet').print()` is the element shortcut. PDF fidelity comes from the **browser's own engine** — the same Indic shaping (reph, conjuncts, matra) and CSS-drawn marks as the screen — so we deliberately avoid html2canvas/jsPDF, which can't shape Indic text.
+
+## Play: `SwaralipiPlayer`
+
+A [Tone.js](https://tonejs.dev) player turns a document into audio — melody on **santoor / harmonium / violin / flute / grand piano**, a **tabla** loop (metronome for unrecorded taals), and a **tanpura** drone — and drives the viewer's highlight in sync. Tone is dynamically imported on first `play()`, so importing the module never touches `AudioContext` — safe in Node/SSR.
+
+```ts
+import { SwaralipiPlayer } from '@ugfoundation/swaralipi-js/player';
+
+const player = new SwaralipiPlayer();        // zero-config: samples from the project CDN
+player.load(doc);
+player.bindSheet(document.querySelector('swaralipi-sheet'), { autoScroll: true });
+
+playButton.onclick = () => player.play();    // must be a user gesture (AudioContext)
+```
+
+Controls: `setTonic('C#')`, `setBpm(120)`, `setInstrument(id)`, `setTaal(id|null)`, `setRhythm('tabla'|'metronome'|'none')`, `setTanpura(bool)`, `pause()` / `stop()` / `dispose()`. Each song loads only the samples covering its pitch range.
+
+- **Self-host samples:** override `soundsBaseUrl` (layout: `santoor/<note>.mp3`, `tabla/<taal>/<taal><bpm>bpm.mp3`, `tanpura/<pc>.mp3`).
+- **Add instruments:** `customInstruments: { sitar: { label, urls, baseUrl } }`.
+- **Liveness:** `await player.checkInstruments()` → `{ id: available }`, to grey out picker options whose samples are down.
+
+The pure, audio-free scheduler is exported too (`buildSchedule`, `svaraToMidi`, `parseTonic`, `INSTRUMENTS`, …) for a custom transport.
+
+## Convert: NLTR HTML → JSON
+
+[NLTR's Rabindra Rachanabali](https://rabindra-rachanabali.nltr.org) renders swaralipi as HTML grids in the ASCII-encoded **Swarabitan** webfont. The converter decodes that codec into spec JSON, losslessly. Across the full 1,738-song corpus: 100% of files convert, **99.95%** of notation cells decode semantically, the rest preserved raw and reported.
+
+```sh
+swaralipi convert 4270.html                          # spec JSON to stdout
+swaralipi convert nltr/html -o out/ --report out/_report.json
+```
+
+```ts
+import { convertNltrHtml } from '@ugfoundation/swaralipi-js/convert';   // Node-only subpath
+const { doc, report } = convertNltrHtml(html, { nltrId: 4270 });
+```
+
+## Subpath exports
+
+| Import | Environment |
+|--------|-------------|
+| `@ugfoundation/swaralipi-js` (root, re-exports `/spec`) | any |
+| `@ugfoundation/swaralipi-js/spec` | any |
+| `@ugfoundation/swaralipi-js/viewer` | browser / SSR |
+| `@ugfoundation/swaralipi-js/player` | browser (Node/SSR-safe import) |
+| `@ugfoundation/swaralipi-js/convert` | Node only |
+| `swaralipi` CLI | Node |
+
+---
+
+## Develop
+
+```sh
+pnpm install
+pnpm build   # tsup → dist/ (ESM + CJS + .d.ts)
+pnpm test    # vitest
+pnpm check   # tsc --noEmit
+```
+
+Node 20 LTS (`.nvmrc`), pnpm 9. Contributions are welcome under a CLA — see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Credits
+
+- **[NLTR](https://nltr.org)** (Society for Natural Language Technology Research) — the [Rabindra Rachanabali](https://rabindra-rachanabali.nltr.org) digital edition and its Swarabitan-encoded swaralipi are the source corpus this package decodes. Tagore's notation itself is in the public domain.
+- **[sargam-spec](https://github.com/Studio-kalavati/sargam-spec)** by **Studio Kalavati** (EPL-2.0) — swaralipi-js's spec is an independent reimplementation that extends sargam-spec's format; we keep its `[octave, letter]` svara tuple and octave/letter conventions.
+- **Audio samples**, all **CC-BY**: the default Salamander Grand Piano by Alexander Holm; harmonium / violin / flute from [tonejs-instruments](https://github.com/nbrosowsky/tonejs-instruments) by Nicholaus Brosowsky; santoor / tabla / tanpura / metronome redistributed on the project CDN.
+
+## License
+
+GPL-2.0-only © Upal & Gopa Das Foundation. See [LICENSE](./LICENSE).

package/dist/batch-NF2Q2CFS.js

@@ -0,0 +1,47 @@
+import { convertNltrHtml, aggregate, formatSummary } from './chunk-N3NNWAOW.js';
+import './chunk-C6O7DYU5.js';
+import './chunk-GWXI2HJA.js';
+import { stat, readdir, mkdir, readFile, writeFile } from 'fs/promises';
+import { join, basename } from 'path';
+
+var nltrIdOf = (file) => {
+  const m = basename(file).match(/^(\d+)\.html$/);
+  return m ? Number(m[1]) : void 0;
+};
+var serialize = (doc, compact) => (compact ? JSON.stringify(doc) : JSON.stringify(doc, null, 2)) + "\n";
+async function runConvert(input, opts = {}) {
+  const log = opts.log ?? ((line) => process.stderr.write(line + "\n"));
+  const stats = await stat(input);
+  const files = stats.isDirectory() ? (await readdir(input)).filter((f) => f.endsWith(".html")).sort((a, b) => (nltrIdOf(a) ?? 0) - (nltrIdOf(b) ?? 0) || a.localeCompare(b)).map((f) => join(input, f)) : [input];
+  const isDir = stats.isDirectory();
+  if (isDir && !opts.out) throw new Error("directory input requires -o <outDir>");
+  if (isDir && opts.out) await mkdir(opts.out, { recursive: true });
+  const reports = [];
+  const failures = [];
+  for (const file of files) {
+    try {
+      const html = await readFile(file, "utf8");
+      const { doc, report: report2 } = convertNltrHtml(html, { nltrId: nltrIdOf(file) });
+      reports.push(report2);
+      const json = serialize(doc, opts.compact);
+      if (isDir) {
+        const name = `${nltrIdOf(file) ?? basename(file, ".html")}.json`;
+        await writeFile(join(opts.out, name), json);
+      } else if (opts.out) {
+        await writeFile(opts.out, json);
+      } else {
+        process.stdout.write(json);
+      }
+    } catch (err) {
+      failures.push({ file: basename(file), error: err instanceof Error ? err.message : String(err) });
+    }
+  }
+  const report = aggregate(reports, failures);
+  if (opts.reportPath) await writeFile(opts.reportPath, serialize(report, false));
+  if (!opts.quiet) log(formatSummary(report));
+  return { exitCode: failures.length > 0 ? 1 : 0, report };
+}
+
+export { runConvert };
+//# sourceMappingURL=batch-NF2Q2CFS.js.map
+//# sourceMappingURL=batch-NF2Q2CFS.js.map

package/dist/batch-NF2Q2CFS.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/convert/batch.ts"],"names":["report"],"mappings":"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","file":"batch-NF2Q2CFS.js","sourcesContent":["/**\n * File/dir conversion driver for the CLI (Node-only; not part of the\n * public `/convert` export). Continues past per-file failures and reports\n * them in the aggregate.\n */\nimport { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';\nimport { basename, join } from 'node:path';\nimport { convertNltrHtml } from './index.js';\nimport { aggregate, formatSummary, type BatchFailure, type BatchReport, type FileReport } from './report.js';\n\nexport interface BatchOptions {\n  /** Output file (single input) or directory (directory input). */\n  out?: string;\n  /** Write the aggregate report JSON here. */\n  reportPath?: string;\n  compact?: boolean;\n  quiet?: boolean;\n  /** Progress/summary sink (default stderr). */\n  log?: (line: string) => void;\n}\n\nconst nltrIdOf = (file: string): number | undefined => {\n  const m = basename(file).match(/^(\\d+)\\.html$/);\n  return m ? Number(m[1]) : undefined;\n};\n\nconst serialize = (doc: unknown, compact: boolean | undefined): string =>\n  (compact ? JSON.stringify(doc) : JSON.stringify(doc, null, 2)) + '\\n';\n\nexport async function runConvert(\n  input: string,\n  opts: BatchOptions = {},\n): Promise<{ exitCode: 0 | 1; report: BatchReport }> {\n  const log = opts.log ?? ((line: string) => process.stderr.write(line + '\\n'));\n  const stats = await stat(input);\n  const files = stats.isDirectory()\n    ? (await readdir(input))\n        .filter((f) => f.endsWith('.html'))\n        .sort((a, b) => (nltrIdOf(a) ?? 0) - (nltrIdOf(b) ?? 0) || a.localeCompare(b))\n        .map((f) => join(input, f))\n    : [input];\n\n  const isDir = stats.isDirectory();\n  if (isDir && !opts.out) throw new Error('directory input requires -o <outDir>');\n  if (isDir && opts.out) await mkdir(opts.out, { recursive: true });\n\n  const reports: FileReport[] = [];\n  const failures: BatchFailure[] = [];\n  for (const file of files) {\n    try {\n      const html = await readFile(file, 'utf8');\n      const { doc, report } = convertNltrHtml(html, { nltrId: nltrIdOf(file) });\n      reports.push(report);\n      const json = serialize(doc, opts.compact);\n      if (isDir) {\n        const name = `${nltrIdOf(file) ?? basename(file, '.html')}.json`;\n        await writeFile(join(opts.out!, name), json);\n      } else if (opts.out) {\n        await writeFile(opts.out, json);\n      } else {\n        process.stdout.write(json);\n      }\n    } catch (err) {\n      failures.push({ file: basename(file), error: err instanceof Error ? err.message : String(err) });\n    }\n  }\n\n  const report = aggregate(reports, failures);\n  if (opts.reportPath) await writeFile(opts.reportPath, serialize(report, false));\n  if (!opts.quiet) log(formatSummary(report));\n  return { exitCode: failures.length > 0 ? 1 : 0, report };\n}\n"]}