@elizaos/plugin-video 2.0.0-beta.1 → 2.0.3-beta.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+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

@@ -1,31 +1,68 @@
-# @elizaos/plugin-video Video Service
-
-The VideoService provides comprehensive video processing capabilities with a focus on efficient handling and transcription:
-
-**Key Features:**
-- **Video Download**: Supports both YouTube videos and direct MP4 URLs
-- **Format Handling**: 
-  - Automatic format detection and conversion
-  - MP4 to MP3 conversion for audio processing
-  - Support for various video platforms (YouTube, Vimeo)
-- **Transcription Pipeline**:
-  1. Attempts to extract manual subtitles (SRT format)
-  2. Falls back to automatic captions if available
-  3. Uses audio transcription as final fallback
-- **Performance Optimizations**:
-  - Queue-based processing for multiple videos
-  - Built-in caching system for processed results
-  - Efficient temporary file management
-- **Error Handling**:
-  - Graceful fallbacks for different transcription methods
-  - Comprehensive error reporting
-  - Automatic cleanup of temporary files
-
-**Usage Example:**
+# @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:
+
+```json
+{
+  "plugins": ["@elizaos/plugin-video"]
+}
+```
+
+## Usage
+
 ```typescript
+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
 
-// Process a video URL
-const result = await videoService.processVideo(videoUrl, runtime);
-// Returns: Media object with id, url, title, source, description, and transcript
+// 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_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.
+- **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.

package/build.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env bun
+import { rmSync } from "node:fs";
+import { $ } from "bun";
+import { externalsFromPackageJson } from "../plugin-build-externals.ts";
+
+const external = await externalsFromPackageJson("./package.json", {
+  extra: ["node:*", "bun:*"],
+});
+
+console.log("🔨 Building @elizaos/plugin-video...");
+const start = Date.now();
+
+rmSync("dist", { recursive: true, force: true });
+
+const result = await Bun.build({
+  entrypoints: ["src/index.ts"],
+  outdir: "dist",
+  target: "node",
+  format: "esm",
+  sourcemap: "external",
+  external,
+  minify: false,
+});
+
+if (!result.success) {
+  for (const log of result.logs) {
+    console.error(log);
+  }
+  process.exit(1);
+}
+
+console.log("📝 Generating TypeScript declarations...");
+await $`tsc --emitDeclarationOnly --declaration --declarationDir dist --noCheck -p tsconfig.json`.quiet();
+
+console.log(
+  `✅ Build complete in ${((Date.now() - start) / 1000).toFixed(2)}s`,
+);

package/dist/index.d.ts

@@ -1,5 +1,3 @@
-import { Plugin } from '@elizaos/core';
-
+import type { Plugin } from "@elizaos/core";
 declare const videoPlugin: Plugin;
-
-export { videoPlugin as default };
+export default videoPlugin;