FFmpeg video processing plugin for Uploadista Flow with 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.
- 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
``bash`
npm install @uploadista/flow-videos-av-node
No additional dependencies or system packages required - FFmpeg binaries are included with node-av.
`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))
);
`
`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 4.x detected" or warning if not found
`
- MP4 (MPEG-4)
- WebM (VP8/VP9)
- MOV (QuickTime)
- AVI (Audio Video Interleave)
- MKV (Matroska)
- FLV (Flash Video)
- MP4 (H.264/AAC) - Most compatible
- WebM (VP9/Opus) - Modern web standard
- MOV (H.264/AAC) - Apple ecosystem
- AVI (various codecs)
- H.264 (h264) - Universal compatibilityhevc
- H.265/HEVC () - Better compressionvp9
- VP9 () - Open-source, good for webav1
- AV1 () - Next-gen, best compression
- AAC - Standard for MP4
- Opus - Modern, efficient
- MP3 - Legacy compatibility
- Vorbis - WebM standard
The plugin uses typed UploadistaError codes:
- VIDEO_PROCESSING_FAILED - Generic processing errorINVALID_VIDEO_FORMAT
- - Unsupported formatCODEC_NOT_SUPPORTED
- - Codec unavailableVIDEO_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);
})
);
`
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.
- 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
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
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
Error: Cannot find module 'node-av'
Solution: Ensure node-av is installed:
`bash`
npm install node-av
Error: TypeScript compilation errors
Solution: node-av requires modern TypeScript features. Ensure you're using TypeScript 5.2+:
`bash``
npm install -D typescript@latest
| 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.
MIT