mes-engine 0.0.2 → 1.0.0

package/package.json

@@ -1,48 +1,69 @@
-{
-  "name": "mes-engine",
-  "version": "0.0.2",
-  "description": "mes-engine is a video processing engine that handles video chunking, processing and other video high density and intensive processing and caching processes.",
-  "keywords": [
-    "mes",
-    "mes-engine",
-    "video",
-    "processing",
-    "video-framework",
-    "framework"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+"
-  },
-  "license": "MIT",
-  "author": "Bumho Nisubire",
-  "main": "dist/index.js",
-  "scripts": {
-    "test": "mocha -r ts-node/register 'tests/**/*.test.ts' --timeout 10000",
-    "build": "rollup -c rollup.config.js"
-  },
-  "dependencies": {
-    "@types/node-fetch": "^2.6.12",
-    "mes-engine": "file:",
-    "node-fetch": "^3.3.2",
-    "tslib": "^2.8.1"
-  },
-  "devDependencies": {
-    "@rollup/plugin-commonjs": "^28.0.2",
-    "@rollup/plugin-node-resolve": "^16.0.0",
-    "@rollup/plugin-typescript": "^12.1.2",
-    "@types/chai": "^4.3.11",
-    "@types/jest": "^29.5.14",
-    "@types/mocha": "^10.0.6",
-    "@types/node": "^22.10.5",
-    "chai": "^4.3.10",
-    "jest": "^29.7.0",
-    "mocha": "^10.8.2",
-    "rollup": "^4.30.1",
-    "rollup-plugin-peer-deps-external": "^2.2.4",
-    "ts-jest": "^29.2.5",
-    "ts-mocha": "^10.0.0",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.3.3"
-  }
-}
+{
+  "name": "mes-engine",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "A powerful and flexible video processing framework for Node.js with support for multiple processing engines, adaptive streaming, and intelligent caching.",
+  "keywords": [
+    "mes",
+    "mes-engine",
+    "video",
+    "processing",
+    "video-framework",
+    "framework"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+"
+  },
+  "license": "MIT",
+  "author": "Bumho Nisubire",
+  "main": "dist/index.js",
+  "scripts": {
+    "test": "ts-mocha -p tsconfig.test.json tests/**/*.test.ts --timeout 10000",
+    "build": "rollup -c rollup.config.js",
+    "demo": "ts-node examples/demo.ts"
+  },
+  "dependencies": {
+    "cors": "^2.8.5",
+    "express": "^5.2.1",
+    "fluent-ffmpeg": "^2.1.3",
+    "hls.js": "^1.6.15",
+    "lucide-react": "^0.562.0",
+    "morgan": "^1.10.1",
+    "multer": "^2.0.2",
+    "node-fetch": "^2.7.0",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^28.0.2",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^16.0.0",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@types/chai": "^4.3.11",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/fluent-ffmpeg": "^2.1.28",
+    "@types/jest": "^29.5.14",
+    "@types/mocha": "^10.0.6",
+    "@types/morgan": "^1.9.10",
+    "@types/multer": "^2.0.0",
+    "@types/node": "^22.10.5",
+    "@types/node-fetch": "^2.6.12",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.2",
+    "chai": "^4.3.10",
+    "concurrently": "^9.2.1",
+    "jest": "^29.7.0",
+    "mocha": "^10.8.2",
+    "rollup": "^4.30.1",
+    "rollup-plugin-peer-deps-external": "^2.2.4",
+    "ts-jest": "^29.2.5",
+    "ts-mocha": "^10.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3",
+    "vite": "^7.3.1"
+  }
+}

package/rollup.config.js

@@ -2,6 +2,7 @@ import typescript from '@rollup/plugin-typescript';
 import { nodeResolve } from '@rollup/plugin-node-resolve';
 import commonjs from '@rollup/plugin-commonjs';
 import peerDepsExternal from 'rollup-plugin-peer-deps-external';
+import json from '@rollup/plugin-json';
 
 export default {
     input: 'src/index.ts', // Entry point
@@ -13,6 +14,7 @@ export default {
         },
     ],
     plugins: [
+        json(), // Handle JSON imports
         peerDepsExternal(), // Externalize peer dependencies
         nodeResolve(), // Resolve dependencies from node_modules
         commonjs(), // Convert CommonJS to ES6
@@ -21,4 +23,4 @@ export default {
     external: [
         'node-fetch', // Prevent bundling node-fetch
     ],
-};
+};

