@karaplay/file-coder 1.5.0 → 1.5.1

package/DEMO_ENHANCED.md

@@ -1,168 +1,241 @@
-# ✨ Demo Enhanced with EMK Analysis & Comparison
-
-## 🎯 New Features Added
-
-### 1. **EMK File Analysis** (Before Conversion)
-When you select an EMK file, it now automatically analyzes:
-- ✅ Title and Artist (Thai encoding)
-- ✅ Format type (ZXIO or MThd)
-- ✅ **Original Tempo** (BPM)
-- ✅ **Original Duration** (seconds and minutes)
-- ✅ PPQ (Ticks per beat)
-- ✅ Number of tracks
-- ✅ Number of notes
-- ✅ Lyric and cursor data size
-
-### 2. **Comparison Table** (EMK vs KAR)
-After conversion, see a detailed comparison:
-- 📊 Format changes
-- 📊 Tempo ratio (e.g., 2.78x for ZXIO, 4x for MThd)
-- 📊 Duration changes
-- 📊 Tempo verification (✅ or ⚠️)
-- 📊 Track and note count
-- 📊 Visual indicators for increases/decreases
-
-## 🚀 How to Use
-
-### Step 1: Open Demo
-```
-http://localhost:3000/demo-simple.html
-```
+# Demo Page Enhanced - MIDI Player
 
-### Step 2: Select EMK File
-- Click on any EMK file
-- **Wait for automatic analysis** (1-2 seconds)
-- See original EMK info displayed
+**Date:** 2026-01-13  
+**Version:** v1.5.0 with MIDI Player
 
-### Step 3: Convert to KAR
-- Click "Convert to KAR"
-- Wait for conversion
-- See converted KAR info
+## 🎵 New Feature: MIDI Player
 
-### Step 4: View Comparison Table
-- Automatically displays after conversion
-- Compare original vs converted values
-- Verify tempo ratio is correct
+### Added to `demo-simple.html`
 
-### Step 5: Download & Test
-- Click "Download KAR" to save file
-- Test with external karaoke player
+#### 1. **UI Components**
+- ▶️ **Play Button** - Start MIDI playback
+- ⏸️ **Pause Button** - Pause playback (currently restarts on resume)
+- ⏹️ **Stop Button** - Stop and reset playback
+- **Progress Bar** - Visual playback progress
+- **Time Display** - Current time / Total duration
+- **Status Display** - Shows player state and messages
 
-## 📊 Sample Comparison Table
+#### 2. **Libraries Used**
+```html
+<!-- MIDI Parser -->
+<script src="https://cdn.jsdelivr.net/npm/midi-parser-js@4.0.4/src/main.min.js"></script>
+
+<!-- Soundfont Player for audio synthesis -->
+<script src="https://cdn.jsdelivr.net/npm/soundfont-player@0.12.0/dist/soundfont-player.min.js"></script>
+```
 
+#### 3. **Features**
+- ✅ **Auto-initialize** - Loads instrument on first play
+- ✅ **Parse MIDI** - Converts base64 KAR data to playable MIDI
+- ✅ **Tempo-aware** - Respects MIDI tempo events
+- ✅ **Real-time progress** - Updates every 100ms
+- ✅ **Multi-track support** - Plays all MIDI tracks simultaneously
+- ✅ **Note scheduling** - Uses Web Audio API for precise timing
+- ✅ **Piano soundfont** - Uses Acoustic Grand Piano (MusyngKite)
+
+#### 4. **How It Works**
+
+**Step 1: Initialization**
+```javascript
+await initMidiPlayer();
+// Creates AudioContext
+// Loads soundfont from: https://gleitz.github.io/midi-js-soundfonts/
 ```
-┌──────────────────────┬─────────────────┬─────────────────┬─────────────────┐
-│ Property             │ Original EMK    │ Converted KAR   │ Change          │
-├──────────────────────┼─────────────────┼─────────────────┼─────────────────┤
-│ Format               │ ZXIO            │ ZXIO            │ Same            │
-│ Tempo (BPM)          │ 64.00           │ 178.09          │ ×2.78 (increase)│
-│ Duration (seconds)   │ 351.56          │ 126.34          │ ×0.36 (decrease)│
-│ Duration (minutes)   │ 5.86            │ 2.11            │ 64.1% shorter   │
-│ PPQ                  │ 96              │ Same            │ Unchanged       │
-│ Tracks               │ 25              │ Same + Karaoke  │ +1 (lyrics)     │
-│ Notes                │ 6313            │ 6313            │ Same            │
-│ Tempo Ratio          │ -               │ 2.78x           │ ✅ Correct      │
-└──────────────────────┴─────────────────┴─────────────────┴─────────────────┘
+
+**Step 2: Parse MIDI**
+```javascript
+parseMidiData(base64Data);
+// Decodes base64 → Uint8Array
+// Parses with MidiParser.js
+// Extracts tempo, PPQ, notes
 ```
 
