@uploadista/flow-videos-av-node 0.0.13-beta.1

package/.turbo/turbo-build.log

@@ -0,0 +1,16 @@
+
+
+> @uploadista/flow-videos-av-node@0.0.12 build /Users/denislaboureyras/Documents/uploadista/dev/uploadista-workspace/uploadista-sdk/packages/flow/videos/av-node
+> tsdown
+
+ℹ tsdown v0.16.0 powered by rolldown v1.0.0-beta.46
+ℹ entry: src/index.ts
+ℹ tsconfig: tsconfig.json
+ℹ Build start
+ℹ Cleaning 4 files
+ℹ dist/index.mjs        17.17 kB │ gzip: 3.52 kB
+ℹ dist/index.mjs.map    33.87 kB │ gzip: 6.59 kB
+ℹ dist/index.d.mts.map   0.88 kB │ gzip: 0.46 kB
+ℹ dist/index.d.mts       3.37 kB │ gzip: 1.04 kB
+ℹ 4 files, total: 55.28 kB
+✔ Build complete in 10244ms

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 uploadista
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+# @uploadista/flow-videos-av-node
+
+Modern FFmpeg-based video processing plugin for Uploadista Flow using node-av. Provides video transcoding, resizing, trimming, thumbnail generation, and metadata extraction with native FFmpeg bindings.
+
+## Features
+
+- **No System Dependencies**: node-av includes prebuilt FFmpeg binaries - no system installation required
+- **TypeScript Native**: Full type safety with modern TypeScript support
+- **Modern API**: Uses native async/await and AsyncIterators
+- **Memory Efficient**: Automatic resource management with `using` declarations
+- **Cross-Platform**: Works on Windows, macOS, and Linux out of the box
+
+## Installation
+
+```bash
+npm install @uploadista/flow-videos-av-node
+```
+
+No additional dependencies or system packages required - FFmpeg binaries are included with node-av.
+
+## Usage
+
+### Provide the Plugin Layer
+
+```typescript
+import { AVNodeVideoPluginLive } from "@uploadista/flow-videos-av-node";
+import { Effect } from "effect";
+
+// Provide the node-av plugin to your flow execution
+const result = await Effect.runPromise(
+  flowProgram.pipe(Effect.provide(AVNodeVideoPluginLive))
+);
+```
+
+### With Availability Check
+
+```typescript
+import { AVNodeVideoPluginWithCheck } from "@uploadista/flow-videos-av-node";
+
+// Checks node-av availability on initialization
+const result = await Effect.runPromise(
+  flowProgram.pipe(Effect.provide(AVNodeVideoPluginWithCheck))
+);
+// Logs: "✓ node-av 3.x detected" or warning if not found
+```
+
+## Supported Formats
+
+### Input Formats
+
+- MP4 (MPEG-4)
+- WebM (VP8/VP9)
+- MOV (QuickTime)
+- AVI (Audio Video Interleave)
+- MKV (Matroska)
+- FLV (Flash Video)
+
+### Output Formats
+
+- MP4 (H.264/AAC) - Most compatible
+- WebM (VP9/Opus) - Modern web standard
+- MOV (H.264/AAC) - Apple ecosystem
+- AVI (various codecs)
+
+### Video Codecs
+
+- **H.264** (`h264`) - Universal compatibility
+- **H.265/HEVC** (`hevc`) - Better compression
+- **VP9** (`vp9`) - Open-source, good for web
+- **AV1** (`av1`) - Next-gen, best compression
+
+### Audio Codecs
+
+- **AAC** - Standard for MP4
+- **Opus** - Modern, efficient
+- **MP3** - Legacy compatibility
+- **Vorbis** - WebM standard
+
+## Error Handling
+
+The plugin uses typed UploadistaError codes:
+
+- `VIDEO_PROCESSING_FAILED` - Generic processing error
+- `INVALID_VIDEO_FORMAT` - Unsupported format
+- `CODEC_NOT_SUPPORTED` - Codec unavailable
+- `VIDEO_METADATA_EXTRACTION_FAILED` - Cannot read metadata
+
+```typescript
+import { Effect } from "effect";
+import { UploadistaError } from "@uploadista/core/errors";
+
+const program = Effect.gen(function* () {
+  const videoPlugin = yield* VideoPlugin;
+  const result = yield* videoPlugin.transcode(videoBytes, {
+    format: "webm",
+    codec: "vp9",
+  });
+  return result;
+}).pipe(
+  Effect.catchTag("UploadistaError", (error) => {
+    if (error.code === "VIDEO_PROCESSING_FAILED") {
+      console.error("Video processing failed:", error.message);
+    }
+    return Effect.fail(error);
+  })
+);
+```
+
+## Performance Considerations
+
+Video processing is computationally intensive. Approximate processing times (on modern CPU):
+
+| Operation                | 1 min video | 5 min video |
+| ------------------------ | ----------- | ----------- |
+| Transcode H.264 → WebM   | ~30s        | ~2.5m       |
+| Resize 1080p → 720p      | ~15s        | ~1.5m       |
+| Thumbnail extraction     | ~2s         | ~2s         |
+| Metadata extraction      | <1s         | <1s         |
+| Trim (with re-encode)    | ~10s        | ~50s        |
+
+Times vary based on video complexity, codec settings, and hardware.
+
+## Advantages over fluent-ffmpeg
+
+- **Modern**: node-av is actively maintained with TypeScript support
+- **No System Dependencies**: Includes prebuilt FFmpeg binaries
+- **Type Safe**: Full TypeScript definitions and modern API
+- **Memory Efficient**: Better resource management with automatic cleanup
+- **Performance**: Direct FFmpeg bindings without wrapper overhead
+
+## Current Limitations
+
+This is an initial implementation focusing on core functionality:
+
+- **Resize Quality**: Currently uses encoder-based resizing. For production use, consider adding FilterAPI support for better quality scaling
+- **Frame Extraction**: Extracts frames as MJPEG or PNG. Additional format support can be added
+- **Hardware Acceleration**: Not yet implemented, but node-av supports it via HardwareContext
+
+## Roadmap
+
+Future improvements planned:
+
+1. **FilterAPI Integration**: Add support for high-quality video filters (scale, crop, overlay, etc.)
+2. **Hardware Acceleration**: GPU-accelerated encoding/decoding support
+3. **Additional Formats**: Support for more image formats in frame extraction
+4. **Stream Processing**: Direct stream input/output without temporary files
+5. **Progress Callbacks**: Real-time progress reporting for long operations
+
+## Troubleshooting
+
+### Import Error
+
+**Error**: Cannot find module 'node-av'
+
+**Solution**: Ensure node-av is installed:
+
+```bash
+npm install node-av
+```
+
+### TypeScript Errors
+
+**Error**: TypeScript compilation errors
+
+**Solution**: node-av requires modern TypeScript features. Ensure you're using TypeScript 5.2+:
+
+```bash
+npm install -D typescript@latest
+```
+
+## Comparison with @uploadista/flow-videos-ffmpeg
+
+| Feature | av-node (this package) | ffmpeg (fluent-ffmpeg) |
+|---------|----------------------|------------------------|
+| System Dependencies | ❌ None (bundled) | ✅ Requires FFmpeg install |
+| Maintenance | ✅ Active | ⚠️ Deprecated |
+| TypeScript Support | ✅ Native | ⚠️ Via @types |
+| API Style | ✅ Modern async/await | ⚠️ Callback-based |
+| Memory Management | ✅ Automatic | ⚠️ Manual |
+| Performance | ✅ Direct bindings | ⚠️ CLI wrapper |
+
+**Recommendation**: Use this package (@uploadista/flow-videos-av-node) for new projects. The fluent-ffmpeg package is deprecated and unmaintained.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,99 @@
+import { FFEncoderCodec } from "node-av/constants";
+import { Layer } from "effect";
+import { TranscodeParams, VideoPlugin, VideoPluginShape } from "@uploadista/core/flow";
+
+//#region src/utils/av-check.d.ts
+/**
+ * Result of node-av availability check
+ */
+type AVCheckResult = {
+  available: boolean;
+  version?: string;
+  error?: string;
+};
+/**
+ * Checks if node-av is available and can access FFmpeg binaries
+ * @returns Promise with availability status and version info
+ */
+declare function checkAVAvailable(): Promise<AVCheckResult>;
+//#endregion
+//#region src/utils/format-mappings.d.ts
+/**
+ * Maps video format to MIME type
+ */
+declare const formatToMimeType: Record<TranscodeParams["format"], string>;
+/**
+ * Maps video format to file extension
+ */
+declare const formatToExtension: Record<TranscodeParams["format"], string>;
+/**
+ * Maps codec parameter to node-av codec constant
+ */
+declare const codecToAVName: Record<NonNullable<TranscodeParams["codec"]>, FFEncoderCodec>;
+/**
+ * Maps audio codec parameter to node-av audio codec constant
+ */
+declare const audioCodecToAVName: Record<NonNullable<TranscodeParams["audioCodec"]>, FFEncoderCodec>;
+/**
+ * Maps image format to encoder constant
+ */
+declare const imageFormatToEncoder: Record<string, FFEncoderCodec>;
+//#endregion
+//#region src/video-plugin.d.ts
+/**
+ * Creates a node-av based video processing plugin
+ */
+declare function createAVNodeVideoPlugin(): VideoPluginShape;
+//#endregion
+//#region src/video-plugin-layer.d.ts
+/**
+ * Effect Layer for the node-av video plugin
+ *
+ * This layer provides video processing capabilities using node-av (FFmpeg bindings).
+ * Note: node-av includes prebuilt FFmpeg binaries, so no system installation is required.
+ *
+ * @example
+ * ```typescript
+ * import { AVNodeVideoPlugin } from "@uploadista/flow-videos-av-node";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const videoPlugin = yield* VideoPlugin;
+ *   const metadata = yield* videoPlugin.describe(videoBytes);
+ *   return metadata;
+ * });
+ *
+ * // Run with node-av plugin layer
+ * const result = await Effect.runPromise(
+ *   program.pipe(Effect.provide(AVNodeVideoPluginLive))
+ * );
+ * ```
+ */
+declare const AVNodeVideoPlugin: Layer.Layer<VideoPlugin, never, never>;
+/**
+ * Effect Layer for the node-av video plugin with availability check
+ *
+ * This layer checks if node-av is properly installed and logs status information.
+ * The plugin will still be created, but operations will fail if node-av is not available.
+ *
+ * @example
+ * ```typescript
+ * import { AVNodeVideoPluginWithCheck } from "@uploadista/flow-videos-av-node";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const videoPlugin = yield* VideoPlugin;
+ *   const metadata = yield* videoPlugin.describe(videoBytes);
+ *   return metadata;
+ * });
+ *
+ * // Run with node-av plugin layer (with check)
+ * const result = await Effect.runPromise(
+ *   program.pipe(Effect.provide(AVNodeVideoPluginWithCheck))
+ * );
+ * ```
+ */
+declare const AVNodeVideoPluginWithCheck: Layer.Layer<VideoPlugin, never, never>;
+//#endregion
+export { AVCheckResult, AVNodeVideoPlugin, AVNodeVideoPluginWithCheck, audioCodecToAVName, checkAVAvailable, codecToAVName, createAVNodeVideoPlugin, formatToExtension, formatToMimeType, imageFormatToEncoder };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/utils/av-check.ts","../src/utils/format-mappings.ts","../src/video-plugin.ts","../src/video-plugin-layer.ts"],"sourcesContent":[],"mappings":";;;;;;;;KAGY,aAAA;;EAAA,OAAA,CAAA,EAAA,MAAa;EAUH,KAAA,CAAA,EAAA,MAAA;;;;ACKtB;AAUA;AAUa,iBDzBS,gBAAA,CAAA,CCiCrB,EDjCyC,OCiCzC,CDjCiD,aCiCjD,CAAA;;;;;;AD3CW,cCeC,gBDfY,ECeM,MDfN,CCea,eDfb,CAAA,QAAA,CAAA,EAAA,MAAA,CAAA;AAUzB;;;cCea,mBAAmB,OAAO;AAVvC;AAUA;AAUA;AACc,cADD,aACC,EADc,MACd,CAAZ,WAAY,CAAA,eAAA,CAAA,OAAA,CAAA,CAAA,EACZ,cADY,CAAA;;;;AADoB,cAarB,kBAbqB,EAaD,MAbC,CAchC,WAdgC,CAcpB,eAdoB,CAAA,YAAA,CAAA,CAAA,EAehC,cAfgC,CAAA;AAalC;;;AAEE,cAWW,oBAXX,EAWiC,MAXjC,CAAA,MAAA,EAWgD,cAXhD,CAAA;;;;;;iBC9Bc,uBAAA,CAAA,GAA2B;;;;;;AFpB3C;AAUA;;;;ACKA;AAUA;AAUA;;;;;;AAaA;;;;;;AAaA;cEpCa,mBAAiB,KAAA,CAAA,MAAA;;;ADL9B;;;;ACKA;AA4BA;;;;;;;;;;;;;;;;cAAa,4BAA0B,KAAA,CAAA,MAAA"}