@karaplay/file-coder 1.5.1 → 1.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (16) hide show
  1. package/DOCUMENTATION_INDEX.md +317 -0
  2. package/EMK_REFERENCE_DATA.json +190 -0
  3. package/EMK_SONGS_INFO.md +336 -0
  4. package/EMK_TEST_SUITE_README.md +456 -0
  5. package/EMK_TEST_SUITE_SUMMARY.txt +197 -0
  6. package/RELEASE_v1.5.2.md +238 -0
  7. package/SONG_LIST.txt +268 -0
  8. package/TEMPO_TRICKS_SUMMARY.md +240 -0
  9. package/dist/ncntokar.browser.js +13 -1
  10. package/dist/ncntokar.js +13 -1
  11. package/package.json +4 -1
  12. package/verify-emk-reference.js +230 -0
  13. package/debug-duration.js +0 -124
  14. package/manual-test-validator.js +0 -79
  15. package/test-demo-player.sh +0 -63
  16. package/test-duration-fix.sh +0 -53
package/DOCUMENTATION_INDEX.md ADDED
@@ -0,0 +1,317 @@
1
+ # 📚 Documentation Index
2
+
3
+ **@karaplay/file-coder v1.5.1+**
4
+ Complete guide to EMK/KAR conversion and testing
5
+
6
+ ---
7
+
8
+ ## 🚀 Getting Started
9
+
10
+ ### For Users
11
+
12
+ 1. **[README.md](./README.md)** ⭐ START HERE
13
+ - Installation and quick start
14
+ - Main API documentation
15
+ - Features and examples
16
+ - Browser/Server usage
17
+
18
+ 2. **[BROWSER_API.md](./BROWSER_API.md)**
19
+ - Client-side conversion guide
20
+ - Next.js integration
21
+ - Browser examples
22
+
23
+ ---
24
+
25
+ ## 🎵 Song Conversion
26
+
27
+ ### Main Workflow
28
+
29
+ 3. **[EMK_TO_KAR_WORKFLOW.md](./EMK_TO_KAR_WORKFLOW.md)**
30
+ - Complete EMK → KAR pipeline
31
+ - Step-by-step guide
32
+ - Advanced options
33
+
34
+ 4. **[HOWTOEMKTONCN.md](./HOWTOEMKTONCN.md)**
35
+ - EMK to NCN conversion
36
+ - Technical details
37
+
38
+ ---
39
+
40
+ ## ⏱️ Tempo & Duration
41
+
42
+ ### Understanding Tempo
43
+
44
+ 5. **[TEMPO_TRICKS_SUMMARY.md](./TEMPO_TRICKS_SUMMARY.md)** ⭐ BEST PRACTICES
45
+ - How to use @tonejs/midi correctly
46
+ - Common pitfalls and solutions
47
+ - ZXIO vs MThd formats
48
+ - Why duration decreases when tempo increases
49
+
50
+ 6. **[WHY_DURATION_DECREASES.md](./WHY_DURATION_DECREASES.md)**
51
+ - Mathematical explanation
52
+ - Tempo-duration relationship
53
+
54
+ ---
55
+
56
+ ## 🧪 Testing & Validation
57
+
58
+ ### Test Suite
59
+
60
+ 7. **[EMK_TEST_SUITE_README.md](./EMK_TEST_SUITE_README.md)** ⭐ TESTING GUIDE
61
+ - Complete test suite documentation
62
+ - How to run tests
63
+ - Debugging failed tests
64
+ - Best practices
65
+
66
+ 8. **[EMK_SONGS_INFO.md](./EMK_SONGS_INFO.md)**
67
+ - Song information database
68
+ - Expected results for each file
69
+ - Format statistics
70
+ - Verification checklist
71
+
72
+ 9. **[EMK_TEST_SUITE_SUMMARY.txt](./EMK_TEST_SUITE_SUMMARY.txt)**
73
+ - Quick reference summary
74
+ - Test results overview
75
+ - Statistics
76
+
77
+ 10. **[EMK_REFERENCE_DATA.json](./EMK_REFERENCE_DATA.json)**
78
+ - Machine-readable reference data
79
+ - Used by test scripts
80
+ - Auto-generated from conversions
81
+
82
+ ---
83
+
84
+ ## 🔧 Technical Details
85
+
86
+ ### Problem Solving
87
+
88
+ 11. **[KAR_FILE_VALIDATION_SOLUTION.md](./KAR_FILE_VALIDATION_SOLUTION.md)**
89
+ - KAR file validation
90
+ - Quality checks
91
+
92
+ 12. **[BROWSER_KAR_CORRUPTION_FIX.md](./BROWSER_KAR_CORRUPTION_FIX.md)**
93
+ - Browser-specific issues
94
+ - Corruption fixes
95
+
96
+ 13. **[BUG_FIX_SUMMARY.md](./BUG_FIX_SUMMARY.md)**
97
+ - Historical bug fixes
98
+ - Solutions applied
99
+
100
+ ---
101
+
102
+ ## 🎭 Demo & Examples
103
+
104
+ ### Live Demo
105
+
106
+ 14. **[DEMO_ENHANCED.md](./DEMO_ENHANCED.md)**
107
+ - Demo page documentation
108
+ - Features and usage
109
+
110
+ 15. **[demo-simple.html](./demo-simple.html)**
111
+ - Live demo page
112
+ - Run: `npm run demo`
113
+ - Browser: http://localhost:3000
114
+
115
+ 16. **[examples/NextJSComponent.tsx](./examples/NextJSComponent.tsx)**
116
+ - React/Next.js example
117
+ - Client-side conversion
118
+
119
+ ---
120
+
121
+ ## 📋 Release Notes
122
+
123
+ ### Version History
124
+
125
+ 17. **[RELEASE_v1.5.1.md](./RELEASE_v1.5.1.md)** ⭐ LATEST
126
+ - Validation utilities
127
+ - Enhanced documentation
128
+ - Test suite
129
+
130
+ 18. **[RELEASE_v1.5.0.md](./RELEASE_v1.5.0.md)**
131
+ - ZXIO tempo fix (1.24x)
132
+ - Duration accuracy improvements
133
+
134
+ 19. **[RELEASE_v1.4.9.md](./RELEASE_v1.4.9.md)**
135
+ - ZXIO format support improvements
136
+
137
+ 20. **[RELEASE_v1.4.7.md](./RELEASE_v1.4.7.md)**
138
+ - ZXIO "zxio" header support
139
+
140
+ 21. **Previous Releases:**
141
+ - v1.4.0 - v1.4.6: See individual release notes
142
+ - v1.3.0 - v1.3.9: See individual release notes
143
+ - v1.1.1 - v1.2.0: See individual release notes
144
+
145
+ ---
146
+
147
+ ## 🎯 Quick Reference
148
+
149
+ ### Common Tasks
150
+
151
+ | Task | Documentation | Command |
152
+ |------|---------------|---------|
153
+ | **Convert EMK to KAR** | [README.md](./README.md#emk-to-kar-workflow-complete-pipeline) | `convertEmkToKar()` |
154
+ | **Validate KAR file** | [TEMPO_TRICKS_SUMMARY.md](./TEMPO_TRICKS_SUMMARY.md#4-validation-functions) | `validateKarTempo()` |
155
+ | **Run tests** | [EMK_TEST_SUITE_README.md](./EMK_TEST_SUITE_README.md#-quick-start) | `npm run test:emk` |
156
+ | **Fix tempo issues** | [TEMPO_TRICKS_SUMMARY.md](./TEMPO_TRICKS_SUMMARY.md#6-common-pitfalls) | Auto-fixed in v1.5.0+ |
157
+ | **Browser usage** | [BROWSER_API.md](./BROWSER_API.md) | `convertEmkFileToKar()` |
158
+ | **Run demo** | [DEMO_ENHANCED.md](./DEMO_ENHANCED.md) | `npm run demo` |
159
+
160
+ ---
161
+
162
+ ## 🔍 By Topic
163
+
164
+ ### For Developers
165
+
166
+ **Converting Files:**
167
+ - [README.md](./README.md) - Main API
168
+ - [EMK_TO_KAR_WORKFLOW.md](./EMK_TO_KAR_WORKFLOW.md) - Complete workflow
169
+ - [BROWSER_API.md](./BROWSER_API.md) - Client-side
170
+
171
+ **Understanding Tempo:**
172
+ - [TEMPO_TRICKS_SUMMARY.md](./TEMPO_TRICKS_SUMMARY.md) - ⭐ Best practices
173
+ - [WHY_DURATION_DECREASES.md](./WHY_DURATION_DECREASES.md) - Explanation
174
+ - [RELEASE_v1.5.0.md](./RELEASE_v1.5.0.md) - ZXIO fix
175
+
176
+ **Testing:**
177
+ - [EMK_TEST_SUITE_README.md](./EMK_TEST_SUITE_README.md) - ⭐ Complete guide
178
+ - [EMK_SONGS_INFO.md](./EMK_SONGS_INFO.md) - Reference data
179
+ - [EMK_REFERENCE_DATA.json](./EMK_REFERENCE_DATA.json) - Test data
180
+
181
+ ### For QA / Testing
182
+
183
+ **Quality Assurance:**
184
+ - [EMK_TEST_SUITE_README.md](./EMK_TEST_SUITE_README.md) - Test procedures
185
+ - [EMK_SONGS_INFO.md](./EMK_SONGS_INFO.md) - Expected results
186
+ - [KAR_FILE_VALIDATION_SOLUTION.md](./KAR_FILE_VALIDATION_SOLUTION.md) - Validation
187
+
188
+ **Troubleshooting:**
189
+ - [TEMPO_TRICKS_SUMMARY.md](./TEMPO_TRICKS_SUMMARY.md) - Common issues
190
+ - [BUG_FIX_SUMMARY.md](./BUG_FIX_SUMMARY.md) - Known bugs & fixes
191
+ - [EMK_TEST_SUITE_README.md](./EMK_TEST_SUITE_README.md#-debugging-failed-tests) - Debugging
192
+
193
+ ### For End Users
194
+
195
+ **Getting Started:**
196
+ 1. [README.md](./README.md) - Install and basic usage
197
+ 2. [DEMO_ENHANCED.md](./DEMO_ENHANCED.md) - Try the demo
198
+ 3. [examples/NextJSComponent.tsx](./examples/NextJSComponent.tsx) - Code examples
199
+
200
+ **Understanding Results:**
201
+ - [WHY_DURATION_DECREASES.md](./WHY_DURATION_DECREASES.md) - Why duration changes
202
+ - [EMK_SONGS_INFO.md](./EMK_SONGS_INFO.md) - Song information
203
+
204
+ ---
205
+
206
+ ## 📊 Statistics
207
+
208
+ ### Documentation Coverage
209
+
210
+ - **Total Documents:** 21+ files
211
+ - **API Documentation:** 3 files
212
+ - **Technical Guides:** 7 files
213
+ - **Testing Documentation:** 4 files
214
+ - **Release Notes:** 15+ files
215
+ - **Examples:** 2 files
216
+
217
+ ### Lines of Documentation
218
+
219
+ - **README.md:** ~290 lines
220
+ - **Test Suite Docs:** ~1,200 lines
221
+ - **Tempo Guides:** ~500 lines
222
+ - **Release Notes:** ~3,000 lines
223
+ - **Total:** ~5,000+ lines
224
+
225
+ ---
226
+
227
+ ## 🎓 Learning Paths
228
+
229
+ ### Path 1: Basic User (15 minutes)
230
+
231
+ 1. Read [README.md](./README.md) - Quick Start section
232
+ 2. Try the demo: `npm run demo`
233
+ 3. Copy example from [examples/NextJSComponent.tsx](./examples/NextJSComponent.tsx)
234
+
235
+ ### Path 2: Integration Developer (1 hour)
236
+
237
+ 1. [README.md](./README.md) - Full API
238
+ 2. [BROWSER_API.md](./BROWSER_API.md) - Client-side API
239
+ 3. [EMK_TO_KAR_WORKFLOW.md](./EMK_TO_KAR_WORKFLOW.md) - Workflow
240
+ 4. [TEMPO_TRICKS_SUMMARY.md](./TEMPO_TRICKS_SUMMARY.md) - Best practices
241
+
242
+ ### Path 3: Library Contributor (3 hours)
243
+
244
+ 1. [README.md](./README.md) - Overview
245
+ 2. [TEMPO_TRICKS_SUMMARY.md](./TEMPO_TRICKS_SUMMARY.md) - Technical details
246
+ 3. [EMK_TEST_SUITE_README.md](./EMK_TEST_SUITE_README.md) - Testing
247
+ 4. [RELEASE_v1.5.0.md](./RELEASE_v1.5.0.md) - Recent changes
248
+ 5. Source code in `src/`
249
+
250
+ ### Path 4: QA Tester (2 hours)
251
+
252
+ 1. [EMK_TEST_SUITE_README.md](./EMK_TEST_SUITE_README.md) - Test suite
253
+ 2. [EMK_SONGS_INFO.md](./EMK_SONGS_INFO.md) - Expected results
254
+ 3. Run: `npm run test:emk`
255
+ 4. [TEMPO_TRICKS_SUMMARY.md](./TEMPO_TRICKS_SUMMARY.md) - Debugging
256
+
257
+ ---
258
+
259
+ ## 🆘 Getting Help
260
+
261
+ ### If you need to...
262
+
263
+ **Convert a file:**
264
+ → See [README.md](./README.md#emk-to-kar-workflow-complete-pipeline)
265
+
266
+ **Fix tempo issues:**
267
+ → See [TEMPO_TRICKS_SUMMARY.md](./TEMPO_TRICKS_SUMMARY.md#6-common-pitfalls)
268
+
269
+ **Run tests:**
270
+ → See [EMK_TEST_SUITE_README.md](./EMK_TEST_SUITE_README.md#-quick-start)
271
+
272
+ **Understand duration changes:**
273
+ → See [WHY_DURATION_DECREASES.md](./WHY_DURATION_DECREASES.md)
274
+
275
+ **Debug a conversion:**
276
+ → See [EMK_TEST_SUITE_README.md](./EMK_TEST_SUITE_README.md#-debugging-failed-tests)
277
+
278
+ **Use in browser:**
279
+ → See [BROWSER_API.md](./BROWSER_API.md)
280
+
281
+ **Check song info:**
282
+ → See [EMK_SONGS_INFO.md](./EMK_SONGS_INFO.md)
283
+
284
+ ---
285
+
286
+ ## 📝 Document Status
287
+
288
+ | Document | Status | Last Updated |
289
+ |----------|--------|--------------|
290
+ | README.md | ✅ Current | 2026-01-13 |
291
+ | TEMPO_TRICKS_SUMMARY.md | ✅ Current | 2026-01-13 |
292
+ | EMK_TEST_SUITE_README.md | ✅ Current | 2026-01-13 |
293
+ | EMK_SONGS_INFO.md | ✅ Current | 2026-01-13 |
294
+ | RELEASE_v1.5.1.md | ✅ Current | 2026-01-13 |
295
+ | Other docs | ✅ Current | Various |
296
+
297
+ ---
298
+
299
+ ## 🔗 External Resources
300
+
301
+ ### npm Package
302
+
303
+ - **Package:** [@karaplay/file-coder](https://www.npmjs.com/package/@karaplay/file-coder)
304
+ - **Version:** 1.5.1+
305
+ - **License:** ISC
306
+
307
+ ### Dependencies
308
+
309
+ - [@tonejs/midi](https://www.npmjs.com/package/@tonejs/midi) - MIDI parsing (recommended)
310
+ - [karaoke-player](https://www.npmjs.com/package/karaoke-player) - KAR playback
311
+ - [iconv-lite](https://www.npmjs.com/package/iconv-lite) - TIS-620 encoding
312
+
313
+ ---
314
+
315
+ **Last Updated:** 2026-01-13
316
+ **Maintained by:** @karaplay/file-coder team
317
+ **Status:** ✅ Complete and Up-to-Date
package/EMK_REFERENCE_DATA.json ADDED
@@ -0,0 +1,190 @@
1
+ {
2
+ "generatedAt": "2026-01-13T10:35:06.632Z",
3
+ "version": "1.5.1",
4
+ "totalFiles": 11,
5
+ "successful": 9,
6
+ "failed": 2,
7
+ "songs": [
8
+ {
9
+ "filename": "001.emk",
10
+ "status": "success",
11
+ "title": "คนกระจอก",
12
+ "artist": "บุ๊ค ศุภกาญจน์",
13
+ "format": "ZXIO",
14
+ "emkTempo": 64,
15
+ "karTempo": 79.35930587060466,
16
+ "tempoRatio": 1.2399891542281978,
17
+ "expectedRatio": 1.24,
18
+ "ratioMatch": true,
19
+ "duration": 283.520625,
20
+ "durationFormatted": "4:43",
21
+ "ppq": 96,
22
+ "trackCount": 29,
23
+ "noteCount": 6313,
24
+ "warnings": 0,
25
+ "errors": 0
26
+ },
27
+ {
28
+ "filename": "001_original_emk.emk",
29
+ "status": "success",
30
+ "title": "คนกระจอก",
31
+ "artist": "บุ๊ค ศุภกาญจน์",
32
+ "format": "ZXIO",
33
+ "emkTempo": 64,
34
+ "karTempo": 79.35930587060466,
35
+ "tempoRatio": 1.2399891542281978,
36
+ "expectedRatio": 1.24,
37
+ "ratioMatch": true,
38
+ "duration": 283.520625,
39
+ "durationFormatted": "4:43",
40
+ "ppq": 96,
41
+ "trackCount": 29,
42
+ "noteCount": 6313,
43
+ "warnings": 0,
44
+ "errors": 0
45
+ },
46
+ {
47
+ "filename": "500006.emk",
48
+ "status": "error",
49
+ "error": "EMK to KAR conversion failed: MIDI data block not found in EMK file."
50
+ },
51
+ {
52
+ "filename": "Z2510001.emk",
53
+ "status": "success",
54
+ "title": "เสน่ห์เมืองพระรถ(Ab)",
55
+ "artist": "วงข้าหลวง ",
56
+ "format": "MThd",
57
+ "emkTempo": 67.00002903334591,
58
+ "karTempo": 267.99951760086833,
59
+ "tempoRatio": 3.999991066682747,
60
+ "expectedRatio": 4,
61
+ "ratioMatch": true,
62
+ "duration": 54.822859875,
63
+ "durationFormatted": "0:54",
64
+ "ppq": 96,
65
+ "trackCount": 12,
66
+ "noteCount": 2181,
67
+ "warnings": 0,
68
+ "errors": 0
69
+ },
70
+ {
71
+ "filename": "Z2510002.emk",
72
+ "status": "success",
73
+ "title": "สามปอยหลวง ( Dm )",
74
+ "artist": "เมตตา วงค์ธานีKara",
75
+ "format": "MThd",
76
+ "emkTempo": 72.00002880001152,
77
+ "karTempo": 288.0004608007373,
78
+ "tempoRatio": 4.00000480000768,
79
+ "expectedRatio": 4,
80
+ "ratioMatch": true,
81
+ "duration": 53.383161114583324,
82
+ "durationFormatted": "0:53",
83
+ "ppq": 96,
84
+ "trackCount": 18,
85
+ "noteCount": 4160,
86
+ "warnings": 0,
87
+ "errors": 0
88
+ },
89
+ {
90
+ "filename": "Z2510003.emk",
91
+ "status": "success",
92
+ "title": "มีคู่เสียเถิด",
93
+ "artist": "บัดส์ อันตราย",
94
+ "format": "MThd",
95
+ "emkTempo": 142.0000710000355,
96
+ "karTempo": 1135.997879470625,
97
+ "tempoRatio": 7.99998106670201,
98
+ "expectedRatio": 8,
99
+ "ratioMatch": true,
100
+ "duration": 18.611390375,
101
+ "durationFormatted": "0:18",
102
+ "ppq": 192,
103
+ "trackCount": 12,
104
+ "noteCount": 4126,
105
+ "warnings": 1,
106
+ "errors": 0
107
+ },
108
+ {
109
+ "filename": "Z2510004.emk",
110
+ "status": "success",
111
+ "title": "น้ำท่วมน้องทิ้ง",
112
+ "artist": "สันติ ดวงสว่าง",
113
+ "format": "MThd",
114
+ "emkTempo": 67.00002903334591,
115
+ "karTempo": 267.99951760086833,
116
+ "tempoRatio": 3.999991066682747,
117
+ "expectedRatio": 4,
118
+ "ratioMatch": true,
119
+ "duration": 47.20390959375,
120
+ "durationFormatted": "0:47",
121
+ "ppq": 96,
122
+ "trackCount": 20,
123
+ "noteCount": 3165,
124
+ "warnings": 0,
125
+ "errors": 0
126
+ },
127
+ {
128
+ "filename": "Z2510005.emk",
129
+ "status": "success",
130
+ "title": "คนแบกรัก",
131
+ "artist": "แจ๊ค ธนพล",
132
+ "format": "MThd",
133
+ "emkTempo": 67.99999546666697,
134
+ "karTempo": 272.0002901336428,
135
+ "tempoRatio": 4.000004533338169,
136
+ "expectedRatio": 4,
137
+ "ratioMatch": true,
138
+ "duration": 60.882287999999996,
139
+ "durationFormatted": "1:00",
140
+ "ppq": 96,
141
+ "trackCount": 25,
142
+ "noteCount": 3655,
143
+ "warnings": 0,
144
+ "errors": 0
145
+ },
146
+ {
147
+ "filename": "Z2510006.emk",
148
+ "status": "success",
149
+ "title": "Move On แบบใด",
150
+ "artist": "โจอี้ ภูวศิษฐ์",
151
+ "format": "MThd",
152
+ "emkTempo": 87.00002175000543,
153
+ "karTempo": 87,
154
+ "tempoRatio": 1,
155
+ "expectedRatio": 1,
156
+ "ratioMatch": true,
157
+ "duration": 256.64,
158
+ "durationFormatted": "4:16",
159
+ "ppq": 480,
160
+ "trackCount": 17,
161
+ "noteCount": 7046,
162
+ "warnings": 1,
163
+ "errors": 0
164
+ },
165
+ {
166
+ "filename": "f0000001.emk",
167
+ "status": "error",
168
+ "error": "EMK to KAR conversion failed: undefined"
169
+ },
170
+ {
171
+ "filename": "failed01.emk",
172
+ "status": "success",
173
+ "title": "คนกระจอก",
174
+ "artist": "บุ๊ค ศุภกาญจน์",
175
+ "format": "ZXIO",
176
+ "emkTempo": 64,
177
+ "karTempo": 79.35930587060466,
178
+ "tempoRatio": 1.2399891542281978,
179
+ "expectedRatio": 1.24,
180
+ "ratioMatch": true,
181
+ "duration": 283.520625,
182
+ "durationFormatted": "4:43",
183
+ "ppq": 96,
184
+ "trackCount": 29,
185
+ "noteCount": 6313,
186
+ "warnings": 0,
187
+ "errors": 0
188
+ }
189
+ ]
190
+ }