- The Youtube Channel Downloader
- Configuration
To get started, you will need to download the Project, and install the required Dependencies.
Simply download the latest project files from Github.
Then extract the files to a location of your choice.
Alternatively you can clone the repository with Git using:
git clone "https://github.com/ZGorlock/YoutubeDownloader.git"
To run this project you will need to have the following dependencies installed:
Dependency | Minimum Version | Website | Windows | Linux |
---|---|---|---|---|
Java | 13.0.2 |
jdk.java.net | openjdk-13.0.2_windows-x64_bin.zip | openjdk-13.0.2_linux-x64_bin.tar.gz |
Maven | 3.8.7 |
maven.apache.org | apache-maven-3.8.7-bin.zip | apache-maven-3.8.7-bin.tar.gz |
FFmpeg | recommended | ffmpeg.org | ffmpeg-master-latest-win64-gpl.zip | ffmpeg-master-latest-linux64-gpl.tar.xz |
Git | optional | git-scm.com | Git-2.40.0-64-bit.exe | git-2.40.0.tar.gz |
If you do not already have these dependencies installed then download the packages for your operating system.
Then extract the packages to a location of your choice.
Add the /bin
folder of each dependency to your Path
environment variable so they are accessible on the system path.
You can verify that they are installed properly by executing the following commands and checking the versions:
java --version
mvn -v
ffmpeg -version
git --version
This project contains two programs:
The project can be run by using the scripts provided in the project directory:
-
YoutubeDownloader.bat
🗋 -
YoutubeChannelDownloader.bat
🗋 -
YoutubeDownloader.sh
🗋 -
YoutubeChannelDownloader.sh
🗋
Depending on your operating system use either the .bat scripts (Windows) or the .sh scripts (Linux):
On Windows:
YoutubeDownloader.bat
YoutubeChannelDownloader.bat
On Linux:
./YoutubeDownloader.sh
./YoutubeChannelDownloader.sh
Alternatively you can run the project with Maven using:
mvn compile && mvn exec:java -Dexec.mainClass="youtube.YoutubeDownloader"
mvn compile && mvn exec:java -Dexec.mainClass="youtube.YoutubeChannelDownloader"
Also, if you prefer, you could always run or debug the project in an IDE.
You can configure this project to use either yt-dlp or youtube-dl.
- yt-dlp
- A newer drop-in replacement of the Youtube Downloader executable
- Actively maintained by new developers
- Includes additional features
- youtube-dl
- The original Youtube Downloader executable
- As of the time of writing this it appears it may no longer be maintained
- Throttling and failures often occur when downloading videos
Specify your choice of executable in the project configuration as explained under:
The project will automatically download the executable that you choose.
At the beginning of each run it will check for updates to the executable and download the latest version if needed.
This project should work as it does now indefinitely, as long as yt-dlp and youtube-dl continue to exist on the same websites they do now.
However, additional improvements and features may be added from time to time.
If you wish to receive these updates then you can download the latest project files from Github.
More information about the download process is provided under: Downloading the Project.
If you cloned the repository with Git then you can update to the latest code using:
git pull origin master
This program is just a simple Youtube video downloader.
It will download the videos from the Youtube urls entered into the console while the program is running.
Videos will be saved in a ~/Youtube
folder in your user directory.
This can be customized by defining location.outputDir in the Youtube Downloader Configuration.
You can also create a list of Youtube urls in the file data/downloadQueue.txt
and when the program is executed it will download the provided list of videos.
The program will continue to run until an empty line in entered: Enter
.
You can customize the operation of the Youtube Downloader by changing the settings inside the file conf.json
🗋.
To configure the Youtube Downloader, find or create the "YoutubeDownloader"
json configuration and customize the Settings it contains.
SETTING | DESCRIPTION |
---|---|
location | The location settings for the Youtube Downloader : |
location.outputDir | The path of the directory where downloaded content will be saved. For example: "C:/Users/User/Downloads" . By leaving this blank ( "" or null ), content will be saved in a ~/Youtube folder in your user directory. |
location.browser | The name of the browser that you use locally to watch Youtube. This is the browser that cookies will be used from when attempting to retry certain failed downloads, assuming that flag.neverUseBrowserCookies is disabled. The acceptable values for this setting are "Brave" , "Chrome" , "Chromium" , "Edge" , "Firefox" , "Opera" , "Safari" , or "Vivaldi" . |
process | The process settings for the Youtube Downloader : |
process.asAudio | When this setting is enabled, the Youtube Downloader will download content as audio files instead of video files. When this setting is enabled, you must have FFmpeg installed and accessible on the path. The acceptable values for this setting are true or false . (disabled by default) |
flag | The flag settings for the Youtube Downloader : |
When the Youtube Downloader fails to download an age-restricted video, before marking that video as blocked, it can attempt one more time using the local browser cookies. When this setting is disabled, and when location.browser is properly set, the previously described functionality will be active. When this setting is enabled, the Youtube Downloader will never attempt to use local browser cookies. The acceptable values for this setting are true or false . (enabled by default) |
|
flag.test | The test flag settings for the Youtube Downloader : |
flag.test.safeMode | When this setting is enabled, flag.test.preventDownload, flag.test.preventVideoFetch, flag.test.preventExeAutoUpdate, and flag.test.preventExeVersionCheck will be enabled; overriding their individual values. (for use in testing) The acceptable values for this setting are true or false . (disabled by default) |
flag.test.preventRun | When this setting is enabled, the Youtube Downloader will not attempt to run the main code; it will only initialize and then shutdown. (for use in testing) The acceptable values for this setting are true or false . (disabled by default) |
flag.test.preventDownload | When this setting is enabled, or when flag.test.safeMode is enabled, the Youtube Downloader will not attempt to download any videos. (for use in testing) The acceptable values for this setting are true or false . (disabled by default) |
flag.test.preventVideoFetch | When this setting is enabled, or when flag.test.safeMode is enabled, the Youtube Downloader will not attempt to fetch the video information (title, publish date, etc.) prior to downloading. The acceptable values for this setting are true or false . (disabled by default) |
flag.test.preventExeAutoUpdate | When this setting is enabled, or when flag.test.safeMode is enabled, the Youtube Downloader will not attempt to download or automatically update the selected executable. The acceptable values for this setting are true or false . (disabled by default) |
flag.test.preventExeVersionCheck | When this setting is enabled, or when flag.test.safeMode is enabled, the Youtube Downloader will not attempt to check the current or latest version of the selected executable. The acceptable values for this setting are true or false . (disabled by default) |
sponsorBlock | The program-level SponsorBlock configuration for the Youtube Downloader : Instructions on how to define a SponsorBlock configuration can be found under: SponsorBlock Configuration. |
"YoutubeDownloader": {
"location": {
"outputDir": "C:/Users/User/Downloads",
"browser": "Chrome"
},
"process": {
"asAudio": false
},
"flag": {
"neverUseBrowserCookies": true,
"test": {
"safeMode": false,
"preventRun": false,
"preventDownload": false,
"preventVideoFetch": false,
"preventExeAutoUpdate": false,
"preventExeVersionCheck": false
}
}
}
This program is a more complex Youtube video downloader and the main focus of this project.
It will download and keep entire playlists and channels synchronized on your hard drive.
This document will explain everything you need to know to set up the Youtube Channel Downloader to work for you.
In order to use the Youtube Channel Downloader, you will need to get a Google API key.
A Google API key is completely free through your Google account.
The Youtube Channel Downloader uses the Youtube Data API to query the video lists of channels and playlists.
The free quota for the Youtube Data API is 10,000 queries per day, which is more than you should ever need.
- Go to: Google Cloud - APIs & Services
- Click Create Project
- Set Project name: '
Youtube Downloader
' - Click Create
- Set Project name: '
- Click Enable APIs and Services
- Search for: '
Youtube
'- Select
YouTube Data API v3
- Select
- Click Enable
- Click Create Credentials
- Select
YouTube Data API v3
- Click Public Data
- Click Next
- Select
- Copy the API Key to the file
apiKey
🗋 in the project directory
- Go to: Google Cloud - APIs & Services
- Click Select Project
- Select
Youtube Downloader
- Click Open
- Select
- Click Credentials
- Select your API key
- Click Show Key
- Copy the API Key to the file
apiKey
🗋 in the project directory
You can customize the operation of the Youtube Channel Downloader by changing the settings inside the file conf.json
🗋.
To configure the Youtube Channel Downloader, find or create the "YoutubeChannelDownloader"
json configuration and customize the Settings it contains.
SETTING | DESCRIPTION |
---|---|
location | The location settings for the Youtube Channel Downloader : |
location.storageDrive | The path of the drive where downloaded content will be saved. For example: "C:/" . You may leave this blank ( "" or null ) if you wish to specify the full path for each Channel in channels.json 🗋. |
location.musicDir | The path of the directory where audio will be saved. For example: "Users/User/Music/" . This path is relative to location.storageDrive. You may leave this blank ( "" or null ) if you wish to specify the full path for each Channel in channels.json 🗋. If you leave this blank you must also leave location.storageDrive and location.videoDir blank. |
location.videoDir | The path of the directory where video will be saved. For example: "Users/User/Videos/" . This path is relative to location.storageDrive. You may leave this blank ( "" or null ) if you wish to specify the full path for each Channel in channels.json 🗋. If you leave this blank you must also leave location.storageDrive and location.musicDir blank. |
location.browser | The name of the browser that you use locally to watch Youtube. This is the browser that cookies will be used from when attempting to retry certain failed downloads, assuming that flag.neverUseBrowserCookies is disabled. The acceptable values for this setting are "Brave" , "Chrome" , "Chromium" , "Edge" , "Firefox" , "Opera" , "Safari" , or "Vivaldi" . |
process | The process settings for the Youtube Channel Downloader : |
process.enableCustomRenameProcesses | When this setting is enabled, the user-defined Channel Processes for renaming videos will be executed before the download queue is produced for each Channel that has such a process defined. When this setting is disabled, all Channel Processes for renaming videos will be skipped. The acceptable values for this setting are true or false . (enabled by default) More information about custom Channel Processes is provided under: Special Channel Processing. |
process.enableCustomFilterProcesses | When this setting is enabled, the user-defined Channel Processes for filtering videos will be executed after the download queue is produced for each Channel that has such a process defined. When this setting is disabled, all Channel Processes for filtering videos will be skipped. The acceptable values for this setting are true or false . (enabled by default) More information about custom Channel Processes is provided under: Special Channel Processing. |
filter | The filter settings for the Youtube Channel Downloader : |
filter.enableFiltering | When this setting is enabled, the specified filter settings will used to be determine which Channels should be processed. When this setting is disabled, the filter settings will be ignored and all Channels will be processed. The acceptable values for this setting are true or false . (enabled by default) |
filter.channel | There may be times where you want to process only a single Channel and not all of them. Set this to "<YOUR_CHANNEL_KEY>" to process only that Channel. To return to processing all Channels, leave this blank ( "" or null ). When filter.channelList is configured, this setting will be ignored. |
filter.channelList | There may be times where you want to process only a specific set of Channels and not all of them. Set this to ["<YOUR_FIRST_CHANNEL_KEY>","<YOUR_SECOND_CHANNEL_KEY>","<YOUR_THIRD_CHANNEL_KEY>"] , etc., to process only those Channels. To return to processing all Channels, leave this blank ( [] or null ). This setting takes priority over filter.channel. |
filter.group | There may be times where you want to process only a single group and not all of them. Set this to "<YOUR_CHANNEL_GROUP>" to process only that group. To return to processing all groups, leave this blank ( "" or null ). When filter.channel, filter.channelList, or filter.groupList are configured, this setting will be ignored. |
filter.groupList | There may be times where you want to process only a specific set of groups and not all of them. Set this to ["<YOUR_FIRST_CHANNEL_GROUP>","<YOUR_SECOND_CHANNEL_GROUP>","<YOUR_THIRD_CHANNEL_GROUP>"] , etc., to process only those groups. To return to processing all groups, leave this blank ( [] or null ). This setting takes priority over filter.group. When filter.channel or filter.channelList are configured, this setting will be ignored. |
filter.startAt | There may be times where you want to start processing at a specified Channel, skipping all Channels before it. The values for this setting work the same as for filter.channel. The Channels are processed in the order that they appear in your Channel configuration. To return to processing Channels normally, leave this blank ( "" or null ). When filter.channel or filter.channelList are configured, this setting will be ignored. |
filter.stopAt | There may be times where you want to stop processing at a specified Channel, skipping all Channels after it. The values for this setting work the same as for filter.channel. The Channels are processed in the order that they appear in your Channel configuration. To return to processing Channels normally, leave this blank ( "" or null ). When filter.channel or filter.channelList are configured, this setting will be ignored. |
log | The log settings for the Youtube Channel Downloader : |
log.printChannels | Whether to print the Channel list to the console at the start of the run or not. The acceptable values for this setting are true or false . (disabled by default) |
log.printStats | Whether to print statistics to the console at the end of the run or not. The acceptable values for this setting are true or false . (enabled by default) |
log.printReport | Whether to print a download report to the console at the end of the run or not. The acceptable values for this setting are true or false . (disabled by default) |
backup | The backup settings for the Youtube Channel Downloader : |
backup.enableBackups | When this setting is enabled, the specified backup settings will be used to create periodic snapshots of the project state. When this setting is disabled, the backup settings will be ignored and no backups will be created. The acceptable values for this setting are true or false . (disabled by default) |
backup.backupDir | The path of the directory where backups will be saved. For example: "C:/Users/User/Backups" . By leaving this blank ( "" or null ), backups will be saved in the backup/ folder in the project directory. |
backup.compressBackups | When this setting is enabled, backups that are created will be compressed to a zip archive (.zip). The acceptable values for this setting are true or false . (enabled by default) |
backup.daysBetweenBackups | The number of days in between backups. Once the most recent backup has become older than the value specified, a new backup will be created the next time the program runs. You may set this setting to -1 to indicate that a backup should be created every time the program runs. The acceptable values for this setting are any positive integer, or -1 . (7 by default) |
backup.daysToKeepBackups | The number of days to retain backups before deleting them. Once a backup has become older than the value specified, it will be deleted the next time the program runs. You may set this setting to -1 to indicate that backups should never be automatically deleted. The acceptable values for this setting are any positive integer, or -1 . (30 by default) |
backup.files | The backup file inclusion settings for the Youtube Channel Downloader : |
backup.files.includeConfigs | When this setting is enabled, configuration files (conf.json 🗋 and channels.json 🗋) will be included in any backups that are created. When this setting is disabled, configuration files will be excluded from any backups that are created. The acceptable values for this setting are true or false . (enabled by default) |
backup.files.includeData | When this setting is enabled, data files (data/* ) will be included in any backups that are created. When this setting is disabled, data files will be excluded from any backups that are created. The acceptable values for this setting are true or false . (enabled by default) |
backup.files.includeLogs | When this setting is enabled, log files (log/* ) will be included in any backups that are created. When this setting is disabled, log files will be excluded from any backups that are created. The acceptable values for this setting are true or false . (enabled by default) |
backup.files.includeSourceCode | When this setting is enabled, source code files (src/* ) will be included in any backups that are created. When this setting is disabled, source code files will be excluded from any backups that are created. The acceptable values for this setting are true or false . (disabled by default) |
backup.files.includeCompiledSource | When this setting is enabled, compiled source code files (bin/* ) will be included in any backups that are created. When this setting is disabled, compiled source code files will be excluded from any backups that are created. The acceptable values for this setting are true or false . (disabled by default) |
backup.files.includeApiKey | When this setting is enabled, your api key file (apiKey 🗋) will be included in any backups that are created. When this setting is disabled, your api key file will be excluded from any backups that are created. The acceptable values for this setting are true or false . (disabled by default) |
backup.files.includeExecutable | When this setting is enabled, the selected executable file (e.g. yt-dlp.exe ) will be included in any backups that are created. When this setting is disabled, the selected executable file will be excluded from any backups that are created. The acceptable values for this setting are true or false . (disabled by default) |
flag | The flag settings for the Youtube Channel Downloader : |
flag.deleteToRecyclingBin | When this setting is enabled, the Youtube Channel Downloader will attempt to move files to the recycling bin instead of deleting them. The acceptable values for this setting are true or false . (disabled by default) |
When the Youtube Channel Downloader fails to download an age-restricted video, before marking that video as blocked, it can attempt one more time using the local browser cookies. When this setting is disabled, and when location.browser is properly set, the previously described functionality will be active. When this setting is enabled, the Youtube Channel Downloader will never attempt to use local browser cookies. The acceptable values for this setting are true or false . (enabled by default) |
|
flag.retryPreviousFailures | When the Youtube Channel Downloader fails to download a video, either because of a connection issue or because a video is "not available in your country", etc., it will mark that video as blocked and will not automatically attempt to download it again; however sometimes the download will succeed if reattempted. When this setting is enabled, all previously failed downloads from all Channels will be reattempted. This should only be enabled occasionally and disabled after the run. The acceptable values for this setting are true or false . (disabled by default) |
flag.test | The test flag settings for the Youtube Channel Downloader : |
flag.test.safeMode | When this setting is enabled, flag.test.preventDownload, flag.test.preventDeletion, flag.test.preventRenaming, flag.test.preventPlaylistEdit, flag.test.preventChannelFetch, flag.test.preventExeAutoUpdate, and flag.test.preventExeVersionCheck will be enabled; overriding their individual values. (for use in testing) The acceptable values for this setting are true or false . (disabled by default) |
flag.test.preventRun | When this setting is enabled, the Youtube Channel Downloader will not attempt to run the main code; it will only initialize and then shutdown. (for use in testing) The acceptable values for this setting are true or false . (disabled by default) |
flag.test.preventProcess | When this setting is enabled, the Youtube Channel Downloader will not attempt to process any Channels. (for use in testing) The acceptable values for this setting are true or false . (disabled by default) |
flag.test.preventDownload | When this setting is enabled, or when flag.test.safeMode is enabled, the Youtube Channel Downloader will not attempt to download any videos. (for use in testing) The acceptable values for this setting are true or false . (disabled by default) |
flag.test.preventDeletion | When the Youtube Channel Downloader detects that a video has been deleted off Youtube, from a Channel that has keepClean enabled, then it will also be deleted from your hard drive. When this setting is enabled, or when flag.test.safeMode is enabled, media deletion will be globally disabled; overriding the keepClean flag for all Channels. The acceptable values for this setting are true or false . (disabled by default) |
flag.test.preventRenaming | When the Youtube Channel Downloader detects that a video has been renamed on Youtube, or when you modify your Channel Processes, then it will also be renamed on your hard drive. When this setting is enabled, or when flag.test.safeMode is enabled, media renaming will be globally disabled. The acceptable values for this setting are true or false . (disabled by default) |
flag.test.preventPlaylistEdit | When the Youtube Channel Downloader detects that a video has been added, removed, or renamed on Youtube, or when you modify your Channel Processes, for a Channel that has a playlistFile, then the playlist file will be modified to reflect the changes. When this setting is enabled, or when flag.test.safeMode is enabled, playlist modification will be globally disabled. The acceptable values for this setting are true or false . (disabled by default) |
flag.test.preventChannelFetch | When this setting is enabled, or when flag.test.safeMode is enabled, the Youtube Channel Downloader will not attempt to fetch the latest data for Channels; this will result in the previously fetched data being used. (for use in testing) The acceptable values for this setting are true or false . (disabled by default) |
flag.test.preventExeAutoUpdate | When this setting is enabled, or when flag.test.safeMode is enabled, the Youtube Channel Downloader will not attempt to download or automatically update the selected executable. The acceptable values for this setting are true or false . (disabled by default) |
flag.test.preventExeVersionCheck | When this setting is enabled, or when flag.test.safeMode is enabled, the Youtube Channel Downloader will not attempt to check the current or latest version of the selected executable. The acceptable values for this setting are true or false . (disabled by default) |
sponsorBlock | The program-level SponsorBlock configuration for the Youtube Channel Downloader : Instructions on how to define a SponsorBlock configuration can be found under: SponsorBlock Configuration. |
"YoutubeChannelDownloader": {
"location": {
"storageDrive": "C:/",
"musicDir": "Users/User/Music/",
"videoDir": "Users/User/Videos/",
"browser": "Chrome"
},
"process": {
"enableCustomRenameProcesses": true,
"enableCustomFilterProcesses": true
},
"filter": {
"enableFiltering": true,
"channel": null,
"group": null,
"startAt": null,
"stopAt": null
},
"log": {
"printChannels": false,
"printStats": true,
"printReport": false
},
"backup": {
"enableBackups": false,
"backupDir": null,
"compressBackups": true,
"daysBetweenBackups": 7,
"daysToKeepBackups": 30,
"files": {
"includeConfigs": true,
"includeData": true,
"includeLogs": true,
"includeSourceCode": false,
"includeCompiledSource": false,
"includeApiKey": false,
"includeExecutable": false
}
},
"flag": {
"deleteToRecyclingBin": true,
"neverUseBrowserCookies": true,
"retryPreviousFailures": false,
"test": {
"safeMode": false,
"preventRun": false,
"preventProcess": false,
"preventDownload": false,
"preventDeletion": false,
"preventRenaming": false,
"preventPlaylistEdit": false,
"preventChannelFetch": false,
"preventExeAutoUpdate": false,
"preventExeVersionCheck": false
}
}
}
You can specify the Youtube channels and playlists that you want to process by configuring Channels inside the file channels.json
🗋.
There are many examples in channels-sample.json
🗋 that you can use as a reference.
The file channels-sample.json
🗋 is also my personal Channel configuration; if you see any Channels that you like you can copy them to your channels.json
🗋.
To add a Channel, create a new Channel json configuration and customize the Settings it contains.
SETTING | DESCRIPTION |
---|---|
key | The key which uniquely identifies the Channel within your configuration. For example: "MY_CHANNEL" . This setting is required and is an identifier which must be unique; a key used for a Channel must not be used by any other Channel in the configuration. As a best practice, only uppercase letters ( A-Z ), numbers (0-9 ), and underscores (_ ) should be used when defining a key. This setting should not contain spaces and should not be blank ( "" or null ). |
active | When this setting is enabled, the Channel is active; meaning it will be processed when the Youtube Channel Downloader runs and its data will be synced. When this setting is disabled, the Channel is inactive; meaning it will be ignored when the Youtube Channel Downloader runs. The acceptable values for this setting are true or false . (enabled by default) |
name | The human readable name of the Channel. For example: "MyChannel" . This setting is an identifier which must be unique; a name used for a Channel must not be used by any other Channel in the configuration. If this setting is not provided, a name will be automatically generated for the Channel based on the key. This setting should not contain spaces or special characters and should not be blank ( "" or null ). |
group | The user-defined group or category for the Channel. For example: "FAVORITES" . You may also define multiple groups or categories by separating them with delimiters. For example: "FAVORITES : VIDEOS : GENERAL" . As a best practice, only uppercase letters ( A-Z ), numbers (0-9 ), and underscores (_ ) should be used when defining a group. The following characters are valid for use as delimiters: ( . , , , ; , : , + , & ). This setting should not contain spaces, except surrounding delimiters, and should not be blank ( "" or null ). Note: It is now recommended to use Channel Groups instead; instructions on how to define Channel Groups can be found under: Grouping Channels. |
url | The url of the Youtube playlist or channel. For example: "https://www.youtube.com/c/MyFavoriteChannel" . This setting is not used by the program, but it can be useful when returning to the playlist or channel in the future. |
playlistId | The id of the Youtube playlist or channel. For example: "UU65aMyFavoriteChannelXY" . Instructions on how to obtain the playlist id can be found under: Finding Youtube Playlist IDs. |
outputFolder | The path of the output directory of the Channel where downloaded content will be saved. For example: "Youtube/My Channel" . If this Channel is being used to download audio (based on saveAsAudio), then this path is relative to location.musicDir defined in the Youtube Channel Downloader Configuration. If this Channel is being used to download video (based on saveAsAudio), then this path is relative to location.videoDir defined in the Youtube Channel Downloader Configuration. If you chose to leave the location settings blank in the Youtube Channel Downloader Configuration, or if ignoreGlobalLocations is enabled, then this setting must specify the full path of the output directory. |
playlistFile | The path of the playlist file (.m3u) to be used to enumerate the downloaded content of the Channel. For example: "Youtube/My Channel.m3u" . This path is relative to the same base path as outputFolder, however it does not necessarily need to be in the same folder as outputFolder. If you chose to leave the location settings blank in the Youtube Channel Downloader Configuration, or if ignoreGlobalLocations is enabled, then this setting must specify the full path of the playlist file. If this setting is not provided, but savePlaylist is enabled, the playlist will be saved in the default location described by savePlaylist. If this setting is provided, but savePlaylist is disabled, savePlaylist will take precedence and the playlist file will not be created. |
saveAsAudio | When this setting is enabled, the content of the Channel will be downloaded as audio files instead of video files. When this setting is enabled, you must have FFmpeg installed and accessible on the path. The acceptable values for this setting are true or false . (disabled by default) |
savePlaylist | When this setting is enabled, a playlist file (.m3u) will be created to enumerate the downloaded content of the Channel. When this setting is disabled, no playlist file will be created; this setting takes precedence over playlistFile. The playlist file, if it is created, will be placed at the location specified by playlistFile. If no playlistFile is provided, then the playlist file will be placed in the parent folder of the outputFolder and have the same name as the outputFolder. The acceptable values for this setting are true or false . (disabled by default) |
reversePlaylist | When this setting is enabled, and when savePlaylist is enabled, the playlist will be saved in reverse order; newer content will be placed at the beginning of the playlist instead of the end. The acceptable values for this setting are true or false . (disabled by default) |
ignoreGlobalLocations | When this setting is enabled, the location settings defined in the Youtube Channel Downloader Configuration are disregarded for outputFolder and playlistFile. When this setting is enabled, you must specify the full path for outputFolder and playlistFile. When this setting is enabled, then outputFolder and playlistFile may contain ${D} , ${V} , or ${M} which will translate to location.storageDrive, location.videoDir, and location.musicDir respectively. (disabled by default) |
keepClean | When this setting is enabled, and when savePlaylist is enabled, the output directory of the Channel will be kept synchronized with the Youtube playlist or channel. If the output directory is synchronized then videos that are deleted off of Youtube will also be deleted locally. If the output directory is not synchronized then videos that are deleted off of Youtube will not be deleted locally, and will only be removed from the playlist file. The acceptable values for this setting are true or false . (disabled by default) |
sponsorBlock | The SponsorBlock configuration for the Channel : Instructions on how to define a SponsorBlock configuration can be found under: SponsorBlock Configuration. |
{
"key": "MY_CHANNEL",
"active": true,
"name": "MyChannel",
"group": "FAVORITES",
"url": "https://www.youtube.com/c/MyFavoriteChannel",
"playlistId": "UU65aMyFavoriteChannelXY",
"outputFolder": "Youtube/My Channel",
"playlistFile": "Youtube/My Channel.m3u",
"saveAsAudio": false,
"savePlaylist": true,
"reversePlaylist": true,
"ignoreGlobalLocations": false,
"keepClean": false
}
- Again, make sure you set the outputFolder for each Channel to an empty directory or a directory that does not exist yet
- These directories may have files deleted from them in certain circumstances
- By default, files that are deleted in this way are not sent to the recycle bin and would be difficult, if not impossible, to recover
- Examples:
- BAD: A directory that also contains your personal home videos
- BAD: A directory that also contains important work documents
- BAD: A directory that also contains videos that you have downloaded previously for this Channel before starting to use this program
- GOOD: An empty directory or a directory that does not exist yet
When creating a Channel Configuration you need to provide a setting called playlistId.
This is what links your Channel with the actual channel or playlist on Youtube.
This playlist id already exists and you just have to get it from Youtube and set it in your Channel.
The process of obtaining the playlist id depends on whether your Channel represents a Youtube Channel or a Youtube Playlist.
- Go to the home page of the channel on Youtube
- Right click the blank area of the page
- Select View page source
- Search for: '
externalId
'
- Right click the blank area of the page
- Copy the external id from the page source:
···,"externalId":"UC65aMyFavoriteChannelXY",···
··················UC65aMyFavoriteChannelXY·····
- Change the second letter in the external id from '
C
' to 'U
' to get the playlist id - Set the playlist id as playlistId in your Channel
- Go to the home page of the playlist on Youtube
- Copy the playlist id from the url:
https://www.youtube.com/watch?v=L_MupB3z1g4&list=PLUja9k1MyFavoriteChannel5Py_guZ3R
·················································PLUja9k1MyFavoriteChannel5Py_guZ3R
- Set the playlist id as playlistId in your Channel
After you have finished adding Channel Configurations, you have the option to group your Channels; making them easier to read, search, and filter.
You can specify the groups that you want by configuring Channel Groups inside the file channels.json
🗋.
To add a Channel Group, create a new Channel Group json configuration and customize the Settings it contains.
SETTING | DESCRIPTION |
---|---|
key | The key which uniquely identifies the Channel Group within your configuration. For example: "MY_GROUP" . This setting is required and is an identifier which must be unique; a key used for a Channel Group must not be used by any other Channel Group in the configuration. As a best practice, only uppercase letters ( A-Z ), numbers (0-9 ), and underscores (_ ) should be used when defining a key. This setting should not contain spaces and should not be blank ( "" or null ). |
channels | The list of Channels and Channel Groups that are children of the Channel Group. This setting is an array and can contain any number of Channel json configurations and Channel Group json configurations. In the case of nested Channel Groups, a child will be considered a member of all of the enclosing Channel Groups. If the child is a Channel, it will also be considered a member of the group specified by its own group setting, if provided. Any of these groups may be used for filtering. |
{
"key": "MY_GROUP",
"channels": [
...
]
}
When creating a Channel Group Configuration you can also define the default setting configuration for that group.
In addition to the required key and channels settings, any Setting available in a Channel Configuration can also be configured in a Channel Group. (excluding: playlistFile)
When a setting is configured in this way, all children of that group will inherit the setting.
For example, if a Channel Group enables saveAsAudio, then all children of the group will save their downloaded content as audio files.
Even though saveAsAudio is usually disabled by default, within that group saveAsAudio will act as though it is enabled by default, even when that setting is not explicitly configured for a specific child configuration.
To disable saveAsAudio for a specific child, that child's configuration would have to explicitly disable saveAsAudio.
The active setting will behave slightly differently; instead of the standard inheritance described above, it will work in an all-or-nothing manner.
For example, if a child is active, but its parent group is inactive, the child will not be processed. This will also be the case if any of its enclosing groups are inactive.
If a group specifies an outputFolder, then its children may define their outputFolder and playlistFile relative to it using ~
to denote the relative path.
For example, if the parent outputFolder is configured as "Youtube/Videos"
, then:
- Defining the child outputFolder as
"~/Favorites"
would be interpreted as"Youtube/Videos/Favorites"
- Defining the child playlistFile as
"~ - Favorites.m3u"
would be interpreted as"Youtube/Videos - Favorites.m3u"
{
"key": "MY_GROUP",
"active": true,
"outputFolder": "Youtube",
"saveAsAudio": false,
"reversePlaylist": true,
"keepClean": false,
"channels": [
{
"key": "FAVORITE",
"active": true,
"url": "https://www.youtube.com/c/MyFavoriteChannel",
"outputFolder": "~/Favorite",
"channels": [
{
"key": "FAVORITE_VIDEOS",
"name": "FavoriteVideos",
"playlistId": "PLUja9k1MyFavoriteVideos65Py_guZ3R",
"outputFolder": "~ Videos",
"playlistFile": "~/Favorite Videos.m3u",
"keepClean": true
},
{
"key": "FAVORITE_SONGS",
"active": false,
"name": "FavoriteSongs",
"playlistId": "PLUja9k1MyFavoriteSongs865Py_guZ3R",
"outputFolder": "~ Songs",
"playlistFile": "~/Favorite Songs.m3u",
"saveAsAudio": true
}
]
}
]
}
This would be equivalent to:
{
"key": "FAVORITE_VIDEOS",
"active": true,
"name": "FavoriteVideos",
"group": "FAVORITE",
"url": "https://www.youtube.com/c/MyFavoriteChannel",
"playlistId": "PLUja9k1MyFavoriteVideos65Py_guZ3R",
"outputFolder": "Youtube/Favorite Videos",
"playlistFile": "Youtube/Favorite/Favorite Videos.m3u",
"saveAsAudio": false,
"reversePlaylist": true,
"keepClean": true
},
{
"key": "FAVORITE_SONGS",
"active": false,
"name": "FavoriteSongs",
"group": "FAVORITE",
"url": "https://www.youtube.com/c/MyFavoriteChannel",
"playlistId": "PLUja9k1MyFavoriteSongs865Py_guZ3R",
"outputFolder": "Youtube/Favorite Songs",
"playlistFile": "Youtube/Favorite/Favorite Songs.m3u",
"saveAsAudio": true,
"reversePlaylist": true,
"keepClean": false
}
There are certain instances where you may want to perform some additional processing on the Channel to filter which videos are downloaded, to rename the downloaded videos to something that you prefer, etc. This functionality is possible granted that you know a bit of Java.
There are two methods in the file src/youtube/channel/process/ChannelProcesses.java
🗋 :
- performSpecialPreConditions()
- Executed before the download queue is produced for the Channel
- Used to rename the videos that will be downloaded
- Can be enabled or disabled using process.enableCustomRenameProcesses
- performSpecialPostConditions()
- Executed after the download queue is produced for the Channel
- Used to filter out videos that should not be downloaded; do not use this method to rename videos
- Can be enabled or disabled using process.enableCustomFilterProcesses
In both of these methods, all you have to do is add another case for your Channel key to the switch statement.
You may also add whatever logic you like to the body of the method, or even call your own custom methods or classes, for special use cases.
These methods have no return value; any changes that you want to make should be achieved by modifying the following accessible objects:
OBJECT | DESCRIPTION |
---|---|
channel |
The Channel object containing the details of your Channel. |
videoMap |
A map of Video objects, containing the name, output file, etc. of all videos for the Channel; indexed by video ids. |
channel.state.queued |
A list of video ids that are queued for download by the Channel. |
channel.state.saved |
A list of video ids that have already been downloaded by the Channel and are currently on your hard drive. |
channel.state.blocked |
A list of video ids that have not already been downloaded, but are also not queued for download. |
You can modify the video map and Channel state lists using your own custom logic.
There is also a collection of macro methods provided that you can call to perform certain actions.
These macro methods are defined in the files src/youtube/channel/process/macro/RenameProcess.java
🗋 and src/youtube/channel/process/macro/FilterProcess.java
🗋.
All of these methods will take the videoMap
as their first argument, and the macro action will be performed on each Video in the video map.
There are many examples of these processes in the file src/youtube/channel/process/ChannelProcesses_Sample.java
🗋 that you can use as a reference.
The file src/youtube/channel/process/ChannelProcesses_Sample.java
🗋 contains the processes for my personal Channel configuration; if you copied some of my Channel configurations from channels-sample.json
🗋 then you may also wish to copy the corresponding processes.
All of the configuration settings for the project are stored in the file conf.json
🗋.
NAME | DESCRIPTION | DETAILS | SAMPLE |
---|---|---|---|
YoutubeChannelDownloader | Youtube Channel Downloader project configuration | Configuring the Youtube Channel Downloader | sample |
YoutubeDownloader | Youtube Downloader project configuration | Configuring the Youtube Downloader | sample |
process | Global process configuration | Process Configuration | sample |
sponsorBlock | Global SponsorBlock configuration | SponsorBlock Configuration | sample |
color | Global color configuration | Color Configuration | sample |
log | Global logging configuration | Logging Configuration | sample |
{
"YoutubeChannelDownloader": {
...
},
"YoutubeDownloader": {
...
},
"process": {
...
},
"sponsorBlock": {
...
},
"color": {
...
},
"log": {
...
}
}
You can customize how content will be downloaded and processed by changing the settings inside the file conf.json
🗋.
Changing these settings will affect the logging for both the Youtube Downloader and the Youtube Channel Downloader.
Any of these settings can also be defined in the "process"
section inside of the Youtube Downloader Configuration or Youtube Channel Downloader Configuration to override them for the respective program.
To configure the process, find or create the "process"
json configuration and customize the Settings it contains.
SETTING | DESCRIPTION |
---|---|
executable | The name of the executable which will be used to download content from Youtube. The two valid options for this setting are "yt-dlp" and "youtube-dl" . More information about these executables is provided under: Executable Options. |
customFlags | The custom flags to pass to the executable when downloading content from Youtube. For a list of available options see the yt-dlp Documentation or the youtube-dl Documentation, depending on your choice of executable. |
process.format | The process format settings : |
process.format.preMerged | When this setting is enabled, the processor will download videos in the best pre-merged format. When this setting is disabled, and when executable is set to "yt-dlp" , the Youtube Downloader will download videos in the best possible format, not just the best pre-merged format. When this setting is disabled, content might be downloaded in a format other than the process.format.defaultVideoFormat or process.format.defaultAudioFormat. When this setting is disabled, you must have FFmpeg installed and accessible on the path. The acceptable values for this setting are true or false . (enabled by default) |
process.format.defaultVideoFormat | The default file format that the processor will use when saving content as video files. The acceptable values for this setting are 3gp , flv , mp4 , or webm . (mp4 by default) |
process.format.defaultAudioFormat | The default file format that the processor will use when saving content as audio files. The acceptable values for this setting are aac , m4a , mp3 , ogg , or wav . (mp3 by default) |
"process": {
"executable": "yt-dlp",
"customFlags": null,
"format": {
"preMerged": true,
"defaultVideoFormat": "mp4",
"defaultAudioFormat": "mp3"
}
}
You can set up SponsorBlock by changing the settings inside the file conf.json
🗋 or channels.json
🗋.
SponsorBlock is able to automatically cut out unwanted segments from the content you download. (sponsored sections, self promotions, interaction reminders, etc.)
To use SponsorBlock, you must have FFmpeg installed and accessible on the path.
This is only available when using yt-dlp as the executable.
SponsorBlock is capable of distinguishing and skipping several types of segments which can be enabled independently.
Details about these segments and what each covers can be found on the Category Breakdown page of the SponsorBlock Wiki.
You can set up a global SponsorBlock configuration for the entire project, or for the Youtube Downloader or Youtube Channel Downloader programs individually.
You can also have custom SponsorBlock configurations for individual Channel Groups or Channels.
To configure SponsorBlock, find or create a "sponsorBlock"
json configuration and customize the Settings it contains.
- A configuration in
conf.json
🗋 will function as a global configuration for the entire project. - A configuration in
conf.json
🗋 inside the Youtube Downloader Configuration or Youtube Channel Downloader Configuration will affect all content downloaded by the respective program. - A configuration in
channels.json
🗋 inside a Channel Configuration will affect only that Channel, and one inside a Channel Group Configuration will affect all Channels and Channel Groups which are children of the group.
SETTING | DESCRIPTION |
---|---|
enabled | When this setting is enabled, the SponsorBlock configuration is active; meaning downloaded content will be post-processed and cleaned according to the provided settings. When this setting is disabled, the SponsorBlock configuration is inactive; meaning downloaded content will not be post-processed. The acceptable values for this setting are true or false . (enabled by default) |
forceGlobally | When this setting is enabled, this SponsorBlock configuration will be used in place of a specific lower-level configuration. In that case, this configuration will be used even if the lower-level configuration is active, provided that this configuration is active and the lower-level configuration does not have overrideGlobal enabled. The acceptable values for this setting are true or false . (disabled by default) Note: This setting is only valid for global SponsorBlock configurations. |
overrideGlobal | When this setting is enabled, this SponsorBlock configuration will be used regardless of the global configuration. When this configuration has overrideGlobal enabled and the global configuration has forceGlobally enabled, overrideGlobal will take precedence. The acceptable values for this setting are true or false . (disabled by default) Note: This setting is only valid for non-global SponsorBlock configurations. |
skipAll | When this setting is enabled, all segments recognized by SponsorBlock will be skipped when downloading content. The acceptable values for this setting are true or false . (disabled by default) |
skipSponsor | When this setting is enabled, Sponsor segments will be skipped when downloading content. The acceptable values for this setting are true or false . (disabled by default) |
skipIntro | When this setting is enabled, Intro segments will be skipped when downloading content. The acceptable values for this setting are true or false . (disabled by default) |
skipOutro | When this setting is enabled, Outro segments will be skipped when downloading content. The acceptable values for this setting are true or false . (disabled by default) |
skipSelfPromo | When this setting is enabled, Self-Promo segments will be skipped when downloading content. The acceptable values for this setting are true or false . (disabled by default) |
skipPreview | When this setting is enabled, Preview segments will be skipped when downloading content. The acceptable values for this setting are true or false . (disabled by default) |
skipInteraction | When this setting is enabled, Interaction segments will be skipped when downloading content. The acceptable values for this setting are true or false . (disabled by default) |
skipMusicOffTopic | When this setting is enabled, Music Off-Topic segments will be skipped when downloading content. The acceptable values for this setting are true or false . (disabled by default) |
"sponsorBlock": {
"enabled": true,
"forceGlobally": false,
"overrideGlobal": false,
"skipAll": false,
"skipSponsor": false,
"skipIntro": false,
"skipOutro": false,
"skipSelfPromo": false,
"skipPreview": false,
"skipInteraction": false,
"skipMusicOffTopic": false
}
You can customize the colors used by the project when printing output to the console by changing the settings inside the file conf.json
🗋.
Changing these settings will affect the colors for both the Youtube Downloader and the Youtube Channel Downloader.
Any of these settings can also be defined in the "color"
section inside of the Youtube Downloader Configuration or Youtube Channel Downloader Configuration to override them for the respective program.
These colors will only work if your console supports ANSI SGR codes.
The project supports this list of Supported Colors.
To configure the colors, find or create the "color"
json configuration and customize the Settings it contains.
SETTING | DESCRIPTION |
---|---|
enableColors | When this setting is enabled, colors will be used when printing output to the console. When this setting is disabled, all output will be printed to the console using its default color. The acceptable values for this setting are true or false . (enabled by default) |
base | The base color to print in. The acceptable values for this setting are any of the Supported Colors. ( "GREEN" by default) |
good | The color to print "good" text in. The acceptable values for this setting are any of the Supported Colors. ( "CYAN" by default) |
bad | The color to print "bad" text in. The acceptable values for this setting are any of the Supported Colors. ( "RED" by default) |
log | The color to print logs in. The acceptable values for this setting are any of the Supported Colors. ( "DARK_GREY" by default) |
channel | The color to print Channel names in. The acceptable values for this setting are any of the Supported Colors. ( "YELLOW" by default) |
video | The color to print Video titles in. The acceptable values for this setting are any of the Supported Colors. ( "PURPLE" by default) |
number | The color to print numbers in. The acceptable values for this setting are any of the Supported Colors. ( "WHITE" by default) |
file | The color to print file names and file paths in. The acceptable values for this setting are any of the Supported Colors. ( "GREY" by default) |
exe | The color to print the name of the executable in. The acceptable values for this setting are any of the Supported Colors. ( "ORANGE" by default) |
link | The color to print links in. The acceptable values for this setting are any of the Supported Colors. ( "TEAL" by default) |
progressBar | The progress bar color settings : |
progressBar.base | The base color to print progress bars in. The acceptable values for this setting are any of the Supported Colors. ( "GREEN" by default) |
progressBar.good | The color to print the "good" text of progress bars in. The acceptable values for this setting are any of the Supported Colors. ( "CYAN" by default) |
progressBar.bad | The color to print the "bad" text of progress bars in. The acceptable values for this setting are any of the Supported Colors. ( "RED" by default) |
"color": {
"enableColors": true,
"base": "GREEN",
"good": "CYAN",
"bad": "RED",
"log": "DARK_GREY",
"channel": "YELLOW",
"video": "PURPLE",
"number": "WHITE",
"file": "GREY",
"exe": "ORANGE",
"link": "TEAL",
"progressBar": {
"base": "GREEN",
"good": "CYAN",
"bad": "RED"
}
}
You can customize what is printed to the console when running the project by changing the settings inside the file conf.json
🗋.
Changing these settings will affect the logging for both the Youtube Downloader and the Youtube Channel Downloader.
Any of these settings can also be defined in the "log"
section inside of the Youtube Downloader Configuration or Youtube Channel Downloader Configuration to override them for the respective program.
To configure the logging, find or create the "log"
json configuration and customize the Settings it contains.
SETTING | DESCRIPTION |
---|---|
printSettings | Whether to print the active configuration settings to the console at the start of the run or not. The acceptable values for this setting are true or false . (enabled by default) |
printExeVersion | Whether to print the version of the executable to the console at the start of the run or not. The acceptable values for this setting are true or false . (enabled by default) |
printExecutionTime | Whether to print the time elapsed during execution of the run to the console at the end of the run or not. The acceptable values for this setting are true or false . (enabled by default) |
download | The download log settings : |
download.showCommand | When this setting is enabled, the commands sent to the executable to download each video will be printed to the console. The acceptable values for this setting are true or false . (enabled by default) |
download.showWork | When this setting is enabled, the work being done by the executable while downloading each video will be printed to the console. When this setting is enabled, download.showProgressBar will be automatically disabled. The acceptable values for this setting are true or false . (disabled by default) |
download.showProgressBar | When this setting is enabled, and when download.showWork is disabled, a progress bar will be shown in the console while downloading each video. The acceptable values for this setting are true or false . (enabled by default) |
file | The file log settings : |
file.allowFileLogging | When this setting is enabled, logging to files in the log/ directory will be permitted. When this setting is disabled, all file logging will be disabled. The acceptable values for this setting are true or false . (enabled by default) |
file.writeMainLog | When this setting is enabled, the program will be permitted to write to the main log file. When this setting is disabled, logging to the main log file will be disabled. The acceptable values for this setting are true or false . (enabled by default) |
file.writeDownloadLog | When this setting is enabled, the program will be permitted to write to the download log file. When this setting is disabled, logging to the download log file will be disabled. The acceptable values for this setting are true or false . (enabled by default) |
file.writeApiLog | When this setting is enabled, the program will be permitted to write to the api log file. When this setting is disabled, logging to the api log file will be disabled. The acceptable values for this setting are true or false . (enabled by default) |
file.daysToKeepLogs | The number of days to retain log files before deleting them. Once a log file has become older than the value specified, it will be deleted the next time the program runs. You may set this setting to -1 to indicate that logs should never be automatically deleted. The acceptable values for this setting are any positive integer, or -1 . (30 by default) |
"log": {
"printSettings": true,
"printExeVersion": true,
"printExecutionTime": true,
"download": {
"showCommand": true,
"showWork": false,
"showProgressBar": true,
},
"file": {
"allowFileLogging": true,
"writeMainLog": true,
"writeDownloadLog": true,
"writeApiLog": true,
"daysToKeepLogs": 30
}
}
~~ This project is for educational and testing purposes only and is not intended to be used in any way that would violate the Youtube ToS or to download copyrighted material ~~