package/src/bandwidth.ts

@@ -1,5 +1,5 @@
+// src/bandwidth.ts
 
-// bandwidth.ts
 class BandwidthDetector {
     private samples: Array<[number, number]> = [];
     private readonly windowSize = 10000; // 10 seconds in ms

package/src/core/VideoEngine.ts

@@ -1,10 +1,18 @@
-
-// core/VideoEngine.ts
+// src/core/VideoEngine.ts
 import { EventEmitter } from 'events';
-import { VideoConfig, QualityLevel, VideoManifest } from './types';
-import { VideoEvent } from './events';
+import { QualityLevel } from './types.js';
 
+/**
+ * Base class for video processing engines (e.g., FFmpeg, GStreamer).
+ */
 export abstract class VideoEngine extends EventEmitter {
+    /**
+     * Extracts and transcodes a chunk of video.
+     * @param inputPath - Path to source video
+     * @param outputPath - Destination for the chunk
+     * @param startTime - Start offset in seconds
+     * @param quality - Target quality level
+     */
     abstract processChunk(
         inputPath: string,
         outputPath: string,
@@ -12,5 +20,22 @@ export abstract class VideoEngine extends EventEmitter {
         quality: QualityLevel
     ): Promise<void>;
 
+    /**
+     * Extracts a frame from the video as an image.
+     * @param inputPath - Path to source video
+     * @param outputPath - Destination for the image
+     * @param time - Time offset in seconds
+     */
+    abstract extractScreenshot(
+        inputPath: string,
+        outputPath: string,
+        time: number
+    ): Promise<void>;
+
+    /**
+     * Gets the total duration of the video.
+     * @param inputPath - Path to source video
+     * @returns Promise resolving to duration in seconds
+     */
     abstract getDuration(inputPath: string): Promise<number>;
 }

package/src/core/events.ts

@@ -1,4 +1,12 @@
-
+// src/core/events.ts
+/**
+ * Options:
+ * 
+ *  - CHUNK_PROCESSED
+ *  - QUALITY_PROCESSED
+ *  - PROCESSING_COMPLETE
+ *  - ERROR
+ */
 export enum VideoEvent {
     CHUNK_PROCESSED = 'chunkProcessed',
     QUALITY_PROCESSED = 'qualityProcessed',

package/src/core/types.ts

@@ -1,26 +1,61 @@
+// src/core/types.ts
 
-// core/types.ts
-
+/** Configuration for video processing engine */
 export interface VideoConfig {
+    /** Size of each video chunk in seconds */
     chunkSize: number;
+    /** Directory for temporary cache files */
     cacheDir: string;
+    /** Maximum cache size in bytes */
     maxCacheSize: number;
+    /** Default quality levels for processing */
     defaultQualities: QualityLevel[];
 }
 
+/** Definition of a video quality level */
 export interface QualityLevel {
+    /** Vertical resolution (e.g., 720, 1080) */
     height: number;
+    /** Target bitrate (e.g., "2500k") */
     bitrate: string;
 }
 
+/** Options for a specific processing job */
+export interface ProcessingOptions {
+    /** Title of the video */
+    title?: string;
+    /** Overall description of the video content */
+    overallDescription?: string;
+    /** Descriptions for individual chunks indexed by chunk number */
+    descriptions?: Record<number, string>;
+}
+
+/** Represents a processed video chunk */
 export interface VideoChunk {
+    /** Height of the quality level */
     quality: number;
+    /** Sequential index of the chunk */
     number: number;
+    /** Local path to the processed file */
     path: string;
+    /** Optional path to a screenshot for this chunk */
+    screenshotPath?: string;
+    /** Optional localized description */
+    description?: string;
 }
 
+/** Full manifest for a processed video */
 export interface VideoManifest {
+    /** Unique identifier for the video */
     videoId: string;
+    /** Available quality levels */
     qualities: QualityLevel[];
+    /** List of all processed chunks */
     chunks: VideoChunk[];
-}
+    /** Core metadata */
+    metadata: {
+        title?: string;
+        description?: string;
+        createdAt: string;
+    };
+}

package/src/engines/FFmpegEngine.ts

@@ -1,51 +1,192 @@
-
-// engines/FFmpegEngine.ts
+// src/engines/FFmpegEngine.ts
+import { VideoEngine } from '../core/VideoEngine.js';
+import { QualityLevel } from '../core/types.js';
 import { spawn } from 'child_process';
-import { VideoEngine } from '../core/VideoEngine';
-import { QualityLevel } from '../core/types';
+import fs from 'fs';
+import { dirname } from 'path';
 
+/**
+ * FFmpeg implementation of the VideoEngine.
+ * Requires `ffmpeg` and `ffprobe` to be installed on the system path.
+ */
 export 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: string,
         outputPath: string,
         startTime: number,
         quality: QualityLevel
     ): Promise<void> {
+        // Ensure output directory exists
+        await fs.promises.mkdir(dirname(outputPath), { recursive: true });
+
         return new Promise((resolve, reject) => {
-        const ffmpeg = spawn('ffmpeg', [
-            '-i', inputPath,
-            '-ss', startTime.toString(),
-            '-t', '10',
-            '-vf', `scale=-1:${quality.height}`,
-            '-c:v', 'libx264',
-            '-b:v', quality.bitrate,
-            '-c:a', 'aac',
-            '-b:a', '128k',
-            '-preset', 'fast',
-            '-y',
-            outputPath
-        ]);
-
-        ffmpeg.on('close', code => {
-            code === 0 ? resolve() : reject(new Error(`FFmpeg error: ${code}`));
+            const args = [
+                '-i', inputPath,
+                '-ss', startTime.toString(),
+                '-t', '10',
+                // 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
+            ];
+
+            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: string,
+        outputPath: string,
+        time: number
+    ): Promise<void> {
+        // 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: string): Promise<number> {
+        // Use ffprobe for more reliable duration detection
         return new Promise((resolve, reject) => {
-        const ffprobe = 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}`));
-        });
+            const ffprobeProcess = spawn('ffprobe', [
+                '-v', 'error',
+                '-show_entries', 'format=duration',
+                '-of', 'default=noprint_wrappers=1:nokey=1',
+                inputPath
+            ]);
+
+            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);
+                }
+            });
         });
     }
+
+    private async getDurationFromBuffer(inputPath: string): Promise<number> {
+        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);
+    }
+
+    private parseMp4Duration(buffer: Buffer): number {
+        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;
+    }
+
+    private parseMediaDuration(buffer: Buffer): number {
+        // 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;
+    }
 }

package/src/engines/GStreamerEngine.ts

@@ -1,4 +1,4 @@
-// engines/GStreamerEngine.ts
+// src/engines/GStreamerEngine.ts
 import { spawn } from 'child_process';
 import { VideoEngine } from '../core/VideoEngine';
 import { QualityLevel } from '../core/types';
@@ -27,6 +27,29 @@ export class GStreamerEngine extends VideoEngine {
         });
     }
 
+    async extractScreenshot(
+        inputPath: string,
+        outputPath: string,
+        time: number
+    ): Promise<void> {
+        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: string): Promise<number> {
         return new Promise((resolve, reject) => {
             const gst = spawn('gst-launch-1.0', [

package/src/index.ts

@@ -1,13 +1,13 @@
-// index.ts
-export * from './core/types';
-export * from './core/events';
-export * from './core/VideoEngine';
-export * from './engines/FFmpegEngine';
-export * from './streaming/StreamManager';
-export * from './engines/GStreamerEngine';
-export * from './storage/StorageProvider';
-export * from './storage/FileSystemStorage';
-export * from './cache/cacheStrategy';
-export * from './cache/internalCache';
-export * from './cache/ExternalCache';
-export * from './processor';
+// src/index.ts
+export * from './core/types.js';
+export * from './core/events.js';
+export * from './core/VideoEngine.js';
+export * from './engines/FFmpegEngine.js';
+export * from './streaming/StreamManager.js';
+export * from './engines/GStreamerEngine.js';
+export * from './storage/StorageProvider.js';
+export * from './storage/FileSystemStorage.js';
+export * from './cache/cacheStrategy.js';
+export * from './cache/internalCache.js';
+export * from './cache/ExternalCache.js';
+export * from './processor.js';