@karaplay/file-coder 1.2.0 → 1.3.0

package/README.md

@@ -216,3 +216,39 @@ MIT
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
+
+## Changelog
+
+### v1.3.0 (Latest)
+**🔧 Critical Fix: Beginning Lyrics Preservation**
+
+- **Fixed**: Beginning lyrics were being cut off during EMK to KAR and NCN to KAR conversion
+- **Improved**: Smart detection and skipping of instrumental intro markers (e.g., "....ดนตรี....")
+- **Added**: 6 comprehensive tests to verify beginning lyrics preservation
+- **Verified**: All 119 tests passing, ensuring complete lyric integrity from EMK decode to KAR output
+
+**What was fixed:**
+Previously, the conversion process was double-skipping the first 4 lines of lyrics, causing the actual beginning of songs to be missing from KAR files. This version correctly preserves all lyrics from the beginning while intelligently filtering out non-lyrical markers.
+
+**Comparison test:**
+```typescript
+// EMK decoded lyrics vs KAR output: 100% match
+// First lyric: "ท่องเที่ยวมาแล้วแทบทั่วเมืองไทย" ✅
+// Last lyric: "กับยุพิน ที่เมืองพระรถ..." ✅
+```
+
+### v1.2.0
+- Added Thai encoding tests (6 new tests)
+- Verified TIS-620 encoding preservation
+- Updated README with encoding clarification
+
+### v1.1.1
+- Documentation update for Thai encoding in KAR files
+- No code changes
+
+### v1.0.0
+- Initial release
+- Full browser and server support
+- EMK decoding and NCN to KAR conversion
+- Thai language support (TIS-620)
+

package/RELEASE_v1.2.0.md

@@ -0,0 +1,161 @@
+# Release v1.2.0 - Thai Encoding Fix 🎉
+
+## 🐛 Bug Fix Release
+
+**Package**: `@karaplay/file-coder`  
+**Version**: 1.2.0  
+**Published**: December 17, 2025
+
+## ✅ What Was Fixed
+
+### Thai Lyrics Now Fully Readable!
+
+Fixed a critical bug where Thai lyrics in KAR files generated from EMK files were not readable when extracted programmatically.
+
+#### The Problem
+- EMK to KAR conversion was writing Thai text correctly (TIS-620 encoding)
+- BUT when reading KAR files back, Thai characters appeared garbled
+- The `extractLyricsFromKar()` function was not properly decoding Thai text
+
+#### The Solution
+- Fixed `readKarFile()` to properly decode TIS-620 bytes as Thai characters
+- Fixed `extractLyricsFromKar()` to return properly decoded Thai text
+- Applied same fix to browser versions (`readKarBuffer`, `extractLyricsFromKarBuffer`)
+
+## 🧪 New Tests
+
+Added **6 comprehensive Thai encoding tests**:
+
+1. ✅ Preserve Thai characters in title and artist
+2. ✅ Preserve Thai characters when reading KAR file back
+3. ✅ Extract readable Thai lyrics from KAR file
+4. ✅ Handle Thai characters in karaoke track
+5. ✅ Preserve Thai encoding in KAR file bytes
+6. ✅ Match Thai content between EMK and KAR
+
+**Total Tests**: 113 passing (107 original + 6 new)
+
+## 📊 Test Results
+
+```
+Test Suites: 8 passed, 8 total
+Tests:       113 passed, 113 total
+```
+
+All tests pass including:
+- Unit tests for all functions
+- Integration tests with real EMK files
+- Thai encoding verification tests
+- Browser API tests
+
+## 🔧 Technical Details
+
+### Files Modified
+
+1. **`src/kar-reader.ts`**
+   - Fixed `readKarFile()` to decode TIS-620 text events
+   - Simplified `extractLyricsFromKar()` to use decoded text
+
+2. **`src/kar-reader.browser.ts`**
+   - Applied same fixes for browser environment
+
+3. **`src/emk-to-kar.ts`**
+   - Added comment clarifying TIS-620 encoding preservation
+
+### How It Works
+
+```typescript
+// Before (garbled):
+// midi-file decodes as Latin-1 → "àʹèËìàÁ×ͧ¾ÃÐö"
+
+// After (correct):
+// Re-encode as Latin-1 bytes → Decode as TIS-620 → "เสน่ห์เมืองพระรถ"
+```
+
+The fix converts the garbled Latin-1 strings back to their original bytes, then properly decodes them as TIS-620 (Thai encoding).
+
+## 📦 Installation
+
+```bash
+npm install @karaplay/file-coder@1.2.0
+```
+
+Or update:
+
+```bash
+npm update @karaplay/file-coder
+```
+
+## 🎯 Usage Example
+
+```typescript
+import { convertEmkToKar, extractLyricsFromKar } from '@karaplay/file-coder';
+
+// Convert EMK to KAR
+const result = convertEmkToKar({
+  inputEmk: 'song.emk',
+  outputKar: 'song.kar'
+});
+
+console.log(result.metadata.title);  // ✅ Thai text readable!
+console.log(result.metadata.artist); // ✅ Thai text readable!
+
+// Extract lyrics
+const lyrics = extractLyricsFromKar('song.kar');
+lyrics.forEach(lyric => {
+  console.log(lyric); // ✅ Thai lyrics readable!
+});
+```
+
+## 🔍 Verification
+
+Test with your own EMK files:
+
+```javascript
+const { convertEmkToKar, extractLyricsFromKar } = require('@karaplay/file-coder');
+
+// Convert
+convertEmkToKar({
+  inputEmk: 'your-thai-song.emk',
+  outputKar: 'output.kar'
+});
+
+// Extract and verify
+const lyrics = extractLyricsFromKar('output.kar');
+const thaiRegex = /[\u0E00-\u0E7F]/;
+const hasThaiChars = lyrics.some(l => thaiRegex.test(l));
+
+console.log('Thai characters preserved:', hasThaiChars); // Should be true!
+```
+
+## 📝 Breaking Changes
+
+**None** - This is a bug fix release. All existing code will continue to work, but Thai text will now be properly readable.
+
+## 🎊 Summary
+
+| Metric | Value |
+|--------|-------|
+| Version | 1.2.0 |
+| Tests | 113 passing |
+| Bug Fixes | Thai encoding |
+| New Tests | 6 |
+| Breaking Changes | None |
+
+## 🔗 Links
+
+- **npm**: https://www.npmjs.com/package/@karaplay/file-coder
+- **Version**: 1.2.0
+
+## 🙏 Thank You
+
+Thank you for reporting this issue! Thai lyrics are now fully supported and readable throughout the entire EMK→KAR conversion process.
+
+---
+
+**Upgrade now to get proper Thai encoding support!** 🚀
+
+```bash
+npm install @karaplay/file-coder@1.2.0
+```
+

