Skip to content
Uploadista Docs

Video Nodes

Transcode, resize, trim, and extract metadata from videos.

Required Plugin

Section titled “Required Plugin”

Available Plugin

Section titled “Available Plugin”
Plugin Package Operations Requirements
videoPlugin @uploadista/flow-videos-av-node Transcode, resize, trim, thumbnail, metadata None (FFmpeg bundled)

Installation

Section titled “Installation”
npm install @uploadista/flow-videos-nodes @uploadista/flow-videos-av-node
 
import { createUploadistaServer } from "@uploadista/server";
import { videoPlugin } from "@uploadista/flow-videos-av-node";


const uploadista = await createUploadistaServer({
  // ...
  plugins: [
    videoPlugin(),
  ],
});

With Availability Check

Section titled “With Availability Check”
import { createUploadistaServer } from "@uploadista/server";
import { videoPluginWithCheck } from "@uploadista/flow-videos-av-node";


const uploadista = await createUploadistaServer({
  // ...
  plugins: [
    videoPluginWithCheck(), // Logs: "✓ node-av 4.x detected" or warning
  ],
});

Plugin Features

Section titled “Plugin Features”
  • No System Dependencies - FFmpeg binaries bundled with node-av
  • Cross-Platform - Works on Windows, macOS, and Linux
  • TypeScript Native - Full type safety
  • Memory Efficient - Automatic resource management

Supported Formats

Section titled “Supported Formats”

Input: MP4, WebM, MOV, AVI, MKV, FLV

Output: MP4 (H.264/AAC), WebM (VP9/Opus), MOV (H.264/AAC), AVI

Video Codecs: H.264, H.265/HEVC, VP9, AV1

Audio Codecs: AAC, Opus, MP3, Vorbis

Transcode Node

Section titled “Transcode Node”

Convert video to different formats and codecs.

Package: @uploadista/flow-videos-nodes

import { createTranscodeVideoNode } from "@uploadista/flow-videos-nodes";


// Convert to WebM with VP9 codec
const transcodeNode = yield* createTranscodeVideoNode("transcode-1", {
  format: "webm",
  codec: "vp9",
  videoBitrate: "1000k",
});


// Convert to MP4 with H.264 for compatibility
const mp4Node = yield* createTranscodeVideoNode("transcode-2", {
  format: "mp4",
  codec: "h264",
  videoBitrate: "2M",
  audioBitrate: "128k",
  audioCodec: "aac",
});


// With streaming mode for large files
const streamingNode = yield* createTranscodeVideoNode("transcode-3", {
  format: "mp4",
  codec: "h264",
}, {
  mode: "streaming",
  naming: { mode: "auto" },
});

Parameters

Section titled “Parameters”
Parameter Type Required Description
format "mp4" | "webm" | "mov" | "avi" Yes Output container format
codec "h264" | "h265" | "vp9" | "av1" No Video codec
videoBitrate string No Video bitrate (e.g., “1000k”, “2M”)
audioBitrate string No Audio bitrate (e.g., “128k”, “192k”)
audioCodec "aac" | "mp3" | "opus" | "vorbis" No Audio codec

Options

Section titled “Options”
Option Type Default Description
mode "auto" | "buffered" | "streaming" "auto" Processing mode
keepOutput boolean false Keep output in flow results
naming FileNamingConfig - File naming configuration
streamingConfig.fileSizeThreshold number 10000000 Threshold for auto streaming (10MB)

Resize Video Node

Section titled “Resize Video Node”

Change video resolution.

Package: @uploadista/flow-videos-nodes

import { createVideoResizeNode } from "@uploadista/flow-videos-nodes";


// Resize to 720p
const resizeNode = yield* createVideoResizeNode("resize-1", {
  width: 1280,
  height: 720,
  aspectRatio: "keep",
  scaling: "bicubic",
});


// Resize to 1080p width, auto height
const widthOnlyNode = yield* createVideoResizeNode("resize-2", {
  width: 1920,
  aspectRatio: "keep",
});