-## 🎯 What to Verify
+**Step 3: Schedule Notes**
+```javascript
+// Converts ticks to seconds
+ticksToSeconds(ticks, tempo, ppq);
+
+// Schedules note events
+instrument.play(midiNote, scheduleTime, options);
+```
 
-### ZXIO Format (001.emk, failed01.emk)
-**Original EMK:**
-- Tempo: 64 BPM
-- Duration: ~5.86 minutes (351 seconds)
+**Step 4: Playback Control**
+```javascript
+playMidi()   // Start playback
+pauseMidi()  // Stop all notes
+stopMidi()   // Reset to beginning
+```
 
-**Converted KAR:**
-- Tempo: **178.09 BPM** (2.78x)
-- Duration: **~2.11 minutes** (126 seconds)
-- Tempo Ratio: ✅ **Correct (2.78x)**
+## 🎯 Usage
 
-### MThd Format (Z2510001.emk)
-**Original EMK:**
-- Tempo: 67 BPM
-- Duration: Variable
+### 1. Convert EMK to KAR
+1. Select an EMK file from the list
+2. Click "🔄 Convert to KAR"
+3. Wait for conversion to complete
 
-**Converted KAR:**
-- Tempo: **268 BPM** (4x)
-- Duration: Adjusted proportionally
-- Tempo Ratio: ✅ **Correct (4x)**
+### 2. Play Converted KAR
+1. After successful conversion, MIDI Player appears
+2. Click "▶️ Play" to start playback
+3. Use "⏸️ Pause" or "⏹️ Stop" to control playback
 
-## 🔍 New API Endpoint
+### 3. Monitor Playback
+- **Progress Bar** - Shows current position
+- **Time Display** - Shows current time / total duration
+- **Status** - Shows player state (Playing, Paused, Stopped)
 
-### POST `/api/analyze-emk`
-Analyze EMK file before conversion
+## 🔧 Technical Details
 
-**Request:**
-```json
-{
-  "filename": "001.emk"
-}
+### MIDI Processing
+
+**Tempo Calculation:**
+```javascript
+microsecondsPerBeat = (data[0] << 16) | (data[1] << 8) | data[2];
 ```
 
-**Response:**
-```json
-{
-  "success": true,
-  "emkInfo": {
-    "format": "ZXIO",
-    "title": "คนกระจอก",
-    "artist": "บุ๊ค ศุภกาญจน์",
-    "tempo": "64.00",
-    "duration": "351.56",
-    "durationMinutes": "5.86",
-    "ppq": 96,
-    "tracks": 25,
-    "notes": 6313,
-    "hasLyrics": 3456,
-    "hasCursor": 3742
-  }
-}
+**Time Conversion:**
+```javascript
+seconds = (ticks × microsecondsPerBeat) / (ppq × 1000000)
 ```
 
-## 📈 Visual Indicators
+**Note Events:**
+- **Type 9 (Note On):** data[0] = note, data[1] = velocity
+- **Type 8 (Note Off):** data[0] = note
+- **Type 255, Meta 81:** Set Tempo event
+
+### Audio Synthesis
+
+**Soundfont:**
+- Source: `https://gleitz.github.io/midi-js-soundfonts/`
+- Format: MusyngKite (high quality)
+- Instrument: Acoustic Grand Piano
+
+**Web Audio API:**
+- Uses `AudioContext` for precise timing
+- Schedules notes in advance
+- Supports dynamic gain (velocity)
 
-### Tempo Ratio Status
-- ✅ **Correct (2.78x)** - ZXIO format with correct tempo
-- ✅ **Correct (~4x)** - MThd format with correct tempo
-- ⚠️ **Unexpected** - Tempo ratio doesn't match expected value
+## 📊 Testing
 
-### Change Indicators
-- 🟡 **Yellow badge** - Increase (tempo, duration)
-- 🟢 **Green badge** - Decrease (expected for ZXIO duration)
-- ⚪ **Gray badge** - Same/Unchanged
+### Test File: `001_original_emk.emk`
+
+**Expected Results:**
+```
+Format:   ZXIO
+Tempo:    79 BPM
+Duration: 4:43 (283 seconds)
+Tracks:   25
+Notes:    6313
+```
 