package/dist/ncntokar.browser.js

@@ -170,11 +170,18 @@ function buildKaraokeTrackBrowser(metadata, cursorBuffer, ticksPerBeat) {
     const cursor = new BrowserCursorReader(cursorBuffer);
     const splitter = new grapheme_splitter_1.default();
     let previousAbsoluteTimestamp = 0;
+    // Note: metadata.fullLyric already has title/artist removed (starts from line 4 of original file)
+    // We should process ALL lines in fullLyric to avoid cutting off the beginning
     const lyricsWithEndings = splitLinesKeepEndings(metadata.fullLyric);
-    for (let i = 4; i < lyricsWithEndings.length; i++) {
+    for (let i = 0; i < lyricsWithEndings.length; i++) {
         const trimmed = trimLineEndings(lyricsWithEndings[i]);
         if (!trimmed || trimmed.length === 0)
             continue;
+        // Skip instrumental intro markers (e.g., "....ดนตรี...." or similar patterns)
+        // These are common in EMK files but don't have timing data
+        if (trimmed.match(/^\.{2,}[^.]+\.{2,}$/)) {
+            continue;
+        }
         const lineForTiming = "/" + trimmed;
         const graphemes = splitter.splitGraphemes(lineForTiming);
         for (const g of graphemes) {

package/dist/ncntokar.js

@@ -209,11 +209,18 @@ function buildKaraokeTrack(metadata, cursorBuffer, ticksPerBeat) {
     const splitter = new grapheme_splitter_1.default();
     let previousAbsoluteTimestamp = 0;
     // Process each lyric line
+    // Note: metadata.fullLyric already has title/artist removed (starts from line 4 of original file)
+    // We should process ALL lines in fullLyric to avoid cutting off the beginning
     const lyricsWithEndings = splitLinesKeepEndings(metadata.fullLyric);
-    for (let i = 4; i < lyricsWithEndings.length; i++) {
+    for (let i = 0; i < lyricsWithEndings.length; i++) {
         const trimmed = trimLineEndings(lyricsWithEndings[i]);
         if (!trimmed || trimmed.length === 0)
             continue;
+        // Skip instrumental intro markers (e.g., "....ดนตรี...." or similar patterns)
+        // These are common in EMK files but don't have timing data
+        if (trimmed.match(/^\.{2,}[^.]+\.{2,}$/)) {
+            continue;
+        }
         const lineForTiming = "/" + trimmed;
         const graphemes = splitter.splitGraphemes(lineForTiming);
         for (const g of graphemes) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karaplay/file-coder",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "A comprehensive library for encoding/decoding karaoke files (.emk, .kar, MIDI) with Next.js support. Convert EMK to KAR, read/write karaoke files, full browser and server support.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/temp/Z2510001.lyr

@@ -1,37 +0,0 @@
-�ʹ������ͧ���ö(Ab)
-ǧ�����ǧ 
- Ab
-
-....�����....
-��ͧ�����������᷺�������ͧ��
-������ǧ�������
-���ʹ㨹֡��ҡ��蹪�
-������� ��ǧ�����ʹԤ�
-���͹㨡�ѧ���� �֡��ҡ���繤�����
-��������Ҿ������ʺ��
-�������������˹��
-������觾������ҡ�ҡ˹�
-���ʹԤ� ࢵᴹ��鹪ź���
-�����ͧ���ö����
-����ͧ���������㹵ӹҹ
-���ʹԤ� �֧���¡������ͧ���ö
-����ǧ�����ʴ ���ǵӺż�餹����Ǣҹ
-������§ ��͹�ҧ ��Ң���
-⤡���� ��Шѹ��� ˹�Ҿ�иҵ�
-�Ѵ��ǧ�Ǻ��� �Դ���ҭ
-��ǹ��ѧ�Թ ���˹ͧ��Ҵ
-��觢�ҧ �د�� ��Һح�դ�����
-˹ͧ���§͹��� ������ؾԹ
-��ǹ��е�� ���������Ҫ�������
-�����ҡ���������ӡԹ �Ѻ�ؾԹ������ͧ
-���ö
-....�����...
-���˹ͧ��Ҵ ��觢�ҧ
-�د�� ��Һح�դ�����
-˹ͧ���§͹��������ؾԹ
-��ǹ��е�� ���������Ҫ�������
-�����ҡ���������ӡԹ
-�Ѻ�ؾԹ ������ͧ���ö...
-..���ŧ..
-
-

package/test-emk-to-kar.js

@@ -1,79 +0,0 @@
-const { convertEmkToKar } = require('./dist/emk-to-kar');
-const { readKarFile, extractLyricsFromKar } = require('./dist/kar-reader');
-const fs = require('fs');
-const iconv = require('iconv-lite');
-const path = require('path');
-
-console.log('=== Testing EMK to KAR conversion with Thai lyrics ===\n');
-
-// Clean up old output
-const outputPath = path.join(__dirname, 'test-emk-output.kar');
-if (fs.existsSync(outputPath)) {
-  fs.unlinkSync(outputPath);
-}
-
-// Convert EMK to KAR
-const result = convertEmkToKar({
-  inputEmk: path.join(__dirname, 'songs/emk/Z2510001.emk'),
-  outputKar: outputPath,
-  keepIntermediateFiles: true,
-  intermediateDir: __dirname
-});
-
-console.log('Conversion result:', result.success);
-console.log('Title:', result.metadata.title);
-console.log('Artist:', result.metadata.artist);
-
-// Read the intermediate lyric file
-const lyricPath = path.join(__dirname, 'Z2510001.lyr');
-if (fs.existsSync(lyricPath)) {
-  const lyricBuffer = fs.readFileSync(lyricPath);
-  const lyricText = iconv.decode(lyricBuffer, 'tis-620');
-  console.log('\nIntermediate lyric file (first 200 chars):');
-  console.log(lyricText.substring(0, 200));
-  
-  const thaiRegex = /[\u0E00-\u0E7F]/;
-  console.log('Has Thai in intermediate lyric:', thaiRegex.test(lyricText));
-}
-
-// Read back the KAR file
-console.log('\n=== Reading back the KAR file ===');
-const karInfo = readKarFile(outputPath);
-console.log('KAR Title:', karInfo.metadata.title);
-console.log('KAR Artist:', karInfo.metadata.artist);
-
-// Extract lyrics
-const lyrics = extractLyricsFromKar(outputPath);
-console.log('\nExtracted lyrics (first 10):');
-lyrics.slice(0, 10).forEach((lyric, i) => {
-  console.log(`${i + 1}. "${lyric}"`);
-});
-
-// Check for Thai characters
-const thaiRegex = /[\u0E00-\u0E7F]/;
-const hasThaiInLyrics = lyrics.some(l => thaiRegex.test(l));
-console.log('\n❌ ERROR: Has Thai characters in extracted lyrics:', hasThaiInLyrics);
-console.log('Expected: true');
-console.log('Actual:', hasThaiInLyrics);
-
-// Check the actual bytes in the KAR file
-console.log('\n=== Checking KAR file bytes ===');
-const karBuffer = fs.readFileSync(outputPath);
-let foundThai = false;
-for (let i = 0; i < karBuffer.length - 20; i++) {
-  if (karBuffer[i] === 0x40 && karBuffer[i+1] === 0x54) { // @T
-    const slice = karBuffer.slice(i, Math.min(i + 30, karBuffer.length));
-    const text = iconv.decode(slice, 'tis-620');
-    if (thaiRegex.test(text)) {
-      console.log('✓ Found Thai in KAR bytes:', text.substring(0, 25));
-      foundThai = true;
-      break;
-    }
-  }
-}
-
-if (!foundThai) {
-  console.log('❌ ERROR: No Thai characters found in KAR file bytes!');
-}
-
-process.exit(hasThaiInLyrics ? 0 : 1);

package/test-extract-simple.js

@@ -1,22 +0,0 @@
-const { extractLyricsFromKar } = require('./dist/kar-reader');
-
-const lyrics = extractLyricsFromKar('test-emk-output.kar');
-
-console.log('Total lyrics:', lyrics.length);
-console.log('\nFirst 20 lyrics:');
-lyrics.slice(0, 20).forEach((lyric, i) => {
-  const bytes = Buffer.from(lyric, 'utf8');
-  console.log(`${i + 1}. "${lyric}" [${bytes.length} bytes] [${Array.from(bytes.slice(0, 10)).map(b => '0x'+b.toString(16)).join(', ')}]`);
-});
-
-// Check for Thai
-const thaiRegex = /[\u0E00-\u0E7F]/;
-const hasThaiInLyrics = lyrics.some(l => thaiRegex.test(l));
-console.log('\nHas Thai characters:', hasThaiInLyrics);
-
-// Show some that have Thai
-const thaiLyrics = lyrics.filter(l => thaiRegex.test(l));
-console.log('\nLyrics with Thai (first 10):');
-thaiLyrics.slice(0, 10).forEach((lyric, i) => {
-  console.log(`${i + 1}. "${lyric}"`);
-});

package/test-readkar.js

@@ -1,24 +0,0 @@
-const { readKarFile } = require('./dist/kar-reader');
-
-const info = readKarFile('test-emk-output.kar');
-
-console.log('=== KAR File Info ===');
-console.log('Title:', info.metadata.title);
-console.log('Artist:', info.metadata.artist);
-console.log('Has Karaoke Track:', info.metadata.hasKaraokeTrack);
-console.log('\nTracks:');
-
-info.tracks.forEach((track, i) => {
-  console.log(`\nTrack ${i}: ${track.name || 'unnamed'}`);
-  console.log(`  Events: ${track.events}`);
-  console.log(`  Has Text: ${track.hasText}`);
-  console.log(`  Text Events: ${track.textEvents.length}`);
-  
-  if (track.name === 'Words' && track.textEvents.length > 0) {
-    console.log('  First 15 text events:');
-    track.textEvents.slice(0, 15).forEach((text, j) => {
-      const bytes = Buffer.from(text, 'utf8');
-      console.log(`    ${j}. "${text}" [${bytes.length} bytes]`);
-    });
-  }
-});