Chompy

Download and watch videos easily on iOS

Chompy wraps youtube-dl in an API, allowing ad-free downloading and streaming on devices that can't run youtube-dl directly, such as iOS.

Usage

Docker images located at ghcr.io/hebo/chompy

1. Run Docker image

docker cli

docker run -p 8000:8000 \
  -e TZ=America/Los_Angeles \
  -e FORMAT= `#optional` \
  -e PLAYLIST_SYNC= `#optional` \
  -e MAX_SIZE= `#optional (in MiB)` \
  -v /path/to/downloads:/downloads \
  --restart unless-stopped \
  ghcr.io/hebo/chompy

2. Install the associated shortcut and set your hostname.
3. Trigger a download by sharing a video URL to the shortcut. You can exit while the shortcut is downloading, but you won't be automatically redirected when the download completes.

Show all downloads

You can see all the videos downloaded by visiting /videos

Video Formats

The default format for downloaded videos is mp4, at resolutions up to 1080p. You can see the format string in downloader/options.go.

Set the format for a download by setting the format request parameter. Details on format strings in youtube-dl docs. For instance:

http -v post localhost:8000/download url="https://www.youtube.com/watch?v=L5emxkKNf9Y" format='worstvideo'

To change the default format for all downloads, set the FORMAT env variable

Playlist Sync

Chompy can automatically download videos from a Youtube playlist, including your "Watch Later" list. To enable this, set the PLAYLIST_SYNC environment variable.

To sync private playlists (such as the "Watch Later" playlist), you need to add your cookies in a file named .ytdl-cookies.txt within the downloads folder. See the youtube-dl instructions for how to extract cookies into the correct format.

docker run -e "PLAYLIST_SYNC=https://www.youtube.com/playlist?list=PLMM9FcCPG72z8fGbr-R4mLXebKcV45tkR" chompy

Limit Disk Usage

Chompy can delete videos (oldest first) to keep disk usage within a specified limit. Set the MAX_SIZE environment variable (in MiB) to enable. Video deletion occurs after every successful download.

ex.

-e MAX_SIZE=1024 # limit to 1 GiB

Note that we can't predict the size of a downloaded video, so the disk usage may exceed your specified limit temporarily until cleanup is performed.

Authentication with .netrc

Chompy can authenticate to sites by placing credentials in the NETRC_CONTENTS env variable, written in the .netrc format and base64-encoded:

echo "machine watchnebula login myaccount@gmail.com password my_password" | base64
# bWFjaGluZSBuZWJ1bGEgbG9na...

Development

Run locally

Dependencies: ffmpeg and yt-dlp. API examples use HTTPie

Run the app

go run ./cmd/chompy

Download something exciting

http -v post localhost:8000/download url="https://www.youtube.com/watch?v=L5emxkKNf9Y"

HTTP/1.1 200 OK
Content-Length: 168
Content-Type: application/json; charset=UTF-8
Date: Thu, 24 Dec 2020 23:40:11 GMT

{
    "filename": "How to Protect Your Shopping Trolley From Improvised Explosives.mp4",
    "path": "/videos/How to Protect Your Shopping Trolley From Improvised Explosives.mp4"
}

Then play it

http 'localhost:8000/videos/How to Protect Your Shopping Trolley From Improvised Explosives.mp4'
HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Length: 34311123
Content-Type: video/mp4

Docker

docker build -t chompy .

docker run -p 8000:8000 --env TZ=America/Los_Angeles chompy