Video Nodes

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

Required Plugin

Plugin Required

Video processing nodes require a plugin to execute. You must install and provide the video plugin.

Available Plugin

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

Installation

npm

npm install @uploadista/flow-videos-nodes @uploadista/flow-videos-av-node

pnpm

pnpm add @uploadista/flow-videos-nodes @uploadista/flow-videos-av-node

yarn

yarn add @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

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

• 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

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

Convert video to different formats and codecs.

Requires Plugin

VideoPlugin - Use @uploadista/flow-videos-av-node

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

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

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

Change video resolution.

Requires Plugin

VideoPlugin - Use @uploadista/flow-videos-av-node

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

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

Extract a segment from a video.

Requires Plugin

VideoPlugin - Use @uploadista/flow-videos-av-node

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

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

Generate a preview image from the video.

Requires Plugin

VideoPlugin - Use @uploadista/flow-videos-av-node

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

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

Extract comprehensive video metadata.

Requires Plugin

VideoPlugin - Use @uploadista/flow-videos-av-node

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

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

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

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

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);
  })
);

---

Related

• Plugins Concept - How plugins work
• Flow Nodes Overview - All available nodes