// With streaming mode
const streamingNode = yield* createVideoResizeNode("resize-3", {
  width: 1280,
  height: 720,
}, {
  mode: "streaming",
  naming: { mode: "auto" },
});

Parameters

Section titled “Parameters”
Parameter Type Required Description
width number No* Target width in pixels
height number No* Target height in pixels
aspectRatio "keep" | "ignore" No Aspect ratio handling mode
scaling "bicubic" | "bilinear" | "lanczos" No Scaling algorithm quality

*At least one of width or height must be specified.

Trim Video Node

Section titled “Trim Video Node”

Extract a segment from a video.

Package: @uploadista/flow-videos-nodes

import { createTrimVideoNode } from "@uploadista/flow-videos-nodes";


// Extract segment using endTime
const trimNode = yield* createTrimVideoNode("trim-1", {
  startTime: 10,
  endTime: 30,
});


// Extract segment using duration
const durationNode = yield* createTrimVideoNode("trim-2", {
  startTime: 10,
  duration: 20,
});


// With streaming mode for large files
const streamingNode = yield* createTrimVideoNode("trim-3", {
  startTime: 5,
  endTime: 25,
}, {
  mode: "streaming",
  naming: { mode: "auto" },
});

Parameters

Section titled “Parameters”
Parameter Type Required Description
startTime number Yes Start time in seconds
endTime number No End time in seconds
duration number No Duration in seconds (alternative to endTime)

Note: Cannot specify both endTime and duration.

Thumbnail Node

Section titled “Thumbnail Node”

Generate a preview image from the video.

Package: @uploadista/flow-videos-nodes

import { createVideoThumbnailNode } from "@uploadista/flow-videos-nodes";


// Extract frame at 15 seconds as JPEG
const thumbnailNode = yield* createVideoThumbnailNode("thumbnail-1", {
  timestamp: 15,
  format: "jpeg",
  quality: 85,
});


// Extract frame as PNG
const pngThumbNode = yield* createVideoThumbnailNode("thumbnail-2", {
  timestamp: 5,
  format: "png",
});


// With auto naming
const namedThumb = yield* createVideoThumbnailNode("thumbnail-3", {
  timestamp: 10,
  format: "jpeg",
  quality: 90,
}, {
  naming: { mode: "auto" },
});

Parameters

Section titled “Parameters”
Parameter Type Required Default Description
timestamp number Yes - Time position in seconds
format "jpeg" | "png" No "jpeg" Output image format
quality number (1-100) No - JPEG quality (only for jpeg format)

Describe Video Node

Section titled “Describe Video Node”

Extract comprehensive video metadata.

Package: @uploadista/flow-videos-nodes

import { createDescribeVideoNode } from "@uploadista/flow-videos-nodes";


// Extract video metadata
const describeNode = yield* createDescribeVideoNode("describe-1");


// With keepOutput option
const keepOutputNode = yield* createDescribeVideoNode("describe-2", {
  keepOutput: true,
});

Parameters

Section titled “Parameters”
Parameter Type Required Default Description
keepOutput boolean No false Keep output in flow results

Output Metadata:

{
  "width": 1920,
  "height": 1080,
  "duration": 120.5,
  "frameRate": 30,
  "codec": "h264",
  "bitrate": 5000000,
  "audioCodec": "aac",
  "audioChannels": 2
}

Streaming Modes

Section titled “Streaming Modes”

All video transform nodes support three processing modes:

Mode Description When to Use
auto Automatically selects streaming for files > 10MB Default, recommended
buffered Loads entire file into memory Small files, predictable memory
streaming Processes file as chunks Large files, memory-constrained

Performance

Section titled “Performance”

Video processing is computationally intensive. Approximate 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.

Error Handling

Section titled “Error Handling”

The plugin uses typed error codes:

Error Code Description
VIDEO_PROCESSING_FAILED Generic processing error
INVALID_VIDEO_FORMAT Unsupported format
CODEC_NOT_SUPPORTED Codec unavailable
VIDEO_METADATA_EXTRACTION_FAILED Cannot read metadata 
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);
  })
);
Section titled “Related”