@karaplay/file-coder 1.5.0 → 1.5.2

package/README.md

@@ -14,6 +14,8 @@ A comprehensive library for encoding/decoding karaoke files (.emk, .kar, MIDI) w
 - ⚛️ Next.js compatible (both client and server side)
 - 🌐 **NEW**: Browser-compatible API for client-side processing
 - 🇹🇭 Thai language support (TIS-620 encoding)
+- 🎯 **v1.5.0**: Accurate tempo handling for ZXIO format (1.24x ratio)
+- ⏱️ **NEW**: Tempo validation and duration accuracy
 - ✅ **FIXED v1.3.2**: Client-side EMK decoder now works correctly!
 - ✅ 131 tests - 100% pass rate (including integration tests with real files)
 
@@ -83,6 +85,94 @@ const results = convertEmkToKarBatch(
 
 See [EMK_TO_KAR_WORKFLOW.md](./EMK_TO_KAR_WORKFLOW.md) for complete documentation.
 
+---
+
+## ⏱️ Tempo Handling & Duration Accuracy
+
+### Understanding EMK Tempo Conversion
+
+EMK files use non-standard MIDI timing that requires tempo adjustment during conversion. This library **automatically** handles tempo correction based on the EMK format:
+
+#### ZXIO Format (v1.5.0+)
+```
+Original EMK:  64 BPM  →  Converted KAR: 79 BPM
+Tempo Ratio:   1.24x   (ticksPerBeat / 77.42)
+Duration:      4:43    ✅ Accurate!
+```
+
+#### MThd Format
+```
+Tempo Ratio:   4x, 8x, or 20x  (auto-detected)
+```
+
+### Validating Conversion Accuracy
+
+Use `@tonejs/midi` to verify tempo and duration:
+
+```typescript
+import { Midi } from '@tonejs/midi';
+import { convertEmkToKar } from '@karaplay/file-coder';
+import * as fs from 'fs';
+
+// Convert EMK to KAR
+const result = convertEmkToKar({
+  inputEmk: 'song.emk',
+  outputKar: 'song.kar'
+});
+
+// Validate with Tone.js
+const karBuffer = fs.readFileSync('song.kar');
+const midi = new Midi(karBuffer);
+
+console.log('✅ Validation Results:');
+console.log(`   Tempo: ${midi.header.tempos[0].bpm.toFixed(2)} BPM`);
+console.log(`   Duration: ${(midi.duration / 60).toFixed(2)} minutes`);
+console.log(`   PPQ: ${midi.header.ppq}`);
+console.log(`   Tracks: ${midi.tracks.length}`);
+```
+
+### 🔧 Troubleshooting Tempo Issues
+
+**Problem:** Converted KAR plays too fast or too slow  
+**Solution:** The library automatically applies correct tempo ratios:
+
+| Format | Original BPM | Ratio | Converted BPM | Status |
+|--------|--------------|-------|---------------|--------|
+| ZXIO   | 64 BPM      | 1.24x | 79 BPM        | ✅ v1.5.0+ |
+| MThd   | 160 BPM     | 4x    | 640 BPM       | ✅ Auto |
+| MThd   | 142 BPM     | 8x    | 1136 BPM      | ✅ Auto |
+
+**Important Notes:**
+1. ✅ **Tempo is automatically corrected** - no manual adjustment needed
+2. ✅ **Use @tonejs/midi for accurate duration** - it handles tempo events correctly
+3. ⚠️ **Don't use karaoke-player's getTickResolution()** - it can give incorrect timing
+4. ✅ **Duration decrease is normal** - faster tempo = shorter playback time
+
+### Best Practices for MIDI Playback
+
+When implementing a player for converted KAR files:
+
+```typescript
+import { Midi } from '@tonejs/midi';
+
+// ✅ CORRECT: Use Tone.js for timing
+const midi = new Midi(karBuffer);
+const duration = midi.duration; // Accurate!
+
+midi.tracks.forEach(track => {
+  track.notes.forEach(note => {
+    const time = note.time;     // ✅ Correct time in seconds
+    const noteNum = note.midi;  // MIDI note number
+    const velocity = note.velocity;
+  });
+});
+
+// ❌ INCORRECT: Don't manually calculate from ticks
+// const time = ticks * tickResolution; // May be wrong!
+```
+
+---
+
 ### NCN to KAR Conversion
 
 ```typescript

package/RELEASE_v1.5.1.md

@@ -0,0 +1,190 @@
+# Release v1.5.1 - Tempo Validation & Documentation
+
+**Date:** 2026-01-13
+
+## 🎯 New Features: Tempo Validation Utilities
+
+### Added Validation Functions
+
+This release adds comprehensive tempo and duration validation utilities to ensure conversion accuracy.
+
+#### 1. **`validateKarTempo()`** - Validate KAR File Accuracy
+
+```typescript
+import { validateKarTempo } from '@karaplay/file-coder';
+import * as fs from 'fs';
+
+const karBuffer = fs.readFileSync('song.kar');
+const validation = validateKarTempo(karBuffer);
+
+console.log(`Valid: ${validation.valid}`);
+console.log(`Tempo: ${validation.tempo} BPM`);
+console.log(`Duration: ${validation.durationMinutes}`);
+console.log(`Warnings: ${validation.warnings.length}`);
+```
+
+**Returns:**
+- `valid`: boolean - Overall validation status
+- `tempo`: number - Tempo in BPM
+- `duration`: number - Duration in seconds
+- `durationMinutes`: string - Formatted as "M:SS"
+- `ppq`: number - Ticks per beat
+- `trackCount`: number - Number of tracks
+- `noteCount`: number - Total notes
+- `format`: number - MIDI format (0, 1, or 2)
+- `warnings`: string[] - Non-critical issues
+- `errors`: string[] - Critical issues
+
+#### 2. **`compareEmkKarTempo()`** - Compare EMK vs KAR
+
+```typescript
+import { compareEmkKarTempo } from '@karaplay/file-coder';
+
+const emkBuffer = fs.readFileSync('song.emk');
+const karBuffer = fs.readFileSync('song.kar');
+
+const comparison = compareEmkKarTempo(emkBuffer, karBuffer);
+
+console.log(`Format: ${comparison.format}`);              // "ZXIO" or "MThd"
+console.log(`Tempo Ratio: ${comparison.tempoRatio}x`);    // 1.24x for ZXIO
+console.log(`Expected: ${comparison.expectedRatio}x`);     // 1.24x
+console.log(`Match: ${comparison.ratioMatch}`);            // true
+```
+
+**Returns:**
+- `emkTempo`: number - Original EMK tempo
+- `karTempo`: number - Converted KAR tempo
+- `tempoRatio`: number - Actual ratio applied
+- `emkDuration`: number - EMK duration
+- `karDuration`: number - KAR duration
+- `durationRatio`: number - Duration change
+- `format`: string - "ZXIO" or "MThd"
+- `expectedRatio`: number - Expected ratio for format
+- `ratioMatch`: boolean - Whether ratio is correct
+
+## 📚 Enhanced Documentation
+
+### New README Section: "Tempo Handling & Duration Accuracy"
+
+Added comprehensive guide covering:
+
+1. **Understanding EMK Tempo Conversion**
+   - ZXIO format: 1.24x ratio
+   - MThd format: 4x, 8x, or 20x (auto-detected)
+
+2. **Validating Conversion Accuracy**
+   - Using @tonejs/midi for verification
+   - Duration and tempo checks
+
+3. **Troubleshooting Tempo Issues**
+   - Common problems and solutions
+   - Format-specific ratios
+
+4. **Best Practices for MIDI Playback**
+   - ✅ Use Tone.js for timing (accurate!)
+   - ❌ Don't use karaoke-player's getTickResolution() (can be wrong!)
+
+### Example Usage
+
+```typescript
+import { Midi } from '@tonejs/midi';
+import { convertEmkToKar, validateKarTempo } from '@karaplay/file-coder';
+
+// Convert
+const result = convertEmkToKar({
+  inputEmk: 'song.emk',
+  outputKar: 'song.kar'
+});
+
+// Validate
+const karBuffer = fs.readFileSync('song.kar');
+const midi = new Midi(karBuffer);
+
+console.log(`✅ Tempo: ${midi.header.tempos[0].bpm.toFixed(2)} BPM`);
+console.log(`✅ Duration: ${(midi.duration / 60).toFixed(2)} minutes`);
+```
+
+## 🔧 Technical Details
+
+### Why Use @tonejs/midi?
+
+**Problem:** `karaoke-player`'s `getTickResolution()` can calculate incorrect timing:
+```
+karaoke-player: 5,208 ms/tick ❌ (660x too high!)
+Tone.js:        7.87 ms/tick   ✅ (correct!)
+```
+
+**Solution:** Always use `@tonejs/midi` for:
+- Accurate tempo event handling
+- Correct duration calculations
+- Reliable timing information
+
+### Tempo Ratios
+
+| Format | Original BPM | Ratio | Converted BPM | Duration Example |
+|--------|--------------|-------|---------------|------------------|
+| ZXIO   | 64 BPM       | 1.24x | 79 BPM        | 4:43 ✅          |
+| MThd   | 160 BPM      | 4x    | 640 BPM       | Auto ✅          |
+| MThd   | 142 BPM      | 8x    | 1136 BPM      | Auto ✅          |
+
+## ✅ Testing
+
+**Test Results:**
+```
+Test 1: validateKarTempo()
+   ✅ Valid: true
+   ✅ Tempo: 87.00 BPM
+   ✅ Duration: 4:16
+
+Test 2: compareEmkKarTempo() - ZXIO
+   ✅ Format: ZXIO
+   ✅ Tempo: 64 → 79 BPM (1.24x)
+   ✅ Expected: 1.24x, Match: YES ✅
+
+Test 3: Duration Accuracy
+   ✅ Expected: 283s (4:43)
+   ✅ Actual: 283.5s (4:43)
+   ✅ Difference: 0.5s - PASS
+```
+
+## 📊 What Changed
+
+### New Files
+- `src/kar-validator.ts` - Validation utilities
+- `tests/kar-validator.test.ts` - Test suite
+- `RELEASE_v1.5.1.md` - This file
+
+### Updated Files
+- `README.md` - Added "Tempo Handling & Duration Accuracy" section
+- `src/index.ts` - Exported validator functions
+- `package.json` - Version bump to 1.5.1
+
+## 🚀 Migration from v1.5.0
+
+No breaking changes! Simply update:
+
+```bash
+npm install @karaplay/file-coder@1.5.1
+```
+
+New validator functions are optional - existing code continues to work.
+
+## 💡 Key Takeaways
+
+1. ✅ **Automatic tempo correction** - no manual adjustment needed
+2. ✅ **Use @tonejs/midi** for accurate timing
+3. ✅ **New validation utilities** for quality assurance
+4. ✅ **Comprehensive documentation** for tempo handling
+5. ⚠️ **Duration decrease is normal** - faster tempo = shorter playback
+
+## 📖 Documentation
+
+- [README.md](./README.md) - Main documentation
+- [EMK_TO_KAR_WORKFLOW.md](./EMK_TO_KAR_WORKFLOW.md) - Conversion workflow
+- [RELEASE_v1.5.0.md](./RELEASE_v1.5.0.md) - Previous release (ZXIO fix)
+
+---
+
+**Status:** ✅ Ready for Production
+
+**Recommended Action:** Update to get validation utilities and improved documentation

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