@karaplay/file-coder 1.1.0

package/BROWSER_API.md

@@ -0,0 +1,318 @@
+# Browser API Documentation
+
+This document describes how to use file-coder in browser and Next.js client-side environments.
+
+## Installation
+
+```bash
+npm install file-coder
+```
+
+## Usage in Next.js Client Components
+
+### Basic Import
+
+```tsx
+'use client';
+
+import { 
+  convertEmkFileToKar,
+  convertEmkToKarBrowser,
+  type BrowserEmkToKarResult 
+} from 'file-coder/client';
+```
+
+### Example 1: Single File Conversion with Auto-Download
+
+```tsx
+'use client';
+
+import { convertEmkFileToKar } from 'file-coder/client';
+
+function MyComponent() {
+  const handleFileUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (!file) return;
+    
+    try {
+      // Convert and auto-download
+      const result = await convertEmkFileToKar(file, { 
+        autoDownload: true 
+      });
+      
+      console.log('Converted:', result.metadata.title);
+      console.log('Artist:', result.metadata.artist);
+    } catch (error) {
+      console.error('Conversion failed:', error);
+    }
+  };
+  
+  return <input type="file" accept=".emk" onChange={handleFileUpload} />;
+}
+```
+
+### Example 2: Buffer-Based Conversion
+
+```tsx
+'use client';
+
+import { convertEmkToKarBrowser, fileToBuffer } from 'file-coder/client';
+
+async function convertFromBuffer(emkFile: File) {
+  // Convert File to Buffer
+  const emkBuffer = await fileToBuffer(emkFile);
+  
+  // Convert EMK to KAR
+  const result = convertEmkToKarBrowser({
+    emkBuffer,
+    outputFileName: 'output.kar',
+    autoDownload: false  // We'll handle the buffer ourselves
+  });
+  
+  // Access the KAR buffer
+  console.log('KAR buffer size:', result.karBuffer.length);
+  console.log('Title:', result.metadata.title);
+  
+  // Manually download if needed
+  if (result.success) {
+    const { downloadBuffer } = await import('file-coder/client');
+    downloadBuffer(result.karBuffer, result.fileName);
+  }
+  
+  return result;
+}
+```
+
+### Example 3: Batch Conversion
+
+```tsx
+'use client';
+
+import { convertEmkFilesBatch } from 'file-coder/client';
+
+function BatchConverter() {
+  const handleBatchUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
+    const files = Array.from(e.target.files || []);
+    if (files.length === 0) return;
+    
+    try {
+      // Convert multiple files
+      const results = await convertEmkFilesBatch(files, {
+        autoDownload: true
+      });
+      
+      const successCount = results.filter(r => r.success).length;
+      console.log(`Converted ${successCount}/${files.length} files`);
+      
+      // Check results
+      results.forEach(result => {
+        if (result.success) {
+          console.log(`✓ ${result.fileName}: ${result.metadata.title}`);
+        } else {
+          console.error(`✗ ${result.fileName}:`, result.warnings);
+        }
+      });
+    } catch (error) {
+      console.error('Batch conversion failed:', error);
+    }
+  };
+  
+  return (
+    <input 
+      type="file" 
+      accept=".emk" 
+      multiple 
+      onChange={handleBatchUpload} 
+    />
+  );
+}
+```
+
+## API Reference
+
+### Main Functions
+
+#### `convertEmkFileToKar(emkFile: File, options?: { autoDownload?: boolean })`
+
+Converts a File object (from file input) to KAR format.
+
+**Parameters:**
+- `emkFile`: File object from file input
+- `options.autoDownload`: If true, automatically downloads the KAR file (default: true)
+
+**Returns:** `Promise<BrowserEmkToKarResult>`
+
+#### `convertEmkToKarBrowser(options: BrowserEmkToKarOptions)`
+
+Converts an EMK buffer to KAR buffer.
+
+**Parameters:**
+```typescript
+interface BrowserEmkToKarOptions {
+  emkBuffer: Buffer;
+  outputFileName?: string;
+  autoDownload?: boolean;
+}
+```
+
+**Returns:** `BrowserEmkToKarResult`
+
+```typescript
+interface BrowserEmkToKarResult {
+  success: boolean;
+  karBuffer: Buffer;
+  fileName: string;
+  intermediateBuffers?: {
+    midi: Buffer;
+    lyric: Buffer;
+    cursor: Buffer;
+  };
+  metadata: {
+    title: string;
+    artist: string;
+    code?: string;
+  };
+  warnings: string[];
+}
+```
+
+#### `convertEmkFilesBatch(emkFiles: File[], options?: { autoDownload?: boolean })`
+
+Converts multiple EMK files at once.
+
+**Parameters:**
+- `emkFiles`: Array of File objects
+- `options.autoDownload`: If true, automatically downloads all KAR files (default: false)
+
+**Returns:** `Promise<BrowserEmkToKarResult[]>`
+
+### Helper Functions
+
+#### `fileToBuffer(file: File): Promise<Buffer>`
+
+Converts a File object to a Buffer for use with buffer-based APIs.
+
+#### `downloadBuffer(buffer: Buffer, fileName: string, mimeType?: string): void`
+
+Triggers a browser download of a buffer.
+
+**Parameters:**
+- `buffer`: The data to download
+- `fileName`: Name for the downloaded file
+- `mimeType`: MIME type (default: 'audio/midi')
+
+### NCN to KAR (Browser)
+
+#### `convertNcnToKarBrowser(options: BrowserConversionOptions)`
+
+Converts MIDI, Lyric, and Cursor buffers to a KAR buffer.
+
+**Parameters:**
+```typescript
+interface BrowserConversionOptions {
+  midiBuffer: Buffer;
+  lyricBuffer: Buffer;
+  cursorBuffer: Buffer;
+  outputFileName?: string;
+}
+```
+
+**Returns:** `BrowserConversionResult`
+
+### KAR Reader (Browser)
+
+#### `readKarBuffer(buffer: Buffer): KarFileInfo`
+
+Reads and parses a KAR file buffer.
+
+#### `validateKarBuffer(buffer: Buffer)`
+
+Validates a KAR buffer structure.
+
+#### `extractLyricsFromKarBuffer(buffer: Buffer): string[]`
+
+Extracts lyrics from a KAR buffer.
+
+#### `readKarFile(file: File): Promise<KarFileInfo>`
+
+Reads a File object as a KAR file.
+
+## Complete Example Component
+
+See [examples/NextJSComponent.tsx](./examples/NextJSComponent.tsx) for a full-featured Next.js component with:
+- Single file upload and conversion
+- Batch file processing
+- Error handling
+- Loading states
+- Success/error messages
+- Auto-download functionality
+
+## Browser Compatibility
+
+- ✅ Chrome/Edge (Chromium)
+- ✅ Firefox
+- ✅ Safari
+- ✅ Next.js 13+ (App Router)
+- ✅ React 18+
+
+## Features
+
+- 🎵 Client-side EMK decoding
+- 🎤 Thai lyrics support (TIS-620 encoding)
+- 📦 No server required - all processing in browser
+- ⚡ Fast conversion
+- 💾 Auto-download support
+- 🔄 Batch processing
+- 📊 Metadata extraction
+- ✅ KAR file validation
+
+## Notes
+
+- All processing happens in the browser - no files are uploaded to servers
+- Large files may take a few seconds to process
+- The library uses Pako for decompression (browser-compatible alternative to zlib)
+- Supports TIS-620 encoding for proper Thai character handling
+
+## TypeScript Support
+
+Full TypeScript support with type definitions included:
+
+```typescript
+import type {
+  BrowserEmkToKarOptions,
+  BrowserEmkToKarResult,
+  BrowserConversionOptions,
+  BrowserConversionResult,
+  KarFileInfo,
+  KarTrack
+} from 'file-coder/client';
+```
+
+## Performance Tips
+
+1. **Batch Processing**: Use `convertEmkFilesBatch` for multiple files instead of calling `convertEmkFileToKar` in a loop
+2. **Auto-Download**: Set `autoDownload: false` if you want to process the buffer before downloading
+3. **Web Workers**: For heavy processing, consider running conversions in a Web Worker (not included in library)
+
+## Error Handling
+
+```tsx
+try {
+  const result = await convertEmkFileToKar(file);
+  
+  if (result.success) {
+    console.log('Success:', result.metadata.title);
+    
+    if (result.warnings.length > 0) {
+      console.warn('Warnings:', result.warnings);
+    }
+  }
+} catch (error) {
+  console.error('Conversion failed:', error.message);
+}
+```
+
+## License
+
+MIT
+

