elizaos--eliza/plugins/plugin-video

@elizaos/plugin-video

Video download, processing, and transcription plugin for elizaOS agents.

What it does

This plugin adds a VideoService to any Eliza agent's service registry. Once loaded, other plugins and actions can call runtime.getService<IVideoService>(ServiceType.VIDEO) to:

• Download video from YouTube, Vimeo, or any direct MP4 URL.
• Extract audio from a video file (MP4 → MP3 via ffmpeg).
• Generate thumbnails from a specific timestamp.
• Convert video to a different format, resolution, bitrate, codec, or time range.
• Fetch available formats for a URL via yt-dlp.
• Process a video URL end-to-end into a Media object with title, description, source, and a full transcript. Transcription priority:
  1. Manual subtitles (SRT), if available.
  2. Automatic captions, if available.
  3. Audio transcription via ServiceType.TRANSCRIPTION (requires a loaded plugin that registers an ITranscriptionService).

Results are cached under ./content_cache/ by content hash. yt-dlp is automatically kept up to date: on known extractor failures the plugin re-downloads the latest yt-dlp release from GitHub and retries.

Enabling the plugin

Add @elizaos/plugin-video to the agent's plugin list in its character file or runtime configuration:

{
  "plugins": ["@elizaos/plugin-video"]
}

Usage

import { IVideoService, ServiceType } from "@elizaos/core";

// Inside an action or provider handler:
const videoService = runtime.getService<IVideoService>(ServiceType.VIDEO);
if (!videoService) throw new Error("plugin-video not loaded");

// Fetch full transcript + metadata:
const media = await videoService.processVideo("https://www.youtube.com/watch?v=...", runtime);
// media.text contains the transcript
// media.title, media.source, media.description have metadata

// Download only:
const filePath = await videoService.downloadVideo("https://www.youtube.com/watch?v=...");

// Extract audio from a local file:
const mp3Path = await videoService.extractAudio("/path/to/video.mp4");

Required environment variables

None are required. The plugin resolves binaries automatically.

Variable	Purpose	Default
ELIZA_YT_DLP_PATH	Path to a specific yt-dlp binary	Auto-resolved
ELIZA_YT_DLP_PREFER_PATH	1 to prefer system yt-dlp over the managed cache	0
ELIZA_DISABLE_YTDLP_AUTOUPDATE	1 to disable automatic yt-dlp updates on failure	0
ELIZA_FFMPEG_PATH	Path to a specific ffmpeg binary	Auto-resolved
ELIZA_NODE_BIN / NODE_BINARY	Node executable used when running the bundled ffmpeg installer from non-Node runtimes	node
ELIZA_BINARIES_DIR	Directory where managed yt-dlp is cached	<stateDir>/binaries

System dependencies

• ffmpeg — required for audio extraction, thumbnail generation, and video conversion. Resolved from ELIZA_FFMPEG_PATH, then system PATH, then the bundled ffmpeg-static npm package; if the static package is present without its downloaded binary, the plugin runs its installer once.
• yt-dlp — required for YouTube/Vimeo downloads and subtitle extraction. Resolved from ELIZA_YT_DLP_PATH, system PATH, or automatically downloaded and cached from GitHub releases.
• Transcription service — needed only for the audio-transcription fallback path. Any plugin that registers an ITranscriptionService under ServiceType.TRANSCRIPTION will work.