description:"Welcome to the official docs for YoutubeDL-Material.\n\n\nYou can check out all the available endpoints. Remember to authenticate with your API key using the \"apiKey\" query parameter with your requests.\n\n\nTo do so, simply add this to the end of your API call:\n\n\n`?apiKey=API_KEY`\n\n\nReplce API_KEY with the API key in the settings menu. If one doesn't exist, click generate to create one.\n\n### Multi-user mode\n\nWhen using multi-user mode, you will need to supply a JWT token to authenticate requests through that user. This lets the server know which user to run the task for, like downloading a video for a specific user. \n\nTo do this, you must use the `/api/auth/login` endpoint to login using a user's username and password. This will result in an object containing a `token`. Supply this along with your API key like so:\n\n`?apiKey=API_KEY&jwt=JWT_TOKEN`\n\nNotice the `&` between the `API_KEY` and `jwt`."
YoutubeDL-Material is a Material Design frontend for [youtube-dl](https://rg3.github.io/youtube-dl/) / yt-dlp workflows. It's coded using [Angular 21](https://angular.dev/) for the frontend, and [Node.js](https://nodejs.org/) on the backend.
Current builds require Node.js 24 (`>=24 <26`),soCentOS7isnolongerasupportedhostfornativeinstalls.UseDockeroranewerdistro.
</details>
### Installing
If you are using Docker, skip to the [Docker](#Docker) section. Otherwise, continue:
@ -111,13 +101,16 @@ The repo currently uses Angular 21 and `@videogular/ngx-videogular@20`. Videogul
Please keep this file when building locally or in Docker until Videogular publishes Angular 21 peer support.
Lastly, type `npm -g install pm2` to install pm2 globally.
### Run backend
The frontend is now complete. The backend is much easier. Just go into the `backend` folder, and type `npm start`.
Install `pm2` globally, then start the backend:
Finally, if you want your instance to be available from outside your network, you can set up a [reverse proxy](https://github.com/voc0der/YoutubeDL-Material/wiki/Reverse-Proxy-Setup).
```bash
npm -g install pm2
npm start --prefix backend
```
Alternatively, you can port forward the port specified in the config (defaults to `17442`) and point it to the server's IP address. Make sure the port is also allowed through the server's firewall.
If you want your instance available outside your network, set up a [reverse proxy](https://github.com/voc0der/YoutubeDL-Material/wiki/Reverse-Proxy-Setup) or port forward the configured backend port (default `17442`).
## Docker
@ -136,31 +129,39 @@ If you are looking to setup YoutubeDL-Material with Docker, this section is for
3. Run `docker compose up -d` (or `docker-compose up -d`) to start it up. The container exposes port `17442` internally. Please check your `docker-compose.yml` file for the *external* port. If you downloaded the file as described above, it defaults to **8998**.
4. Make sure you can connect to the specified URL + *external* port, and if so, you are done!
### Custom UID/GID
By default, the Docker container runs as non-root with UID=1000 and GID=1000. To set this to your own UID/GID, simply update the `environment` section in your `docker-compose.yml` like so:
```yml
environment:
UID: YOUR_UID
GID: YOUR_GID
```
### Logging
<details>
<summary>Docker environment variables (click to expand)</summary>
You can control backend log verbosity with the `YTDL_LOG_LEVEL` environment variable (or `ytdl_log_level`).
Common Docker env vars used by the provided `docker-compose.yml` (plus logging):
- Default: `info` (mostly startup messages, warnings, and errors)
- Use `debug` to enable verbose yt-dlp/debug diagnostics
If you prefer, you can also use Docker's `user: "UID:GID"` setting instead of `UID`/`GID`.
</details>
## MongoDB
For much better scaling with large datasets please run your YoutubeDL-Material instance with MongoDB backend rather than the json file-based default. It will fix a lot of performance problems (especially with datasets in the tens of thousands videos/audios)!
@ -175,12 +176,6 @@ To get started, go to the settings menu and enable the public API from the *Extr
Once you have enabled the API and have the key, you can start sending requests by adding the query param `apiKey=API_KEY`. Replace `API_KEY` with your actual API key, and you should be good to go! Nearly all of the backend should be at your disposal. View available endpoints in the link above.
## iOS Shortcut
If you are using iOS, try YoutubeDL-Material more conveniently with a Shortcut. With this Shorcut, you can easily start downloading YouTube video with just two taps! (Or maybe three?)
You can download Shortcut [here.](https://routinehub.co/shortcut/10283/)
## Contributing
If you're interested in contributing, first: awesome! Second, please refer to the guidelines/setup information located in the [Contributing](https://github.com/voc0der/YoutubeDL-Material/wiki/Contributing) wiki page, it's a helpful way to get you on your feet and coding away.
If you would like to see the latest updates, use the `nightly` tag on Docker.
If you'd like to stick with more stable releases, use the `latest` tag on Docker or download the [latest release here](https://github.com/Tzahi12345/YoutubeDL-Material/releases/latest).
If you'd like to stick with more stable releases, use the `latest` tag on Docker or download the [latest release here](https://github.com/voc0der/YoutubeDL-Material/releases/latest).
<p><ahref="https://github.com/Tzahi12345/YoutubeDL-Material/blob/master/chrome-extension/youtubedl-material-chrome-extension.zip?raw=true"><ng-containeri18n="Chrome ext click here">Click here</ng-container></a> <ng-containeri18n="Chrome click here suffix">to download the official YoutubeDL-Material Chrome extension manually.</ng-container></p>
<p><ahref="https://github.com/voc0der/YoutubeDL-Material/blob/master/chrome-extension/youtubedl-material-chrome-extension.zip?raw=true"><ng-containeri18n="Chrome ext click here">Click here</ng-container></a> <ng-containeri18n="Chrome click here suffix">to download the official YoutubeDL-Material Chrome extension manually.</ng-container></p>
<p><ng-containeri18n="Chrome setup suffix">You must manually load the extension and modify the extension's settings to set the frontend URL.</ng-container></p>
<mat-dividerclass="ext-divider"></mat-divider>
</div>
<divclass="col-12">
<h6>Firefox</h6>
<p><ahref="https://addons.mozilla.org/en-US/firefox/addon/youtubedl-material/"target="_blank"><ng-containeri18n="Firefox ext click here">Click here</ng-container></a> <ng-containeri18n="Firefox click here suffix">to install the official YoutubeDL-Material Firefox extension right off the Firefox extensions page.</ng-container></p>
<p><ahref="https://github.com/Tzahi12345/YoutubeDL-Material/wiki/Firefox-Extension" target="_blank"><ng-containeri18n="Firefox setup prefix link">Detailed setup instructions.</ng-container></a> <ng-containeri18n="Firefox setup suffix">Not much is required other than changing the extension's settings to set the frontend URL.</ng-container></p>
<p><ahref="https://github.com/voc0der/YoutubeDL-Material/wiki/Firefox-Extension" target="_blank"><ng-containeri18n="Firefox setup prefix link">Detailed setup instructions.</ng-container></a> <ng-containeri18n="Firefox setup suffix">Not much is required other than changing the extension's settings to set the frontend URL.</ng-container></p>
voc0der
2 months ago