java-youtube-downloader

Simple java parser for retrieving youtube video metadata.

Library is not stable, because Youtube often changes web structure of its pages. I don't use this library regularly to find the errors. Thats why errors are fixed as soon as someone finds it and opens an issue. Feel free to report an error or sumbit a PR.

WARNING: Youtube API does not support a video download. In fact, it is prohibited - Terms of Service - II. Prohibitions.
WARNING: Downloading videos may violate copyrights!

This project is only for educational purposes. I urge not to use this project to violate any laws.

Usage

// init downloader
YoutubeDownloader downloader = new YoutubeDownloader();

// you can easly implement or extend default parsing logic 
YoutubeDownloader downloader = new YoutubeDownloader(new Parser()); 
// downloader configurations
downloader.setParserRequestProperty("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.121 Safari/537.36");
downloader.setParserRetryOnFailure(1);

// parsing data
String videoId = "abc12345"; // for url https://www.youtube.com/watch?v=abc12345
YoutubeVideo video = downloader.getVideo(videoId);

// video details
VideoDetails details = video.details();
System.out.println(details.title());
...
System.out.println(details.viewCount());
details.thumbnails().forEach(image -> System.out.println("Thumbnail: " + image));

// get videos with audio
List<AudioVideoFormat> videoWithAudioFormats = video.videoWithAudioFormats();
videoWithAudioFormats.forEach(it -> {
    System.out.println(it.audioQuality() + " : " + it.url());
});

// filtering only video formats
List<VideoFormat> videoFormats = video.findVideoWithQuality(VideoQuality.hd720);
videoFormats.forEach(it -> {
    System.out.println(it.videoQuality() + " : " + it.url());
});

// itags can be found here - https://gist.github.com/sidneys/7095afe4da4ae58694d128b1034e01e2
Format formatByItag = video.findFormatByItag(136); 
if (formatByItag != null) {
    System.out.println(formatByItag.url());
}

File outputDir = new File("my_videos");
Format format = videoFormats.get(0);

// sync downloading
File file = video.download(format, outputDir);

// async downloading with callback
Future<File> future = video.downloadAsync(videoFormats.get(0), outputDir, new OnYoutubeDownloadListener() {
    @Override
    public void onDownloading(int progress) {
        System.out.printf("Downloaded %d%%\n", progress);
    }
            
    @Override
    public void onFinished(File file) {
        System.out.println("Finished file: " + file);
    }

    @Override
    public void onError(Throwable throwable) {
        System.out.println("Error: " + throwable.getLocalizedMessage());
    }
});

// async downloading without callback
Future<File> future = video.downloadAsync(format, outputDir);
File file = future.get(5, TimeUnit.SECONDS);

// cancel downloading
future.cancel(true); // true is required to interrupt downloading thread

// live videos and streams
if (video.details().isLive()) {
    System.out.println("Live Stream HLS URL: " + video.details().liveUrl());
}

// naming
// by default file name will be same as video title on youtube, 
// but you can specify output file name
File myAwesomeFile = video.download(format, outputDir, "myAwesomeName");
System.out.println(file.getName()); // myAwesomeName.mp4
// if file with such name already exits sufix will be added myAwesomeFile(1).mp4
// you may disable this feature by passing overwrite flag
File myAwesomeFile = video.download(format, outputDir, "myAwesomeName", true);

// subtitles
// you can get subtitles from video captions if you have already parsed video meta
List<SubtitlesInfo> subtitles = video.subtitles(); // NOTE: includes auto-generated
// if you don't need video meta, but just subtitles use this instead
List<SubtitlesInfo> subtitles = downloader.getVideoSubtitles(videoId); // NOTE: does not include auto-generated

for (SubtitlesInfo info : subtitles) {
    Subtitles subtitles = info.getSubtitles()
             .formatTo(Extension.JSON3)
             .translateTo("uk"); // // NOTE: subtitle translation supported only for "subtitles from captions"
        // sync download
    String subtitlesData = subtitles.download();
    // async download
    Future<String> subtitlesFuture = subtitles.downloadAsync(callback/*optional*/);
    // to download using external download manager
    String downloadUrl = subtitles.getDownloadUrl(); 
}

// playlists

// parsing data
String playlistId = "abc12345"; // for url https://www.youtube.com/playlist?list=abc12345
YoutubePlaylist playlist = downloader.getPlaylist(playlistId);

// playlist details
PlaylistDetails details = playlist.details();
System.out.println(details.title());
...
System.out.println(details.videoCount());

// get video details
PlaylistVideoDetails videoDetails = playlist.videos().get(0);
System.out.println(videoDetails.title());
...
System.out.println(videoDetails.index());

// get video
YoutubeVideo video = downloader.getVideo(videoDetails.videoId());

Include

Maven

<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>

<dependency>
  <groupId>com.github.sealedtx</groupId>
  <artifactId>java-youtube-downloader</artifactId>
  <version>2.5.2</version>
</dependency>

Gradle

allprojects {
  repositories {
    ...
    maven { url 'https://jitpack.io' }
  }
}

dependencies {
  implementation 'com.github.sealedtx:java-youtube-downloader:2.5.2'
}

Android

android {
  ...
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
  // For Kotlin projects
  kotlinOptions {
    jvmTarget = "1.8"
  }
}