mes-engine 0.0.3 → 1.0.1

package/.mocharc.json

@@ -0,0 +1,7 @@
+{
+    "extension": [
+        "ts"
+    ],
+    "spec": "tests/**/*.test.ts",
+    "timeout": 10000
+}

package/README.md

@@ -1,86 +1,94 @@
-# mes-engine
-
-A powerful and flexible video processing framework for Node.js with support for multiple processing engines, adaptive streaming, and intelligent caching.
-
-[![npm version](https://badge.fury.io/js/mes-engine.svg)](https://badge.fury.io/js/mes-engine)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-## Features
-
-- 🎥 Multiple video processing engines (FFmpeg, GStreamer)
-- 🔄 Adaptive streaming with quality switching
-- 📦 Chunk-based processing for efficient streaming
-- 💾 Flexible storage providers
-- 🚀 Built-in caching strategies (internal/external)
-- 📡 Event-driven architecture
-- 🔌 Extensible plugin system
-
-## Quick Start
-
-### Installation
-
-```bash
-npm install mes-engine
-
-# Install required engine
-npm install ffmpeg-static  # For FFmpeg engine
-# or
-npm install gstreamer     # For GStreamer engine
-```
-
-### Basic Usage
-
-```typescript
-import {
-  VideoProcessor,
-  FFmpegEngine,
-  FileSystemStorage,
-  InternalCache
-} from 'mes-engine';
-
-// Initialize processor
-const processor = new VideoProcessor({
-  engine: new FFmpegEngine(),
-  storage: new FileSystemStorage(),
-  cache: new InternalCache({
-    maxSize: 1024 * 1024 * 100, // 100MB
-    ttl: 3600,
-    preloadNextChunk: true
-  })
-});
-
-// Process video
-const manifest = await processor.processVideo('input.mp4');
-
-// Stream video chunk
-const stream = await processor.streamChunk(
-  manifest.videoId,
-  720, // quality
-  0    // chunk number
-);
-```
-
-## Documentation
-
-Full documentation is available in the [docs directory](./docs).
-
-### Key Topics:
-- [Getting Started](./docs/getting-started.md)
-- [Video Engines](./docs/engines.md)
-- [Storage Providers](./docs/storage.md)
-- [Caching Strategies](./docs/caching.md)
-- [API Reference](./docs/api.md)
-
-## Supported Engines
-
-- **FFmpegEngine**: Full-featured video processing using FFmpeg
-- **GStreamerEngine**: High-performance processing using GStreamer
-- **Custom Engines**: Create your own by extending `VideoEngine`
-
-## Contributing
-
-Contributions are welcome! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.
-
-## License
-
+# mes-engine
+
+A powerful and flexible video processing framework for Node.js with support for multiple processing engines, adaptive streaming, and intelligent caching.
+
+[![npm version](https://badge.fury.io/js/mes-engine.svg)](https://badge.fury.io/js/mes-engine)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 🎥 **Multiple Video Engines**: FFmpeg and GStreamer support.
+- 🔄 **Adaptive Streaming**: Automatic HLS (`.m3u8`) manifest generation with master and quality playlists.
+- 📦 **Chunk-based Processing**: Parallelizable video chunking for efficient delivery.
+- 📸 **Screenshot Extraction**: Automatic thumbnail generation for every video chunk.
+- 💾 **Flexible Storage**: Abstract storage layer supporting local filesystem and easily extensible to S3/Cloud storage.
+- 🚀 **Intelligent Caching**: Built-in strategies for preloading and caching video segments.
+- 📡 **Event-driven**: Comprehensive event system for monitoring processing progress.
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install mes-engine
+```
+
+### Basic Usage
+
+```typescript
+import {
+  VideoProcessor,
+  FFmpegEngine,
+  FileSystemStorage
+} from 'mes-engine';
+
+// 1. Initialize Storage and Engine
+const storage = new FileSystemStorage();
+const engine = new FFmpegEngine();
+
+// 2. Setup Configuration
+const config = {
+  chunkSize: 10, // seconds
+  cacheDir: './output',
+  maxCacheSize: 1024 * 1024 * 1024, // 1GB
+  defaultQualities: [
+    { height: 720, bitrate: '2500k' },
+    { height: 1080, bitrate: '5000k' }
+  ]
+};
+
+// 3. Initialize Processor
+const processor = new VideoProcessor(engine, storage, config);
+
+// 4. Listen for Progress
+processor.on('chunk_processed', (event) => {
+  console.log(`Processed ${event.quality.height}p chunk ${event.chunkNumber}`);
+});
+
+// 5. Process Video
+const manifest = await processor.processVideo('input.mp4', {
+  title: 'My Awesome Video',
+  overallDescription: 'A high-quality adaptive stream.'
+});
+
+console.log('Master Playlist:', manifest.hls?.masterPlaylist);
+```
+
+### Examples
+- **[Simple Usage](./examples/simple-usage)**: Minimal setup to get started quickly.
+- **[Full Demo](./examples/full-demo)**: A complete React + Node.js application.
+
+## Documentation
+
+Full documentation is available in the [docs directory](./docs).
+
+### Key Topics:
+- [Adaptive Streaming (HLS)](https://github.com/Bum-Ho12/mes-engine/blob/main/docs/HLS.md)
+- [Video Engines](https://github.com/Bum-Ho12/mes-engine/blob/main/docs/engines.md)
+- [Storage Providers](https://github.com/Bum-Ho12/mes-engine/blob/main/docs/storage.md)
+- [Caching Strategies](https://github.com/Bum-Ho12/mes-engine/blob/main/docs/caching.md)
+- [API Reference](https://github.com/Bum-Ho12/mes-engine/blob/main/docs/API.md)
+
+## Supported Engines
+
+- **FFmpegEngine**: Full-featured video processing using FFmpeg
+- **GStreamerEngine**: High-performance processing using GStreamer
+- **Custom Engines**: Create your own by extending `VideoEngine`
+
+## Contributing
+
+Contributions are welcome! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.
+
+## License
+
 MIT © [Bumho Nisubire]

package/dist/index.js

@@ -1,10 +1,19 @@
 import { EventEmitter } from 'events';
 import { spawn } from 'child_process';
+import fs, { promises } from 'fs';
+import { dirname, join } from 'path';
 import { Readable } from 'stream';
-import { promises } from 'fs';
 import fetch from 'node-fetch';
-import { join } from 'path';
 
+// src/core/events.ts
+/**
+ * Options:
+ *
+ *  - CHUNK_PROCESSED
+ *  - QUALITY_PROCESSED
+ *  - PROCESSING_COMPLETE
+ *  - ERROR
+ */
 var VideoEvent;
 (function (VideoEvent) {
     VideoEvent["CHUNK_PROCESSED"] = "chunkProcessed";
@@ -13,50 +22,171 @@ var VideoEvent;
     VideoEvent["ERROR"] = "error";
 })(VideoEvent || (VideoEvent = {}));
 
-// core/VideoEngine.ts
+// src/core/VideoEngine.ts
+/**
+ * Base class for video processing engines (e.g., FFmpeg, GStreamer).
+ */
 class VideoEngine extends EventEmitter {
 }
 
-// engines/FFmpegEngine.ts
+// src/engines/FFmpegEngine.ts
+/**
+ * FFmpeg implementation of the VideoEngine.
+ * Requires `ffmpeg` and `ffprobe` to be installed on the system path.
+ */
 class FFmpegEngine extends VideoEngine {
+    /**
+     * Processes a chunk of video using FFmpeg.
+     *
+     * @param inputPath - The path to the input video file.
+     * @param outputPath - The path where the processed video chunk will be saved.
+     * @param startTime - The start time (in seconds) of the chunk to process.
+     * @param quality - The desired quality level for the output video.
+     * @returns A Promise that resolves when the chunk is processed, or rejects on error.
+     */
     async processChunk(inputPath, outputPath, startTime, quality) {
+        // Ensure output directory exists
+        await fs.promises.mkdir(dirname(outputPath), { recursive: true });
         return new Promise((resolve, reject) => {
-            const ffmpeg = spawn('ffmpeg', [
+            const args = [
                 '-i', inputPath,
                 '-ss', startTime.toString(),
                 '-t', '10',
-                '-vf', `scale=-1:${quality.height}`,
+                // Force dimensions divisible by 2 for H.264 encoding
+                // The scale filter with -2 rounds to the nearest even number
+                '-vf', `scale=-2:${quality.height}`,
                 '-c:v', 'libx264',
                 '-b:v', quality.bitrate,
                 '-c:a', 'aac',
                 '-b:a', '128k',
                 '-preset', 'fast',
+                // Use yuv420p for maximum compatibility
+                '-pix_fmt', 'yuv420p',
                 '-y',
                 outputPath
-            ]);
-            ffmpeg.on('close', code => {
-                code === 0 ? resolve() : reject(new Error(`FFmpeg error: ${code}`));
+            ];
+            const ffmpegProcess = spawn('ffmpeg', args);
+            let stderr = '';
+            ffmpegProcess.stderr.on('data', (data) => {
+                stderr += data.toString();
+            });
+            ffmpegProcess.on('error', (err) => {
+                reject(new Error(`Failed to spawn FFmpeg: ${err.message}`));
+            });
+            ffmpegProcess.on('close', (code) => {
+                if (code === 0) {
+                    resolve();
+                }
+                else {
+                    console.error('FFmpeg stderr:', stderr);
+                    reject(new Error(`FFmpeg error: ${code}\nCommand: ffmpeg ${args.join(' ')}\nStderr: ${stderr}`));
+                }
+            });
+        });
+    }
+    async extractScreenshot(inputPath, outputPath, time) {
+        // Ensure output directory exists
+        await fs.promises.mkdir(dirname(outputPath), { recursive: true });
+        return new Promise((resolve, reject) => {
+            const args = [
+                '-ss', time.toString(),
+                '-i', inputPath,
+                '-vframes', '1',
+                '-q:v', '2',
+                '-y',
+                outputPath
+            ];
+            const ffmpegProcess = spawn('ffmpeg', args);
+            let stderr = '';
+            ffmpegProcess.stderr.on('data', (data) => {
+                stderr += data.toString();
+            });
+            ffmpegProcess.on('error', (err) => {
+                reject(new Error(`Failed to spawn FFmpeg for screenshot: ${err.message}`));
+            });
+            ffmpegProcess.on('close', (code) => {
+                if (code === 0) {
+                    resolve();
+                }
+                else {
+                    console.error('FFmpeg screenshot stderr:', stderr);
+                    reject(new Error(`FFmpeg screenshot error: ${code}\nCommand: ffmpeg ${args.join(' ')}\nStderr: ${stderr}`));
+                }
             });
         });
     }
     async getDuration(inputPath) {
+        // Use ffprobe for more reliable duration detection
         return new Promise((resolve, reject) => {
-            const ffprobe = spawn('ffprobe', [
+            const ffprobeProcess = spawn('ffprobe', [
                 '-v', 'error',
                 '-show_entries', 'format=duration',
                 '-of', 'default=noprint_wrappers=1:nokey=1',
                 inputPath
             ]);
-            let output = '';
-            ffprobe.stdout.on('data', data => output += data);
-            ffprobe.on('close', code => {
-                code === 0 ? resolve(parseFloat(output)) : reject(new Error(`FFprobe error: ${code}`));
+            let stdout = '';
+            let stderr = '';
+            ffprobeProcess.stdout.on('data', (data) => {
+                stdout += data.toString();
+            });
+            ffprobeProcess.stderr.on('data', (data) => {
+                stderr += data.toString();
+            });
+            ffprobeProcess.on('error', (err) => {
+                // Fallback to buffer parsing if ffprobe not available
+                console.warn('ffprobe not available, falling back to buffer parsing');
+                this.getDurationFromBuffer(inputPath)
+                    .then(resolve)
+                    .catch(reject);
+            });
+            ffprobeProcess.on('close', (code) => {
+                if (code === 0) {
+                    const duration = parseFloat(stdout.trim());
+                    if (!isNaN(duration)) {
+                        resolve(duration);
+                    }
+                    else {
+                        reject(new Error('Could not parse duration'));
+                    }
+                }
+                else {
+                    // Fallback to buffer parsing
+                    this.getDurationFromBuffer(inputPath)
+                        .then(resolve)
+                        .catch(reject);
+                }
             });
         });
     }
+    async getDurationFromBuffer(inputPath) {
+        const buffer = await fs.promises.readFile(inputPath);
+        // Parse MP4 moov atom for duration
+        if (inputPath.endsWith('.mp4')) {
+            return this.parseMp4Duration(buffer);
+        }
+        // For other formats, extract from file metadata
+        return this.parseMediaDuration(buffer);
+    }
+    parseMp4Duration(buffer) {
+        const moovStart = buffer.indexOf(Buffer.from('moov'));
+        if (moovStart === -1)
+            return 0;
+        const mvhdStart = buffer.indexOf(Buffer.from('mvhd'), moovStart);
+        if (mvhdStart === -1)
+            return 0;
+        const timeScale = buffer.readUInt32BE(mvhdStart + 12);
+        const duration = buffer.readUInt32BE(mvhdStart + 16);
+        return duration / timeScale;
+    }
+    parseMediaDuration(buffer) {
+        // Look for duration metadata in file headers
+        const durationStr = buffer.toString('utf8', 0, Math.min(1000, buffer.length));
+        const match = durationStr.match(/duration["\s:]+(\d+\.?\d*)/i);
+        return match ? parseFloat(match[1]) : 0;
+    }
 }
 
-// streaming/StreamManager.ts
+// src/streaming/StreamManager.ts
 class StreamManager {
     constructor(storage) {
         this.storage = storage;
@@ -75,7 +205,7 @@ class StreamManager {
     }
 }
 
-// engines/GStreamerEngine.ts
+// src/engines/GStreamerEngine.ts
 class GStreamerEngine extends VideoEngine {
     async processChunk(inputPath, outputPath, startTime, quality) {
         return new Promise((resolve, reject) => {
@@ -93,6 +223,23 @@ class GStreamerEngine extends VideoEngine {
             });
         });
     }
+    async extractScreenshot(inputPath, outputPath, time) {
+        return new Promise((resolve, reject) => {
+            const gst = spawn('gst-launch-1.0', [
+                'filesrc', `location=${inputPath}`,
+                '!', 'decodebin',
+                '!', 'videoconvert',
+                '!', 'videorate',
+                '!', `video/x-raw,framerate=1/1`,
+                '!', 'videocut', `starting-time=${time * 1000000000}`,
+                '!', 'jpegenc',
+                '!', 'filesink', `location=${outputPath}`
+            ]);
+            gst.on('close', code => {
+                code === 0 ? resolve() : reject(new Error(`GStreamer screenshot error: ${code}`));
+            });
+        });
+    }
     async getDuration(inputPath) {
         return new Promise((resolve, reject) => {
             const gst = spawn('gst-launch-1.0', [
@@ -109,11 +256,14 @@ class GStreamerEngine extends VideoEngine {
     }
 }
 
-// storage/StorageProvider.ts
+// src/storage/StorageProvider.ts
+/**
+ * Interface for storage backends (e.g., Local File System, S3, Cloud Storage).
+ */
 class StorageProvider {
 }
 
-// storage/FileSystemStorage.ts
+// src/storage/FileSystemStorage.ts
 class FileSystemStorage extends StorageProvider {
     async saveChunk(chunkPath, data) {
         await promises.writeFile(chunkPath, data);
@@ -247,6 +397,10 @@ class ExternalCache extends CacheStrategy {
     }
 }
 
+/**
+ * Main orchestrator for video processing.
+ * Handles chunking, transcoding (via engines), and manifest generation.
+ */
 class VideoProcessor extends EventEmitter {
     constructor(engine, storage, config) {
         super();
@@ -254,25 +408,60 @@ class VideoProcessor extends EventEmitter {
         this.streamManager = new StreamManager(storage);
         this.config = config;
     }
-    async processVideo(inputPath) {
+    /**
+     * Processes an input video file into multiple quality levels and chunks.
+     * Generates HLS playlists and a JSON manifest.
+     *
+     * @param inputPath - Absolute path to the source video file
+     * @param options - Optional metadata and processing instructions
+     * @returns Promise resolving to the generated VideoManifest
+     * @throws Error if processing fails at any stage
+     */
+    async processVideo(inputPath, options) {
         const videoId = await this.generateVideoId(inputPath);
         const manifest = {
             videoId,
             qualities: this.config.defaultQualities,
-            chunks: []
+            chunks: [],
+            metadata: {
+                title: options?.title,
+                description: options?.overallDescription,
+                createdAt: new Date().toISOString()
+            }
         };
+        // Create base directory structure
+        const baseDir = join(this.config.cacheDir, videoId);
+        const screenshotDir = join(baseDir, 'screenshots');
+        await promises.mkdir(baseDir, { recursive: true });
+        await promises.mkdir(screenshotDir, { recursive: true });
         const duration = await this.engine.getDuration(inputPath);
         const chunks = Math.ceil(duration / this.config.chunkSize);
         for (const quality of this.config.defaultQualities) {
+            // Create quality-specific directory
+            const qualityDir = join(baseDir, `${quality.height}p`);
+            await promises.mkdir(qualityDir, { recursive: true });
+            let m3u8Content = '#EXTM3U\n#EXT-X-VERSION:3\n#EXT-X-TARGETDURATION:' + this.config.chunkSize + '\n#EXT-X-MEDIA-SEQUENCE:0\n#EXT-X-PLAYLIST-TYPE:VOD\n';
             for (let i = 0; i < chunks; i++) {
                 const chunkPath = this.getChunkPath(videoId, quality.height, i);
+                const screenshotPath = this.getScreenshotPath(videoId, i);
                 try {
+                    // Process chunk
                     await this.engine.processChunk(inputPath, chunkPath, i * this.config.chunkSize, quality);
-                    manifest.chunks.push({
+                    // Extract screenshot (only once per chunk number, e.g., for the first quality)
+                    if (quality.height === this.config.defaultQualities[0].height) {
+                        await this.engine.extractScreenshot(inputPath, screenshotPath, i * this.config.chunkSize + 1 // 1 second into the chunk
+                        );
+                    }
+                    const chunk = {
                         quality: quality.height,
                         number: i,
-                        path: chunkPath
-                    });
+                        path: chunkPath,
+                        screenshotPath: screenshotPath,
+                        description: options?.descriptions?.[i]
+                    };
+                    manifest.chunks.push(chunk);
+                    // Add to M3U8
+                    m3u8Content += `#EXTINF:${this.config.chunkSize}.0,\nchunk_${i}.mp4\n`;
                     this.emit(VideoEvent.CHUNK_PROCESSED, { quality, chunkNumber: i });
                 }
                 catch (error) {
@@ -280,11 +469,37 @@ class VideoProcessor extends EventEmitter {
                     throw error;
                 }
             }
+            m3u8Content += '#EXT-X-ENDLIST';
+            // Save M3U8 for this quality
+            const m3u8Path = join(qualityDir, 'playlist.m3u8');
+            await promises.writeFile(m3u8Path, m3u8Content);
             this.emit(VideoEvent.QUALITY_PROCESSED, quality);
         }
+        // Generate Master M3U8
+        if (this.config.defaultQualities.length > 1) {
+            let masterM3u8 = '#EXTM3U\n';
+            for (const quality of this.config.defaultQualities) {
+                masterM3u8 += `#EXT-X-STREAM-INF:BANDWIDTH=${quality.bitrate.replace('k', '000')},RESOLUTION=-1x${quality.height}\n${quality.height}p/playlist.m3u8\n`;
+            }
+            const masterPath = join(baseDir, 'master.m3u8');
+            await promises.writeFile(masterPath, masterM3u8);
+        }
+        // Save JSON Manifest
+        const manifestPath = join(baseDir, 'manifest.json');
+        await promises.writeFile(manifestPath, JSON.stringify(manifest, null, 2));
         this.emit(VideoEvent.PROCESSING_COMPLETE, manifest);
         return manifest;
     }
+    /**
+     * Creates a readable stream for a specific video chunk.
+     * Supported for on-demand delivery of processed segments.
+     *
+     * @param videoId - ID of the processed video
+     * @param quality - Target quality (height)
+     * @param chunkNumber - Sequential index of the chunk
+     * @param range - Optional byte range for partial content
+     * @returns Promise resolving to a Readable stream
+     */
     async streamChunk(videoId, quality, chunkNumber, range) {
         const chunkPath = this.getChunkPath(videoId, quality, chunkNumber);
         return this.streamManager.createStream(chunkPath, range);
@@ -292,9 +507,13 @@ class VideoProcessor extends EventEmitter {
     getChunkPath(videoId, quality, chunkNumber) {
         return join(this.config.cacheDir, videoId, `${quality}p`, `chunk_${chunkNumber}.mp4`);
     }
+    getScreenshotPath(videoId, chunkNumber) {
+        return join(this.config.cacheDir, videoId, 'screenshots', `chunk_${chunkNumber}.jpg`);
+    }
     async generateVideoId(inputPath) {
         const stats = await promises.stat(inputPath);
-        return `${inputPath.split('/').pop()?.split('.')[0]}_${stats.mtimeMs}`;
+        const fileName = inputPath.split(/[\\/]/).pop()?.split('.')[0];
+        return `${fileName}_${Math.floor(stats.mtimeMs)}`;
     }
 }