JavaFX YouTube Downloader

A desktop YouTube download manager built with JavaFX, yt-dlp, FFmpeg, and Apache Derby. The application supports single-video and playlist downloads, audio/video download preferences, persistent queue storage, thumbnail restoration, progress tracking, and configurable tool/database locations.

This project was built as a practical desktop application rather than a simple script. It focuses on a clean JavaFX user interface, user-configurable settings, resumable workflow state, and a packaged Windows experience.

Download

The latest Windows build is available from the Releases page.

Features

• Download individual YouTube videos by URL.
• Add YouTube playlists to the queue.
• Display video metadata such as title, uploader, duration, resolution, format, file size, thumbnail, progress, speed, ETA, and status.
• Download video with audio or extract audio only.
• Configure audio format, audio quality, and video quality.
• Select custom download, database, yt-dlp, and FFmpeg locations.
• Save and restore the download queue using an embedded Apache Derby database.
• Restore thumbnail URLs from the database when the app restarts.
• Pause active downloads and restart them later.
• Right-click queue actions such as open in browser, copy URL, download, pause, and remove.
• Clean JavaFX styling for the main window, queue table, row buttons, and preferences window.
• Designed to be packaged as both a runnable JAR and a Windows executable.

Main Window

Log Window

Preferences Window

Tech Stack

• Java
• JavaFX
• FXML
• CSS
• Apache Derby Embedded Database
• yt-dlp
• FFmpeg / FFprobe
• Jackson Databind
• Eclipse IDE

Requirements

To run from source, you need:

• JDK compatible with the JavaFX version used by the project.
• JavaFX SDK configured in Eclipse or on the command line.
• Apache Derby libraries.
• Jackson libraries.
• yt-dlp executable.
• FFmpeg and FFprobe.

For the packaged Windows version, the app can be distributed with yt-dlp.exe, ffmpeg.exe, and ffprobe.exe inside a tools folder.

Recommended packaged structure:

JavafxYoutubeDownloader/
  JavafxYoutubeDownloader.exe
  tools/
    yt-dlp.exe
    ffmpeg.exe
    ffprobe.exe

For a runnable JAR distribution:

JavafxYoutubeDownloader/
  JavafxYoutubeDownloader.jar
  tools/
    yt-dlp.exe
    ffmpeg.exe
    ffprobe.exe

How To Run From Eclipse

1. Clone or download the project.
2. Open the project in Eclipse.
3. Make sure the JavaFX SDK is configured on the build path or module path.
4. Make sure the required Derby and Jackson JARs are available on the build path.
5. Place yt-dlp.exe, ffmpeg.exe, and ffprobe.exe in the project tools folder, or configure custom paths in the Preferences window.
6. Run application.Main.

How To Run From The Command Line

The exact command depends on where JavaFX, Derby, and Jackson are installed on your machine. A typical Windows command looks like this:

java `
  --module-path "C:\path\to\javafx-sdk\lib" `
  --add-modules javafx.controls,javafx.fxml `
  -cp "bin;C:\path\to\derby\lib\*;C:\path\to\jackson\*" `
  application.Main

If running a packaged JAR, the command may look like:

java `
  --module-path "C:\path\to\javafx-sdk\lib" `
  --add-modules javafx.controls,javafx.fxml `
  -jar JavafxYoutubeDownloader.jar

If JavaFX and dependencies are bundled into the package, users can launch the generated .exe directly.

Configuring yt-dlp And FFmpeg

By default, the app expects tools to be available in the project or packaged app directory:

tools/yt-dlp.exe
tools/

If yt-dlp or FFmpeg is not detected automatically, open Preferences and select:

• tools/yt-dlp.exe
• tools/

The Preferences window allows the user to select:

• Download location
• Database location
• yt-dlp executable location
• FFmpeg location

Audio-only downloads require FFmpeg/FFprobe because yt-dlp uses FFmpeg for audio extraction and conversion.

Download Preferences

The Preferences window controls how yt-dlp commands are generated.

Video mode downloads normal video with audio. The app converts the selected video quality into a yt-dlp format selector. For example, selecting 1080p uses a selector similar to:

bestvideo[height<=1080]+bestaudio/best[height<=1080]/best

Audio Only mode uses yt-dlp audio extraction:

-x --audio-format mp3 --audio-quality 192K

The app maps user-friendly values such as 192 kbps into yt-dlp-compatible arguments such as 192K.

Persistence And Database

The app uses Apache Derby as an embedded database for persistence.

The database stores the download queue so the user can close the application and continue later. Saved queue data includes:

• URL
• Title
• Uploader
• Duration
• Resolution
• Format
• File size
• Thumbnail URL
• Status
• Progress

By default, the database is stored in the user's Downloads folder. Users can select a custom database location in Preferences. The app can also load an existing Derby database from a selected folder.

Packaging Notes

This project is intended to support both:

• Runnable JAR distribution
• Windows executable distribution

When packaging as an executable, include the tools folder beside the application so yt-dlp and FFmpeg can be found by the default settings.

Known Limitations

• The app currently targets Windows most directly, especially when packaged with .exe tools.
• macOS and Linux users may need to manually select their yt-dlp and FFmpeg paths.
• Pause works by stopping the active yt-dlp process and allowing yt-dlp to resume from partial files when restarted.
• Some videos may not expose every metadata field.
• Download behavior depends on yt-dlp and FFmpeg availability.
• Very large playlists may take time to parse and load metadata.
• Error handling is still being improved for unsupported URLs, private videos, age-restricted content, and unavailable videos.

Roadmap

• Refactor the large DownloadViewController into smaller service classes.
• Add a Preferences command preview showing the exact yt-dlp command that will be used.
• Add tool validation buttons for yt-dlp and FFmpeg.
• Add retry failed downloads.
• Add remove completed downloads.
• Add queue reordering.
• Add duplicate URL detection.
• Add automatic periodic database saves.
• Add clearer error messages for yt-dlp failures.
• Add packaged release downloads through GitHub Releases.
• Add more complete cross-platform testing.

What I Learned

This project helped me practice building a full desktop application rather than a small demo. Some of the main areas I worked on include:

• Designing JavaFX layouts with FXML and CSS.
• Building a cleaner desktop user experience with TableView controls, context menus, preferences, and status updates.
• Running external processes from Java with ProcessBuilder.
• Parsing yt-dlp JSON output with Jackson.
• Handling long-running background tasks without blocking the JavaFX UI thread.
• Persisting application state with an embedded Apache Derby database.
• Restoring queue state and thumbnails after application restart.
• Translating user-friendly preferences into real command-line arguments.
• Preparing a JavaFX project for portfolio presentation and packaging.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgements

• yt-dlp for video and audio downloading.
• FFmpeg for media processing.
• Apache Derby for embedded database persistence.
• JavaFX for the desktop UI framework.