youtube-dl-react-viewer is a web app for yt-dlp that supports viewing and downloading videos.
📷Screenshots | 🌎Live Demo
- FEATURES
- ✨INSTALL WITH DOCKER✨
- INSTALL MANUALLY
- ENVIRONMENT VARIABLES
- DOWNLOADING
- IMPORTING ALREADY DOWNLOADED VIDEOS
- ISSUES & LIMITATIONS
- SCRIPTS
- HANDLING DOWNLOAD ERRORS
- FAQ
- PLANNED
- LICENSE/CREDITS
- DISCLAIMER
- Download videos using yt-dlp by creating and running download jobs
- Watch downloaded videos in the browser
- Import already downloaded videos
- SponsorBlock integration
- Return YouTube Dislike integration
- Watch history and resume playback across devices
- Full-text search for video titles, descriptions, and playlists
- Playlist autoplay & looping
- Open video streams in VLC
- Download video comments
- YouTube live chat replay
- Channel icon downloader (YouTube and SoundCloud)
- Caption and subtitle support
- Light and dark themes
- Display videos related to the current video
- Restrict access to the web app with a global password
- Verify the integrity (hash) of downloaded videos
Caution
Only install the web app using release tags. Avoid installing directly from the main branch, as there may be breaking changes introduced between official releases.
Caution
Downgrading an existing installation is not supported and may lead to database corruption. It is recommended to backup your database before upgrading versions.
-
Clone this repository
-
Open the repository directory
cd ./youtube-dl-react-viewer -
Run
git checkout tags/v1.5.0to select the latest release -
Copy
.env.sampleto.env -
Edit
.envand configure the required environment variables -
Run
docker compose up -dto build the image and start the container -
The web app will be accessible in the browser at
http://localhost:5000
Because .env is copied to the container during the build step the Docker image must be rebuilt in order to change environment variables. After editing .env run docker compose build --no-cache app && docker compose up -d to rebuild.
Caution
If you are updating a Docker installation from a version prior to 1.4.0 see the v1.4.0 Docker Update Guide
-
Run
git pull -
Run
git checkout tags/v1.5.0to select the latest release -
Run
docker compose build --no-cache && docker compose up -dto rebuild and restart the container
-
Install yt-dlp and add
yt-dlpto PATH -
Install FFmpeg and FFprobe and add
ffmpegandffprobeto PATH -
Clone this repository
-
Open the repository directory
cd ./youtube-dl-react-viewer -
Run
git checkout tags/v1.5.0to select the latest release -
Copy
.env.sampleto.env -
Edit
.envand configure the required environment variables -
Run the install script located in
./youtube-dl-react-viewer/scripts -
The web app will be accessible in the browser at
http://localhost:5000
When installed manually the web app process is managed by pm2.
Usage:
- Start the web app
pm2 start youtube-dl-react-viewer - Stop the web app
pm2 stop youtube-dl-react-viewer - View logs
pm2 logs youtube-dl-react-viewer - Run at pc startup
pm2 startup youtube-dl-react-viewer(unix only)
-
Run
git pull -
Run
git checkout tags/v1.5.0to select the latest release -
Rerun the install script located in
./youtube-dl-react-viewer/scripts
Configure environment variables by editing the .env file in the repository root directory. If this file does not exist yet copy .sample.env to .env. Use this file to set environment variables for both the frontend and backend. Some variables are required for the app to run, see required environment variables for details.
OUTPUT_DIRECTORY Location downloads will be saved to
(path, default: '/youtube-dl')
SUPERUSER_USERNAME Admin account username. The admin account
is created when the web app is started
(string < 50, default: admin)
SUPERUSER_PASSWORD Admin account password. If the value is
`password` or less than 8 characters the
web app will not start
(string >= 8 && !== password, default:
password)
JWT_TOKEN_SECRET Secret key to sign the JSON Web Token. If
the value is `secret` the web app will not
start. Use a securely generated random
string at least 32 characters long
(string !== secret, default: secret)
MONGOOSE_URL Database connection URL. If the database
does not exist it will be created
(url, default:
mongodb://127.0.0.1:27017/youtubeDlDB)
BACKEND_PORT Port used to serve the web app
(0-65535, default: 5000)
SECURE_COOKIES Only serve cookies over HTTPS. Enable if
not running locally
(true|false, default: false)
YOUTUBE_DL_PATH Path to yt-dlp. Forks should work as drop
in replacements
(path, default: yt-dlp)
FFMPEG_PATH Path to FFmpeg
(path, default: ffmpeg)
FFPROBE_PATH Path to FFprobe
(path, default: ffprobe)
THUMBNAIL_QUALITY JPEG quality level used when creating
new thumbnails
(0-100, default: 80)
THUMBNAIL_CHROMA_SUBSAMPLING Chroma subsampling used when creating
new thumbnails
(4:4:4|4:2:0, default: 4:4:4)
PAGE_SIZE Number of videos that are loaded per page
(number >= 1, default: 54)
SKIP_HASHING Skip generating hashes when downloading
or importing videos
(true|false, default: false)
ENABLE_USER_REGISTRATION Allow users to create new accounts
(true|false, default: true)
DISPLAY_SIMILAR_VIDEOS Algorithm used to find similar videos.
Consider disabling if page loads start to
become slow
(complex|simple|disabled, default: complex)
SPONSORBLOCK_API_URL API used to retrieve sponsor segments
(url, default: https://sponsor.ajay.app/)
SPONSORBLOCK_K_ANONYMITY Use the k-anonymity system when fetching
sponsor segments to preserve privacy
(true|false, default: true)
RETURN_YOUTUBE_DISLIKE_API_URL API used to retrieve video dislikes
(url, default:
https://returnyoutubedislikeapi.com/)
EXPOSE_LOCAL_VIDEO_PATH Expose the local video path to allow for
local VLC playback
(true|false, default: false)
YOUTUBE_DL_UPDATE_COMMAND Command run when updating yt-dlp from the
admin panel. If not set will run `-U`
(string, default: '')
UPDATE_YOUTUBE_DL_ON_JOB_START Automatically update yt-dlp when a download
job is started
(true|false, default: false)
AUDIO_ONLY_MODE_ENABLED Enable usage of audio only mode. Audio
transcription is done live which may have
a performance impact on the server
(true|false, default: true)
AUDIO_ONLY_MODE_BITRATE Bitrate to use when transcoding the audio
stream in audio only mode
(number, default: 128000)
VERBOSE Print detailed error messages to the
console
(true|false, default: false)
NODE_ENV Should be set to `production` unless
running in development mode `development`
(string, default: production)
REACT_APP_BRAND Name shown in the navbar
(string, default: youtube-dl Viewer)
REACT_APP_CHECK_FOR_UPDATES Automatically check for new releases on the
admin page
(true|false, default: true)
REACT_APP_SHOW_VERSION_TAG Show the current release version number
in the navbar
(true|false, default: true)
REACT_APP_LIGHT_THEME_LOGO Light theme icon in the navbar
(url, default: /logo.svg)
REACT_APP_DARK_THEME_LOGO Dark theme icon in the navbar
(url, default: /logo.svg)
REACT_APP_LOAD_EXTERNAL_THUMBNAILS Load thumbnails and avatars from third
parties
(true|false, default: false)
REACT_APP_OUT_OF_DATE_COLOR_DAYS Days until a job is highlighted in red to
indicate it has not been run recently
(number > 0, default: 30)
REACT_APP_REPO_NAME Name of the repository
(string, default: youtube-dl-react-viewer)
REACT_APP_REPO_URL Link to the repository
(url)
REACT_APP_GITHUB_API_URL Link to the GitHub API URL for the latest
release
(url)
REACT_APP_LATEST_RELEASE_LINK Link to the latest release page
(url)
PORT Port used by the web app frontend in
development mode
If the web app was installed using Docker you will need to rebuild the image after changing any environment variables by running docker compose build --no-cache app && docker compose up -d.
If the web app was installed manually you will need to rebuild the web app frontend after changing environment variables that start with REACT_APP_.
Changing REACT_APP_LIGHT_THEME_LOGO/REACT_APP_DARK_THEME_LOGO will not change the favicon and manifest icons. They can only be changed by replacing the icon files in ./youtube-dl-react-frontend/public and rebuilding the web app frontend.
To rebuild the web app frontend:
cd ./youtube-dl-react-frontend
npm install --unsafe-perm
npm run build
These environment variables are required for the web app to run. Ensure they are set in the .env file in the repository root directory.
The location on your device where downloads will be saved.
The username for the admin account. If an admin account with this username does not already exist, it will be created.
The password for the admin account. The value cannot be 'password' and must be at least 8 characters long.
Used to sign the JSON Web Tokens (JWT). The value cannot be 'secret' and it is recommended to use a random string of at least 32 characters.
Determines whether cookies should be marked as secure. Set to true if using an HTTPS server. Set to false if running locally.
The port on which the web app will be served. The default port is 5000. If another service is already using port 5000, specify any other available port.
-
Sign into the web app with the admin account
-
Go to the admin panel and scroll to the Jobs section
-
Click the plus icon to create a new job, configure, and save it
Job name Display name Format code Format code used by yt-dlp when downloading videos Download audio only Enable to only download audio Download comments Enable to download comments if supported for the website Recode video Enable to convert downloaded videos to mp4 to increase browser playback compatibility (may reduce quality) URLs URLs that will be downloaded each time the job is run. URLs can be individual videos, channels, playlists, etc. One URL per line Override config Arguments passed to yt-dlp when downloading. For example, you can add `--cookies` here Override uploader Treat all videos downloaded by this job as if they were uploaded by the specified uploader. Useful for websites that do not return a uploader name -
Scroll to the Download section
-
Select and run the jobs you want to download. Multiple jobs can be selected. Jobs will run in the order they are started
You can import videos already downloaded with yt-dlp as long as they were downloaded with --write-info-json and --write-thumbnail and the thumbnail and JSON files are in the same folder as the video.
- Sign into the web app with the admin account
- Go to the admin panel and scroll to the Import videos section, configure, and import
Folder to import Folder to import videos from
Job Job imported videos will be added to.
Imported videos will appear in the web app
as if they were downloaded by this job
Search subfolders Search subfolders for videos
Copy files Copy files instead of moving them
Continue on failed Continue importing videos instead of
stopping if a video fails to import
Override ext Sometimes the video file extension cannot
be determined when importing. If you know
the extension and it is the same for all
videos you can specify it here
Caution
If the web app was installed using Docker you will need to copy the videos you want to import into the output directory first, then import the videos using the path on the container filesystem.
- Copy your videos from
C:\Your Existing DownloadstoC:\Output Directory\TEMP - In the web app import the folder
/youtube-dl/TEMP - After importing
C:\Output Directory\TEMPcan be deleted
The default format code used to download videos is bestvideo*+bestaudio/best. This can sometimes create a video that cannot be played in the browser, although this is dependent on the specific browser and device. If a playback error occurs try:
- Enabling spoof type
- Opening the video in VLC
- Using a different browser
- Changing the format code and redownloading the video
To download videos that may have a greater chance of playing in the browser try:
- Using the format code
(bestvideo[vcodec^=h264]+bestaudio[acodec^=aac])/mp4/best - Enabling recode video in the download job settings. This will reencode the video into a mp4 container if necessary
Safari and iOS have limited support for video playback. Generally only mp4 videos downloaded with the h264 vcodec and aac acodec will play correctly. You can try either:
- Installing the VLC app and opening videos in VLC
- Adding
--postprocessor-args "-c:v libx264 -c:a aac -b:a 192k -movflags +faststart"to arguments under advanced options in the download job settings. This will reencode the video taking time and reducing quality and therefore is not recommended
yt-dlp only downloads playlist metadata for videos if they were downloaded as part of a playlist. If you have already downloaded a video and then download a playlist that includes the same video it will not appear in the playlist in the web app. To prevent this it is recommended to download playlists before downloading individual videos.
File paths on Windows cannot be longer than 260 characters. To prevent errors where downloaded videos exceed the path length limit, set the output directory to a location as close to the root directory as possible (i.e., C:\Output Directory). Alternatively, you can remove the path length limit on Windows by enabling long paths.
Scripts offer or extend functionality that is not present in youtube-dl-react-viewer by default.
- A Node.js script to automatically run download jobs at a specified time using a cron scheduler
- A bookmarklet to append the URL of the current page to a specified download job
- A bookmarklet to start running any number of specified download jobs
There are two types of errors that can occur when downloading videos:
This could happen for many reasons: poor internet connection, broken extractor, private video, etc. yt-dlp will try to download the video again the next time the job is run.
If the web app fails to parse the video metadata the video will appear under the Failed to parse section of the admin panel. yt-dlp will not try to redownload the video as it has been successfully downloaded.
You can attempt to retry parsing the video from the Failed to parse section of the admin panel, however, this will likely still fail until a version of the web app that fixes the issue is released. Report parsing errors here.
Videos can be opened in VLC from the web app using the Open in VLC button on the video page.
On PC/Mac you must first register the vlc:// URL protocol. You can do this with stefansundin/vlc-protocol. No additional configuration is required on iOS/Android devices.
You can download from websites that require a login by passing your cookies to the download job. In job settings under Advanced options in Override config you can set --cookies or --cookies-from-browser.
If the web app was installed using Docker --cookies-from-browser will not work. To pass cookies to a job when using Docker:
- Export a Netscape formatted cookie file with the cookies for the desired websites
- Save the cookies file to the root of your output directory
C:\Output Directory\cookies.txt - In Override config set
--cookies /youtube-dl/cookies.txt
You can update yt-dlp from the yt-dlp section of the admin panel. This will run the value of the YOUTUBE_DL_UPDATE_COMMAND environment variable.
Navigate to the page of the channel/uploader and click the current icon to replace it.
Channel/uploader icons can be automatically downloaded from the Uploader icons section of the admin panel. Icons are downloaded using the third-party service unavatar.io. The icon downloader currently only supports YouTube and SoundCloud.
To change the output directory stop the web app and set the environment variable OUTPUT_DIRECTORY to the new location. Move the contents from the previous output directory to the new one. You do not need to update anything else.
If you need more space than a single hard drive can offer try using a drive pooling solution like DrivePool.
Videos can be deleted the Delete videos section of the admin panel.
If you are deleting videos because you are running low on storage be aware that the actual video files are not deleted from the disk until the web app is restarted.
These files are located at the root of the output directory. You can also view them from the Logs section of the admin panel.
You can access the web app from other devices on your local network by replacing localhost with the ip address of the device the web app is running on. You can find this by running ipconfig on Windows or ip addr on Linux. If the web app does not load check if your firewall settings are blocking Node.js or Docker Desktop Backend, or if your router is blocking communication between devices.
- Install the MongoDB Command Line Database Tools
- Run
mongodump /d youtubeDlDBto backup the database to the disk
- Run
docker exec -it youtube-dl-react-viewer-db-1 /bin/bashto open a new shell session in the database container - In the new session run
mongodump /d youtubeDlDBto backup the database to the disk - Exit the session and run
docker cp youtube-dl-react-viewer-db-1:/dump/youtubeDlDB "C:\Your Backups Folder\youtubeDlDB"to copy the backup from the docker container to your disk
Planned features in no particular order. There is no timeline or guarantee features will be added.
In release 1.2.1:
- Import already downloaded videos
- Docker container
- Video channel/uploader pages
- Update yt-dlp from the web app
In release 1.3.0:
- Watch history
- Video playback resume
- Dark theme
- Verify the integrity of video file hashes
- SponsorBlock integration
- Display video chapters in the player
- Chat replay (YouTube only)
In release 1.3.1
- User setting to hide shorts
In release 1.4.0
- Return YouTube Dislike integration
In release 1.4.1
- API key system
In release 1.5.0
- Search and sort for uploaders, playlists, and jobs
- Audio only playback mode
Planned for future releases:
- Create custom playlists, favorites, comments
- 3D/VR video playback
- Refetch updated metadata for downloaded videos
- Twitch chat replay
- API documentation
- The function
doProbeSync()in./youtube-dl-express-backend/exec.jsis based on node-ffprobe, MIT - Created with facebook/create-react-app, MIT
- Permission to mirror the videos in the live demo obtained from Public Domain Films
- Original Dockerfile created by JamoDevNich
- SponsorBlock API from SponsorBlock
- See packages for additional licenses
youtube-dl-react-viewer is free and open-source software. This software is provided "as-is", without warranty of any kind. See the LICENSE file for more details.
