@karaplay/file-coder 1.5.1 → 1.5.3

package/RELEASE_v1.5.2.md

@@ -0,0 +1,238 @@
+# Release v1.5.2 - High PPQ File Support
+
+**Date:** 2026-01-13  
+**Type:** Bug Fix
+
+## 🐛 Bug Fix: Incorrect Tempo Ratio for High PPQ Files
+
+### Problem
+
+The file `Z2510006.emk` (Move On แบบใด - โจอี้ ภูวศิษฐ์) was incorrectly converted with:
+- **Tempo Ratio:** 20x ❌ (should be 1x)
+- **Duration:** 0:12 (12.83 seconds) ❌ (should be 4:16)
+- **Tempo:** 87 BPM → 1,740 BPM ❌ (should stay 87 BPM)
+
+**Root Cause:**  
+The system calculated tempo ratio as `PPQ / 24`:
+- Z2510006 has `PPQ = 480`
+- Calculated ratio: `480 / 24 = 20x` ❌
+- But this file already has correct tempo and doesn't need adjustment!
+
+### Solution
+
+Added special handling for **high PPQ files** (PPQ >= 480):
+
+```typescript
+if (isZxioFormat) {
+  ratio = ticksPerBeat / 77.42;  // ZXIO: 1.24x
+} else if (ticksPerBeat >= 480) {
+  ratio = 1.0;  // High PPQ: No adjustment needed ✅
+} else {
+  ratio = ticksPerBeat / 24;  // Standard MThd: 4x, 8x, etc.
+}
+```
+
+### Results
+
+**Before Fix:**
+```
+Move On แบบใด (Z2510006.emk):
+  - Tempo: 87 → 1,740 BPM (20x) ❌
+  - Duration: 0:12 ❌
+  - Status: Incorrect
+```
+
+**After Fix:**
+```
+Move On แบบใด (Z2510006.emk):
+  - Tempo: 87 → 87 BPM (1x) ✅
+  - Duration: 4:16 ✅
+  - Matches reference KAR: 100% ✅
+```
+
+---
+
+## 📊 Impact
+
+### Files Affected
+
+**Z2510006.emk only:**
+- This is the only file in our test set with PPQ >= 480
+- Other files (PPQ < 480) are not affected
+- All 9/9 tests pass ✅
+
+### Tempo Ratio Distribution (Updated)
+
+| Ratio | Format | Count | Files |
+|-------|--------|-------|-------|
+| 1.00x | MThd (High PPQ) | 1 | Z2510006 ✅ **NEW** |
+| 1.24x | ZXIO | 3 | 001, 001_original, failed01 |
+| 4.00x | MThd | 4 | Z2510001, Z2510002, Z2510004, Z2510005 |
+| 8.00x | MThd | 1 | Z2510003 |
+
+**Old (incorrect):**
+- 20x: 1 file ❌ (removed)
+
+---
+
+## ✅ Testing
+
+### Test Results
+
+```
+$ npm run test:emk
+
+✅ Passed:   9/9
+⚠️  Warnings: 0/9
+❌ Failed:   0/9
+
+🎉 All tests passed!
+```
+
+### Specific Test: Z2510006
+
+```
+Testing: Z2510006.emk
+   ✅ PASS: All checks passed
+
+Comparison with Reference KAR:
+   Converted Tempo: 87.00 BPM
+   Reference Tempo: 87.00 BPM
+   Match: YES ✅
+
+   Converted Duration: 256.64 s (4:16)
+   Reference Duration: 256.64 s (4:16)
+   Difference: 0.00 s
+   Match: YES ✅
+```
+
+---
+
+## 📝 Changed Files
+
+### Core Library
+
+1. **src/ncntokar.ts**
+   - Updated `fixEmkMidiTempo()` function
+   - Added PPQ >= 480 check
+
+2. **src/ncntokar.browser.ts**
+   - Updated `fixEmkMidiTempoBrowser()` function
+   - Same PPQ >= 480 logic
+
+### Documentation
+
+3. **EMK_REFERENCE_DATA.json**
+   - Updated Z2510006 expected values
+   - Tempo: 1740 → 87 BPM
+   - Duration: 12.83 → 256.64s
+   - Ratio: 20x → 1x
+
+4. **SONG_LIST.txt**
+   - Updated Z2510006 information
+   - Fixed duration statistics
+
+---
+
+## 🚀 Migration
+
+### From v1.5.1 to v1.5.2
+
+**No Breaking Changes!**
+
+Simply update:
+
+```bash
+npm install @karaplay/file-coder@1.5.2
+```
+
+**All existing code continues to work.**
+
+### What Changed
+
+If you were converting `Z2510006.emk` or similar files with PPQ >= 480:
+
+**Before (v1.5.1):**
+```typescript
+// Would produce incorrect 12-second file
+convertEmkToKar({ 
+  inputEmk: 'Z2510006.emk', 
+  outputKar: 'output.kar' 
+});
+// Duration: 0:12 ❌
+```
+
+**After (v1.5.2):**
+```typescript
+// Now produces correct 4:16 file
+convertEmkToKar({ 
+  inputEmk: 'Z2510006.emk', 
+  outputKar: 'output.kar' 
+});
+// Duration: 4:16 ✅
+```
+
+---
+
+## 🎓 Technical Details
+
+### PPQ (Pulses Per Quarter Note)
+
+**Common PPQ Values:**
+- 96: Standard (ratio = 96/24 = 4x)
+- 120: Standard (ratio = 120/24 = 5x)  
+- 480: High resolution (ratio = 1x, no conversion needed)
+
+**Why PPQ 480 is different:**
+- Higher temporal resolution
+- Usually means the file is already properly timed
+- Common in professional MIDI editors
+- Doesn't need our EMK tempo correction
+
+### Detection Logic
+
+```typescript
+// ZXIO: Always 1.24x
+if (isZxioFormat) {
+  return ticksPerBeat / 77.42;
+}
+
+// High PPQ: No conversion
+if (ticksPerBeat >= 480) {
+  return 1.0;  // ← NEW in v1.5.2
+}
+
+// Standard MThd: Calculate ratio
+return ticksPerBeat / 24;
+```
+
+---
+
+## 📚 Documentation
+
+### Updated Documentation
+
+- [SONG_LIST.txt](./SONG_LIST.txt) - Corrected Z2510006 info
+- [EMK_REFERENCE_DATA.json](./EMK_REFERENCE_DATA.json) - Updated test data
+- [RELEASE_v1.5.2.md](./RELEASE_v1.5.2.md) - This file
+
+### Related Documentation
+
+- [TEMPO_TRICKS_SUMMARY.md](./TEMPO_TRICKS_SUMMARY.md) - Tempo handling guide
+- [EMK_TEST_SUITE_README.md](./EMK_TEST_SUITE_README.md) - Test suite guide
+- [EMK_SONGS_INFO.md](./EMK_SONGS_INFO.md) - Song information
+
+---
+
+## ✨ Summary
+
+**Fixed:** Z2510006.emk now converts correctly with proper 4:16 duration  
+**Added:** Support for high PPQ files (PPQ >= 480)  
+**Status:** All 9/9 tests pass ✅  
+**Breaking:** None - fully backward compatible  
+
+---
+
+**Recommended Action:** Update to v1.5.2 if you're converting files with high PPQ values.
+
+**npm:** https://www.npmjs.com/package/@karaplay/file-coder

