Very spartan Web and REST interface for downloading YouTube videos onto a server. starlette + yt-dlp.

This example uses the docker run command to create the container to run the app. Here we also use host networking for simplicity. Also note the -v argument. This directory will be used to output the resulting videos.

docker run -d --net="host" --name youtube-dl-server -v /home/core/youtube-dl:/youtube-dl qx6ghqkz/youtube-dl-server:latest

This is an example service definition that could be put in docker-compose.yml. This service uses a VPN client container for its networking.

  youtube-dl-server:
    image: qx6ghqkz/youtube-dl-server:latest
    network_mode: container:vpn
    volumes:
      - /home/core/youtube-dl:/youtube-dl
    restart: unless-stopped

If you have Python ^3.6.0 installed in your PATH you can simply run like this, providing optional environment variable overrides inline.

YDL_UPDATE_TIME=False python3 -m uvicorn youtube-dl-server:app --port 8123

In this example, YDL_UPDATE_TIME=False is the same as the command line option --no-mtime.

Environment variables can be set to change different settings, for example using docker run.

docker run -d \
  --name youtube-dl-server \
  --user 1000:1000 \
  -p 8080:8080 \
  -v /path/to/data:/data \
  --mount type=bind,source=/path/to/videos,target=/youtube-dl \
  -e YDL_FORMAT="bestvideo[ext=mp4]+bestaudio[ext=m4a]/bestvideo+bestaudio/best" \
  -e YDL_MERGE_OUTPUT_FORMAT="mp4/mkv" \
  -e YDL_OUTPUT_TEMPLATE="/youtube-dl/%(title).200s [%(id)s].%(ext)s" \
  -e YDL_NO_PLAYLIST=True \
  -e YDL_ARCHIVE_FILE="/data/archive.txt" \
  -e YDL_COOKIES_FILE="/data/cookies.txt" \
  -e YDL_IGNORE_ERRORS=True \
  -e YDL_WRITE_THUMBNAIL=True \
  -e YDL_THUMBNAIL_FORMAT="png/jpg" \
  -e YDL_WRITE_SUBTITLES=True \
  -e YDL_SUBTITLES_FORMAT="srt/vtt/best" \
  -e YDL_CONVERT_SUBTITLES="srt" \
  -e YDL_SUBTITLES_LANGS="en.*,ja" \
  -e YDL_EMBED_METADATA=True \
  --restart unless-stopped \
  qx6ghqkz/youtube-dl-server:latest

Environment variables can also be placed in a .env file when using docker compose up.

For more information on these options, see the yt-dlp docs and YouTubeDL object parameters.

Downloads can be triggered by supplying the {{url}} of the requested video through the Web UI or through the REST interface via curl, etc.

Just navigate to http://{{host}}:8080/youtube-dl and enter the requested {{url}}.

curl -X POST --data-urlencode "url={{url}}" http://{{host}}:8080/youtube-dl/q

fetch(`http://${host}:8080/youtube-dl/q`, {
  method: "POST",
  body: new URLSearchParams({
    url: url,
    format: "bestvideo"
  }),
});

Add the following bookmarklet to your bookmark bar so you can conveniently send the current page URL to your youtube-dl-server instance.

javascript:!function(){fetch("http://${host}:8080/youtube-dl/q",{body:new URLSearchParams({url:window.location.href,format:"bestvideo"}),method:"POST"})}();

The server uses starlette for the web framework and yt-dlp to handle the downloading. The integration with yt-dlp makes use of their Python API.

The Docker image is based on python:alpine and consequently alpine.