ytdl
Yet another CLI based YouTube downloader tool for linux.
Features:
- Download only neccessary stream, not the whole video
- Download all videos or audios belong to a playlist
- Download with custom name and bounding
Just gather your favourite videos into a playlist, then let's ytdl download them overnight.
Prerequisites
- Fedora 32+, Ubuntu 20+, Debian 10+
- python 3.6.5 or newer
- ffmpeg 4.0 or newer
- YouTube API key
Install
Recommend to use pipx:
pipx install ytdl
ytdl configHowever, pip may work too:
pip install ytdl
# don't
sudo pip install ytdlBuild from source requires poetry:
git clone git@github.com:ndaidong/ytdl.git && cd ytdl
poetry install
# use raw script
poetry run python main.py info
poetry run python main.py [command] [arguments]
# build wheel to `./dist` folder
poetry build
# then install it
pipx install dist/ytdl-VERSION-py3-none-any.whl
# test it
ytdl infoCLIs
Basic commands
| Command | Description | Shortcut |
|---|---|---|
ytdl config KEY VALUE |
Set config value | c |
ytdl config KEY |
Show config property | |
ytdl playlist PLAYLIST_URL |
Get playlist index | p |
ytdl video VIDEO_URL |
Download a video | v |
ytdl audio VIDEO_URL |
Download audio only | a |
Almost cases, VIDEO_URL and PLAYLIST_URL can be replaced with video ID or playlist ID.
Advanced usage
Config
There are 2 properties to configure: api_key and store_dir.
At the first time, api_key is empty and you have to set it before using other features.
# set new `api_key`
ytdl config api_key YOUR_OWN_YOUTUBE_API_KEY
# change `store_dir` to new path
ytdl config store_dir /storage/downloads/youtube
# get the current value of `api_key`
ytdl config api_key
# show all
ytdl configBy default, store_dir is being set to /home/{YOUR_USER_NAME}/ytdl_files, you should change it to more appropriate place.
Playlist
Note that this command does not download actual video/audio, but a list of indexed items.
# get playlist metadata into `{store_dir}/{title}.json`
# this file contains a list of videos with their ID and title to download later
ytdl playlist https://www.youtube.com/playlist?list=PLAYLIST_ID
# get playlist metadata into `{store_dir}/my_custom_playlist_name.json`
ytdl playlist https://www.youtube.com/playlist?list=PLAYLIST_ID my_custom_playlist_nameFor example if we download the playlist Linux Tips and Tricks
The indexed file looks like below:
Then we will have some powerful ways to download the videos in this list with ytdl video or ytdl audio.
Video
Download a single video file.
# download a video file to `{store_dir}/video/{VIDEO_TITLE}.mp4`
ytdl video https://www.youtube.com/watch?v=VIDEO_ID
# custom name
ytdl video https://www.youtube.com/watch?v=VIDEO_ID my_custom_video_name
To download multi items from indexed playlist, please refer the following arguments:
-
--index_file: path to playlist index file (required) -
--since: video ID of the video where you want to start downloading from -
--limit: number of items to download, count fromsinceor the begining of the list -
--prefix_name: to auto naming downloaded file -
--prefix_num: to auto naming downloaded file
Examples:
# download all videos from saved playlist index file above
# these video files will be stored in `{store_dir}/video`
ytdl video --index_file "/path/to/Linux Tips and Tricks.json"
# download 5 videos from saved playlist index file above, since first item
ytdl video --index_file "/path/to/Linux Tips and Tricks.json" --limit 5
# download 5 videos from saved playlist index file above, with prefix name
ytdl video --index_file "/path/to/Linux Tips and Tricks.json" --limit 5 --prefix_name "Linux Tutorial"
# downloaded videos should look like "Linux Tutorial - 1.mp4", "Linux Tutorial - 2.mp4" and so on
# prefix_name will be useful when you want to put these files into an already created list for your different purpose
# download 5 videos from saved playlist index file above, with prefix name and prefix number
ytdl video --index_file "/path/to/Linux Tips and Tricks.json" --limit 5 --prefix_name "Linux Tutorial" --prefix_num 25
# this will be useful for the playlists those are splited to multi parts
# in this case, your serie "Linux Tutorial" had already 24 items before, now count from 25 onwards
# downloaded videos should look like "Linux Tutorial - 25.mp4", "Linux Tutorial - 26.mp4" and so on
# similar to above command, but start from given item
ytdl video --index_file "/path/to/Linux Tips and Tricks.json" --since VIDEO_ID --limit 5 --prefix_name "Linux Tutorial" --prefix_num 25While downloading video, the stream with highest resolution will be selected.
Audio
This is similar to ytdl video, but only download audio file.
While downloading, the stream with highest abr (average bitrate) will be selected.
# download a audio file to `{store_dir}/audio/{VIDEO_TITLE}.mp3`
ytdl audio https://www.youtube.com/watch?v=VIDEO_ID
# custom name
ytdl audio https://www.youtube.com/watch?v=VIDEO_ID my_custom_audio_nameTo download multi items from indexed playlist, please refer the following arguments:
-
--index_file: path to playlist index file (required) -
--since: video ID of the video where you want to start downloading from -
--limit: number of items to download, count fromsinceor the begining of the list -
--prefix_name: to auto naming downloaded file -
--prefix_num: to auto naming downloaded file
Examples:
# download all audios from saved playlist index file above
# these audio files will be stored in `{store_dir}/audio`
ytdl audio --index_file "/path/to/Linux Tips and Tricks.json"
# download 5 audios from saved playlist index file above, since first item
ytdl audio --index_file "/path/to/Linux Tips and Tricks.json" --limit 5
# download 5 audios from saved playlist index file above, with prefix name
ytdl audio --index_file "/path/to/Linux Tips and Tricks.json" --limit 5 --prefix_name "Linux Tutorial"
# downloaded audios should look like "Linux Tutorial - 1.mp3", "Linux Tutorial - 2.mp3" and so on
# prefix_name will be useful when you want to put these files into an already created list for your different purpose
# download 5 audios from saved playlist index file above, with prefix name and prefix number
ytdl audio --index_file "/path/to/Linux Tips and Tricks.json" --limit 5 --prefix_name "Linux Tutorial" --prefix_num 25
# this will be useful for the playlists those are splited to multi parts
# in this case, your serie "Linux Tutorial" had already 24 items before, now count from 25 onwards
# downloaded audios should look like "Linux Tutorial - 25.mp3", "Linux Tutorial - 26.mp3" and so on
# similar to above command, but start from given item
ytdl audio --index_file "/path/to/Linux Tips and Tricks.json" --since VIDEO_ID --limit 5 --prefix_name "Linux Tutorial" --prefix_num 25Downloaded stream will be converted to .mp3 with ffmpeg.
Dependencies
This lib was built on top of the following packages:
| Dependency | License |
|---|---|
| pytube3 | MIT |
| python-youtube | MIT |
| python-fire | Apache License v2 |
Test
git clone git@github.com:ndaidong/ytdl.git && cd ytdl
poetry install
YOUTUBE_API_KEY=your_own_key ./run_test.shLicense
The MIT License (MIT)
