@karaplay/file-coder 1.4.9 → 1.5.0

package/DEMO_ENHANCED.md

@@ -0,0 +1,168 @@
+# ✨ 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
+```
+
+### Step 2: Select EMK File
+- Click on any EMK file
+- **Wait for automatic analysis** (1-2 seconds)
+- See original EMK info displayed
+
+### Step 3: Convert to KAR
+- Click "Convert to KAR"
+- Wait for conversion
+- See converted KAR info
+
+### Step 4: View Comparison Table
+- Automatically displays after conversion
+- Compare original vs converted values
+- Verify tempo ratio is correct
+
+### Step 5: Download & Test
+- Click "Download KAR" to save file
+- Test with external karaoke player
+
+## 📊 Sample Comparison Table
+
+```
+┌──────────────────────┬─────────────────┬─────────────────┬─────────────────┐
+│ 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      │
+└──────────────────────┴─────────────────┴─────────────────┴─────────────────┘
+```
+
+## 🎯 What to Verify
+
+### ZXIO Format (001.emk, failed01.emk)
+**Original EMK:**
+- Tempo: 64 BPM
+- Duration: ~5.86 minutes (351 seconds)
+
+**Converted KAR:**
+- Tempo: **178.09 BPM** (2.78x)
+- Duration: **~2.11 minutes** (126 seconds)
+- Tempo Ratio: ✅ **Correct (2.78x)**
+
+### MThd Format (Z2510001.emk)
+**Original EMK:**
+- Tempo: 67 BPM
+- Duration: Variable
+
+**Converted KAR:**
+- Tempo: **268 BPM** (4x)
+- Duration: Adjusted proportionally
+- Tempo Ratio: ✅ **Correct (4x)**
+
+## 🔍 New API Endpoint
+
+### POST `/api/analyze-emk`
+Analyze EMK file before conversion
+
+**Request:**
+```json
+{
+  "filename": "001.emk"
+}
+```
+
+**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
+  }
+}
+```
+
+## 📈 Visual Indicators
+
+### 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
+
+### Change Indicators
+- 🟡 **Yellow badge** - Increase (tempo, duration)
+- 🟢 **Green badge** - Decrease (expected for ZXIO duration)
+- ⚪ **Gray badge** - Same/Unchanged
+
+## 🎉 Benefits
+
+### 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
+
+### 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
+
+### 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
+
+## 🚀 Ready to Test!
+
+**Server is running at:**
+```
+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!
+
+---
+
+**Perfect for demonstrating v1.4.9 fixes! 🎤✨**

package/DEMO_FIXED.md

@@ -0,0 +1,57 @@
+# ✅ Demo Fixed!
+
+## 🐛 Issue Resolved
+
+**Problem:** `demo.html` tried to import from local `node_modules` which browsers cannot access directly:
+```javascript
+// ❌ This doesn't work in browser
+import { KaraokePlayer } from './node_modules/karaoke-player/dist/index.js';
+```
+
+**Solution:** Use `demo-client.html` instead, which uses CDN:
+```javascript
+// ✅ This works!
+import { Player } from 'https://cdn.jsdelivr.net/npm/karaoke-player@latest/dist/index.min.js';
+```
+
+## 🚀 How to Use (Updated)
+
+### Step 1: Start Server
+```bash
+npm run demo
+```
+
+### Step 2: Open Browser
+```
+http://localhost:3000/demo-client.html
+```
+
+### Step 3: Test EMK to KAR Conversion
+1. Select an EMK file from the list
+2. Click "Convert to KAR"
+3. Click "Play" to hear the result
+4. Verify tempo and lyrics sync
+
+## 📝 Files
+
+- ✅ **demo-client.html** - Working demo page (uses CDN)
+- ❌ ~~demo.html~~ - Removed (had import errors)
+- ✅ **demo-server.js** - API server (updated to use demo-client.html)
+
+## 🎯 Testing Checklist
+
+### ZXIO Format
+- [ ] 001.emk → Tempo: 178.09 BPM ✅
+- [ ] failed01.emk → Tempo: 178.09 BPM ✅
+
+### MThd Format  
+- [ ] Z2510001.emk → Tempo: 268 BPM ✅
+- [ ] Z2510002.emk → Tempo: 288 BPM ✅
+- [ ] Z2510003.emk → Tempo: 1136 BPM ✅
+
+## 🎤 Ready to Test!
+
+Server is running at:
+**http://localhost:3000/demo-client.html**
+
+Enjoy testing! 🎵

package/DEMO_GUIDE.md

@@ -0,0 +1,204 @@
+# 🎤 EMK to KAR Conversion Demo - Testing Guide
+
+## ✅ Setup Complete!
+
+Demo server is now running at **http://localhost:3000**
+
+## 🚀 How to Use
+
+### Step 1: Open Demo Page
+
+Open your browser and navigate to:
+```
+http://localhost:3000/demo-client.html
+```
+
+### Step 2: Select EMK File
+
+Click on any EMK file from the left panel:
+- **ZXIO files** (green badge): `001.emk`, `failed01.emk`
+- **MThd files** (blue badge): `Z2510001.emk`, `Z2510002.emk`, etc.
+
+### Step 3: Convert to KAR
+
+Click the **"🔄 Convert to KAR"** button and wait for conversion to complete.
+
+### Step 4: Play & Verify
+
+1. Click **"▶ Play"** to start playback
+2. Watch the lyrics sync with the music
+3. Check the metadata panel for tempo and duration
+4. Use pause/stop controls as needed
+
+## 🎯 What to Verify
+
+### ZXIO Format (001.emk, failed01.emk)
+
+✅ **Expected Results:**
+- **Tempo:** 178.09 BPM (2.78x ratio)
+- **Duration:** ~2.11 minutes (126 seconds)
+- **Format Badge:** Green "ZXIO"
+- **Lyrics:** Should sync perfectly with music
+- **Speed:** Should match original KAR playback
+
+❌ **Known Issues (Fixed in v1.4.9):**
+- ~~Previously played at 256 BPM (too fast)~~
+- ~~Previously had 1.44x speed issue~~
+
+### MThd Format (Z251xxxx.emk)
+
+✅ **Expected Results:**
+- **Z2510001.emk:** 268 BPM (4x ratio)
+- **Z2510002.emk:** 288 BPM (4x ratio)
+- **Z2510003.emk:** 1136 BPM (8x ratio)
+- **Format Badge:** Blue "MThd"
+- **Lyrics:** Should sync with music
+
+## 📊 Verification Checklist
+
+### Before Publishing to NPM
+
+- [ ] Test all ZXIO files (001.emk, failed01.emk)
+  - [ ] Tempo is 178.09 BPM
+  - [ ] Duration is ~2.11 minutes
+  - [ ] Lyrics sync perfectly with music
+  - [ ] No speed issues
+
+- [ ] Test MThd files (Z251xxxx.emk)
+  - [ ] Tempo ratios are correct (4x, 8x, 20x)
+  - [ ] Duration matches expected values
+  - [ ] Lyrics sync with music
+
+- [ ] Test playback controls
+  - [ ] Play button starts playback
+  - [ ] Pause button pauses/resumes
+  - [ ] Stop button stops and resets
+  - [ ] Progress bar updates correctly
+
+- [ ] Test conversion info
+  - [ ] Title displays correctly (Thai encoding)
+  - [ ] Artist displays correctly (Thai encoding)
+  - [ ] Format detection is accurate (ZXIO vs MThd)
+  - [ ] Tempo and duration match analysis
+
+## 🔍 Comparison with v1.4.8
+
+### What Was Fixed in v1.4.9
+
+**Problem (v1.4.8):**
+```
+001.emk (ZXIO):
+  Tempo: 256 BPM  ❌ (too fast)
+  Duration: 87.89s ❌ (too short)
+  Ratio: 4x ❌ (incorrect)
+```
+
+**Solution (v1.4.9):**
+```
+001.emk (ZXIO):
+  Tempo: 178.09 BPM ✅ (correct)
+  Duration: 126.34s ✅ (correct)
+  Ratio: 2.78x ✅ (correct)
+```
+
+### Technical Changes
+
+**ZXIO Format:**
+- Old: `ratio = PPQ / 24 = 4x`
+- New: `ratio = PPQ / 34.5 = 2.78x`
+
+**MThd Format:**
+- Unchanged: `ratio = PPQ / 24 = 4x`
+
+## 🎵 Sample Files Included
+
+### ZXIO Format
+1. **001.emk** - คนกระจอก by บุ๊ค ศุภกาญจน์
+   - Best for testing ZXIO tempo fix
+   - Should play at 178.09 BPM
+   - Duration: 2.11 minutes
+
+2. **failed01.emk** - Same as 001.emk
+   - Was failing in earlier versions
+   - Now converts successfully
+   - Perfect for regression testing
+
+### MThd Format
+1. **Z2510001.emk** - เสน่ห์เมืองพระรถ
+   - Tempo: 268 BPM (4x ratio)
+   - Duration: ~0.91 minutes
+
+2. **Z2510002.emk** - สามปอยหลวง
+   - Tempo: 288 BPM (4x ratio)
+   - Duration: ~0.89 minutes
+
+3. **Z2510003.emk** - มีคู่เสียเถิด
+   - Tempo: 1136 BPM (8x ratio)
+   - Duration: ~0.31 minutes
+
+## 🐛 Troubleshooting
+
+### Lyrics Not Syncing
+- Check browser console for errors
+- Verify tempo in metadata panel matches expected value
+- Try converting the file again
+- Test with a different EMK file
+
+### Playback Too Fast/Slow
+- Check the **Format** badge (ZXIO vs MThd)
+- Compare tempo with expected values
+- ZXIO should be ~178 BPM
+- MThd should be 4x original EMK tempo
+
+### Conversion Fails
+- Check server console for error messages
+- Verify EMK file exists in `songs/emk/`
+- Try with a known-working file (001.emk)
+- Restart demo server if needed
+
+### Server Won't Start
+```bash
+# Stop existing server
+lsof -ti:3000 | xargs kill -9
+
+# Restart
+npm run demo
+```
+
+## 📝 Next Steps
+
+Once all tests pass:
+
+1. ✅ All ZXIO files play correctly
+2. ✅ All MThd files play correctly
+3. ✅ Lyrics sync perfectly
+4. ✅ No timing drift
+5. ✅ Tempo ratios are accurate
+
+**Then you're ready to publish!**
+
+```bash
+# The package is already published as v1.4.9
+# This demo confirms it works correctly
+```
+
+## 🎉 Success Indicators
+
+You'll know it's working correctly when:
+
+- ✅ **001.emk** plays at 178.09 BPM (not 256 BPM)
+- ✅ **failed01.emk** converts successfully
+- ✅ Lyrics appear **exactly** when they should
+- ✅ Music duration matches displayed duration
+- ✅ No lag or advance in lyrics
+- ✅ Format badges show correct type (ZXIO/MThd)
+
+## 📚 Additional Resources
+
+- **Package:** [@karaplay/file-coder v1.4.9](https://www.npmjs.com/package/@karaplay/file-coder)
+- **Release Notes:** [RELEASE_v1.4.9.md](./RELEASE_v1.4.9.md)
+- **Karaoke Player:** [karaoke-player](https://www.npmjs.com/package/karaoke-player)
+
+---
+
+**Happy Testing! 🎤🎵**

package/DEMO_README.md

@@ -0,0 +1,193 @@
+# EMK to KAR Conversion Demo
+
+## 🎤 Overview
+
+Interactive demo for testing **@karaplay/file-coder v1.4.9** with real-time KAR file playback using `karaoke-player` library.
+
+## ✨ Features
+
+- 📁 **Browse EMK Files** - Select from available EMK files in `songs/emk/`
+- 🔄 **Real-time Conversion** - Convert EMK to KAR using server-side API
+- 🎵 **Karaoke Playback** - Play converted KAR files with synchronized lyrics
+- 📊 **Metadata Display** - View tempo, duration, format (ZXIO/MThd)
+- ⏯️ **Playback Controls** - Play, pause, stop, seek
+- 📈 **Progress Bar** - Visual playback progress
+- ⚡ **Format Detection** - Auto-detect ZXIO vs MThd format
+- 🎯 **Tempo Verification** - Verify correct tempo ratios (2.78x for ZXIO, 4x for MThd)
+
+## 🚀 Quick Start
+
+### 1. Install Dependencies
+
+```bash
+npm install
+```
+
+### 2. Build the Project
+
+```bash
+npm run build
+```
+
+### 3. Start Demo Server
+
+```bash
+npm run demo
+```
+
+### 4. Open Browser
+
+```
+http://localhost:3000/demo-client.html
+```
+
+## 📝 Testing Checklist
+
+### ZXIO Format Files
+- [ ] `001.emk` - Should play at **178.09 BPM** (2.78x ratio)
+- [ ] `failed01.emk` - Should play at **178.09 BPM** (2.78x ratio)
+
+### MThd Format Files
+- [ ] `Z2510001.emk` - Should play at **268 BPM** (4x ratio)
+- [ ] `Z2510002.emk` - Should play at **288 BPM** (4x ratio)
+- [ ] `Z2510003.emk` - Should play at **1136 BPM** (8x ratio)
+- [ ] `Z2510004.emk` - Should play at **268 BPM** (4x ratio)
+- [ ] `Z2510005.emk` - Should play at **272 BPM** (4x ratio)
+
+### Verification Points
+
+1. **Tempo Accuracy**
+   - ZXIO files should use 2.78x tempo ratio
+   - MThd files should use 4x tempo ratio (or higher for special cases)
+   - Check displayed BPM matches expected values
+
+2. **Lyrics Synchronization**
+   - Lyrics should appear in sync with music
+   - No lag or advance
+   - Smooth transitions between lyrics
+
+3. **Duration Accuracy**
+   - Playback duration should match displayed duration
+   - Progress bar should align with actual playback
+
+4. **Format Detection**
+   - ZXIO badge should show for 001.emk and failed01.emk
+   - MThd badge should show for Z251xxxx.emk files
+
+## 🔧 API Endpoints
+
+### GET `/api/emk-files`
+Returns list of available EMK files
+
+**Response:**
+```json
+{
+  "success": true,
+  "files": [
+    {
+      "name": "001.emk",
+      "size": 16985,
+      "path": "/songs/emk/001.emk"
+    }
+  ]
+}
+```
+
+### POST `/api/convert`
+Convert EMK file to KAR
+
+**Request:**
+```json
+{
+  "filename": "001.emk"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "metadata": {
+    "title": "คนกระจอก",
+    "artist": "บุ๊ค ศุภกาญจน์",
+    "format": "ZXIO",
+    "tempo": "178.09",
+    "duration": "126.34",
+    "durationMinutes": "2.11",
+    "warnings": []
+  },
+  "karData": "base64_encoded_kar_file"
+}
+```
+
+## 📊 Technical Details
+
+### Tempo Ratio Logic
+
+**ZXIO Format:**
+```
+Ratio = PPQ / 34.5 = 96 / 34.5 ≈ 2.78x
+Cursor multiply: 4x (PPQ / 24)
+```
+
+**MThd Format:**
+```
+Ratio = PPQ / 24 = 96 / 24 = 4x
+Cursor: raw values (no multiply)
+```
+
+### File Structure
+
+```
+file-coder/
+├── demo-server.js          # Express server for conversion API
+├── demo-client.html        # Interactive demo UI
+├── songs/
+│   └── emk/               # EMK test files
+└── temp/                  # Temporary KAR files (auto-created)
+```
+
+## 🐛 Troubleshooting
+
+### Port Already in Use
+```bash
+# Kill process on port 3000
+lsof -ti:3000 | xargs kill -9
+```
+
+### Module Not Found
+```bash
+# Reinstall dependencies
+rm -rf node_modules package-lock.json
+npm install
+npm run build
+```
+
+### Playback Issues
+- Check browser console for errors
+- Verify KAR file was converted successfully
+- Test with different EMK files
+- Clear browser cache and reload
+
+## 🎯 Success Criteria
+
+Before publishing to npm, verify:
+
+- [x] ✅ All ZXIO files convert with 2.78x tempo ratio
+- [x] ✅ All MThd files convert with correct tempo ratio (4x, 8x, 20x)
+- [x] ✅ Lyrics synchronize perfectly with music
+- [x] ✅ Duration matches original KAR files
+- [x] ✅ No timing drift during playback
+- [x] ✅ Format detection works correctly
+- [x] ✅ Browser and server versions both work
+
+## 📚 Libraries Used
+
+- **@karaplay/file-coder v1.4.9** - EMK to KAR conversion
+- **karaoke-player v1.1.2** - KAR file playback
+- **@tonejs/midi v2.0.28** - MIDI analysis
+- **express v5.2.1** - Demo server
+
+## 📝 License
+
+MIT