-## 🎉 Benefits
+**Playback:**
+- ✅ Should play piano notes
+- ✅ Should follow correct tempo (79 BPM)
+- ✅ Should complete in ~4:43
+- ✅ Progress bar should update smoothly
+- ✅ Time display should increment correctly
 
-### For Testing
-1. **Before/After Comparison** - See exact changes from conversion
-2. **Tempo Verification** - Confirm correct ratio is applied
-3. **Duration Accuracy** - Verify music length is correct
-4. **Format Detection** - Ensure ZXIO vs MThd is identified correctly
+## 🐛 Known Limitations
 
-### For Documentation
-1. **Clear Evidence** - Shows conversion works correctly
-2. **Ratio Validation** - Proves 2.78x (ZXIO) and 4x (MThd) formulas
-3. **Quality Assurance** - Demonstrates accurate metadata preservation
+1. **Pause/Resume**
+   - Currently restarts playback from beginning
+   - Full resume from pause position requires state tracking
 
-### For Debugging
-1. **Original Values** - Reference point for troubleshooting
-2. **Detailed Metrics** - Track count, note count, PPQ
-3. **Format Info** - Identify which conversion path was used
+2. **Instrument**
+   - Only uses piano soundfont
+   - Does not respect MIDI program changes (instrument selection)
 
-## 🚀 Ready to Test!
+3. **Performance**
+   - Large MIDI files (>10,000 notes) may cause lag
+   - All notes are scheduled at once
 
-**Server is running at:**
+4. **Browser Support**
+   - Requires Web Audio API support
+   - Tested on Chrome, Firefox, Safari
+
+## 🚀 Future Improvements
+
+1. **Lyrics Display**
+   - Show synchronized lyrics during playback
+   - Highlight current lyric line
+
+2. **Multiple Instruments**
+   - Load different soundfonts per track
+   - Respect MIDI program changes
+
+3. **Better Pause**
+   - Resume from exact pause position
+   - Maintain note states
+
+4. **Visualization**
+   - Piano roll display
+   - Waveform visualization
+   - Spectrum analyzer
+
+5. **Playback Controls**
+   - Speed control (0.5x, 1x, 2x)
+   - Volume control
+   - Seek bar (click to jump)
+
+## 📝 Code Structure
+
+```
+demo-simple.html
+├── UI Components
+│   ├── Play/Pause/Stop buttons
+│   ├── Progress bar
+│   ├── Time display
+│   └── Status panel
+│
+├── MIDI Player Object
+│   ├── ac: AudioContext
+│   ├── instrument: Soundfont instance
+│   ├── midiData: Parsed MIDI
+│   └── State: isPlaying, isPaused, etc.
+│
+└── Functions
+    ├── initMidiPlayer() - Initialize audio
+    ├── parseMidiData() - Parse MIDI from base64
+    ├── playMidi() - Start playback
+    ├── pauseMidi() - Pause playback
+    ├── stopMidi() - Stop playback
+    └── ticksToSeconds() - Convert MIDI ticks to time
 ```
-http://localhost:3000/demo-simple.html
+
+## ✅ Verification
+
+### Server Running
+```bash
+npm run demo
+# Server: http://localhost:3000
+# Demo: http://localhost:3000/demo-simple.html
 ```
 
-**Try it now:**
-1. Select **001.emk** (ZXIO format)
-2. See original info: 64 BPM, 5.86 minutes
-3. Convert to KAR
-4. See comparison: 178.09 BPM, 2.11 minutes
-5. Verify: ✅ Tempo Ratio 2.78x Correct!
+### Test Conversion
+1. Open: `http://localhost:3000/demo-simple.html`
+2. Select: `001_original_emk.emk`
+3. Click: "🔄 Convert to KAR"
+4. Verify: Tempo = 79 BPM, Duration = 4:43
+
+### Test Playback
+1. Click: "▶️ Play"
+2. Verify: Piano notes play
+3. Verify: Progress bar moves
+4. Verify: Time display updates
+5. Click: "⏹️ Stop"
+6. Verify: Playback stops, progress resets
 
 ---
 
-**Perfect for demonstrating v1.4.9 fixes! 🎤✨**
+## 🎊 Status: ✅ Complete
+
+**Demo Page Features:**
+- ✅ EMK file list
+- ✅ File selection
+- ✅ EMK analysis (before conversion)
+- ✅ EMK to KAR conversion
+- ✅ Metadata display
+- ✅ Comparison table (EMK vs KAR)
+- ✅ KAR file download
+- ✅ **MIDI Player** (NEW!)
+
+**Ready for testing and demonstration!** 🎉

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