package/README.md

@@ -0,0 +1,216 @@
+# @karaplay/file-coder
+
+A comprehensive library for encoding/decoding karaoke files (.emk, .kar, MIDI) with Next.js support.
+
+## Features
+
+- 🎵 Convert NCN format (.mid + .lyr + .cur) to .kar (MIDI karaoke)
+- 🔓 Decode .emk (Extreme Karaoke) files
+- 📖 Read and validate .kar files
+- ⚡ **NEW**: Complete EMK → KAR workflow (one-step conversion)
+- 🌐 Full TypeScript support
+- ⚛️ Next.js compatible (both client and server side)
+- 🌐 **NEW**: Browser-compatible API for client-side processing
+- 🇹🇭 Thai language support (TIS-620 encoding)
+- ✅ 101+ tests - 100% pass rate (including integration tests with real files)
+
+## Installation
+
+```bash
+npm install @karaplay/file-coder
+```
+
+## Quick Start
+
+### Browser/Client-Side (Next.js) 🌐 NEW
+
+For client-side processing in Next.js or browser environments:
+
+```tsx
+'use client';
+
+import { convertEmkFileToKar } from '@karaplay/file-coder/client';
+
+function MyComponent() {
+  const handleFileUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (!file) return;
+    
+    const result = await convertEmkFileToKar(file, { autoDownload: true });
+    console.log('Converted:', result.metadata.title);
+  };
+  
+  return <input type="file" accept=".emk" onChange={handleFileUpload} />;
+}
+```
+
+**📚 [Full Browser API Documentation →](./BROWSER_API.md)**
+
+### Server-Side (Node.js)
+
+## Usage
+
+### EMK to KAR Workflow (Complete Pipeline) ⭐ NEW
+
+Convert EMK files directly to KAR in one step:
+
+```typescript
+import { convertEmkToKar } from '@karaplay/file-coder';
+
+const result = convertEmkToKar({
+  inputEmk: 'songs/song.emk',
+  outputKar: 'output/song.kar'
+});
+
+console.log(`Title: ${result.metadata.title}`);
+console.log(`Artist: ${result.metadata.artist}`);
+console.log(`Success: ${result.success}`);
+// Thai text is readable! ✅
+```
+
+**Batch conversion**:
+```typescript
+import { convertEmkToKarBatch } from '@karaplay/file-coder';
+
+const results = convertEmkToKarBatch(
+  ['song1.emk', 'song2.emk', 'song3.emk'],
+  'output/kar'
+);
+```
+
+See [EMK_TO_KAR_WORKFLOW.md](./EMK_TO_KAR_WORKFLOW.md) for complete documentation.
+
+### NCN to KAR Conversion
+
+```typescript
+import { convertNcnToKar } from 'file-coder';
+
+const result = convertNcnToKar({
+  inputMidi: 'path/to/song.mid',
+  inputLyr: 'path/to/song.lyr',
+  inputCur: 'path/to/song.cur',
+  outputKar: 'path/to/output.kar',
+  appendTitles: true
+});
+
+console.log(`Converted: ${result.metadata.title} by ${result.metadata.artist}`);
+```
+
+### EMK Decoding (Server-side)
+
+```typescript
+import { decodeEmkServer, parseSongInfoServer } from 'file-coder';
+import * as fs from 'fs';
+
+const fileBuffer = fs.readFileSync('path/to/song.emk');
+const decoded = decodeEmkServer(fileBuffer);
+
+// Access decoded parts
+const midiData = decoded.midi;
+const lyricData = decoded.lyric;
+const cursorData = decoded.cursor;
+
+// Parse song information
+const songInfo = parseSongInfoServer(decoded.songInfo);
+console.log(`Title: ${songInfo.TITLE}`);
+console.log(`Artist: ${songInfo.ARTIST}`);
+```
+
+### EMK Decoding (Client-side/Next.js)
+
+```typescript
+'use client';
+
+import { decodeEmkClient, parseSongInfoClient } from 'file-coder';
+
+function MyComponent() {
+  const handleFileUpload = async (file: File) => {
+    const arrayBuffer = await file.arrayBuffer();
+    const buffer = Buffer.from(arrayBuffer);
+    
+    const decoded = decodeEmkClient(buffer);
+    const songInfo = parseSongInfoClient(decoded.songInfo);
+    
+    console.log(`Title: ${songInfo.TITLE}`);
+  };
+  
+  return <input type="file" onChange={(e) => handleFileUpload(e.target.files[0])} />;
+}
+```
+
+## API Reference
+
+### NCN to KAR Functions
+
+- `convertNcnToKar(options)` - Main conversion function
+- `parseLyricFile(filePath)` - Parse .lyr file for metadata
+- `buildKaraokeTrack(metadata, cursorBuffer, ticksPerBeat)` - Build karaoke track with timing
+- `buildMetadataTracks(metadata)` - Build metadata tracks
+- `CursorReader` - Class for reading cursor timing data
+
+### EMK to KAR Workflow Functions ⭐ NEW
+
+- `convertEmkToKar(options)` - Complete pipeline: EMK → KAR (one step!)
+- `convertEmkToKarBatch(emkFiles, outputDir, options?)` - Batch convert multiple files
+- `validateThaiLyricReadability(lyricBuffer)` - Validate Thai text readability
+
+### KAR File Reader Functions
+
+- `readKarFile(filePath)` - Read and parse .kar file
+- `validateKarFile(filePath)` - Validate .kar file structure
+- `extractLyricsFromKar(filePath)` - Extract lyrics from .kar file
+
+### EMK Decoder Functions
+
+#### Server-side
+- `decodeEmkServer(fileBuffer)` - Decode .emk file (Node.js)
+- `parseSongInfoServer(songInfoBuffer)` - Parse song metadata
+- `xorDecryptServer(data)` - XOR decryption utility
+- `looksLikeTextServer(buffer)` - Text detection utility
+
+#### Client-side
+- `decodeEmkClient(fileBuffer)` - Decode .emk file (Browser/Next.js)
+- `parseSongInfoClient(songInfoBuffer)` - Parse song metadata
+- `xorDecryptClient(data)` - XOR decryption utility
+- `looksLikeTextClient(buffer)` - Text detection utility
+
+## Development
+
+### Install Dependencies
+
+```bash
+npm install
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Run Tests
+
+```bash
+npm test
+```
+
+### Test Coverage
+
+```bash
+npm run test:coverage
+```
+
+## Requirements
+
+- Node.js >= 16
+- TypeScript >= 5.0
+- Next.js >= 13.0 (optional, for client-side features)
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+