# uptodownbot

Telegram bot for downloading media from any site yt-dlp supports.

## Features

- Download audio, video, or combined audio+video from YouTube, Spotify, SoundCloud, Vimeo, and hundreds more
- Search support: search YouTube/YouTube Music by name when no URL is provided
- DRM fallback: automatically searches YouTube when Spotify/DRM-protected content is detected
- Thumbnail preview with metadata (title, uploader, duration) before download
- Audio-only sites (Spotify, SoundCloud, YouTube Music, etc.) auto-detect and skip to audio quality selection
- Multi-step format selection: type picker (Video/Audio/Ask), quality, secondary format (video+audio combine), language
- Auto-select: skip the format picker entirely when defaults are set in user preferences
- Download progress updates (with speed and ETA)
- Cancel downloads at any time (terminates yt-dlp process)
- Per-user quota system (daily, weekly, monthly; 0 = unlimited)
- User preferences (default media type, audio/video quality, language)
- Download history with pagination
- Configurable file size limit (default 50 MB)
- Cookies support for age-restricted and authenticated content
- Proxy support via HTTP_PROXY/HTTPS_PROXY env vars
- Webhook and polling modes
- SQLite database for persistence
- yt-dlp plugin support — `hanime-plugin` bundled in Docker image

## Commands

- `/start` - Show main menu
- `/download` - Prompt for a download URL
- `/settings` - Open settings
- `/help` - Show help text
- `/history` - View download history

You can also send a URL directly to start downloading immediately.

## Configuration

Copy `.env.example` to `.env` and configure:

| Variable            | Default            | Description                      |
| ------------------- | ------------------ | -------------------------------- |
| `BOT_TOKEN`         | (required)         | Telegram Bot API token           |
| `HTTP_PROXY`        | empty              | Outbound HTTP proxy              |
| `HTTPS_PROXY`       | empty              | Outbound HTTPS proxy             |
| `DB_PATH`           | `data/uptodown.db` | SQLite database path             |
| `DOWNLOAD_DIR`      | `/tmp/uptodown`    | Temporary download directory     |
| `MAX_FILE_SIZE_MB`  | `50`               | Maximum upload file size in MB   |
| `COOKIES_FILE`      | empty              | Path to cookies.txt for auth     |
| `TZ`                | `UTC`              | Timezone                         |
| `BOT_ALLOWED_USERS` | empty              | Comma-separated allowed user IDs |
| `BOT_WEBHOOK_URL`   | empty              | Webhook URL (omit for polling)   |
| `BOT_LISTEN`        | `:8080`            | Webhook listen address           |
| `BOT_TLS_CERT`      | empty              | TLS certificate path             |
| `BOT_TLS_KEY`       | empty              | TLS key path                     |

### Cookies (for age-restricted and authenticated content)

Some sites (YouTube, Spotify, etc.) require cookies for age-restricted content. To set up:

1. Install a browser extension that exports cookies in Netscape format (e.g., "Get cookies.txt" for Chrome/Firefox).
2. Log into the site with a throwaway account.
3. Export cookies to a file named `cookies.txt` in the project root.
4. Set `COOKIES_FILE=/cookies.txt` in your `.env` file.

For Docker, the cookie file is automatically mounted from `./cookies.txt` (see `docker-compose.yml`).

## Running

### Polling mode (default)

```bash
cp .env.example .env
# edit .env with your BOT_TOKEN
make run-dev
```

### Webhook mode

```bash
export BOT_WEBHOOK_URL=https://your.domain.com/webhook
make run-dev
```

### Docker

```bash
make docker-run
```

The Docker image bundles the `hanime-plugin` and the Deno JS runtime for sites like
hanime.tv, hstream.moe, and hentaihaven.com. See [yt-dlp plugins](#yt-dlp-plugins) for details.

### Local (non-Docker)

If running outside Docker, the bot uses whatever yt-dlp is in your PATH.
Install plugins and a JS runtime as described below under [yt-dlp plugins](#yt-dlp-plugins).

## yt-dlp plugins

Some sites require yt-dlp plugins or a JavaScript runtime to work. The Docker image
bundles these automatically; for local installs you need to set them up manually.

### hanime-plugin

Adds support for hanime.tv, hstream.moe, hentaihaven.com and others.

```bash
pip install hanime-plugin
```

The plugin requires a JavaScript runtime. [Deno](https://deno.com) is recommended:

```bash
# Linux/macOS
curl -fsSL https://deno.land/install.sh | sh

# Add to your shell config:
export PATH="$HOME/.deno/bin:$PATH"
```

### Adding other plugins

yt-dlp plugins are Python packages installed via pip. Most work without
additional runtimes. Install any pip-installable yt-dlp plugin with:

```bash
pip install <plugin-name>
```

## Development

```bash
make build      # build binary
make test       # run tests
make fmt        # format code
make vet        # vet code
make check      # fmt + vet
```