ytdlp-java

Java library wrapping yt-dlp via GraalVM Polyglot (GraalPy), with an optional Spring Boot starter and an embedded React 19 web UI.

GroupId: dev.leimuhue Package: dev.leimuhue.ytdlp Java: 17+

Prerequisites

• Java 17+ — Required
• Maven 3.8+ — Required
• ffmpeg — Required (yt-dlp uses it for video/audio processing and muxing)
• yt-dlp — Required for CLI fallback mode; for GraalPy mode, see below
• Node.js 22+ — Optional (only needed for frontend development)

Execution Strategy

The engine uses a hybrid approach:

1. GraalPy Python module (preferred) — calls yt_dlp directly via the GraalPy polyglot context
2. CLI fallback (automatic) — invokes yt-dlp via ProcessBuilder if the Python module is unavailable

For GraalPy mode, run the plugin manually to install yt-dlp in the bundled Python venv:

mvn graalpy:process-graalpy-resources -pl ytdlp-engine

Module Structure

ytdlp-java/
├── pom.xml                              Root multi-module POM
├── ytdlp-engine/                        Core library (53 tests)
│   └── src/main/java/dev/leimuhue/ytdlp/
│       ├── YtdlpEngine.java             Central entry point
│       ├── YtdlpOptions.java            Fluent options builder
│       ├── model/                       Typed response models
│       │   ├── VideoInfo.java
│       │   ├── FormatInfo.java
│       │   ├── DownloadResult.java
│       │   └── PlaylistInfo.java
│       ├── exception/                   Exception hierarchy
│       │   ├── YtdlpException.java
│       │   ├── YtdlpExecutionException.java
│       │   ├── YtdlpTimeoutException.java
│       │   └── YtdlpEnvironmentException.java
│       └── internal/
│           ├── PythonBridge.java        GraalPy integration
│           └── CliFallback.java         CLI via ProcessBuilder
├── ytdlp-engine-spring-boot-starter/    Spring Boot auto-config (4 tests)
│   └── src/main/java/dev/leimuhue/ytdlp/spring/
│       ├── YtdlpProperties.java         @ConfigurationProperties
│       └── YtdlpAutoConfiguration.java  @AutoConfiguration
└── ytdlp-engine-web/                    Web UI + REST API
    ├── frontend/                        React 19 source (Vite)
    └── src/main/java/dev/leimuhue/ytdlp/web/
        └── YtdlpController.java         REST endpoints

Build

mvn clean install

To build without running tests:

mvn clean install -DskipTests

Core Library Usage

YtdlpEngine engine = YtdlpEngine.builder()
        .defaultOptions(YtdlpOptions.create().output("/tmp/%(title)s.%(ext)s"))
        .build();

// Extract metadata
VideoInfo info = engine.extractInfo("https://youtube.com/watch?v=xxx");

// Download with per-call overrides
DownloadResult result = engine.download("https://youtube.com/watch?v=xxx",
    YtdlpOptions.create().format("bestvideo[height<=1080]+bestaudio"));

// List formats
List<FormatInfo> formats = engine.listFormats("https://youtube.com/watch?v=xxx");

// Search
List<VideoInfo> results = engine.search("query", 10);

engine.close();

Web UI

mvn spring-boot:run -pl ytdlp-engine-web

Open http://localhost:8080 — paste a video URL, click Extract to see metadata and formats, select a format and click Download.

Frontend Dev Mode

cd ytdlp-engine-web/frontend
npm run dev

Open http://localhost:3000 with hot reload. API calls proxy to localhost:8080.

Spring Boot Configuration

ytdlp:
  enabled: true
  default-output: /downloads/%(title)s.%(ext)s
  timeout: 300
  allow-create-process: true
  allow-io: true

Quick Start

1. Install dependencies: Java 17+, Maven 3.8+, ffmpeg
2. Build: mvn clean install
3. Run: mvn spring-boot:run -pl ytdlp-engine-web
4. Open http://localhost:8080