package/RELEASE_v1.5.3.md

@@ -0,0 +1,274 @@
+# Release v1.5.3 - Corrupted MIDI Repair
+
+**Date:** 2026-01-13  
+**Type:** Bug Fix + New Feature
+
+## 🐛 Bug Fix: Corrupted MIDI Track Support
+
+### Problem
+
+The file `f0000001.emk` (อีกครั้ง - โลโซ/Loso) failed to convert with:
+- **Error:** "Bad MIDI file. Expected 'MTrk', got: 'iF'" ❌
+- **Cause:** MIDI file had garbage bytes (0x6984461d "iF") instead of valid "MTrk" header at track 3
+- **Result:** Conversion failed with undefined error
+
+**Root Cause:**  
+Some EMK files contain corrupted MIDI data with garbage bytes inserted before valid track headers, causing MIDI parsers to fail.
+
+### Solution
+
+Added automatic MIDI repair functionality:
+
+```typescript
+// New function: repairCorruptedMidi()
+export function repairCorruptedMidi(midiBuffer: Buffer): {
+  repaired: Buffer;
+  fixed: boolean;
+  corrections: number;
+}
+```
+
+**How it works:**
+1. Scans MIDI file for invalid track headers
+2. Detects garbage bytes before "MTrk" chunks
+3. Removes corrupted data
+4. Rebuilds valid MIDI file automatically
+
+### Results
+
+**Before Fix (v1.5.2):**
+```
+f0000001.emk (อีกครั้ง - โลโซ):
+  ❌ Error: Bad MIDI file. Expected 'MTrk', got: 'iF'
+  ❌ Status: Cannot convert
+```
+
+**After Fix (v1.5.3):**
+```
+f0000001.emk (อีกครั้ง - โลโซ):
+  ✅ Conversion: SUCCESS!
+  ✅ Duration: 0:58 (58.96s)
+  ✅ Tempo: 344 BPM (4x ratio)
+  ✅ Warning: Fixed 1 corrupted MIDI track(s)
+```
+
+---
+
+## 📊 Impact
+
+### Conversion Success Rate Improvement
+
+**Before v1.5.3:**
+- Total Files: 11
+- Success: 9 (82%)
+- Failed: 2 (18%)
+
+**After v1.5.3:**
+- Total Files: 11
+- Success: **10 (91%)** ✅ +9%
+- Failed: 1 (9%)
+
+### Files Status
+
+**Fixed:**
+- ✅ `f0000001.emk` (อีกครั้ง - โลโซ) - Now converts successfully!
+
+**Still Failed:**
+- ❌ `500006.emk` - Completely corrupted (no zlib blocks), cannot be recovered
+
+---
+
+## 🔧 Technical Details
+
+### Corrupted MIDI Example
+
+```
+Offset  Chunk ID  Status
+------  --------  ------
+14      MTrk      ✅ Valid
+59      MTrk      ✅ Valid
+1431    iF        ❌ CORRUPTED! (should be MTrk)
+1440    MTrk      ✅ Valid (found after skipping 9 bytes)
+...
+```
+
+### Repair Process
+
+```typescript
+// Automatic repair in convertNcnToKar()
+let midiBuffer: Buffer = fs.readFileSync(options.inputMidi);
+const repairResult = repairCorruptedMidi(midiBuffer);
+
+if (repairResult.fixed) {
+  midiBuffer = repairResult.repaired as Buffer;
+  warnings.push(`Fixed ${repairResult.corrections} corrupted MIDI track(s)`);
+}
+```
+
+**Detection:**
+- Scans for "MTrk" signature (0x4D54726B)
+- When invalid chunk found, searches next 100 bytes for valid "MTrk"
+- Skips garbage bytes and continues
+
+**Safety:**
+- Never modifies header (MThd)
+- Preserves all valid tracks
+- Only removes garbage bytes between tracks
+- Returns original if repair fails
+
+---
+
+## 📝 Changed Files
+
+### Core Library
+
+1. **src/ncntokar.ts**
+   - Added `repairCorruptedMidi()` function
+   - Integrated automatic repair in `convertNcnToKar()`
+   - Reports corrupted tracks in warnings
+
+2. **src/index.ts**
+   - Exported `repairCorruptedMidi` for external use
+
+### Documentation
+
+3. **SONG_LIST.txt**
+   - Added เพลงที่ 10: อีกครั้ง (โลโซ)
+   - Updated success rate: 82% → 91%
+   - Updated failed files: 2 → 1
+
+4. **RELEASE_v1.5.3.md**
+   - This file
+
+---
+
+## 🚀 Migration
+
+### From v1.5.2 to v1.5.3
+
+**No Breaking Changes!**
+
+Simply update:
+
+```bash
+npm install @karaplay/file-coder@1.5.3
+```
+
+**All existing code continues to work.**
+
+### What Changed
+
+If you were trying to convert `f0000001.emk`:
+
+**Before (v1.5.2):**
+```typescript
+convertEmkToKar({ 
+  inputEmk: 'f0000001.emk', 
+  outputKar: 'output.kar' 
+});
+// ❌ Error: Bad MIDI file
+```
+
+**After (v1.5.3):**
+```typescript
+convertEmkToKar({ 
+  inputEmk: 'f0000001.emk', 
+  outputKar: 'output.kar' 
+});
+// ✅ Success! (with warning about fixed MIDI track)
+```
+
+---
+
+## 🎯 Use Cases
+
+### When This Fix Helps
+
+✅ **Corrupted Track Headers:**
+- Garbage bytes before MTrk chunks
+- Invalid chunk IDs in MIDI file
+- Malformed track structures
+
+✅ **Automatic Recovery:**
+- No manual intervention needed
+- Transparent to the user
+- Warning message in result
+
+❌ **When It Doesn't Help:**
+- Completely corrupted files (like 500006.emk)
+- Files with no zlib blocks
+- Files that can't be decoded at all
+
+---
+
+## 🧪 Testing
+
+### Test: f0000001.emk
+
+```typescript
+import { convertEmkToKar, validateKarTempo } from '@karaplay/file-coder';
+
+const result = convertEmkToKar({
+  inputEmk: 'f0000001.emk',
+  outputKar: 'output.kar'
+});
+
+console.log('Success:', result.success);        // true ✅
+console.log('Title:', result.metadata.title);    // "14 อีกครั้ง "
+console.log('Artist:', result.metadata.artist);  // "โลโซ (Loso)"
+console.log('Warnings:', result.warnings);        
+// ["Fixed 1 corrupted MIDI track(s)", ...]
+
+const validation = validateKarTempo(karBuffer);
+console.log('Duration:', validation.durationMinutes); // "0:58"
+console.log('Tempo:', validation.tempo);               // 344 BPM
+```
+
+### Manual Repair Test
+
+```typescript
+import { repairCorruptedMidi } from '@karaplay/file-coder';
+
+const midiBuffer = fs.readFileSync('corrupted.mid');
+const result = repairCorruptedMidi(midiBuffer);
+
+if (result.fixed) {
+  console.log('Repaired!');
+  console.log('Corrections:', result.corrections);
+  fs.writeFileSync('repaired.mid', result.repaired);
+} else {
+  console.log('No corruption detected or repair failed');
+}
+```
+
+---
+
+## 📚 Documentation
+
+### Updated Documentation
+
+- [SONG_LIST.txt](./SONG_LIST.txt) - Added f0000001.emk info
+- [RELEASE_v1.5.3.md](./RELEASE_v1.5.3.md) - This file
+
+### Related Documentation
+
+- [EMK_TEST_SUITE_README.md](./EMK_TEST_SUITE_README.md) - Test suite guide
+- [TEMPO_TRICKS_SUMMARY.md](./TEMPO_TRICKS_SUMMARY.md) - Tempo handling
+- [RELEASE_v1.5.2.md](./RELEASE_v1.5.2.md) - High PPQ fix
+
+---
+
+## ✨ Summary
+
+**Fixed:** f0000001.emk now converts successfully! ✅  
+**Added:** Automatic corrupted MIDI repair  
+**Improved:** Success rate from 82% to 91%  
+**Breaking:** None - fully backward compatible  
+
+**Remaining Issue:** 500006.emk still cannot be converted (file completely corrupted)
+
+---
+
+**Recommended Action:** Update to v1.5.3 to get automatic MIDI repair for corrupted EMK files.
+
+**npm:** https://www.npmjs.com/package/@karaplay/file-coder