fix yt-dlp options overrides (closes #958)

Bumps the github-actions group with 1 update: [softprops/action-gh-release](https://github.com/softprops/action-gh-release).


Updates `softprops/action-gh-release` from 2 to 3
- [Release notes](https://github.com/softprops/action-gh-release/releases)
- [Changelog](https://github.com/softprops/action-gh-release/blob/master/CHANGELOG.md)
- [Commits](https://github.com/softprops/action-gh-release/compare/v2...v3)

---
updated-dependencies:
- dependency-name: softprops/action-gh-release
  dependency-version: '3'
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: github-actions
...

Signed-off-by: dependabot[bot] <support@github.com>

.github/dependabot.yml

@@ -0,0 +1,13 @@
+# Keep GitHub Actions up to date with GitHub's Dependabot...
+# https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot
+# https://docs.github.com/en/code-security/dependabot/working-with-dependabot/dependabot-options-reference#package-ecosystem
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    groups:
+      github-actions:
+        patterns:
+          - "*"  # Group all Actions updates into a single larger pull request
+    schedule:
+      interval: weekly

.github/workflows/main.yml

@@ -4,40 +4,84 @@ on:
   push:
     branches:
       - 'master'
+    paths-ignore:
+      - '**.md'
 
 jobs:
+  quality-checks:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: lts/*
+      - name: Enable pnpm
+        run: corepack enable
+      - name: Install frontend dependencies
+        working-directory: ui
+        run: pnpm install --frozen-lockfile
+      - name: Run frontend lint
+        working-directory: ui
+        run: pnpm run lint
+      - name: Build frontend
+        working-directory: ui
+        run: pnpm run build
+      - name: Run frontend tests
+        working-directory: ui
+        run: pnpm exec ng test --watch=false
+        env:
+          CI: true
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Install Python dependencies
+        run: uv sync --frozen --group dev
+      - name: Run backend smoke checks
+        run: python -m compileall app
+      - name: Run backend tests
+        run: uv run pytest app/tests/
+      - name: Run Trivy filesystem scan
+        uses: aquasecurity/trivy-action@0.35.0
+        with:
+          scan-type: fs
+          scan-ref: .
+          format: table
+          severity: CRITICAL,HIGH
+
   dockerhub-build-push:
+    needs: quality-checks
     runs-on: ubuntu-latest
     steps:
       -
         name: Get current date
         id: date
-        run: echo "::set-output name=date::$(date +'%Y.%m.%d')"
+        run: echo "date=$(date +'%Y.%m.%d')" >> "$GITHUB_OUTPUT"
       -
         name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
       -
         name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
+        uses: docker/setup-qemu-action@v4
       -
         name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
       -
         name: Login to DockerHub
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
       -
         name: Login to GitHub Container Registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           registry: ghcr.io
           username: ${{ github.repository_owner }}
           password: ${{ secrets.GITHUB_TOKEN }}
       -
         name: Build and push
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@v7
         with:
           context: .
           platforms: linux/amd64,linux/arm64
@@ -74,7 +118,7 @@ jobs:
         id: date
         run: echo "date=$(date +'%Y.%m.%d')" >> $GITHUB_OUTPUT
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
       - name: Get commits since last release
@@ -167,7 +211,7 @@ jobs:
             git push origin ":refs/tags/$TAG_NAME" || true
           fi
       - name: Create GitHub Release
-        uses: softprops/action-gh-release@v1
+        uses: softprops/action-gh-release@v3
         with:
           tag_name: ${{ steps.date.outputs.date }}
           name: Release ${{ steps.date.outputs.date }}

.github/workflows/update-yt-dlp.yml

@@ -10,17 +10,17 @@ jobs:
     steps:
       -
         name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           token: ${{ secrets.AUTOUPDATE_PAT }}
       -
         name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v6
         with:
           python-version: '3.13'
       -
         name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@v7
       -
         name: Update yt-dlp
         run: |

.gitignore

@@ -7,6 +7,7 @@
 
 # dependencies
 /ui/node_modules
+/ui/package-lock.json
 
 # profiling files
 chrome-profiler-events*.json

.vscode/launch.json

@@ -13,12 +13,16 @@
                 "env": {
                     "DOWNLOAD_DIR": "${env:USERPROFILE}/Downloads",
                     "STATE_DIR": "${env:TEMP}",
+                    "ALLOW_YTDL_OPTIONS_OVERRIDES": "true",
+                    "YTDL_OPTIONS_PRESETS": "{\"sponsorblock\": {\"postprocessors\": [{\"key\": \"SponsorBlock\", \"categories\": [\"sponsor\", \"selfpromo\", \"interaction\"]}, {\"key\": \"ModifyChapters\", \"remove_sponsor_segments\": [\"sponsor\", \"selfpromo\", \"interaction\"]}]}, \"embed-subs\": {\"writesubtitles\": true, \"writeautomaticsub\": true, \"subtitleslangs\": [\"en\", \"de\"], \"postprocessors\": [{\"key\": \"FFmpegEmbedSubtitle\"}]}, \"limit-rate\": {\"ratelimit\": 5000000}}",
                 }
             },
             "osx": {
                 "env": {
                     "DOWNLOAD_DIR": "${env:HOME}/Downloads",
                     "STATE_DIR": "${env:TMPDIR}",
+                    "ALLOW_YTDL_OPTIONS_OVERRIDES": "true",
+                    "YTDL_OPTIONS_PRESETS": "{\"sponsorblock\": {\"postprocessors\": [{\"key\": \"SponsorBlock\", \"categories\": [\"sponsor\", \"selfpromo\", \"interaction\"]}, {\"key\": \"ModifyChapters\", \"remove_sponsor_segments\": [\"sponsor\", \"selfpromo\", \"interaction\"]}]}, \"embed-subs\": {\"writesubtitles\": true, \"writeautomaticsub\": true, \"subtitleslangs\": [\"en\", \"de\"], \"postprocessors\": [{\"key\": \"FFmpegEmbedSubtitle\"}]}, \"limit-rate\": {\"ratelimit\": 5000000}}",
                 }
             },
             "console": "integratedTerminal"

AGENTS.md

@@ -0,0 +1,60 @@
+# Agent Guidelines
+
+## README.md size constraint
+
+The README.md is synced to Docker Hub, which has a **25,000 character limit**.
+Any change to README.md **must** keep the file under 25,000 characters (`wc -c README.md`).
+If an addition would exceed the limit, trim existing prose elsewhere — prefer tightening verbose descriptions over removing sections.
+
+## Tech stack
+
+- **Backend:** Python 3.13+, aiohttp, python-socketio 5.x, yt-dlp
+- **Frontend:** Angular 21, TypeScript, Bootstrap 5, SASS, ngx-socket-io
+- **Package managers:** uv (Python), pnpm (frontend)
+- **Container:** Multi-stage Docker (Node builder + Python runtime), multi-arch (amd64/arm64)
+
+## Build & test commands
+
+```bash
+# Frontend (run from ui/)
+pnpm install --frozen-lockfile
+pnpm run lint
+pnpm run build
+pnpm exec ng test --watch=false
+
+# Backend (run from repo root)
+uv sync --frozen --group dev
+python -m compileall app
+uv run pytest app/tests/
+```
+
+All of these run in CI (`.github/workflows/main.yml`) on every push to master and must pass.
+
+## Code style
+
+Follow `.editorconfig`:
+- Python: 4-space indent
+- Everything else (TypeScript, YAML, JSON, HTML): 2-space indent
+- UTF-8, LF line endings, trim trailing whitespace, final newline
+
+Frontend additionally uses ESLint (`ui/eslint.config.js`) and Prettier (config in `ui/package.json`: `printWidth=100`, `singleQuote=true`).
+
+## Project structure
+
+```
+app/main.py          — HTTP server, Socket.IO events, REST API routes, Config class
+app/ytdl.py          — Download queue logic, yt-dlp integration
+app/subscriptions.py — Channel/playlist subscription manager
+app/state_store.py   — JSON-based persistent storage with atomic writes
+app/dl_formats.py    — Video/audio codec/quality mapping
+app/tests/           — pytest tests (asyncio_mode=auto)
+ui/src/app/          — Angular standalone components (no NgModules)
+```
+
+## Key conventions
+
+- Backend configuration lives in the `Config` class in `app/main.py` with env-var defaults in `_DEFAULTS`. New env vars go there.
+- Real-time communication uses Socket.IO events, not REST polling.
+- Frontend uses standalone Angular components with `inject()` for DI, RxJS Subjects for state, and `takeUntilDestroyed()` for cleanup.
+- State is persisted as JSON files via `AtomicJsonStore` in `app/state_store.py`.
+- No pre-commit hooks — linting and tests are enforced in CI only.

Dockerfile

@@ -1,43 +1,75 @@
-FROM node:lts-alpine AS builder
-
-WORKDIR /metube
-COPY ui ./
-RUN npm ci && \
-    node_modules/.bin/ng build --configuration production
-
-
-FROM python:3.13-alpine
-
-WORKDIR /app
-
-COPY pyproject.toml uv.lock docker-entrypoint.sh ./
-
-# Use sed to strip carriage-return characters from the entrypoint script (in case building on Windows)
-# Install dependencies
-RUN sed -i 's/\r$//g' docker-entrypoint.sh && \
-    chmod +x docker-entrypoint.sh && \
-    apk add --update ffmpeg aria2 coreutils shadow su-exec curl tini deno && \
-    apk add --update --virtual .build-deps gcc g++ musl-dev uv && \
-    UV_PROJECT_ENVIRONMENT=/usr/local uv sync --frozen --no-dev --compile-bytecode && \
-    apk del .build-deps && \
-    rm -rf /var/cache/apk/* && \
-    mkdir /.cache && chmod 777 /.cache
-
-COPY app ./app
-COPY --from=builder /metube/dist/metube ./ui/dist/metube
-
-ENV UID=1000
-ENV GID=1000
-ENV UMASK=022
-
-ENV DOWNLOAD_DIR /downloads
-ENV STATE_DIR /downloads/.metube
-ENV TEMP_DIR /downloads
-VOLUME /downloads
-EXPOSE 8081
-
-# Add build-time argument for version
-ARG VERSION=dev
-ENV METUBE_VERSION=$VERSION
-
-ENTRYPOINT ["/sbin/tini", "-g", "--", "./docker-entrypoint.sh"]
+FROM node:lts-alpine AS builder
+
+WORKDIR /metube
+COPY ui ./
+RUN corepack enable && corepack prepare pnpm --activate
+RUN CI=true pnpm install && pnpm run build
+
+
+FROM python:3.13-slim
+
+WORKDIR /app
+
+COPY pyproject.toml uv.lock docker-entrypoint.sh ./
+
+# Use sed to strip carriage-return characters from the entrypoint script (in case building on Windows)
+# Install dependencies
+RUN sed -i 's/\r$//g' docker-entrypoint.sh && \
+    chmod +x docker-entrypoint.sh && \
+    apt-get update && \
+    apt-get install -y --no-install-recommends \
+      ca-certificates \
+      ffmpeg \
+      unzip \
+      aria2 \
+      coreutils \
+      gosu \
+      curl \
+      tini \
+      build-essential && \
+    curl -LsSf https://astral.sh/uv/install.sh | UV_INSTALL_DIR=/usr/local/bin sh && \
+    UV_PROJECT_ENVIRONMENT=/usr/local uv sync --frozen --no-dev --compile-bytecode && \
+    uv cache clean && \
+    rm -f /usr/local/bin/uv /usr/local/bin/uvx /usr/local/bin/uvw && \
+    curl -fsSL https://deno.land/install.sh | DENO_INSTALL=/usr/local sh -s -- -y && \
+    apt-get purge -y --auto-remove build-essential && \
+    rm -rf /var/lib/apt/lists/* && \
+    mkdir /.cache && chmod 777 /.cache
+
+ARG TARGETARCH
+
+RUN BGUTIL_TAG="$(curl -Ls -o /dev/null -w '%{url_effective}' https://github.com/jim60105/bgutil-ytdlp-pot-provider-rs/releases/latest | sed 's#.*/tag/##')" && \
+    case "$TARGETARCH" in \
+      amd64) BGUTIL_ARCH="x86_64" ;; \
+      arm64) BGUTIL_ARCH="aarch64" ;; \
+      *) echo "Unsupported TARGETARCH: $TARGETARCH" >&2; exit 1 ;; \
+    esac && \
+    curl -L -o /usr/local/bin/bgutil-pot \
+      "https://github.com/jim60105/bgutil-ytdlp-pot-provider-rs/releases/download/${BGUTIL_TAG}/bgutil-pot-linux-${BGUTIL_ARCH}" && \
+    chmod +x /usr/local/bin/bgutil-pot && \
+    PLUGIN_DIR="$(python3 -c 'import site; print(site.getsitepackages()[0])')" && \
+    curl -L -o /tmp/bgutil-ytdlp-pot-provider-rs.zip \
+      "https://github.com/jim60105/bgutil-ytdlp-pot-provider-rs/releases/download/${BGUTIL_TAG}/bgutil-ytdlp-pot-provider-rs.zip" && \
+    unzip -q /tmp/bgutil-ytdlp-pot-provider-rs.zip -d "${PLUGIN_DIR}" && \
+    rm /tmp/bgutil-ytdlp-pot-provider-rs.zip
+
+COPY app ./app
+COPY --from=builder /metube/dist/metube ./ui/dist/metube
+
+ENV PUID=1000
+ENV PGID=1000
+ENV UMASK=022
+
+ENV DOWNLOAD_DIR=/downloads
+ENV STATE_DIR=/downloads/.metube
+ENV TEMP_DIR=/downloads
+ENV PORT=8081
+VOLUME /downloads
+EXPOSE 8081
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 CMD curl -fsS "http://localhost:${PORT}/" || exit 1
+
+# Add build-time argument for version
+ARG VERSION=dev
+ENV METUBE_VERSION=$VERSION
+
+ENTRYPOINT ["/usr/bin/tini", "-g", "--", "./docker-entrypoint.sh"]

README.md

@@ -1,291 +1,388 @@
-# MeTube
-
-![Build Status](https://github.com/alexta69/metube/actions/workflows/main.yml/badge.svg)
-![Docker Pulls](https://img.shields.io/docker/pulls/alexta69/metube.svg)
-
-Web GUI for youtube-dl (using the [yt-dlp](https://github.com/yt-dlp/yt-dlp) fork) with playlist support. Allows you to download videos from YouTube and [dozens of other sites](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md).
-
-![screenshot1](https://github.com/alexta69/metube/raw/master/screenshot.gif)
-
-## 🐳 Run using Docker
-
-```bash
-docker run -d -p 8081:8081 -v /path/to/downloads:/downloads ghcr.io/alexta69/metube
-```
-
-## 🐳 Run using docker-compose
-
-```yaml
-services:
-  metube:
-    image: ghcr.io/alexta69/metube
-    container_name: metube
-    restart: unless-stopped
-    ports:
-      - "8081:8081"
-    volumes:
-      - /path/to/downloads:/downloads
-```
-
-## ⚙️ Configuration via environment variables
-
-Certain values can be set via environment variables, using the `-e` parameter on the docker command line, or the `environment:` section in docker-compose.
-
-### ⬇️ Download Behavior
-
-* __DOWNLOAD_MODE__: This flag controls how downloads are scheduled and executed. Options are `sequential`, `concurrent`, and `limited`.  Defaults to `limited`:
-    *   `sequential`: Downloads are processed one at a time. A new download won't start until the previous one has finished. This mode is useful for conserving system resources or ensuring downloads occur in strict order.
-    *   `concurrent`: Downloads are started immediately as they are added, with no built-in limit on how many run simultaneously. This mode may overwhelm your system if too many downloads start at once.
-    *   `limited`: Downloads are started concurrently but are capped by a concurrency limit. In this mode, a semaphore is used so that at most a fixed number of downloads run at any given time.
-* __MAX_CONCURRENT_DOWNLOADS__: This flag is used only when `DOWNLOAD_MODE` is set to `limited`.  
-    It specifies the maximum number of simultaneous downloads allowed. For example, if set to `5`, then at most five downloads will run concurrently, and any additional downloads will wait until one of the active downloads completes. Defaults to `3`. 
-* __DELETE_FILE_ON_TRASHCAN__: if `true`, downloaded files are deleted on the server, when they are trashed from the "Completed" section of the UI. Defaults to `false`.
-* __DEFAULT_OPTION_PLAYLIST_STRICT_MODE__: if `true`, the "Strict Playlist mode" switch will be enabled by default. In this mode the playlists will be downloaded only if the URL strictly points to a playlist. URLs to videos inside a playlist will be treated same as direct video URL. Defaults to `false` .
-* __DEFAULT_OPTION_PLAYLIST_ITEM_LIMIT__: Maximum number of playlist items that can be downloaded. Defaults to `0` (no limit).
-
-### 📁 Storage & Directories
-
-* __DOWNLOAD_DIR__: Path to where the downloads will be saved. Defaults to `/downloads` in the Docker image, and `.` otherwise.
-* __AUDIO_DOWNLOAD_DIR__: Path to where audio-only downloads will be saved, if you wish to separate them from the video downloads. Defaults to the value of `DOWNLOAD_DIR`.
-* __CUSTOM_DIRS__: Whether to enable downloading videos into custom directories within the __DOWNLOAD_DIR__ (or __AUDIO_DOWNLOAD_DIR__). When enabled, a dropdown appears next to the Add button to specify the download directory. Defaults to `true`.
-* __CREATE_CUSTOM_DIRS__: Whether to support automatically creating directories within the __DOWNLOAD_DIR__ (or __AUDIO_DOWNLOAD_DIR__) if they do not exist. When enabled, the download directory selector supports free-text input, and the specified directory will be created recursively. Defaults to `true`.
-* __CUSTOM_DIRS_EXCLUDE_REGEX__: Regular expression to exclude some custom directories from the dropdown. Empty regex disables exclusion. Defaults to `(^|/)[.@].*$`, which means directories starting with `.` or `@`.
-* __DOWNLOAD_DIRS_INDEXABLE__: If `true`, the download directories (__DOWNLOAD_DIR__ and __AUDIO_DOWNLOAD_DIR__) are indexable on the web server. Defaults to `false`.
-* __STATE_DIR__: Path to where the queue persistence files will be saved. Defaults to `/downloads/.metube` in the Docker image, and `.` otherwise.
-* __TEMP_DIR__: Path where intermediary download files will be saved. Defaults to `/downloads` in the Docker image, and `.` otherwise.
-  * Set this to an SSD or RAM filesystem (e.g., `tmpfs`) for better performance.
-  * __Note__: Using a RAM filesystem may prevent downloads from being resumed.
-
-### 📝 File Naming & yt-dlp
-
-* __OUTPUT_TEMPLATE__: The template for the filenames of the downloaded videos, formatted according to [this spec](https://github.com/yt-dlp/yt-dlp/blob/master/README.md#output-template). Defaults to `%(title)s.%(ext)s`.
-* __OUTPUT_TEMPLATE_CHAPTER__: The template for the filenames of the downloaded videos when split into chapters via postprocessors. Defaults to `%(title)s - %(section_number)s %(section_title)s.%(ext)s`.
-* __OUTPUT_TEMPLATE_PLAYLIST__: The template for the filenames of the downloaded videos when downloaded as a playlist. Defaults to `%(playlist_title)s/%(title)s.%(ext)s`. When empty, then `OUTPUT_TEMPLATE` is used.
-* __YTDL_OPTIONS__: Additional options to pass to yt-dlp in JSON format. [See available options here](https://github.com/yt-dlp/yt-dlp/blob/master/yt_dlp/YoutubeDL.py#L222). They roughly correspond to command-line options, though some do not have exact equivalents here. For example, `--recode-video` has to be specified via `postprocessors`. Also note that dashes are replaced with underscores. You may find [this script](https://github.com/yt-dlp/yt-dlp/blob/master/devscripts/cli_to_api.py) helpful for converting from command-line options to `YTDL_OPTIONS`.
-* __YTDL_OPTIONS_FILE__: A path to a JSON file that will be loaded and used for populating `YTDL_OPTIONS` above. Please note that if both `YTDL_OPTIONS_FILE` and `YTDL_OPTIONS` are specified, the options in `YTDL_OPTIONS` take precedence. The file will be monitored for changes and reloaded automatically when changes are detected.
-
-### 🌐 Web Server & URLs
-
-* __URL_PREFIX__: Base path for the web server (for use when hosting behind a reverse proxy). Defaults to `/`.
-* __PUBLIC_HOST_URL__: Base URL for the download links shown in the UI for completed files. By default, MeTube serves them under its own URL. If your download directory is accessible on another URL and you want the download links to be based there, use this variable to set it.
-* __PUBLIC_HOST_AUDIO_URL__: Same as PUBLIC_HOST_URL but for audio downloads.
-* __HTTPS__: Use `https` instead of `http` (__CERTFILE__ and __KEYFILE__ required). Defaults to `false`.
-* __CERTFILE__: HTTPS certificate file path.
-* __KEYFILE__: HTTPS key file path.
-* __ROBOTS_TXT__: A path to a `robots.txt` file mounted in the container.
-
-### 🏠 Basic Setup
-
-* __UID__: User under which MeTube will run. Defaults to `1000`.
-* __GID__: Group under which MeTube will run. Defaults to `1000`.
-* __UMASK__: Umask value used by MeTube. Defaults to `022`.
-* __DEFAULT_THEME__: Default theme to use for the UI, can be set to `light`, `dark`, or `auto`. Defaults to `auto`.
-* __LOGLEVEL__: Log level, can be set to `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`, or `NONE`. Defaults to `INFO`. 
-* __ENABLE_ACCESSLOG__: Whether to enable access log. Defaults to `false`.
-
-The project's Wiki contains examples of useful configurations contributed by users of MeTube:
-* [YTDL_OPTIONS Cookbook](https://github.com/alexta69/metube/wiki/YTDL_OPTIONS-Cookbook)
-* [OUTPUT_TEMPLATE Cookbook](https://github.com/alexta69/metube/wiki/OUTPUT_TEMPLATE-Cookbook)
-
-## 🍪 Using browser cookies
-
-In case you need to use your browser's cookies with MeTube, for example to download restricted or private videos:
-
-* Add the following to your docker-compose.yml:
-
-```yaml
-    volumes:
-      - /path/to/cookies:/cookies
-    environment:
-      - YTDL_OPTIONS={"cookiefile":"/cookies/cookies.txt"}
-```
-
-* Install in your browser an extension to extract cookies:
-  * [Firefox](https://addons.mozilla.org/en-US/firefox/addon/export-cookies-txt/)
-  * [Chrome](https://chrome.google.com/webstore/detail/get-cookiestxt-locally/cclelndahbckbenkjhflpdbgdldlbecc)
-* Extract the cookies you need with the extension and rename the file `cookies.txt`
-* Drop the file in the folder you configured in the docker-compose.yml above
-* Restart the container
-
-## 🔌 Browser extensions
-
-Browser extensions allow right-clicking videos and sending them directly to MeTube. Please note that if you're on an HTTPS page, your MeTube instance must be behind an HTTPS reverse proxy (see below) for the extensions to work.
-
-__Chrome:__ contributed by [Rpsl](https://github.com/rpsl). You can install it from [Google Chrome Webstore](https://chrome.google.com/webstore/detail/metube-downloader/fbmkmdnlhacefjljljlbhkodfmfkijdh) or use developer mode and install [from sources](https://github.com/Rpsl/metube-browser-extension).
-
-__Firefox:__ contributed by [nanocortex](https://github.com/nanocortex). You can install it from [Firefox Addons](https://addons.mozilla.org/en-US/firefox/addon/metube-downloader) or get sources from [here](https://github.com/nanocortex/metube-firefox-addon).
-
-## 📱 iOS Shortcut
-
-[rithask](https://github.com/rithask) created an iOS shortcut to send URLs to MeTube from Safari. Enter the MeTube instance address when prompted which will be saved for later use. You can run the shortcut from Safari’s share menu. The shortcut can be downloaded from [this iCloud link](https://www.icloud.com/shortcuts/66627a9f334c467baabdb2769763a1a6).
-
-## 📱 iOS Compatibility
-
-iOS has strict requirements for video files, requiring h264 or h265 video codec and aac audio codec in MP4 container. This can sometimes be a lower quality than the best quality available. To accommodate iOS requirements, when downloading a MP4 format you can choose "Best (iOS)" to get the best quality formats as compatible as possible with iOS requirements.
-
-To force all downloads to be converted to an iOS-compatible codec, insert this as an environment variable: 
-
-```yaml
-  environment:
-    - 'YTDL_OPTIONS={"format": "best", "exec": "ffmpeg -i %(filepath)q -c:v libx264 -c:a aac %(filepath)q.h264.mp4"}'
-```
-
-## 🔖 Bookmarklet
-
-[kushfest](https://github.com/kushfest) has created a Chrome bookmarklet for sending the currently open webpage to MeTube. Please note that if you're on an HTTPS page, your MeTube instance must be configured with `HTTPS` as `true` in the environment, or be behind an HTTPS reverse proxy (see below) for the bookmarklet to work.
-
-GitHub doesn't allow embedding JavaScript as a link, so the bookmarklet has to be created manually by copying the following code to a new bookmark you create on your bookmarks bar. Change the hostname in the URL below to point to your MeTube instance.
-
-```javascript
-javascript:!function(){xhr=new XMLHttpRequest();xhr.open("POST","https://metube.domain.com/add");xhr.withCredentials=true;xhr.send(JSON.stringify({"url":document.location.href,"quality":"best"}));xhr.onload=function(){if(xhr.status==200){alert("Sent to metube!")}else{alert("Send to metube failed. Check the javascript console for clues.")}}}();
-```
-
-[shoonya75](https://github.com/shoonya75) has contributed a Firefox version:
-
-```javascript
-javascript:(function(){xhr=new XMLHttpRequest();xhr.open("POST","https://metube.domain.com/add");xhr.send(JSON.stringify({"url":document.location.href,"quality":"best"}));xhr.onload=function(){if(xhr.status==200){alert("Sent to metube!")}else{alert("Send to metube failed. Check the javascript console for clues.")}}})();
-```
-
-The above bookmarklets use `alert()` as a success/failure notification. The following will show a toast message instead:
-
-Chrome:
-
-```javascript
-javascript:!function(){function notify(msg) {var sc = document.scrollingElement.scrollTop; var text = document.createElement('span');text.innerHTML=msg;var ts = text.style;ts.all = 'revert';ts.color = '#000';ts.fontFamily = 'Verdana, sans-serif';ts.fontSize = '15px';ts.backgroundColor = 'white';ts.padding = '15px';ts.border = '1px solid gainsboro';ts.boxShadow = '3px 3px 10px';ts.zIndex = '100';document.body.appendChild(text);ts.position = 'absolute'; ts.top = 50 + sc + 'px'; ts.left = (window.innerWidth / 2)-(text.offsetWidth / 2) + 'px'; setTimeout(function () { text.style.visibility = "hidden"; }, 1500);}xhr=new XMLHttpRequest();xhr.open("POST","https://metube.domain.com/add");xhr.send(JSON.stringify({"url":document.location.href,"quality":"best"}));xhr.onload=function() { if(xhr.status==200){notify("Sent to metube!")}else {notify("Send to metube failed. Check the javascript console for clues.")}}}();
-```
-
-Firefox:
-
-```javascript
-javascript:(function(){function notify(msg) {var sc = document.scrollingElement.scrollTop; var text = document.createElement('span');text.innerHTML=msg;var ts = text.style;ts.all = 'revert';ts.color = '#000';ts.fontFamily = 'Verdana, sans-serif';ts.fontSize = '15px';ts.backgroundColor = 'white';ts.padding = '15px';ts.border = '1px solid gainsboro';ts.boxShadow = '3px 3px 10px';ts.zIndex = '100';document.body.appendChild(text);ts.position = 'absolute'; ts.top = 50 + sc + 'px'; ts.left = (window.innerWidth / 2)-(text.offsetWidth / 2) + 'px'; setTimeout(function () { text.style.visibility = "hidden"; }, 1500);}xhr=new XMLHttpRequest();xhr.open("POST","https://metube.domain.com/add");xhr.send(JSON.stringify({"url":document.location.href,"quality":"best"}));xhr.onload=function() { if(xhr.status==200){notify("Sent to metube!")}else {notify("Send to metube failed. Check the javascript console for clues.")}}})();
-```
-
-## ⚡ Raycast extension
-
-[dotvhs](https://github.com/dotvhs) has created an [extension for Raycast](https://www.raycast.com/dot/metube) that allows adding videos to MeTube directly from Raycast.
-
-## 🔒 HTTPS support, and running behind a reverse proxy
-
-It's possible to configure MeTube to listen in HTTPS mode. `docker-compose` example:
-
-```yaml
-services:
-  metube:
-    image: ghcr.io/alexta69/metube
-    container_name: metube
-    restart: unless-stopped
-    ports:
-      - "8081:8081"
-    volumes:
-      - /path/to/downloads:/downloads
-      - /path/to/ssl/crt:/ssl/crt.pem
-      - /path/to/ssl/key:/ssl/key.pem
-    environment:
-      - HTTPS=true
-      - CERTFILE=/ssl/crt.pem
-      - KEYFILE=/ssl/key.pem
-```
-
-It's also possible to run MeTube behind a reverse proxy, in order to support authentication. HTTPS support can also be added in this way.
-
-When running behind a reverse proxy which remaps the URL (i.e. serves MeTube under a subdirectory and not under root), don't forget to set the URL_PREFIX environment variable to the correct value.
-
-If you're using the [linuxserver/swag](https://docs.linuxserver.io/general/swag) image for your reverse proxying needs (which I can heartily recommend), it already includes ready snippets for proxying MeTube both in [subfolder](https://github.com/linuxserver/reverse-proxy-confs/blob/master/metube.subfolder.conf.sample) and [subdomain](https://github.com/linuxserver/reverse-proxy-confs/blob/master/metube.subdomain.conf.sample) modes under the `nginx/proxy-confs` directory in the configuration volume. It also includes Authelia which can be used for authentication.
-
-### 🌐 NGINX
-
-```nginx
-location /metube/ {
-        proxy_pass http://metube:8081;
-        proxy_http_version 1.1;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
-        proxy_set_header Host $host;
-}
-```
-
-Note: the extra `proxy_set_header` directives are there to make WebSocket work.
-
-### 🌐 Apache
-
-Contributed by [PIE-yt](https://github.com/PIE-yt). Source [here](https://gist.github.com/PIE-yt/29e7116588379032427f5bd446b2cac4).
-
-```apache
-# For putting in your Apache sites site.conf
-# Serves MeTube under a /metube/ subdir (http://yourdomain.com/metube/)
-<Location /metube/>
-    ProxyPass http://localhost:8081/ retry=0 timeout=30
-    ProxyPassReverse http://localhost:8081/
-</Location>
-
-<Location /metube/socket.io>
-    RewriteEngine On
-    RewriteCond %{QUERY_STRING} transport=websocket    [NC]
-    RewriteRule /(.*) ws://localhost:8081/socket.io/$1 [P,L]
-    ProxyPass http://localhost:8081/socket.io retry=0 timeout=30
-    ProxyPassReverse http://localhost:8081/socket.io
-</Location>
-```
-
-### 🌐 Caddy
-
-The following example Caddyfile gets a reverse proxy going behind [caddy](https://caddyserver.com).
-
-```caddyfile
-example.com {
-  route /metube/* {
-    uri strip_prefix metube
-    reverse_proxy metube:8081
-  }
-}
-```
-
-## 🔄 Updating yt-dlp
-
-The engine which powers the actual video downloads in MeTube is [yt-dlp](https://github.com/yt-dlp/yt-dlp). Since video sites regularly change their layouts, frequent updates of yt-dlp are required to keep up.
-
-There's an automatic nightly build of MeTube which looks for a new version of yt-dlp, and if one exists, the build pulls it and publishes an updated docker image. Therefore, in order to keep up with the changes, it's recommended that you update your MeTube container regularly with the latest image.
-
-I recommend installing and setting up [watchtower](https://github.com/nicholas-fedor/watchtower) for this purpose.
-
-## 🔧 Troubleshooting and submitting issues
-
-Before asking a question or submitting an issue for MeTube, please remember that MeTube is only a UI for [yt-dlp](https://github.com/yt-dlp/yt-dlp). Any issues you might be experiencing with authentication to video websites, postprocessing, permissions, other `YTDL_OPTIONS` configurations which seem not to work, or anything else that concerns the workings of the underlying yt-dlp library, need not be opened on the MeTube project. In order to debug and troubleshoot them, it's advised to try using the yt-dlp binary directly first, bypassing the UI, and once that is working, importing the options that worked for you into `YTDL_OPTIONS`.
-
-In order to test with the yt-dlp command directly, you can either download it and run it locally, or for a better simulation of its actual conditions, you can run it within the MeTube container itself. Assuming your MeTube container is called `metube`, run the following on your Docker host to get a shell inside the container:
-
-```bash
-docker exec -ti metube sh
-cd /downloads
-```
-
-Once there, you can use the yt-dlp command freely.
-
-## 💡 Submitting feature requests
-
-MeTube development relies on code contributions by the community. The program as it currently stands fits my own use cases, and is therefore feature-complete as far as I'm concerned. If your use cases are different and require additional features, please feel free to submit PRs that implement those features. It's advisable to create an issue first to discuss the planned implementation, because in an effort to reduce bloat, some PRs may not be accepted. However, note that opening a feature request when you don't intend to implement the feature will rarely result in the request being fulfilled.
-
-## 🛠️ Building and running locally
-
-Make sure you have Node.js and Python 3.13 installed.
-
-```bash
-cd metube/ui
-# install Angular and build the UI
-npm install
-node_modules/.bin/ng build
-# install python dependencies
-cd ..
-curl -LsSf https://astral.sh/uv/install.sh | sh
-uv sync
-# run
-uv run python3 app/main.py
-```
-
-A Docker image can be built locally (it will build the UI too):
-
-```bash
-docker build -t metube .
-```
-
-Note that if you're running the server in VSCode, your downloads will go to your user's Downloads folder (this is configured via the environment in `.vscode/launch.json`).
+# MeTube
+
+![Build Status](https://github.com/alexta69/metube/actions/workflows/main.yml/badge.svg)
+![Docker Pulls](https://img.shields.io/docker/pulls/alexta69/metube.svg)
+
+MeTube is a self-hosted web UI for `yt-dlp`, for downloading media from YouTube and [dozens of other sites](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md).
+
+Key capabilities:
+* Download videos, audio, captions, and thumbnails from a browser UI.
+* Download playlists and channels, with configurable output and download options.
+* Subscribe to channels and playlists, periodically check for new items, and queue new uploads automatically.
+
+![screenshot1](https://github.com/alexta69/metube/raw/master/screenshot.gif)
+
+## 🐳 Run using Docker
+
+```bash
+docker run -d -p 8081:8081 -v /path/to/downloads:/downloads ghcr.io/alexta69/metube
+```
+
+## 🐳 Run using docker-compose
+
+```yaml
+services:
+  metube:
+    image: ghcr.io/alexta69/metube
+    container_name: metube
+    restart: unless-stopped
+    ports:
+      - "8081:8081"
+    volumes:
+      - /path/to/downloads:/downloads
+```
+
+## ⚙️ Configuration via environment variables
+
+Certain values can be set via environment variables, using the `-e` parameter on the docker command line, or the `environment:` section in docker-compose.
+
+### ⬇️ Download Behavior
+
+* __MAX_CONCURRENT_DOWNLOADS__: Maximum number of simultaneous downloads allowed. For example, if set to `5`, then at most five downloads will run concurrently, and any additional downloads will wait until one of the active downloads completes. Defaults to `3`. 
+* __DELETE_FILE_ON_TRASHCAN__: if `true`, downloaded files are deleted on the server, when they are trashed from the "Completed" section of the UI. Defaults to `false`.
+* __DEFAULT_OPTION_PLAYLIST_ITEM_LIMIT__: Maximum number of playlist items that can be downloaded. Defaults to `0` (no limit).
+* __SUBSCRIPTION_DEFAULT_CHECK_INTERVAL__: Default minutes between automatic checks for each subscription. Defaults to `60`.
+* __SUBSCRIPTION_SCAN_PLAYLIST_END__: Maximum playlist/channel entries to fetch per subscription check (newest-first). Defaults to `50`.
+* __SUBSCRIPTION_MAX_SEEN_IDS__: Cap on stored video IDs per subscription to limit state file growth. Defaults to `50000`.
+* __CLEAR_COMPLETED_AFTER__: Number of seconds after which completed (and failed) downloads are automatically removed from the "Completed" list. Defaults to `0` (disabled).
+
+### 📁 Storage & Directories
+
+* __DOWNLOAD_DIR__: Path to where the downloads will be saved. Defaults to `/downloads` in the Docker image, and `.` otherwise.
+* __AUDIO_DOWNLOAD_DIR__: Path to where audio-only downloads will be saved, if you wish to separate them from the video downloads. Defaults to the value of `DOWNLOAD_DIR`.
+* __CUSTOM_DIRS__: Whether to enable downloading videos into custom directories within the __DOWNLOAD_DIR__ (or __AUDIO_DOWNLOAD_DIR__). When enabled, a dropdown appears next to the Add button to specify the download directory. Defaults to `true`.
+* __CREATE_CUSTOM_DIRS__: Whether to support automatically creating directories within the __DOWNLOAD_DIR__ (or __AUDIO_DOWNLOAD_DIR__) if they do not exist. When enabled, the download directory selector supports free-text input, and the specified directory will be created recursively. Defaults to `true`.
+* __CUSTOM_DIRS_EXCLUDE_REGEX__: Regular expression to exclude some custom directories from the dropdown. Empty regex disables exclusion. Defaults to `(^|/)[.@].*$`, which means directories starting with `.` or `@`.
+* __DOWNLOAD_DIRS_INDEXABLE__: If `true`, the download directories (__DOWNLOAD_DIR__ and __AUDIO_DOWNLOAD_DIR__) are indexable on the web server. Defaults to `false`.
+* __STATE_DIR__: Path to where MeTube will store its persistent state files (`queue.json`, `pending.json`, `completed.json`, `subscriptions.json`). Defaults to `/downloads/.metube` in the Docker image, and `.` otherwise.
+* __TEMP_DIR__: Path where intermediary download files will be saved. Defaults to `/downloads` in the Docker image, and `.` otherwise.
+  * Set this to an SSD or RAM filesystem (e.g., `tmpfs`) for better performance.
+  * __Note__: Using a RAM filesystem may prevent downloads from being resumed.
+* __CHOWN_DIRS__: If `false`, ownership of `DOWNLOAD_DIR`, `STATE_DIR`, and `TEMP_DIR` (and their contents) will not be set on container start. Ensure user under which MeTube runs has necessary access to these directories already. Defaults to `true`.
+
+### 📝 File Naming & yt-dlp
+
+* __OUTPUT_TEMPLATE__: The template for the filenames of the downloaded videos, formatted according to [this spec](https://github.com/yt-dlp/yt-dlp/blob/master/README.md#output-template). Defaults to `%(title)s.%(ext)s`.
+* __OUTPUT_TEMPLATE_CHAPTER__: The template for the filenames of the downloaded videos when split into chapters via postprocessors. Defaults to `%(title)s - %(section_number)s %(section_title)s.%(ext)s`.
+* __OUTPUT_TEMPLATE_PLAYLIST__: The template for the filenames of the downloaded videos when downloaded as a playlist. Defaults to `%(playlist_title)s/%(title)s.%(ext)s`. Set to empty to use `OUTPUT_TEMPLATE` instead.
+* __OUTPUT_TEMPLATE_CHANNEL__: The template for the filenames of the downloaded videos when downloaded as a channel. Defaults to `%(channel)s/%(title)s.%(ext)s`. Set to empty to use `OUTPUT_TEMPLATE` instead.
+* __YTDL_OPTIONS__: Additional options to pass to yt-dlp, as a JSON object. See [Configuring yt-dlp options](#%EF%B8%8F-configuring-yt-dlp-options) for details, examples, and available options reference.
+* __YTDL_OPTIONS_FILE__: Path to a JSON file containing yt-dlp options. Monitored and reloaded automatically on changes. See [Configuring yt-dlp options](#%EF%B8%8F-configuring-yt-dlp-options).
+* __YTDL_OPTIONS_PRESETS__: Named bundles of yt-dlp options, selectable per download in the UI. See [Configuring yt-dlp options](#%EF%B8%8F-configuring-yt-dlp-options) for format and examples.
+* __YTDL_OPTIONS_PRESETS_FILE__: Path to a JSON file containing presets. Monitored and reloaded automatically on changes. See [Configuring yt-dlp options](#%EF%B8%8F-configuring-yt-dlp-options).
+* __ALLOW_YTDL_OPTIONS_OVERRIDES__: Whether to show a free-text field in the UI for per-download yt-dlp option overrides. Defaults to `false`. See [Configuring yt-dlp options](#%EF%B8%8F-configuring-yt-dlp-options) for details and security considerations.
+
+### 🌐 Web Server & URLs
+
+* __HOST__: The host address the web server will bind to. Defaults to `0.0.0.0` (all interfaces).
+* __PORT__: The port number the web server will listen on. Defaults to `8081`.
+* __URL_PREFIX__: Base path for the web server (for use when hosting behind a reverse proxy). Defaults to `/`.
+* __PUBLIC_HOST_URL__: Base URL for the download links shown in the UI for completed files. By default, MeTube serves them under its own URL. If your download directory is accessible on another URL and you want the download links to be based there, use this variable to set it.
+* __PUBLIC_HOST_AUDIO_URL__: Same as PUBLIC_HOST_URL but for audio downloads.
+* __HTTPS__: Use `https` instead of `http` (__CERTFILE__ and __KEYFILE__ required). Defaults to `false`.
+* __CERTFILE__: HTTPS certificate file path.
+* __KEYFILE__: HTTPS key file path.
+* __CORS_ALLOWED_ORIGINS__: Comma-separated list of origins permitted to make cross-origin requests to the MeTube API. When unset or empty, all cross-origin requests are denied. Set to `*` to allow all origins. This must be configured for [browser extensions](#-browser-extensions), [bookmarklets](#-bookmarklet), and any other browser-based tools that contact MeTube from a different origin. For browser extensions use `*` (see below); for bookmarklets you can list specific sites, e.g. `https://www.youtube.com,https://www.vimeo.com`.
+* __ROBOTS_TXT__: A path to a `robots.txt` file mounted in the container.
+
+### 🏠 Basic Setup
+
+* __PUID__: User under which MeTube will run. Defaults to `1000` (legacy `UID` also supported).
+* __PGID__: Group under which MeTube will run. Defaults to `1000` (legacy `GID` also supported).
+* __UMASK__: Umask value used by MeTube. Defaults to `022`.
+* __DEFAULT_THEME__: Default theme to use for the UI, can be set to `light`, `dark`, or `auto`. Defaults to `auto`.
+* __LOGLEVEL__: Log level, can be set to `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`, or `NONE`. Defaults to `INFO`. 
+* __ENABLE_ACCESSLOG__: Whether to enable access log. Defaults to `false`.
+
+## 🎛️ Configuring yt-dlp options
+
+MeTube lets you customize how [yt-dlp](https://github.com/yt-dlp/yt-dlp) behaves at three levels, from broadest to most specific:
+
+1. **Global options** — apply to every download by default.
+2. **Presets** — named bundles of options that users can pick per download from the UI.
+3. **Per-download overrides** — free-form options entered in the UI for a single download.
+
+When a download starts, these layers are combined in order. If the same option appears in more than one layer, the more specific one wins: per-download overrides beat presets, and presets beat global options.
+
+In JSON presets and overrides, setting an option to **`null`** clears that option for that download (for example, `"download_archive": null` overrides a global archive path so the archive is not used). This follows yt-dlp’s usual meaning of `None` for that option.
+
+### Option format
+
+yt-dlp options in MeTube are expressed as JSON objects. The keys are yt-dlp API option names, which roughly correspond to command-line flags with dashes replaced by underscores. For example, the command-line flag `--write-subs` becomes `"writesubtitles": true` in JSON.
+
+> **Tip:** Some command-line flags don't have a direct single-key equivalent — for instance, `--embed-thumbnail` and `--recode-video` must be expressed via `"postprocessors"`. A full list of available API options can be found [in the yt-dlp source](https://github.com/yt-dlp/yt-dlp/blob/master/yt_dlp/YoutubeDL.py#L224), and [this conversion script](https://github.com/yt-dlp/yt-dlp/blob/master/devscripts/cli_to_api.py) can help translate command-line flags to their API equivalents.
+
+### Global options
+
+Global options form the baseline for every download. There are two ways to define them, and you can use either or both:
+
+**Inline via environment variable** (`YTDL_OPTIONS`) — pass a JSON object directly:
+
+```yaml
+environment:
+  - 'YTDL_OPTIONS={"writesubtitles": true, "subtitleslangs": ["en", "de"], "updatetime": false, "writethumbnail": true}'
+```
+
+**Via a JSON file** (`YTDL_OPTIONS_FILE`) — mount a file into the container and point to it:
+
+```yaml
+volumes:
+  - /path/to/ytdl-options.json:/config/ytdl-options.json
+environment:
+  - YTDL_OPTIONS_FILE=/config/ytdl-options.json
+```
+
+where `ytdl-options.json` contains:
+
+```json
+{
+  "writesubtitles": true,
+  "subtitleslangs": ["en", "de"],
+  "updatetime": false,
+  "writethumbnail": true
+}
+```
+
+The file is monitored for changes and reloaded automatically — no container restart needed. If you use both methods and they define the same key, the **file takes precedence**.
+
+### Presets
+
+Presets let you define named bundles of options that appear in the web UI under **Advanced Options** as "Option Presets". Users can select one or more presets per download, making it easy to apply common option combinations without editing global settings.
+
+Like global options, presets can be set inline or via a file:
+
+* `YTDL_OPTIONS_PRESETS` — a JSON object where each key is a preset name and its value is a set of yt-dlp options.
+* `YTDL_OPTIONS_PRESETS_FILE` — path to a JSON file containing presets, monitored and reloaded on changes.
+
+If both are used and they define a preset with the same name, the **file's version takes precedence**.
+
+**Example** — a presets file defining three presets:
+
+```json
+{
+  "sponsorblock": {
+    "postprocessors": [
+      { "key": "SponsorBlock", "categories": ["sponsor", "selfpromo", "interaction"] },
+      { "key": "ModifyChapters", "remove_sponsor_segments": ["sponsor", "selfpromo", "interaction"] }
+    ]
+  },
+  "embed-subs": {
+    "writesubtitles": true,
+    "writeautomaticsub": true,
+    "subtitleslangs": ["en", "de"],
+    "postprocessors": [{ "key": "FFmpegEmbedSubtitle" }]
+  },
+  "limit-rate": {
+    "ratelimit": 5000000
+  }
+}
+```
+
+This makes three presets available in the UI:
+* **sponsorblock** — strips sponsor, self-promo, and interaction segments from videos.
+* **embed-subs** — downloads English and German subtitles and embeds them into the video file.
+* **limit-rate** — caps download speed to ~5 MB/s.
+
+When multiple presets are selected for a download, they are applied in order. If two presets set the same option, the later one wins.
+
+### Per-download overrides
+
+For one-off tweaks, MeTube can expose a free-text JSON field in the UI ("Custom yt-dlp Options") where users type yt-dlp options that apply only to that single download. This is disabled by default:
+
+```yaml
+environment:
+  - ALLOW_YTDL_OPTIONS_OVERRIDES=true
+```
+
+Once enabled, the field appears under **Advanced Options**. Any options entered there take the highest priority, overriding both global options and selected presets.
+
+> **⚠️ Security note:** Enabling this allows arbitrary yt-dlp API options to be supplied by anyone with access to the UI. Depending on the options used, this may enable arbitrary command execution inside the container. Enable only in trusted environments.
+
+### How the layers combine
+
+When a download starts, the final set of yt-dlp options is built in this order:
+
+1. Start with **global options** (`YTDL_OPTIONS` / `YTDL_OPTIONS_FILE`).
+2. Apply each selected **preset** in order (later presets overwrite earlier ones for conflicting keys).
+3. Apply any **per-download overrides** on top (overwrite everything else for conflicting keys).
+
+MeTube always forces its own flat-extract behaviour during the initial metadata fetch (`extract_flat`, `noplaylist`, etc.); presets cannot override those keys for that phase.
+
+**Example:** Suppose your global options set `"writesubtitles": false`, but you select a preset that sets `"writesubtitles": true`. Subtitles will be written for that download because the preset overrides the global setting. If you additionally enter `{"writesubtitles": false}` in the per-download overrides field, that value wins and subtitles will not be written.
+
+### Configuration cookbooks
+
+The project's Wiki contains examples of useful configurations contributed by users of MeTube:
+* [YTDL_OPTIONS Cookbook](https://github.com/alexta69/metube/wiki/YTDL_OPTIONS-Cookbook)
+* [OUTPUT_TEMPLATE Cookbook](https://github.com/alexta69/metube/wiki/OUTPUT_TEMPLATE-Cookbook)
+
+## 🍪 Using browser cookies
+
+In case you need to use your browser's cookies with MeTube, for example to download restricted or private videos:
+
+* Install in your browser an extension to extract cookies:
+  * [Firefox](https://addons.mozilla.org/en-US/firefox/addon/export-cookies-txt/)
+  * [Chrome](https://chrome.google.com/webstore/detail/get-cookiestxt-locally/cclelndahbckbenkjhflpdbgdldlbecc)
+* Extract the cookies you need with the extension and save/export them as `cookies.txt`.
+* In MeTube, open **Advanced Options** and use the **Upload Cookies** button to upload the file.
+* After upload, the cookie indicator should show as active.
+* Use **Delete Cookies** in the same section to remove uploaded cookies.
+
+## 🔌 Browser extensions
+
+Browser extensions allow right-clicking videos and sending them directly to MeTube. If you're on an HTTPS page, your MeTube instance must be behind an HTTPS reverse proxy (see below) for extensions to work.
+
+Since browser extensions make requests from their own origin (`chrome-extension://...` or `moz-extension://...`), you must set `CORS_ALLOWED_ORIGINS=*` for them to work.
+
+__Chrome:__ contributed by [Rpsl](https://github.com/rpsl). You can install it from [Google Chrome Webstore](https://chrome.google.com/webstore/detail/metube-downloader/fbmkmdnlhacefjljljlbhkodfmfkijdh) or use developer mode and install [from sources](https://github.com/Rpsl/metube-browser-extension).
+
+__Firefox:__ contributed by [nanocortex](https://github.com/nanocortex). You can install it from [Firefox Addons](https://addons.mozilla.org/en-US/firefox/addon/metube-downloader) or get sources from [here](https://github.com/nanocortex/metube-firefox-addon).
+
+## 📱 iOS Shortcut
+
+[rithask](https://github.com/rithask) created an iOS shortcut to send URLs to MeTube from Safari. Enter the MeTube instance address when prompted which will be saved for later use. You can run the shortcut from Safari’s share menu. The shortcut can be downloaded from [this iCloud link](https://www.icloud.com/shortcuts/66627a9f334c467baabdb2769763a1a6).
+
+## 🔖 Bookmarklet
+
+[kushfest](https://github.com/kushfest) has created a Chrome bookmarklet for sending the currently open webpage to MeTube. Please note that if you're on an HTTPS page, your MeTube instance must be configured with `HTTPS` as `true` in the environment, or be behind an HTTPS reverse proxy (see below) for the bookmarklet to work.
+
+Since bookmarklets run in the context of the current page (e.g. youtube.com), the requests they make to MeTube are cross-origin. You must add the origins of sites where you use the bookmarklet to the __CORS_ALLOWED_ORIGINS__ environment variable, otherwise the browser will block the requests. For example, to use the bookmarklet on YouTube and Vimeo: `CORS_ALLOWED_ORIGINS=https://www.youtube.com,https://www.vimeo.com`.
+
+GitHub doesn't allow embedding JavaScript as a link, so the bookmarklet has to be created manually by copying the following code to a new bookmark you create on your bookmarks bar. Change the hostname in the URL below to point to your MeTube instance.
+
+```javascript
+javascript:!function(){xhr=new XMLHttpRequest();xhr.open("POST","https://metube.domain.com/add");xhr.withCredentials=true;xhr.send(JSON.stringify({"url":document.location.href,"quality":"best"}));xhr.onload=function(){if(xhr.status==200){alert("Sent to metube!")}else{alert("Send to metube failed. Check the javascript console for clues.")}}}();
+```
+
+[shoonya75](https://github.com/shoonya75) has contributed a Firefox version:
+
+```javascript
+javascript:(function(){xhr=new XMLHttpRequest();xhr.open("POST","https://metube.domain.com/add");xhr.send(JSON.stringify({"url":document.location.href,"quality":"best"}));xhr.onload=function(){if(xhr.status==200){alert("Sent to metube!")}else{alert("Send to metube failed. Check the javascript console for clues.")}}})();
+```
+
+The above bookmarklets use `alert()` for notifications. This variant shows a toast instead (Chrome — for Firefox, replace the `!function(){...}()` wrapper with `(function(){...})()`):
+
+```javascript
+javascript:!function(){function notify(msg) {var sc = document.scrollingElement.scrollTop; var text = document.createElement('span');text.innerHTML=msg;var ts = text.style;ts.all = 'revert';ts.color = '#000';ts.fontFamily = 'Verdana, sans-serif';ts.fontSize = '15px';ts.backgroundColor = 'white';ts.padding = '15px';ts.border = '1px solid gainsboro';ts.boxShadow = '3px 3px 10px';ts.zIndex = '100';document.body.appendChild(text);ts.position = 'absolute'; ts.top = 50 + sc + 'px'; ts.left = (window.innerWidth / 2)-(text.offsetWidth / 2) + 'px'; setTimeout(function () { text.style.visibility = "hidden"; }, 1500);}xhr=new XMLHttpRequest();xhr.open("POST","https://metube.domain.com/add");xhr.send(JSON.stringify({"url":document.location.href,"quality":"best"}));xhr.onload=function() { if(xhr.status==200){notify("Sent to metube!")}else {notify("Send to metube failed. Check the javascript console for clues.")}}}();
+```
+
+## ⚡ Raycast extension
+
+[dotvhs](https://github.com/dotvhs) has created an [extension for Raycast](https://www.raycast.com/dot/metube) for adding videos to MeTube directly from Raycast.
+
+## 🔒 HTTPS support, and running behind a reverse proxy
+
+It's possible to configure MeTube to listen in HTTPS mode. `docker-compose` example:
+
+```yaml
+services:
+  metube:
+    image: ghcr.io/alexta69/metube
+    container_name: metube
+    restart: unless-stopped
+    ports:
+      - "8081:8081"
+    volumes:
+      - /path/to/downloads:/downloads
+      - /path/to/ssl/crt:/ssl/crt.pem
+      - /path/to/ssl/key:/ssl/key.pem
+    environment:
+      - HTTPS=true
+      - CERTFILE=/ssl/crt.pem
+      - KEYFILE=/ssl/key.pem
+```
+
+MeTube can also run behind a reverse proxy for HTTPS termination or authentication. When serving under a subdirectory, set `URL_PREFIX` accordingly.
+
+The [linuxserver/swag](https://docs.linuxserver.io/general/swag) image includes ready-made snippets for MeTube in [subfolder](https://github.com/linuxserver/reverse-proxy-confs/blob/master/metube.subfolder.conf.sample) and [subdomain](https://github.com/linuxserver/reverse-proxy-confs/blob/master/metube.subdomain.conf.sample) modes, plus Authelia for authentication.
+
+### 🌐 NGINX
+
+```nginx
+location /metube/ {
+        proxy_pass http://metube:8081;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+}
+```
+
+Note: the extra `proxy_set_header` directives are there to make WebSocket work.
+
+### 🌐 Apache
+
+Contributed by [PIE-yt](https://github.com/PIE-yt). Source [here](https://gist.github.com/PIE-yt/29e7116588379032427f5bd446b2cac4).
+
+```apache
+# For putting in your Apache sites site.conf
+# Serves MeTube under a /metube/ subdir (http://yourdomain.com/metube/)
+<Location /metube/>
+    ProxyPass http://localhost:8081/ retry=0 timeout=30
+    ProxyPassReverse http://localhost:8081/
+</Location>
+
+<Location /metube/socket.io>
+    RewriteEngine On
+    RewriteCond %{QUERY_STRING} transport=websocket    [NC]
+    RewriteRule /(.*) ws://localhost:8081/socket.io/$1 [P,L]
+    ProxyPass http://localhost:8081/socket.io retry=0 timeout=30
+    ProxyPassReverse http://localhost:8081/socket.io
+</Location>
+```
+
+### 🌐 Caddy
+
+The following example Caddyfile gets a reverse proxy going behind [caddy](https://caddyserver.com).
+
+```caddyfile
+example.com {
+  route /metube/* {
+    uri strip_prefix metube
+    reverse_proxy metube:8081
+  }
+}
+```
+
+## 🔄 Updating yt-dlp
+
+MeTube is powered by [yt-dlp](https://github.com/yt-dlp/yt-dlp), which requires frequent updates as video sites change their layouts. A nightly build automatically publishes a new Docker image whenever a new yt-dlp version is available, so keep your container up to date — [watchtower](https://github.com/nicholas-fedor/watchtower) works well for this.
+
+## 🔧 Troubleshooting and submitting issues
+
+MeTube is only a UI for [yt-dlp](https://github.com/yt-dlp/yt-dlp). Issues with authentication, postprocessing, permissions, or `YTDL_OPTIONS` should be debugged with yt-dlp directly first — once working, import those options into MeTube. To test inside the container:
+
+```bash
+docker exec -ti metube sh
+cd /downloads
+```
+
+## 💡 Submitting feature requests
+
+MeTube development relies on community contributions. If you need additional features, please submit a PR. Create an issue first to discuss the implementation — some PRs may not be accepted to reduce bloat. Feature requests without an accompanying PR are unlikely to be fulfilled.
+
+## 🛠️ Building and running locally
+
+Make sure you have Node.js 22+ and Python 3.13 installed.
+
+```bash
+# install Angular and build the UI
+cd ui
+curl -fsSL https://get.pnpm.io/install.sh | sh -
+pnpm install
+pnpm run build
+# install python dependencies
+cd ..
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uv sync
+# run
+uv run python3 app/main.py
+```
+
+A Docker image can be built locally (it will build the UI too):
+
+```bash
+docker build -t metube .
+```
+
+Note that if you're running the server in VSCode, your downloads will go to your user's Downloads folder (this is configured via the environment in `.vscode/launch.json`).

app/dl_formats.py

@@ -1,75 +1,108 @@
 import copy
 
 AUDIO_FORMATS = ("m4a", "mp3", "opus", "wav", "flac")
+CAPTION_MODES = ("auto_only", "manual_only", "prefer_manual", "prefer_auto")
+
+CODEC_FILTER_MAP = {
+    'h264': "[vcodec~='^(h264|avc)']",
+    'h265': "[vcodec~='^(h265|hevc)']",
+    'av1':  "[vcodec~='^av0?1']",
+    'vp9':  "[vcodec~='^vp0?9']",
+}
 
 
-def get_format(format: str, quality: str) -> str:
+def _normalize_caption_mode(mode: str) -> str:
+    mode = (mode or "").strip()
+    return mode if mode in CAPTION_MODES else "prefer_manual"
+
+
+def _normalize_subtitle_language(language: str) -> str:
+    language = (language or "").strip()
+    return language or "en"
+
+
+def get_format(download_type: str, codec: str, format: str, quality: str) -> str:
     """
-    Returns format for download
+    Returns yt-dlp format selector.
 
     Args:
-      format (str): format selected
-      quality (str): quality selected
+      download_type (str): selected content type (video, audio, captions, thumbnail)
+      codec (str): selected video codec (auto, h264, h265, av1, vp9)
+      format (str): selected output format/profile for type
+      quality (str): selected quality
 
     Raises:
-      Exception: unknown quality, unknown format
+      Exception: unknown type/format
 
     Returns:
-      dl_format: Formatted download string
+      str: yt-dlp format selector
     """
-    format = format or "any"
+    download_type = (download_type or "video").strip().lower()
+    format = (format or "any").strip().lower()
+    codec = (codec or "auto").strip().lower()
+    quality = (quality or "best").strip().lower()
 
     if format.startswith("custom:"):
         return format[7:]
 
-    if format == "thumbnail":
-        # Quality is irrelevant in this case since we skip the download
+    if download_type == "thumbnail":
         return "bestaudio/best"
 
-    if format in AUDIO_FORMATS:
-        # Audio quality needs to be set post-download, set in opts
+    if download_type == "captions":
+        return "bestaudio/best"
+
+    if download_type == "audio":
+        if format not in AUDIO_FORMATS:
+            raise ValueError(f"Unknown audio format {format}")
         return f"bestaudio[ext={format}]/bestaudio/best"
 
-    if format in ("mp4", "any"):
-        if quality == "audio":
-            return "bestaudio/best"
-        # video {res} {vfmt} + audio {afmt} {res} {vfmt}
-        vfmt, afmt = ("[ext=mp4]", "[ext=m4a]") if format == "mp4" else ("", "")
-        vres = f"[height<={quality}]" if quality not in ("best", "best_ios", "worst") else ""
+    if download_type == "video":
+        if format not in ("any", "mp4", "ios"):
+            raise ValueError(f"Unknown video format {format}")
+        vfmt, afmt = ("[ext=mp4]", "[ext=m4a]") if format in ("mp4", "ios") else ("", "")
+        vres = f"[height<={quality}]" if quality not in ("best", "worst") else ""
         vcombo = vres + vfmt
+        codec_filter = CODEC_FILTER_MAP.get(codec, "")
 
-        if quality == "best_ios":
-            # iOS has strict requirements for video files, requiring h264 or h265
-            # video codec and aac audio codec in MP4 container. This format string
-            # attempts to get the fully compatible formats first, then the h264/h265
-            # video codec with any M4A audio codec (because audio is faster to
-            # convert if needed), and falls back to getting the best available MP4
-            # file.
+        if format == "ios":
             return f"bestvideo[vcodec~='^((he|a)vc|h26[45])']{vres}+bestaudio[acodec=aac]/bestvideo[vcodec~='^((he|a)vc|h26[45])']{vres}+bestaudio{afmt}/bestvideo{vcombo}+bestaudio{afmt}/best{vcombo}"
+
+        if codec_filter:
+            return f"bestvideo{codec_filter}{vcombo}+bestaudio{afmt}/bestvideo{vcombo}+bestaudio{afmt}/best{vcombo}"
         return f"bestvideo{vcombo}+bestaudio{afmt}/best{vcombo}"
 
-    raise Exception(f"Unkown format {format}")
+    raise ValueError(f"Unknown download_type {download_type}")
 
 
-def get_opts(format: str, quality: str, ytdl_opts: dict) -> dict:
+def get_opts(
+    download_type: str,
+    _codec: str,
+    format: str,
+    quality: str,
+    ytdl_opts: dict,
+    subtitle_language: str = "en",
+    subtitle_mode: str = "prefer_manual",
+) -> dict:
     """
-    Returns extra download options
-    Mostly postprocessing options
+    Returns extra yt-dlp options/postprocessors.
 
     Args:
-      format (str): format selected
-      quality (str): quality of format selected (needed for some formats)
+      download_type (str): selected content type
+      codec (str): selected codec (unused currently, kept for API consistency)
+      format (str): selected format/profile
+      quality (str): selected quality
       ytdl_opts (dict): current options selected
 
     Returns:
-      ytdl_opts: Extra options
+      dict: extended options
     """
-
+    download_type = (download_type or "video").strip().lower()
+    format = (format or "any").strip().lower()
     opts = copy.deepcopy(ytdl_opts)
 
     postprocessors = []
 
-    if format in AUDIO_FORMATS:
+    if download_type == "audio":
         postprocessors.append(
             {
                 "key": "FFmpegExtractAudio",
@@ -78,8 +111,7 @@ def get_opts(format: str, quality: str, ytdl_opts: dict) -> dict:
             }
         )
 
-        # Audio formats without thumbnail
-        if format not in ("wav") and "writethumbnail" not in opts:
+        if format != "wav" and "writethumbnail" not in opts:
             opts["writethumbnail"] = True
             postprocessors.append(
                 {
@@ -91,13 +123,40 @@ def get_opts(format: str, quality: str, ytdl_opts: dict) -> dict:
             postprocessors.append({"key": "FFmpegMetadata"})
             postprocessors.append({"key": "EmbedThumbnail"})
 
-    if format == "thumbnail":
+    if download_type == "thumbnail":
         opts["skip_download"] = True
         opts["writethumbnail"] = True
         postprocessors.append(
             {"key": "FFmpegThumbnailsConvertor", "format": "jpg", "when": "before_dl"}
         )
 
+    if download_type == "captions":
+        mode = _normalize_caption_mode(subtitle_mode)
+        language = _normalize_subtitle_language(subtitle_language)
+        opts["skip_download"] = True
+        requested_subtitle_format = (format or "srt").lower()
+        if requested_subtitle_format == "txt":
+            requested_subtitle_format = "srt"
+        opts["subtitlesformat"] = requested_subtitle_format
+        if mode == "manual_only":
+            opts["writesubtitles"] = True
+            opts["writeautomaticsub"] = False
+            opts["subtitleslangs"] = [language]
+        elif mode == "auto_only":
+            opts["writesubtitles"] = False
+            opts["writeautomaticsub"] = True
+            # `-orig` captures common YouTube auto-sub tags. The plain language
+            # fallback keeps behavior useful across other extractors.
+            opts["subtitleslangs"] = [f"{language}-orig", language]
+        elif mode == "prefer_auto":
+            opts["writesubtitles"] = True
+            opts["writeautomaticsub"] = True
+            opts["subtitleslangs"] = [f"{language}-orig", language]
+        else:
+            opts["writesubtitles"] = True
+            opts["writeautomaticsub"] = True
+            opts["subtitleslangs"] = [language, f"{language}-orig"]
+
     opts["postprocessors"] = postprocessors + (
         opts["postprocessors"] if "postprocessors" in opts else []
     )

app/state_store.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import base64
+import collections.abc
+import json
+import logging
+import os
+import shelve
+import tempfile
+import time
+from datetime import datetime
+from typing import Any, Optional
+
+log = logging.getLogger("state_store")
+
+STATE_SCHEMA_VERSION = 2
+_BYTES_MARKER = "__metube_bytes__"
+_DATETIME_MARKER = "__metube_datetime__"
+
+
+def to_json_compatible(value: Any) -> Any:
+    if value is None or isinstance(value, (bool, int, float, str)):
+        return value
+    if isinstance(value, bytes):
+        return {_BYTES_MARKER: base64.b64encode(value).decode("ascii")}
+    if isinstance(value, datetime):
+        return {_DATETIME_MARKER: value.isoformat()}
+    if isinstance(value, collections.abc.Mapping):
+        return {str(k): to_json_compatible(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return [to_json_compatible(v) for v in value]
+    if isinstance(value, collections.abc.Iterable):
+        return [to_json_compatible(v) for v in value]
+    raise TypeError(f"Value of type {type(value).__name__} is not JSON serializable")
+
+
+def from_json_compatible(value: Any) -> Any:
+    if isinstance(value, list):
+        return [from_json_compatible(v) for v in value]
+    if isinstance(value, dict):
+        if set(value.keys()) == {_BYTES_MARKER}:
+            return base64.b64decode(value[_BYTES_MARKER].encode("ascii"))
+        if set(value.keys()) == {_DATETIME_MARKER}:
+            return datetime.fromisoformat(value[_DATETIME_MARKER])
+        return {k: from_json_compatible(v) for k, v in value.items()}
+    return value
+
+
+def read_legacy_shelf(path: str) -> Optional[list[tuple[Any, Any]]]:
+    if not os.path.exists(path):
+        return None
+    try:
+        with shelve.open(path, "r") as shelf:
+            return list(shelf.items())
+    except Exception as exc:
+        log.warning("Could not read legacy shelf at %s: %s", path, exc)
+        return None
+
+
+class AtomicJsonStore:
+    def __init__(self, path: str, *, kind: str, schema_version: int = STATE_SCHEMA_VERSION):
+        self.path = path
+        self.kind = kind
+        self.schema_version = schema_version
+
+    def _ensure_parent(self) -> None:
+        parent = os.path.dirname(self.path)
+        if parent and not os.path.isdir(parent):
+            os.makedirs(parent, exist_ok=True)
+
+    def _build_payload(self, data: dict[str, Any]) -> dict[str, Any]:
+        payload = {
+            "schema_version": self.schema_version,
+            "kind": self.kind,
+        }
+        payload.update(data)
+        return payload
+
+    def load(self) -> Optional[dict[str, Any]]:
+        if not os.path.exists(self.path):
+            return None
+        try:
+            with open(self.path, encoding="utf-8") as f:
+                payload = json.load(f)
+            if not isinstance(payload, dict):
+                raise ValueError("State file must contain a JSON object")
+            if payload.get("kind") != self.kind:
+                raise ValueError(
+                    f"State file kind mismatch: expected {self.kind}, got {payload.get('kind')}"
+                )
+            return payload
+        except Exception as exc:
+            self.quarantine_invalid_file(exc)
+            return None
+
+    def save(self, data: dict[str, Any]) -> None:
+        self._ensure_parent()
+        payload = self._build_payload(data)
+        parent = os.path.dirname(self.path) or "."
+        fd, tmp_path = tempfile.mkstemp(
+            prefix=f".{os.path.basename(self.path)}.",
+            suffix=".tmp",
+            dir=parent,
+            text=True,
+        )
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
+                json.dump(payload, f, ensure_ascii=False, separators=(",", ":"))
+                f.write("\n")
+                f.flush()
+                os.fsync(f.fileno())
+            os.replace(tmp_path, self.path)
+            self._fsync_directory(parent)
+        except Exception:
+            try:
+                os.remove(tmp_path)
+            except OSError:
+                pass
+            raise
+
+    def quarantine_invalid_file(self, exc: Exception) -> None:
+        if not os.path.exists(self.path):
+            return
+        ts = time.strftime("%Y%m%d%H%M%S")
+        backup_path = f"{self.path}.invalid.{ts}"
+        try:
+            os.replace(self.path, backup_path)
+            log.warning(
+                "State file at %s was invalid (%s); moved it to %s",
+                self.path,
+                exc,
+                backup_path,
+            )
+        except OSError as move_exc:
+            log.warning(
+                "State file at %s was invalid (%s) and could not be moved aside: %s",
+                self.path,
+                exc,
+                move_exc,
+            )
+
+    @staticmethod
+    def _fsync_directory(path: str) -> None:
+        try:
+            flags = os.O_RDONLY
+            if hasattr(os, "O_DIRECTORY"):
+                flags |= os.O_DIRECTORY
+            fd = os.open(path, flags)
+        except OSError:
+            return
+        try:
+            os.fsync(fd)
+        except OSError:
+            pass
+        finally:
+            os.close(fd)

app/subscriptions.py

@@ -0,0 +1,721 @@
+"""Channel/playlist subscriptions: periodic yt-dlp flat extract + queue new videos."""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import logging
+import os
+import time
+import types
+import uuid
+from dataclasses import dataclass, field, fields
+from typing import Any, Optional
+
+import yt_dlp
+import yt_dlp.networking.impersonate
+from state_store import AtomicJsonStore, read_legacy_shelf
+
+log = logging.getLogger("subscriptions")
+
+VIDEO_ONLY_MSG = (
+    "This URL points to a single video, not a channel or playlist. Use Download instead."
+)
+_MEDIA_HINT_FIELDS = (
+    "duration",
+    "timestamp",
+    "release_timestamp",
+    "upload_date",
+    "view_count",
+    "live_status",
+    "availability",
+)
+
+
+def _impersonate_opt(ytdl_options: dict) -> dict:
+    opts = dict(ytdl_options)
+    if "impersonate" in opts:
+        opts["impersonate"] = yt_dlp.networking.impersonate.ImpersonateTarget.from_str(
+            opts["impersonate"]
+        )
+    return opts
+
+
+def _build_ydl_params(config, *, playlistend: Optional[int] = None) -> dict:
+    params: dict[str, Any] = {
+        "quiet": not logging.getLogger().isEnabledFor(logging.DEBUG),
+        "verbose": logging.getLogger().isEnabledFor(logging.DEBUG),
+        "no_color": True,
+        "extract_flat": True,
+        "ignore_no_formats_error": True,
+        "lazy_playlist": True,
+        "paths": {"home": config.DOWNLOAD_DIR, "temp": config.TEMP_DIR},
+        **config.YTDL_OPTIONS,
+    }
+    params = _impersonate_opt(params)
+    if playlistend is not None and playlistend > 0:
+        params["playlistend"] = playlistend
+    return params
+
+
+def _is_media_entry(entry: Any) -> bool:
+    if not isinstance(entry, dict):
+        return False
+    etype = str(entry.get("_type") or "")
+    if etype in ("playlist", "multi_video", "channel"):
+        return False
+    if entry.get("entries"):
+        return False
+    url = _entry_video_url(entry)
+    if not url:
+        return False
+    ie_key = str(entry.get("ie_key") or entry.get("extractor_key") or "").lower()
+    if any(token in ie_key for token in ("playlist", "channel", "tab")):
+        return any(entry.get(field) is not None for field in _MEDIA_HINT_FIELDS)
+    return True
+
+
+def extract_flat_playlist(config, url: str, playlistend: int, *, _depth: int = 0):
+    """Return (info_dict, entries_list) for playlist/channel URLs."""
+    params = _build_ydl_params(config, playlistend=playlistend)
+    with yt_dlp.YoutubeDL(params=params) as ydl:
+        info = ydl.extract_info(url, download=False)
+    if not info:
+        return None, []
+    etype = info.get("_type") or "video"
+    if etype == "video":
+        return info, []
+    if etype in ("playlist", "channel"):
+        entries = info.get("entries") or []
+        if isinstance(entries, types.GeneratorType):
+            entries = list(entries)
+        # Drop None placeholders from incomplete flat playlists
+        entries = [e for e in entries if e]
+        media_entries = [e for e in entries if _is_media_entry(e)]
+        if media_entries:
+            return info, media_entries
+        if _depth < 1:
+            for ent in entries[:5]:
+                nested_url = _entry_video_url(ent)
+                if not nested_url:
+                    continue
+                nested_info, nested_entries = extract_flat_playlist(
+                    config,
+                    nested_url,
+                    playlistend,
+                    _depth=_depth + 1,
+                )
+                if nested_entries:
+                    return nested_info, nested_entries
+        return info, entries
+    if etype.startswith("url") and info.get("url"):
+        # Single nested URL without playlist wrapper — treat as non-subscribable
+        return info, []
+    return info, []
+
+
+def _entry_video_url(entry: dict) -> Optional[str]:
+    return entry.get("webpage_url") or entry.get("url")
+
+
+def _entry_id(entry: dict) -> Optional[str]:
+    eid = entry.get("id")
+    if eid is not None:
+        return str(eid)
+    url = _entry_video_url(entry)
+    return url
+
+
+@dataclass
+class SubscriptionInfo:
+    id: str
+    name: str
+    url: str
+    enabled: bool = True
+    check_interval_minutes: int = 60
+    download_type: str = "video"
+    codec: str = "auto"
+    format: str = "any"
+    quality: str = "best"
+    folder: str = ""
+    custom_name_prefix: str = ""
+    auto_start: bool = True
+    playlist_item_limit: int = 0
+    split_by_chapters: bool = False
+    chapter_template: str = ""
+    subtitle_language: str = "en"
+    subtitle_mode: str = "prefer_manual"
+    ytdl_options_presets: list[str] = field(default_factory=list)
+    ytdl_options_overrides: dict[str, Any] = field(default_factory=dict)
+    last_checked: Optional[float] = None
+    seen_ids: list[str] = field(default_factory=list)
+    error: Optional[str] = None
+    timestamp: float = field(default_factory=time.time)
+
+    def seen_set(self) -> set[str]:
+        return set(self.seen_ids)
+
+    def to_public_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "url": self.url,
+            "enabled": self.enabled,
+            "check_interval_minutes": self.check_interval_minutes,
+            "download_type": self.download_type,
+            "codec": self.codec,
+            "format": self.format,
+            "quality": self.quality,
+            "folder": self.folder,
+            "last_checked": self.last_checked,
+            "seen_count": len(self.seen_ids),
+            "error": self.error,
+        }
+
+
+def _subscription_to_record(sub: SubscriptionInfo) -> dict[str, Any]:
+    return {
+        "id": sub.id,
+        "name": sub.name,
+        "url": sub.url,
+        "enabled": sub.enabled,
+        "check_interval_minutes": sub.check_interval_minutes,
+        "download_type": sub.download_type,
+        "codec": sub.codec,
+        "format": sub.format,
+        "quality": sub.quality,
+        "folder": sub.folder,
+        "custom_name_prefix": sub.custom_name_prefix,
+        "auto_start": sub.auto_start,
+        "playlist_item_limit": sub.playlist_item_limit,
+        "split_by_chapters": sub.split_by_chapters,
+        "chapter_template": sub.chapter_template,
+        "subtitle_language": sub.subtitle_language,
+        "subtitle_mode": sub.subtitle_mode,
+        "ytdl_options_presets": list(sub.ytdl_options_presets),
+        "ytdl_options_overrides": sub.ytdl_options_overrides,
+        "last_checked": sub.last_checked,
+        "seen_ids": list(sub.seen_ids),
+        "error": sub.error,
+    }
+
+
+def _normalize_subscription_record(rec: dict[str, Any]) -> dict[str, Any]:
+    """Migrate legacy ytdl_options_preset (str) to ytdl_options_presets (list)."""
+    out = dict(rec)
+    if "ytdl_options_presets" not in out:
+        old = out.pop("ytdl_options_preset", None)
+        if old is None:
+            out["ytdl_options_presets"] = []
+        elif isinstance(old, list):
+            out["ytdl_options_presets"] = [str(x).strip() for x in old if str(x).strip()]
+        elif isinstance(old, str):
+            out["ytdl_options_presets"] = [old.strip()] if old.strip() else []
+        else:
+            out["ytdl_options_presets"] = []
+    else:
+        out.pop("ytdl_options_preset", None)
+    return out
+
+
+def _subscription_from_record(record: Any) -> Optional[SubscriptionInfo]:
+    field_names = {f.name for f in fields(SubscriptionInfo)}
+    if isinstance(record, SubscriptionInfo):
+        return record
+    if isinstance(record, dict):
+        try:
+            normalized = _normalize_subscription_record(dict(record))
+            return SubscriptionInfo(**{k: v for k, v in normalized.items() if k in field_names})
+        except TypeError:
+            return None
+    return None
+
+
+def _coerce_bool(value: Any) -> bool:
+    """Accept JSON booleans and common string forms used by API clients."""
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        lowered = value.strip().lower()
+        if lowered in {"true", "1", "on"}:
+            return True
+        if lowered in {"false", "0", "off"}:
+            return False
+    raise ValueError("enabled must be a boolean")
+
+
+class SubscriptionNotifier:
+    """Hook for Socket.IO / UI updates."""
+
+    async def subscription_added(self, sub: SubscriptionInfo) -> None:
+        raise NotImplementedError
+
+    async def subscription_updated(self, sub: SubscriptionInfo) -> None:
+        raise NotImplementedError
+
+    async def subscription_removed(self, sub_id: str) -> None:
+        raise NotImplementedError
+
+    async def subscriptions_all(self, subs: list[SubscriptionInfo]) -> None:
+        raise NotImplementedError
+
+
+class SubscriptionManager:
+    def __init__(self, config, download_queue, notifier: SubscriptionNotifier):
+        self.config = config
+        self.dqueue = download_queue
+        self.notifier = notifier
+        pdir = config.STATE_DIR
+        if not os.path.isdir(pdir):
+            os.makedirs(pdir, exist_ok=True)
+        self._legacy_path = os.path.join(pdir, "subscriptions")
+        self._path = os.path.join(pdir, "subscriptions.json")
+        self._store = AtomicJsonStore(self._path, kind="subscriptions")
+        self._subs: dict[str, SubscriptionInfo] = {}
+        self._url_index: dict[str, str] = {}  # normalized url -> id
+        self._pending_urls: set[str] = set()
+        self._lock = asyncio.Lock()
+        self._loop_task: Optional[asyncio.Task] = None
+        self._load_all()
+
+    def close(self) -> None:
+        # No persistent shelf handle to close.
+        return
+
+    def _normalize_url(self, url: str) -> str:
+        return (url or "").strip()
+
+    def _normalize_seen_ids(self, seen_ids: list[str]) -> list[str]:
+        max_seen = int(getattr(self.config, "SUBSCRIPTION_MAX_SEEN_IDS", 50000))
+        normalized = [str(sid) for sid in dict.fromkeys(seen_ids)]
+        if len(normalized) > max_seen:
+            normalized = normalized[:max_seen]
+        return normalized
+
+    def _load_all(self) -> None:
+        payload = self._store.load()
+        loaded_from_legacy = False
+        if payload is not None:
+            records = payload.get("items") or []
+        else:
+            legacy_items = read_legacy_shelf(self._legacy_path)
+            records = [raw for _key, raw in legacy_items] if legacy_items else []
+            if records:
+                loaded_from_legacy = True
+
+        loaded_subs = self._iter_valid_subs(records)
+        compact_records = []
+        for sub in loaded_subs:
+            sub.seen_ids = self._normalize_seen_ids(sub.seen_ids)
+            self._subs[sub.id] = sub
+            self._url_index[self._normalize_url(sub.url)] = sub.id
+            compact_records.append(_subscription_to_record(sub))
+
+        if loaded_from_legacy or (
+            payload is not None
+            and (
+                payload.get("schema_version") != self._store.schema_version
+                or compact_records != records
+            )
+        ):
+            self._store.save({"items": compact_records})
+
+    def _iter_valid_subs(self, records: list[Any]) -> list[SubscriptionInfo]:
+        subs: list[SubscriptionInfo] = []
+        for record in records:
+            sub = _subscription_from_record(record)
+            if sub is not None:
+                subs.append(sub)
+        return subs
+
+    def _save_locked(self) -> None:
+        self._store.save({"items": [_subscription_to_record(sub) for sub in self._subs.values()]})
+
+    async def _queue_subscription_entries(
+        self,
+        entries: list[dict],
+        *,
+        download_type: str,
+        codec: str,
+        format: str,
+        quality: str,
+        folder: str,
+        custom_name_prefix: str,
+        playlist_item_limit: int,
+        auto_start: bool,
+        split_by_chapters: bool,
+        chapter_template: str,
+        subtitle_language: str,
+        subtitle_mode: str,
+        ytdl_options_presets: Optional[list[str]] = None,
+        ytdl_options_overrides: Optional[dict[str, Any]] = None,
+    ) -> tuple[list[str], list[str]]:
+        queued_ids: list[str] = []
+        queue_errors: list[str] = []
+        presets = list(ytdl_options_presets or [])
+        for ent in entries:
+            eid = _entry_id(ent)
+            vurl = _entry_video_url(ent)
+            if not eid or not vurl:
+                continue
+            queue_entry = dict(ent)
+            if "id" not in queue_entry:
+                queue_entry["id"] = eid
+            queue_entry["_type"] = "video"
+            queue_entry["webpage_url"] = vurl
+            result = await self.dqueue.add_entry(
+                queue_entry,
+                download_type,
+                codec,
+                format,
+                quality,
+                folder or None,
+                custom_name_prefix,
+                playlist_item_limit,
+                auto_start,
+                split_by_chapters,
+                chapter_template or None,
+                subtitle_language,
+                subtitle_mode,
+                presets,
+                ytdl_options_overrides,
+            )
+            if isinstance(result, dict) and result.get("status") == "error":
+                msg = str(result.get("msg") or f"Queueing failed for {vurl}")
+                queue_errors.append(msg)
+                log.warning("Subscription queueing failed for %s: %s", vurl, msg)
+                continue
+            queued_ids.append(eid)
+        return queued_ids, queue_errors
+
+    def list_all(self) -> list[SubscriptionInfo]:
+        return list(self._subs.values())
+
+    def get(self, sub_id: str) -> Optional[SubscriptionInfo]:
+        return self._subs.get(sub_id)
+
+    def start_background_loop(self) -> None:
+        if self._loop_task is not None and not self._loop_task.done():
+            return
+        self._loop_task = asyncio.create_task(self._periodic_loop())
+        self._loop_task.add_done_callback(
+            lambda t: log.error("Subscription loop failed: %s", t.exception())
+            if not t.cancelled() and t.exception()
+            else None
+        )
+
+    async def _periodic_loop(self) -> None:
+        while True:
+            await asyncio.sleep(60)
+            try:
+                await self.run_due_checks()
+            except Exception as e:
+                log.exception("Subscription periodic check error: %s", e)
+
+    async def run_due_checks(self) -> None:
+        now = time.time()
+        due: list[SubscriptionInfo] = []
+        async with self._lock:
+            for sub in list(self._subs.values()):
+                if not sub.enabled:
+                    continue
+                interval_sec = max(60, int(sub.check_interval_minutes) * 60)
+                if sub.last_checked is None:
+                    due.append(sub)
+                    continue
+                if now - sub.last_checked < interval_sec:
+                    continue
+                due.append(sub)
+        for sub in due:
+            await self._check_one_unlocked(sub)
+
+    async def add_subscription(
+        self,
+        url: str,
+        *,
+        check_interval_minutes: int,
+        download_type: str,
+        codec: str,
+        format: str,
+        quality: str,
+        folder: str,
+        custom_name_prefix: str,
+        auto_start: bool,
+        playlist_item_limit: int,
+        split_by_chapters: bool,
+        chapter_template: str,
+        subtitle_language: str,
+        subtitle_mode: str,
+        ytdl_options_presets: Optional[list[str]] = None,
+        ytdl_options_overrides: Optional[dict[str, Any]] = None,
+    ) -> dict:
+        url = self._normalize_url(url)
+        if not url:
+            return {"status": "error", "msg": "Missing URL"}
+
+        async with self._lock:
+            if url in self._url_index or url in self._pending_urls:
+                return {"status": "error", "msg": "This URL is already subscribed"}
+            self._pending_urls.add(url)
+
+        try:
+            scan_first = max(int(getattr(self.config, "SUBSCRIPTION_SCAN_PLAYLIST_END", 50)), 1)
+            try:
+                info, entries = extract_flat_playlist(self.config, url, scan_first)
+            except yt_dlp.utils.YoutubeDLError as exc:
+                return {"status": "error", "msg": str(exc)}
+
+            if not info:
+                return {"status": "error", "msg": "Could not resolve URL"}
+
+            etype = info.get("_type") or "video"
+            if etype not in ("playlist", "channel"):
+                return {"status": "error", "msg": VIDEO_ONLY_MSG}
+
+            name = (
+                info.get("title")
+                or info.get("channel")
+                or info.get("playlist_title")
+                or info.get("uploader")
+                or url
+            )
+
+            seen_entries = [ent for ent in entries if _is_media_entry(ent)]
+            all_ids: list[str] = []
+            for ent in seen_entries:
+                if ent.get("live_status") == "is_upcoming":
+                    continue  # Don't mark scheduled streams as seen; queue them when they go live
+                eid = _entry_id(ent)
+                if eid:
+                    all_ids.append(eid)
+
+            sub = SubscriptionInfo(
+                id=str(uuid.uuid4()),
+                name=str(name),
+                url=url,
+                enabled=True,
+                check_interval_minutes=max(1, int(check_interval_minutes)),
+                download_type=download_type,
+                codec=codec,
+                format=format,
+                quality=quality,
+                folder=folder or "",
+                custom_name_prefix=custom_name_prefix or "",
+                auto_start=bool(auto_start),
+                playlist_item_limit=int(playlist_item_limit),
+                split_by_chapters=bool(split_by_chapters),
+                chapter_template=chapter_template or "",
+                subtitle_language=subtitle_language,
+                subtitle_mode=subtitle_mode,
+                ytdl_options_presets=list(ytdl_options_presets or []),
+                ytdl_options_overrides=dict(ytdl_options_overrides or {}),
+                last_checked=time.time(),
+                seen_ids=list(dict.fromkeys(all_ids)),
+                error=None,
+            )
+
+            async with self._lock:
+                if url in self._url_index:
+                    return {"status": "error", "msg": "This URL is already subscribed"}
+                self._subs[sub.id] = sub
+                self._url_index[url] = sub.id
+                try:
+                    self._save_locked()
+                except Exception:
+                    self._subs.pop(sub.id, None)
+                    self._url_index.pop(url, None)
+                    raise
+
+            await self.notifier.subscription_added(sub)
+            return {"status": "ok", "subscription": sub.to_public_dict()}
+        finally:
+            async with self._lock:
+                self._pending_urls.discard(url)
+
+    async def delete_subscriptions(self, ids: list[str]) -> dict:
+        removed: list[str] = []
+        async with self._lock:
+            previous_subs = self._subs.copy()
+            previous_index = self._url_index.copy()
+            for sid in ids:
+                sub = self._subs.pop(sid, None)
+                if sub:
+                    normalized_url = self._normalize_url(sub.url)
+                    self._url_index.pop(normalized_url, None)
+                    removed.append(sid)
+            if removed:
+                try:
+                    self._save_locked()
+                except Exception:
+                    self._subs = previous_subs
+                    self._url_index = previous_index
+                    raise
+        for sid in removed:
+            await self.notifier.subscription_removed(sid)
+        return {"status": "ok"}
+
+    async def update_subscription(self, sub_id: str, changes: dict) -> dict:
+        async with self._lock:
+            sub = self._subs.get(sub_id)
+            if not sub:
+                return {"status": "error", "msg": "Subscription not found"}
+            previous = copy.deepcopy(sub)
+            old_enabled = sub.enabled
+
+            if "enabled" in changes:
+                sub.enabled = _coerce_bool(changes["enabled"])
+            if "check_interval_minutes" in changes:
+                sub.check_interval_minutes = max(1, int(changes["check_interval_minutes"]))
+            if "name" in changes and changes["name"]:
+                sub.name = str(changes["name"])
+
+            try:
+                self._save_locked()
+            except Exception:
+                self._subs[sub_id] = previous
+                raise
+            updated = sub
+        if "enabled" in changes and updated.enabled != old_enabled:
+            log.info(
+                "Subscription %s %s",
+                updated.name,
+                "resumed" if updated.enabled else "paused",
+            )
+        await self.notifier.subscription_updated(updated)
+        return {"status": "ok", "subscription": updated.to_public_dict()}
+
+    async def check_now(self, ids: Optional[list[str]] = None) -> dict:
+        async with self._lock:
+            targets = (
+                [self._subs[i] for i in ids if i in self._subs]
+                if ids
+                else [s for s in self._subs.values() if s.enabled]
+            )
+        log.info(
+            "Manual subscription check requested for %d subscription(s)",
+            len(targets),
+        )
+        for sub in targets:
+            await self._check_one_unlocked(sub)
+        return {"status": "ok"}
+
+    async def _check_one_unlocked(self, sub: SubscriptionInfo) -> None:
+        sid = sub.id
+        scan = int(getattr(self.config, "SUBSCRIPTION_SCAN_PLAYLIST_END", 50))
+        log.info("Checking subscription: %s", sub.name)
+        try:
+            info, entries = extract_flat_playlist(self.config, sub.url, scan)
+        except yt_dlp.utils.YoutubeDLError as exc:
+            async with self._lock:
+                cur = self._subs.get(sid)
+                if cur:
+                    previous = copy.deepcopy(cur)
+                    cur.error = str(exc)
+                    try:
+                        self._save_locked()
+                    except Exception:
+                        self._subs[sid] = previous
+                        raise
+                    sub = cur
+            log.warning("Subscription check failed for %s: %s", sub.name, exc)
+            await self.notifier.subscription_updated(sub)
+            return
+        entries = [ent for ent in entries if _is_media_entry(ent)]
+
+        etype = (info or {}).get("_type") or "video"
+        if etype == "video" or not entries:
+            async with self._lock:
+                cur = self._subs.get(sid)
+                if cur:
+                    previous = copy.deepcopy(cur)
+                    cur.error = VIDEO_ONLY_MSG
+                    try:
+                        self._save_locked()
+                    except Exception:
+                        self._subs[sid] = previous
+                        raise
+                    sub = cur
+            log.warning("Subscription %s no longer resolves to a subscribable feed", sub.name)
+            await self.notifier.subscription_updated(sub)
+            return
+
+        async with self._lock:
+            cur = self._subs.get(sid)
+            if not cur:
+                return
+            seen = cur.seen_set()
+            seen_ids_snapshot = list(cur.seen_ids)
+            dl_type = cur.download_type
+            dl_codec = cur.codec
+            dl_format = cur.format
+            dl_quality = cur.quality
+            dl_folder = cur.folder
+            dl_prefix = cur.custom_name_prefix
+            dl_plimit = cur.playlist_item_limit
+            dl_autostart = cur.auto_start
+            dl_split = cur.split_by_chapters
+            dl_chapter = cur.chapter_template
+            dl_sublang = cur.subtitle_language
+            dl_submode = cur.subtitle_mode
+            dl_ytdl_presets = list(cur.ytdl_options_presets)
+            dl_ytdl_overrides = dict(cur.ytdl_options_overrides)
+
+        new_entries: list[dict] = []
+        new_ids: list[str] = []
+        for ent in entries:
+            eid = _entry_id(ent)
+            if not eid:
+                continue
+            if eid in seen and ent.get("live_status") != "is_live":
+                continue
+            new_entries.append(ent)
+            new_ids.append(eid)
+
+        queued_ids, queue_errors = await self._queue_subscription_entries(
+            new_entries,
+            download_type=dl_type,
+            codec=dl_codec,
+            format=dl_format,
+            quality=dl_quality,
+            folder=dl_folder,
+            custom_name_prefix=dl_prefix,
+            playlist_item_limit=dl_plimit,
+            auto_start=dl_autostart,
+            split_by_chapters=dl_split,
+            chapter_template=dl_chapter or "",
+            subtitle_language=dl_sublang,
+            subtitle_mode=dl_submode,
+            ytdl_options_presets=dl_ytdl_presets,
+            ytdl_options_overrides=dl_ytdl_overrides,
+        )
+        log.info(
+            "Subscription check finished for %s: %d new, %d queued, %d failed",
+            sub.name,
+            len(new_entries),
+            len(queued_ids),
+            len(queue_errors),
+        )
+
+        merged = list(dict.fromkeys(queued_ids + seen_ids_snapshot))
+        max_seen = int(getattr(self.config, "SUBSCRIPTION_MAX_SEEN_IDS", 50000))
+        if len(merged) > max_seen:
+            merged = merged[:max_seen]
+
+        async with self._lock:
+            cur = self._subs.get(sid)
+            if not cur:
+                return
+            previous = copy.deepcopy(cur)
+            cur.seen_ids = merged
+            cur.last_checked = time.time()
+            cur.error = "; ".join(queue_errors[:3]) if queue_errors else None
+            try:
+                self._save_locked()
+            except Exception:
+                self._subs[sid] = previous
+                raise
+            sub = cur
+        await self.notifier.subscription_updated(sub)
+
+    async def emit_all(self) -> None:
+        await self.notifier.subscriptions_all(self.list_all())

app/tests/conftest.py

@@ -0,0 +1,32 @@
+"""Pytest configuration: set env and filesystem layout before importing ``main``."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+
+def _ensure_test_env() -> None:
+    if os.environ.get("METUBE_TEST_ENV_READY"):
+        return
+    tmp = tempfile.mkdtemp(prefix="metube-pytest-")
+    base = Path(tmp)
+    browser = base / "ui" / "dist" / "metube" / "browser"
+    browser.mkdir(parents=True)
+    (browser / "index.html").write_text("<html><body></body></html>", encoding="utf-8")
+    dl = base / "downloads"
+    st = base / "state"
+    dl.mkdir(parents=True)
+    st.mkdir(parents=True)
+    os.environ["DOWNLOAD_DIR"] = str(dl)
+    os.environ["STATE_DIR"] = str(st)
+    os.environ["TEMP_DIR"] = str(dl)
+    os.environ["YTDL_OPTIONS"] = "{}"
+    os.environ["YTDL_OPTIONS_FILE"] = ""
+    os.environ["BASE_DIR"] = str(base)
+    os.environ["LOGLEVEL"] = "INFO"
+    os.environ["METUBE_TEST_ENV_READY"] = "1"
+
+
+_ensure_test_env()

app/tests/test_api.py

@@ -0,0 +1,281 @@
+"""HTTP handler tests for ``main`` using mocked ``web.Request`` (no TestServer)."""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from aiohttp import web
+
+import main
+
+
+@pytest.fixture
+def mock_dqueue(monkeypatch):
+    d = MagicMock()
+    d.initialize = AsyncMock(return_value=None)
+    d.add = AsyncMock(return_value={"status": "ok"})
+    d.cancel = AsyncMock(return_value={"status": "ok"})
+    d.start_pending = AsyncMock(return_value={"status": "ok"})
+    d.cancel_add = MagicMock()
+    d.queue = MagicMock()
+    d.done = MagicMock()
+    d.pending = MagicMock()
+    d.queue.saved_items = MagicMock(return_value=[])
+    d.done.saved_items = MagicMock(return_value=[])
+    d.pending.saved_items = MagicMock(return_value=[])
+    d.get = MagicMock(return_value=([], []))
+    monkeypatch.setattr(main, "dqueue", d)
+    return d
+
+
+def _valid_video_add_body(**kwargs):
+    base = {
+        "url": "https://example.com/watch?v=1",
+        "download_type": "video",
+        "codec": "auto",
+        "format": "any",
+        "quality": "best",
+        "ytdl_options_presets": [],
+        "ytdl_options_overrides": "",
+    }
+    base.update(kwargs)
+    return base
+
+
+def _json_request(body: dict | None):
+    req = MagicMock(spec=web.Request)
+    req.json = AsyncMock(return_value=body)
+    return req
+
+
+@pytest.mark.asyncio
+async def test_add_ok(mock_dqueue):
+    req = _json_request(_valid_video_add_body())
+    resp = await main.add(req)
+    assert resp.status == 200
+    text = resp.text
+    data = json.loads(text)
+    assert data["status"] == "ok"
+    mock_dqueue.add.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_add_passes_preset_and_overrides(mock_dqueue, monkeypatch):
+    monkeypatch.setattr(main.config, "YTDL_OPTIONS_PRESETS", {"Preset A": {"writesubtitles": True}})
+    monkeypatch.setattr(main.config, "ALLOW_YTDL_OPTIONS_OVERRIDES", True)
+    req = _json_request(
+        _valid_video_add_body(
+            ytdl_options_presets=["Preset A"],
+            ytdl_options_overrides='{"writesubtitles": true}',
+        )
+    )
+    resp = await main.add(req)
+    assert resp.status == 200
+    call = mock_dqueue.add.await_args
+    assert call is not None
+    assert call.args[13] == ["Preset A"]
+    assert call.args[14] == {"writesubtitles": True}
+
+
+@pytest.mark.asyncio
+async def test_add_legacy_string_preset_normalized(mock_dqueue, monkeypatch):
+    monkeypatch.setattr(main.config, "YTDL_OPTIONS_PRESETS", {"Legacy": {}})
+    body = _valid_video_add_body()
+    del body["ytdl_options_presets"]
+    body["ytdl_options_preset"] = "Legacy"
+    req = _json_request(body)
+    resp = await main.add(req)
+    assert resp.status == 200
+    call = mock_dqueue.add.await_args
+    assert call.args[13] == ["Legacy"]
+
+
+@pytest.mark.asyncio
+async def test_add_missing_url_returns_400(mock_dqueue):
+    req = _json_request({"download_type": "video", "quality": "best", "format": "any"})
+    with pytest.raises(web.HTTPBadRequest):
+        await main.add(req)
+    mock_dqueue.add.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_add_invalid_download_type(mock_dqueue):
+    req = _json_request(_valid_video_add_body(download_type="invalid"))
+    with pytest.raises(web.HTTPBadRequest):
+        await main.add(req)
+
+
+@pytest.mark.asyncio
+async def test_add_invalid_video_quality(mock_dqueue):
+    req = _json_request(_valid_video_add_body(quality="9999"))
+    with pytest.raises(web.HTTPBadRequest):
+        await main.add(req)
+
+
+@pytest.mark.asyncio
+async def test_add_invalid_subtitle_language(mock_dqueue):
+    req = _json_request(
+        {
+            "url": "https://example.com/v",
+            "download_type": "captions",
+            "codec": "auto",
+            "format": "srt",
+            "quality": "best",
+            "subtitle_language": "bad language!",
+        }
+    )
+    with pytest.raises(web.HTTPBadRequest):
+        await main.add(req)
+
+
+@pytest.mark.asyncio
+async def test_add_custom_name_prefix_path_traversal(mock_dqueue):
+    req = _json_request(_valid_video_add_body(custom_name_prefix="../evil"))
+    with pytest.raises(web.HTTPBadRequest):
+        await main.add(req)
+
+
+@pytest.mark.asyncio
+async def test_add_chapter_template_path_traversal(mock_dqueue):
+    req = _json_request(
+        _valid_video_add_body(
+            split_by_chapters=True,
+            chapter_template="/etc/passwd%(title)s",
+        )
+    )
+    with pytest.raises(web.HTTPBadRequest):
+        await main.add(req)
+
+
+@pytest.mark.asyncio
+async def test_add_invalid_json_body(mock_dqueue):
+    req = MagicMock(spec=web.Request)
+    req.json = AsyncMock(side_effect=json.JSONDecodeError("msg", "", 0))
+    with pytest.raises(web.HTTPBadRequest):
+        await main.add(req)
+
+
+@pytest.mark.asyncio
+async def test_add_invalid_ytdl_options_override_json(mock_dqueue):
+    req = _json_request(_valid_video_add_body(ytdl_options_overrides="{bad json}"))
+    with pytest.raises(web.HTTPBadRequest):
+        await main.add(req)
+
+
+@pytest.mark.asyncio
+async def test_add_rejects_ytdl_options_overrides_when_disabled(mock_dqueue):
+    req = _json_request(_valid_video_add_body(ytdl_options_overrides='{"exec": "rm -rf /"}'))
+    with pytest.raises(web.HTTPBadRequest):
+        await main.add(req)
+
+
+@pytest.mark.asyncio
+async def test_add_allows_any_ytdl_options_override_key_when_enabled(mock_dqueue, monkeypatch):
+    monkeypatch.setattr(main.config, "ALLOW_YTDL_OPTIONS_OVERRIDES", True)
+    req = _json_request(_valid_video_add_body(ytdl_options_overrides='{"exec": "echo hi"}'))
+    resp = await main.add(req)
+    assert resp.status == 200
+    call = mock_dqueue.add.await_args
+    assert call is not None
+    assert call.args[14] == {"exec": "echo hi"}
+
+
+@pytest.mark.asyncio
+async def test_add_unknown_ytdl_preset(mock_dqueue):
+    req = _json_request(_valid_video_add_body(ytdl_options_presets=["Missing"]))
+    with pytest.raises(web.HTTPBadRequest):
+        await main.add(req)
+
+
+@pytest.mark.asyncio
+async def test_delete_missing_ids(mock_dqueue):
+    req = _json_request({"where": "queue"})
+    with pytest.raises(web.HTTPBadRequest):
+        await main.delete(req)
+
+
+@pytest.mark.asyncio
+async def test_delete_queue_calls_cancel(mock_dqueue):
+    req = _json_request({"where": "queue", "ids": ["http://x"]})
+    resp = await main.delete(req)
+    assert resp.status == 200
+    mock_dqueue.cancel.assert_awaited_once_with(["http://x"])
+
+
+@pytest.mark.asyncio
+async def test_start_pending(mock_dqueue):
+    req = _json_request({"ids": ["a"]})
+    resp = await main.start(req)
+    assert resp.status == 200
+    mock_dqueue.start_pending.assert_awaited_once_with(["a"])
+
+
+@pytest.mark.asyncio
+async def test_history_shape(mock_dqueue):
+    mock_dqueue.queue.saved_items.return_value = []
+    mock_dqueue.done.saved_items.return_value = []
+    mock_dqueue.pending.saved_items.return_value = []
+    req = MagicMock(spec=web.Request)
+    resp = await main.history(req)
+    assert resp.status == 200
+    data = json.loads(resp.text)
+    assert set(data.keys()) == {"done", "queue", "pending"}
+
+
+@pytest.mark.asyncio
+async def test_version_json(mock_dqueue):
+    req = MagicMock(spec=web.Request)
+    resp = await main.version(req)
+    assert resp.status == 200
+    body = json.loads(resp.text)
+    assert "yt-dlp" in body and "version" in body
+
+
+@pytest.mark.asyncio
+async def test_presets_endpoint_returns_names(mock_dqueue, monkeypatch):
+    monkeypatch.setattr(main.config, "YTDL_OPTIONS_PRESETS", {"Preset B": {}, "Preset A": {}})
+    req = MagicMock(spec=web.Request)
+    resp = await main.presets(req)
+    assert resp.status == 200
+    assert json.loads(resp.text) == {"presets": ["Preset A", "Preset B"]}
+
+
+@pytest.mark.asyncio
+async def test_cookie_status(mock_dqueue):
+    req = MagicMock(spec=web.Request)
+    resp = await main.cookie_status(req)
+    assert resp.status == 200
+    data = json.loads(resp.text)
+    assert data.get("status") == "ok"
+    assert "has_cookies" in data
+
+
+@pytest.mark.asyncio
+async def test_options_add_cors(mock_dqueue):
+    req = MagicMock(spec=web.Request)
+    resp = await main.add_cors(req)
+    assert resp.status == 200
+
+
+@pytest.mark.asyncio
+async def test_upload_cookies_missing_field(mock_dqueue):
+    req = MagicMock(spec=web.Request)
+    reader = MagicMock()
+    field = MagicMock()
+    field.name = "wrongname"
+    reader.next = AsyncMock(side_effect=[field, None])
+    req.multipart = AsyncMock(return_value=reader)
+    resp = await main.upload_cookies(req)
+    assert resp.status == 400
+
+
+@pytest.mark.asyncio
+async def test_add_legacy_format_migrated(mock_dqueue):
+    req = _json_request({"url": "https://example.com/v", "format": "m4a", "quality": "best"})
+    resp = await main.add(req)
+    assert resp.status == 200
+    call = mock_dqueue.add.await_args
+    assert call is not None
+    assert call.args[1] == "audio"

app/tests/test_config.py

@@ -0,0 +1,150 @@
+"""Tests for ``Config`` (env parsing, yt-dlp options, frontend_safe)."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import unittest
+from unittest.mock import patch
+
+from main import Config
+
+
+def _base_env(**overrides: str) -> dict[str, str]:
+    env = {k: str(v) for k, v in Config._DEFAULTS.items()}
+    env.update(overrides)
+    return env
+
+
+class ConfigTests(unittest.TestCase):
+    def test_url_prefix_gets_trailing_slash(self):
+        with patch.dict(os.environ, _base_env(URL_PREFIX="foo"), clear=False):
+            c = Config()
+        self.assertEqual(c.URL_PREFIX, "foo/")
+
+    def test_public_host_url_gets_trailing_slash(self):
+        with patch.dict(
+            os.environ,
+            _base_env(PUBLIC_HOST_URL="https://ytdl.example.com"),
+            clear=False,
+        ):
+            c = Config()
+        self.assertEqual(c.PUBLIC_HOST_URL, "https://ytdl.example.com/")
+
+    def test_public_host_audio_url_gets_trailing_slash(self):
+        with patch.dict(
+            os.environ,
+            _base_env(PUBLIC_HOST_AUDIO_URL="https://audio.example.com"),
+            clear=False,
+        ):
+            c = Config()
+        self.assertEqual(c.PUBLIC_HOST_AUDIO_URL, "https://audio.example.com/")
+
+    def test_public_host_url_empty_stays_empty(self):
+        with patch.dict(
+            os.environ,
+            _base_env(PUBLIC_HOST_URL="", PUBLIC_HOST_AUDIO_URL=""),
+            clear=False,
+        ):
+            c = Config()
+        self.assertEqual(c.PUBLIC_HOST_URL, "")
+        self.assertEqual(c.PUBLIC_HOST_AUDIO_URL, "")
+
+    def test_public_host_url_already_slashed_unchanged(self):
+        with patch.dict(
+            os.environ,
+            _base_env(
+                PUBLIC_HOST_URL="https://ytdl.example.com/",
+                PUBLIC_HOST_AUDIO_URL="https://audio.example.com/",
+            ),
+            clear=False,
+        ):
+            c = Config()
+        self.assertEqual(c.PUBLIC_HOST_URL, "https://ytdl.example.com/")
+        self.assertEqual(c.PUBLIC_HOST_AUDIO_URL, "https://audio.example.com/")
+
+    def test_ytdl_options_json_loaded(self):
+        opts = {"quiet": True, "no_warnings": True}
+        with patch.dict(
+            os.environ,
+            _base_env(YTDL_OPTIONS=json.dumps(opts)),
+            clear=False,
+        ):
+            c = Config()
+        self.assertEqual(c.YTDL_OPTIONS["quiet"], True)
+
+    def test_ytdl_option_presets_json_loaded(self):
+        presets = {"Audio extras": {"embed_thumbnail": True}}
+        with patch.dict(
+            os.environ,
+            _base_env(YTDL_OPTIONS_PRESETS=json.dumps(presets)),
+            clear=False,
+        ):
+            c = Config()
+        self.assertEqual(c.YTDL_OPTIONS_PRESETS["Audio extras"]["embed_thumbnail"], True)
+
+    def test_invalid_ytdl_options_exits(self):
+        with patch.dict(os.environ, _base_env(YTDL_OPTIONS="not-json"), clear=False):
+            with self.assertRaises(SystemExit):
+                Config()
+
+    def test_invalid_boolean_env_exits(self):
+        with patch.dict(os.environ, _base_env(CUSTOM_DIRS="maybe"), clear=False):
+            with self.assertRaises(SystemExit):
+                Config()
+
+    def test_frontend_safe_excludes_secrets(self):
+        with patch.dict(os.environ, _base_env(), clear=False):
+            c = Config()
+        safe = c.frontend_safe()
+        self.assertNotIn("YTDL_OPTIONS", safe)
+        self.assertNotIn("HOST", safe)
+        self.assertEqual(safe["ALLOW_YTDL_OPTIONS_OVERRIDES"], False)
+
+    def test_allow_ytdl_options_overrides_boolean_loaded(self):
+        with patch.dict(os.environ, _base_env(ALLOW_YTDL_OPTIONS_OVERRIDES="true"), clear=False):
+            c = Config()
+        self.assertTrue(c.ALLOW_YTDL_OPTIONS_OVERRIDES)
+
+    def test_runtime_override_roundtrip(self):
+        with patch.dict(os.environ, _base_env(), clear=False):
+            c = Config()
+            c.set_runtime_override("cookiefile", "/tmp/c.txt")
+            self.assertEqual(c.YTDL_OPTIONS.get("cookiefile"), "/tmp/c.txt")
+            c.remove_runtime_override("cookiefile")
+            self.assertIsNone(c.YTDL_OPTIONS.get("cookiefile"))
+
+    def test_ytdl_options_file_merges(self):
+        with tempfile.NamedTemporaryFile("w", suffix=".json", delete=False) as f:
+            json.dump({"extractor_args": {"youtube": {"player_client": ["web"]}}}, f)
+            path = f.name
+        try:
+            with patch.dict(
+                os.environ,
+                _base_env(YTDL_OPTIONS="{}", YTDL_OPTIONS_FILE=path),
+                clear=False,
+            ):
+                c = Config()
+            self.assertIn("extractor_args", c.YTDL_OPTIONS)
+        finally:
+            os.unlink(path)
+
+    def test_ytdl_option_presets_file_merges(self):
+        with tempfile.NamedTemporaryFile("w", suffix=".json", delete=False) as f:
+            json.dump({"With subtitles": {"writesubtitles": True}}, f)
+            path = f.name
+        try:
+            with patch.dict(
+                os.environ,
+                _base_env(YTDL_OPTIONS_PRESETS="{}", YTDL_OPTIONS_PRESETS_FILE=path),
+                clear=False,
+            ):
+                c = Config()
+            self.assertIn("With subtitles", c.YTDL_OPTIONS_PRESETS)
+        finally:
+            os.unlink(path)
+
+
+if __name__ == "__main__":
+    unittest.main()

app/tests/test_dl_formats.py

@@ -0,0 +1,139 @@
+"""Tests for ``app.dl_formats`` format selectors and yt-dlp option mapping."""
+
+from __future__ import annotations
+
+import copy
+import unittest
+
+from app.dl_formats import (
+    _normalize_caption_mode,
+    _normalize_subtitle_language,
+    get_format,
+    get_opts,
+)
+
+
+class DlFormatsTests(unittest.TestCase):
+    def test_audio_unknown_format_raises_value_error(self):
+        with self.assertRaises(ValueError):
+            get_format("audio", "auto", "invalid", "best")
+
+    def test_wav_does_not_enable_thumbnail_postprocessing(self):
+        opts = get_opts("audio", "auto", "wav", "best", {})
+        self.assertNotIn("writethumbnail", opts)
+
+    def test_mp3_enables_thumbnail_postprocessing(self):
+        opts = get_opts("audio", "auto", "mp3", "best", {})
+        self.assertTrue(opts.get("writethumbnail"))
+
+    def test_custom_format_passthrough(self):
+        self.assertEqual(get_format("video", "auto", "custom:bestvideo+bestaudio", "best"), "bestvideo+bestaudio")
+
+    def test_thumbnail_and_captions_format_strings(self):
+        self.assertEqual(get_format("thumbnail", "auto", "jpg", "best"), "bestaudio/best")
+        self.assertEqual(get_format("captions", "auto", "srt", "best"), "bestaudio/best")
+
+    def test_audio_formats(self):
+        for fmt in ("m4a", "mp3", "opus", "wav", "flac"):
+            with self.subTest(fmt=fmt):
+                self.assertIn(f"ext={fmt}", get_format("audio", "auto", fmt, "best"))
+
+    def test_video_unknown_format_raises(self):
+        with self.assertRaises(ValueError):
+            get_format("video", "auto", "mkv", "best")
+
+    def test_unknown_download_type_raises(self):
+        with self.assertRaises(ValueError):
+            get_format("unknown", "auto", "any", "best")
+
+    def test_video_any_mp4_ios_with_height_quality(self):
+        self.assertIn("height<=1080", get_format("video", "auto", "any", "1080"))
+        self.assertNotIn("height<=", get_format("video", "auto", "any", "best"))
+        self.assertNotIn("height<=", get_format("video", "auto", "any", "worst"))
+
+    def test_video_codec_filters(self):
+        self.assertIn("h264", get_format("video", "h264", "any", "best"))
+        self.assertIn("hevc", get_format("video", "h265", "any", "best"))
+        self.assertIn("av0?1", get_format("video", "av1", "any", "best"))
+        self.assertIn("vp0?9", get_format("video", "vp9", "any", "best"))
+
+    def test_video_mp4_includes_m4a_audio(self):
+        s = get_format("video", "auto", "mp4", "720")
+        self.assertIn("[ext=m4a]", s)
+
+    def test_video_ios_selector_contains_avc_pattern(self):
+        s = get_format("video", "auto", "ios", "best")
+        self.assertIn("h26[45]", s)
+
+    def test_get_opts_deepcopy_does_not_mutate_input(self):
+        base = {"postprocessors": [{"key": "Existing"}]}
+        orig = copy.deepcopy(base)
+        get_opts("audio", "auto", "mp3", "best", base)
+        self.assertEqual(base, orig)
+
+    def test_get_opts_audio_m4a_postprocessors(self):
+        opts = get_opts("audio", "auto", "m4a", "best", {})
+        keys = [p["key"] for p in opts["postprocessors"]]
+        self.assertIn("FFmpegExtractAudio", keys)
+
+    def test_get_opts_audio_mp3_quality_not_best(self):
+        opts = get_opts("audio", "auto", "mp3", "192", {})
+        ext = next(p for p in opts["postprocessors"] if p["key"] == "FFmpegExtractAudio")
+        self.assertEqual(ext["preferredquality"], "192")
+
+    def test_get_opts_thumbnail_skip_download(self):
+        opts = get_opts("thumbnail", "auto", "jpg", "best", {})
+        self.assertTrue(opts.get("skip_download"))
+        self.assertTrue(opts.get("writethumbnail"))
+
+    def test_get_opts_captions_manual_only(self):
+        opts = get_opts(
+            "captions", "auto", "vtt", "best", {}, subtitle_language="fr", subtitle_mode="manual_only"
+        )
+        self.assertTrue(opts.get("writesubtitles"))
+        self.assertFalse(opts.get("writeautomaticsub"))
+        self.assertEqual(opts["subtitleslangs"], ["fr"])
+
+    def test_get_opts_captions_auto_only(self):
+        opts = get_opts(
+            "captions", "auto", "srt", "best", {}, subtitle_language="de", subtitle_mode="auto_only"
+        )
+        self.assertFalse(opts.get("writesubtitles"))
+        self.assertTrue(opts.get("writeautomaticsub"))
+        self.assertEqual(opts["subtitleslangs"], ["de-orig", "de"])
+
+    def test_get_opts_captions_prefer_auto(self):
+        opts = get_opts(
+            "captions", "auto", "srt", "best", {}, subtitle_language="es", subtitle_mode="prefer_auto"
+        )
+        self.assertTrue(opts.get("writesubtitles"))
+        self.assertTrue(opts.get("writeautomaticsub"))
+        self.assertEqual(opts["subtitleslangs"], ["es-orig", "es"])
+
+    def test_get_opts_captions_prefer_manual_default_branch(self):
+        opts = get_opts(
+            "captions", "auto", "srt", "best", {}, subtitle_language="it", subtitle_mode="prefer_manual"
+        )
+        self.assertEqual(opts["subtitleslangs"], ["it", "it-orig"])
+
+    def test_get_opts_captions_txt_maps_to_srt_format(self):
+        opts = get_opts("captions", "auto", "txt", "best", {})
+        self.assertEqual(opts["subtitlesformat"], "srt")
+
+    def test_get_opts_merges_existing_postprocessors(self):
+        opts = get_opts("audio", "auto", "opus", "best", {"postprocessors": [{"key": "SponsorBlock"}]})
+        keys = [p["key"] for p in opts["postprocessors"]]
+        self.assertIn("SponsorBlock", keys)
+        self.assertIn("FFmpegExtractAudio", keys)
+
+    def test_normalize_caption_mode_invalid_defaults(self):
+        self.assertEqual(_normalize_caption_mode(""), "prefer_manual")
+        self.assertEqual(_normalize_caption_mode("not_a_mode"), "prefer_manual")
+
+    def test_normalize_subtitle_language_empty_defaults_en(self):
+        self.assertEqual(_normalize_subtitle_language(""), "en")
+        self.assertEqual(_normalize_subtitle_language("  "), "en")
+
+
+if __name__ == "__main__":
+    unittest.main()

app/tests/test_download_queue.py

@@ -0,0 +1,310 @@
+"""Tests for ``DownloadQueue`` with mocked yt-dlp extraction."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from ytdl import DownloadQueue
+
+
+@pytest.fixture
+def dq_env():
+    with tempfile.TemporaryDirectory() as tmp:
+        dl = os.path.join(tmp, "downloads")
+        st = os.path.join(tmp, "state")
+        os.makedirs(dl, exist_ok=True)
+        os.makedirs(st, exist_ok=True)
+        cfg = MagicMock()
+        cfg.STATE_DIR = st
+        cfg.DOWNLOAD_DIR = dl
+        cfg.AUDIO_DOWNLOAD_DIR = dl
+        cfg.TEMP_DIR = dl
+        cfg.MAX_CONCURRENT_DOWNLOADS = "3"
+        cfg.YTDL_OPTIONS = {}
+        cfg.YTDL_OPTIONS_PRESETS = {}
+        cfg.CUSTOM_DIRS = True
+        cfg.CREATE_CUSTOM_DIRS = True
+        cfg.CLEAR_COMPLETED_AFTER = "0"
+        cfg.DELETE_FILE_ON_TRASHCAN = False
+        cfg.OUTPUT_TEMPLATE = "%(title)s.%(ext)s"
+        cfg.OUTPUT_TEMPLATE_CHAPTER = "%(title)s.%(ext)s"
+        cfg.OUTPUT_TEMPLATE_PLAYLIST = ""
+        cfg.OUTPUT_TEMPLATE_CHANNEL = ""
+        yield cfg
+
+
+def test_cancel_add_increments_generation(dq_env):
+    notifier = MagicMock()
+    dq = DownloadQueue(dq_env, notifier)
+    before = dq._add_generation
+    dq.cancel_add()
+    assert dq._add_generation == before + 1
+
+
+def test_get_returns_tuple_of_lists(dq_env):
+    notifier = MagicMock()
+    dq = DownloadQueue(dq_env, notifier)
+    q, done = dq.get()
+    assert q == [] and done == []
+
+
+@pytest.mark.asyncio
+async def test_add_single_video_goes_to_pending_when_auto_start_false(dq_env):
+    notifier = AsyncMock()
+
+    def fake_extract(self, url, ytdl_options_presets=None, ytdl_options_overrides=None):
+        return {
+            "_type": "video",
+            "id": "vid1",
+            "title": "Test Video",
+            "url": url,
+            "webpage_url": url,
+        }
+
+    dq = DownloadQueue(dq_env, notifier)
+    with patch.object(DownloadQueue, "_DownloadQueue__extract_info", fake_extract):
+        result = await dq.add(
+            "https://example.com/watch?v=1",
+            "video",
+            "auto",
+            "any",
+            "best",
+            "",
+            "",
+            0,
+            auto_start=False,
+        )
+    assert result["status"] == "ok"
+    assert dq.pending.exists("https://example.com/watch?v=1")
+
+
+@pytest.mark.asyncio
+async def test_cancel_removes_from_pending(dq_env):
+    notifier = AsyncMock()
+
+    def fake_extract(self, url, ytdl_options_presets=None, ytdl_options_overrides=None):
+        return {
+            "_type": "video",
+            "id": "vid1",
+            "title": "Test Video",
+            "url": url,
+            "webpage_url": url,
+        }
+
+    dq = DownloadQueue(dq_env, notifier)
+    with patch.object(DownloadQueue, "_DownloadQueue__extract_info", fake_extract):
+        await dq.add(
+            "https://example.com/pending",
+            "video",
+            "auto",
+            "any",
+            "best",
+            "",
+            "",
+            0,
+            auto_start=False,
+        )
+    url = "https://example.com/pending"
+    await dq.cancel([url])
+    assert not dq.pending.exists(url)
+    notifier.canceled.assert_awaited()
+
+
+@pytest.mark.asyncio
+async def test_start_pending_moves_to_queue(dq_env):
+    notifier = AsyncMock()
+
+    def fake_extract(self, url, ytdl_options_presets=None, ytdl_options_overrides=None):
+        return {
+            "_type": "video",
+            "id": "vid1",
+            "title": "Test Video",
+            "url": url,
+            "webpage_url": url,
+        }
+
+    dq = DownloadQueue(dq_env, notifier)
+    with patch.object(DownloadQueue, "_DownloadQueue__extract_info", fake_extract):
+        await dq.add(
+            "https://example.com/startme",
+            "video",
+            "auto",
+            "any",
+            "best",
+            "",
+            "",
+            0,
+            auto_start=False,
+        )
+    url = "https://example.com/startme"
+    # Starting will spawn real download — cancel immediately before worker runs much
+    with patch.object(DownloadQueue, "_DownloadQueue__start_download", AsyncMock()):
+        await dq.start_pending([url])
+    assert not dq.pending.exists(url)
+
+
+@pytest.mark.asyncio
+async def test_add_entry_queues_single_video_without_reextracting(dq_env):
+    notifier = AsyncMock()
+    dq = DownloadQueue(dq_env, notifier)
+    entry = {
+        "_type": "video",
+        "id": "vid1",
+        "title": "Test Video",
+        "url": "https://example.com/watch?v=1",
+        "webpage_url": "https://example.com/watch?v=1",
+        "playlist_index": "01",
+        "playlist_title": "Playlist",
+    }
+
+    with patch.object(DownloadQueue, "_DownloadQueue__extract_info", side_effect=AssertionError("should not re-extract")):
+        result = await dq.add_entry(
+            entry,
+            "video",
+            "auto",
+            "any",
+            "best",
+            "",
+            "",
+            0,
+            auto_start=False,
+        )
+
+    assert result["status"] == "ok"
+    assert dq.pending.exists("https://example.com/watch?v=1")
+
+
+@pytest.mark.asyncio
+async def test_add_merges_global_preset_and_override_options(dq_env):
+    notifier = AsyncMock()
+    dq_env.YTDL_OPTIONS = {"writesubtitles": False, "cookiefile": "/tmp/global.txt"}
+    dq_env.YTDL_OPTIONS_PRESETS = {
+        "Preset A": {"writesubtitles": True, "proxy": "http://preset-a"},
+        "Preset B": {"writesubtitles": False, "ratelimit": 1000},
+    }
+
+    def fake_extract(self, url, ytdl_options_presets=None, ytdl_options_overrides=None):
+        return {
+            "_type": "video",
+            "id": "vid2",
+            "title": "Preset Video",
+            "url": url,
+            "webpage_url": url,
+        }
+
+    dq = DownloadQueue(dq_env, notifier)
+    with patch.object(DownloadQueue, "_DownloadQueue__extract_info", fake_extract):
+        result = await dq.add(
+            "https://example.com/preset",
+            "video",
+            "auto",
+            "any",
+            "best",
+            "",
+            "",
+            0,
+            auto_start=False,
+            ytdl_options_presets=["Preset A", "Preset B"],
+            ytdl_options_overrides={"proxy": "http://override", "embed_thumbnail": True},
+        )
+
+    assert result["status"] == "ok"
+    queued = dq.pending.get("https://example.com/preset")
+    assert queued.ytdl_opts["cookiefile"] == "/tmp/global.txt"
+    assert queued.ytdl_opts["writesubtitles"] is False
+    assert queued.ytdl_opts["ratelimit"] == 1000
+    assert queued.ytdl_opts["proxy"] == "http://override"
+    assert queued.ytdl_opts["embed_thumbnail"] is True
+
+
+@pytest.mark.asyncio
+async def test_extract_info_preset_null_download_archive_overrides_global(dq_env):
+    """Preset download_archive:null must apply during extract_info (global archive otherwise wins first)."""
+    dq_env.YTDL_OPTIONS = {"download_archive": "/tmp/archive.txt"}
+    dq_env.YTDL_OPTIONS_PRESETS = {"NoArchive": {"download_archive": None}}
+
+    captured_params: list = []
+
+    class FakeYoutubeDL:
+        def __init__(self, params=None):
+            captured_params.append(params)
+
+        def extract_info(self, url, download=False):
+            return {
+                "_type": "video",
+                "id": "vid-archive",
+                "title": "Archive Test",
+                "url": url,
+                "webpage_url": url,
+            }
+
+    notifier = AsyncMock()
+    dq = DownloadQueue(dq_env, notifier)
+    with patch("ytdl.yt_dlp.YoutubeDL", FakeYoutubeDL):
+        result = await dq.add(
+            "https://example.com/archive-test",
+            "video",
+            "auto",
+            "any",
+            "best",
+            "",
+            "",
+            0,
+            auto_start=False,
+            ytdl_options_presets=["NoArchive"],
+        )
+
+    assert result["status"] == "ok"
+    assert len(captured_params) == 1
+    extract_params = captured_params[0]
+    assert extract_params.get("download_archive") is None
+    assert extract_params["extract_flat"] is True
+    assert extract_params["noplaylist"] is True
+
+
+@pytest.mark.asyncio
+async def test_extract_info_metube_extract_keys_win_over_preset(dq_env):
+    """MeTube's flat-extract settings must not be overridden by presets."""
+    dq_env.YTDL_OPTIONS = {}
+    dq_env.YTDL_OPTIONS_PRESETS = {
+        "TryOverride": {"extract_flat": False, "noplaylist": False},
+    }
+
+    captured_params: list = []
+
+    class FakeYoutubeDL:
+        def __init__(self, params=None):
+            captured_params.append(params)
+
+        def extract_info(self, url, download=False):
+            return {
+                "_type": "video",
+                "id": "vid-flat",
+                "title": "Flat Test",
+                "url": url,
+                "webpage_url": url,
+            }
+
+    notifier = AsyncMock()
+    dq = DownloadQueue(dq_env, notifier)
+    with patch("ytdl.yt_dlp.YoutubeDL", FakeYoutubeDL):
+        result = await dq.add(
+            "https://example.com/flat-test",
+            "video",
+            "auto",
+            "any",
+            "best",
+            "",
+            "",
+            0,
+            auto_start=False,
+            ytdl_options_presets=["TryOverride"],
+        )
+
+    assert result["status"] == "ok"
+    assert captured_params[0]["extract_flat"] is True
+    assert captured_params[0]["noplaylist"] is True

app/tests/test_main_helpers.py

@@ -0,0 +1,210 @@
+"""Tests for pure helpers in ``main`` (legacy API migration, logging, JSON serializer)."""
+
+from __future__ import annotations
+
+import json
+import logging
+import unittest
+
+import main
+
+
+class MigrateLegacyRequestTests(unittest.TestCase):
+    def test_already_new_schema_unchanged(self):
+        post = {"download_type": "video", "codec": "h264", "format": "mp4", "quality": "1080"}
+        before = post.copy()
+        self.assertIs(main._migrate_legacy_request(post), post)
+        self.assertEqual(post, before)
+
+    def test_legacy_audio_m4a(self):
+        post = {"format": "m4a", "quality": "best"}
+        main._migrate_legacy_request(post)
+        self.assertEqual(post["download_type"], "audio")
+        self.assertEqual(post["codec"], "auto")
+        self.assertEqual(post["format"], "m4a")
+
+    def test_legacy_thumbnail(self):
+        post = {"format": "thumbnail", "quality": "best"}
+        main._migrate_legacy_request(post)
+        self.assertEqual(post["download_type"], "thumbnail")
+        self.assertEqual(post["format"], "jpg")
+        self.assertEqual(post["quality"], "best")
+
+    def test_legacy_captions_with_subtitle_format(self):
+        post = {"format": "captions", "subtitle_format": "vtt", "quality": "best"}
+        main._migrate_legacy_request(post)
+        self.assertEqual(post["download_type"], "captions")
+        self.assertEqual(post["format"], "vtt")
+
+    def test_legacy_video_best_ios(self):
+        post = {"format": "any", "quality": "best_ios", "video_codec": "auto"}
+        main._migrate_legacy_request(post)
+        self.assertEqual(post["download_type"], "video")
+        self.assertEqual(post["format"], "ios")
+        self.assertEqual(post["quality"], "best")
+
+    def test_legacy_video_quality_audio_maps_to_m4a(self):
+        post = {"format": "mp4", "quality": "audio", "video_codec": "h264"}
+        main._migrate_legacy_request(post)
+        self.assertEqual(post["download_type"], "audio")
+        self.assertEqual(post["format"], "m4a")
+        self.assertEqual(post["quality"], "best")
+
+    def test_legacy_video_default(self):
+        post = {"format": "mp4", "quality": "1080", "video_codec": "h265"}
+        main._migrate_legacy_request(post)
+        self.assertEqual(post["download_type"], "video")
+        self.assertEqual(post["codec"], "h265")
+        self.assertEqual(post["format"], "mp4")
+        self.assertEqual(post["quality"], "1080")
+
+
+class ParseLogLevelTests(unittest.TestCase):
+    def test_valid_levels(self):
+        self.assertEqual(main.parseLogLevel("INFO"), logging.INFO)
+        self.assertEqual(main.parseLogLevel("debug"), logging.DEBUG)
+
+    def test_invalid_returns_none(self):
+        self.assertIsNone(main.parseLogLevel("not_a_level"))
+        self.assertIsNone(main.parseLogLevel(123))
+
+
+class ObjectSerializerTests(unittest.TestCase):
+    def test_dict_like_object(self):
+        class Obj:
+            def __init__(self):
+                self.a = 1
+
+        ser = main.ObjectSerializer()
+        self.assertEqual(json.loads(ser.encode(Obj())), {"a": 1})
+
+    def test_generator_becomes_list(self):
+        ser = main.ObjectSerializer()
+
+        def gen():
+            yield 1
+            yield 2
+
+        self.assertEqual(json.loads(ser.encode(gen())), [1, 2])
+
+    def test_string_not_split_to_chars(self):
+        ser = main.ObjectSerializer()
+        self.assertEqual(json.loads(ser.encode("hello")), "hello")
+
+
+class FrontendSafeTests(unittest.TestCase):
+    def test_only_expected_keys(self):
+        safe = main.config.frontend_safe()
+        for key in main.Config._FRONTEND_KEYS:
+            self.assertIn(key, safe)
+        self.assertNotIn("YTDL_OPTIONS", safe)
+        self.assertNotIn("DOWNLOAD_DIR", safe)
+        self.assertIn("ALLOW_YTDL_OPTIONS_OVERRIDES", safe)
+
+
+class ParseYtdlOverridesTests(unittest.TestCase):
+    def test_empty_override_string_returns_empty_dict(self):
+        self.assertEqual(main._parse_ytdl_options_overrides("", enabled=False), {})
+
+    def test_rejects_non_object_json(self):
+        with self.assertRaises(main.web.HTTPBadRequest):
+            main._parse_ytdl_options_overrides('["bad"]', enabled=True)
+
+    def test_rejects_non_empty_overrides_when_disabled(self):
+        with self.assertRaises(main.web.HTTPBadRequest):
+            main._parse_ytdl_options_overrides('{"exec": "rm -rf /"}', enabled=False)
+
+    def test_allows_any_keys_when_enabled(self):
+        self.assertEqual(
+            main._parse_ytdl_options_overrides('{"exec": "rm -rf /"}', enabled=True),
+            {"exec": "rm -rf /"},
+        )
+
+
+class ParseDownloadOptionsTests(unittest.TestCase):
+    def test_accepts_known_preset_and_overrides(self):
+        previous = dict(main.config.YTDL_OPTIONS_PRESETS)
+        previous_allow = main.config.ALLOW_YTDL_OPTIONS_OVERRIDES
+        main.config.YTDL_OPTIONS_PRESETS = {"With subtitles": {"writesubtitles": True}}
+        main.config.ALLOW_YTDL_OPTIONS_OVERRIDES = True
+        try:
+            parsed = main.parse_download_options({
+                "url": "https://example.com/v",
+                "download_type": "video",
+                "codec": "auto",
+                "format": "any",
+                "quality": "best",
+                "ytdl_options_preset": "With subtitles",
+                "ytdl_options_overrides": '{"writesubtitles": true}',
+            })
+        finally:
+            main.config.YTDL_OPTIONS_PRESETS = previous
+            main.config.ALLOW_YTDL_OPTIONS_OVERRIDES = previous_allow
+        self.assertEqual(parsed["ytdl_options_presets"], ["With subtitles"])
+        self.assertEqual(parsed["ytdl_options_overrides"], {"writesubtitles": True})
+
+    def test_accepts_multiple_presets_in_order(self):
+        previous = dict(main.config.YTDL_OPTIONS_PRESETS)
+        main.config.YTDL_OPTIONS_PRESETS = {
+            "A": {"writesubtitles": True},
+            "B": {"writesubtitles": False},
+        }
+        try:
+            parsed = main.parse_download_options({
+                "url": "https://example.com/v",
+                "download_type": "video",
+                "codec": "auto",
+                "format": "any",
+                "quality": "best",
+                "ytdl_options_presets": ["A", "B"],
+            })
+        finally:
+            main.config.YTDL_OPTIONS_PRESETS = previous
+        self.assertEqual(parsed["ytdl_options_presets"], ["A", "B"])
+
+    def test_legacy_singular_preset_string_normalized_to_list(self):
+        previous = dict(main.config.YTDL_OPTIONS_PRESETS)
+        main.config.YTDL_OPTIONS_PRESETS = {"Solo": {}}
+        try:
+            parsed = main.parse_download_options({
+                "url": "https://example.com/v",
+                "download_type": "video",
+                "codec": "auto",
+                "format": "any",
+                "quality": "best",
+                "ytdl_options_preset": "Solo",
+            })
+        finally:
+            main.config.YTDL_OPTIONS_PRESETS = previous
+        self.assertEqual(parsed["ytdl_options_presets"], ["Solo"])
+
+    def test_rejects_unknown_preset(self):
+        with self.assertRaises(main.web.HTTPBadRequest):
+            main.parse_download_options({
+                "url": "https://example.com/v",
+                "download_type": "video",
+                "codec": "auto",
+                "format": "any",
+                "quality": "best",
+                "ytdl_options_presets": ["Missing preset"],
+            })
+
+    def test_rejects_unknown_preset_in_list(self):
+        previous = dict(main.config.YTDL_OPTIONS_PRESETS)
+        main.config.YTDL_OPTIONS_PRESETS = {"Known": {}}
+        try:
+            with self.assertRaises(main.web.HTTPBadRequest):
+                main.parse_download_options({
+                    "url": "https://example.com/v",
+                    "download_type": "video",
+                    "codec": "auto",
+                    "format": "any",
+                    "quality": "best",
+                    "ytdl_options_presets": ["Known", "Nope"],
+                })
+        finally:
+            main.config.YTDL_OPTIONS_PRESETS = previous
+
+
+if __name__ == "__main__":
+    unittest.main()

app/tests/test_persistent_queue.py

@@ -0,0 +1,291 @@
+"""Integration tests for ``PersistentQueue`` using the JSON state store."""
+
+from __future__ import annotations
+
+import json
+import os
+import shelve
+import sys
+import tempfile
+import types
+import unittest
+from unittest.mock import patch
+
+fake_yt_dlp = types.ModuleType("yt_dlp")
+fake_networking = types.ModuleType("yt_dlp.networking")
+fake_impersonate = types.ModuleType("yt_dlp.networking.impersonate")
+fake_utils = types.ModuleType("yt_dlp.utils")
+
+
+class _ImpersonateTarget:
+    @staticmethod
+    def from_str(value):
+        return value
+
+
+fake_impersonate.ImpersonateTarget = _ImpersonateTarget
+fake_networking.impersonate = fake_impersonate
+fake_utils.STR_FORMAT_RE_TMPL = r"(?P<prefix>)%\((?P<has_key>{})\)(?P<format>[-0-9.]*{})"
+fake_utils.STR_FORMAT_TYPES = "diouxXeEfFgGcrsa"
+fake_yt_dlp.networking = fake_networking
+fake_yt_dlp.utils = fake_utils
+sys.modules.setdefault("yt_dlp", fake_yt_dlp)
+sys.modules.setdefault("yt_dlp.networking", fake_networking)
+sys.modules.setdefault("yt_dlp.networking.impersonate", fake_impersonate)
+sys.modules.setdefault("yt_dlp.utils", fake_utils)
+
+from ytdl import DownloadInfo, PersistentQueue
+
+
+class _FakeDownload:
+    __slots__ = ("info",)
+
+    def __init__(self, info: DownloadInfo):
+        self.info = info
+
+
+def _make_info(url: str = "https://example.com/v") -> DownloadInfo:
+    return DownloadInfo(
+        id="id1",
+        title="Title",
+        url=url,
+        quality="best",
+        download_type="video",
+        codec="auto",
+        format="any",
+        folder="",
+        custom_name_prefix="",
+        error=None,
+        entry=None,
+        playlist_item_limit=0,
+        split_by_chapters=False,
+        chapter_template="",
+    )
+
+
+def _create_legacy_shelf(path: str, *infos: DownloadInfo) -> None:
+    with shelve.open(path, "c") as shelf:
+        for info in infos:
+            shelf[info.url] = info
+
+
+class PersistentQueueTests(unittest.TestCase):
+    def test_put_get_delete_roundtrip(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = os.path.join(tmp, "queue")
+            pq = PersistentQueue("queue", path)
+            dl = _FakeDownload(_make_info("http://a.example"))
+            pq.put(dl)
+            self.assertTrue(os.path.exists(path + ".json"))
+            self.assertTrue(pq.exists("http://a.example"))
+            self.assertFalse(pq.empty())
+            got = pq.get("http://a.example")
+            self.assertEqual(got.info.url, "http://a.example")
+            pq.delete("http://a.example")
+            self.assertFalse(pq.exists("http://a.example"))
+
+    def test_saved_items_sorted_by_timestamp(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = os.path.join(tmp, "queue")
+            pq = PersistentQueue("queue", path)
+            a = _FakeDownload(_make_info("http://first.example"))
+            b = _FakeDownload(_make_info("http://second.example"))
+            a.info.timestamp = 100
+            b.info.timestamp = 200
+            pq.put(a)
+            pq.put(b)
+            keys = [k for k, _ in pq.saved_items()]
+            self.assertEqual(keys, ["http://first.example", "http://second.example"])
+
+    def test_load_restores_from_json(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = os.path.join(tmp, "queue")
+            pq1 = PersistentQueue("queue", path)
+            pq1.put(_FakeDownload(_make_info("http://load.example")))
+            pq2 = PersistentQueue("queue", path)
+            pq2.load()
+            self.assertTrue(pq2.exists("http://load.example"))
+
+    def test_load_imports_legacy_shelve(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = os.path.join(tmp, "queue")
+            _create_legacy_shelf(path, _make_info("http://legacy.example"))
+            pq = PersistentQueue("queue", path)
+            pq.load()
+            self.assertTrue(pq.exists("http://legacy.example"))
+            self.assertTrue(os.path.exists(path + ".json"))
+
+    def test_queue_persists_only_compact_entry_subset(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = os.path.join(tmp, "queue")
+            pq = PersistentQueue("queue", path)
+            info = _make_info("http://entry.example")
+            info.entry = {
+                "playlist_index": "01",
+                "playlist_title": "Playlist",
+                "channel_index": "02",
+                "channel_title": "Channel",
+                "formats": [{"id": "huge"}],
+                "description": "very large payload",
+            }
+            pq.put(_FakeDownload(info))
+
+            with open(path + ".json", encoding="utf-8") as f:
+                payload = json.load(f)
+
+            record = payload["items"][0]["info"]
+            self.assertEqual(
+                record["entry"],
+                {
+                    "playlist_index": "01",
+                    "playlist_title": "Playlist",
+                    "channel_index": "02",
+                    "channel_title": "Channel",
+                },
+            )
+            self.assertNotIn("formats", record["entry"])
+            self.assertNotIn("description", record["entry"])
+
+    def test_completed_queue_does_not_persist_entry_or_transient_progress(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = os.path.join(tmp, "completed")
+            pq = PersistentQueue("completed", path)
+            info = _make_info("http://done.example")
+            info.status = "finished"
+            info.percent = 88
+            info.speed = 123
+            info.eta = 9
+            info.entry = {
+                "playlist_index": "01",
+                "playlist_title": "Playlist",
+                "formats": [{"id": "huge"}],
+            }
+            info.filename = "done.mp4"
+            pq.put(_FakeDownload(info))
+
+            with open(path + ".json", encoding="utf-8") as f:
+                payload = json.load(f)
+
+            record = payload["items"][0]["info"]
+            self.assertNotIn("entry", record)
+            self.assertNotIn("percent", record)
+            self.assertNotIn("speed", record)
+            self.assertNotIn("eta", record)
+            self.assertEqual(record["filename"], "done.mp4")
+
+    def test_invalid_json_is_quarantined_and_legacy_is_imported(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = os.path.join(tmp, "queue")
+            _create_legacy_shelf(path, _make_info("http://legacy.example"))
+            with open(path + ".json", "w", encoding="utf-8") as f:
+                f.write("{not valid json")
+
+            pq = PersistentQueue("queue", path)
+            pq.load()
+
+            self.assertTrue(pq.exists("http://legacy.example"))
+            self.assertTrue(
+                any(name.startswith("queue.json.invalid.") for name in os.listdir(tmp))
+            )
+
+    def test_loading_old_json_rewrites_to_compact_format(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = os.path.join(tmp, "queue")
+            with open(path + ".json", "w", encoding="utf-8") as f:
+                json.dump(
+                    {
+                        "schema_version": 1,
+                        "kind": "persistent_queue:queue",
+                        "items": [
+                            {
+                                "key": "http://legacy-json.example",
+                                "info": {
+                                    "id": "id1",
+                                    "title": "Title",
+                                    "url": "http://legacy-json.example",
+                                    "quality": "best",
+                                    "download_type": "video",
+                                    "codec": "auto",
+                                    "format": "any",
+                                    "folder": "",
+                                    "custom_name_prefix": "",
+                                    "playlist_item_limit": 0,
+                                    "split_by_chapters": False,
+                                    "chapter_template": "",
+                                    "subtitle_language": "en",
+                                    "subtitle_mode": "prefer_manual",
+                                    "status": "pending",
+                                    "timestamp": 1,
+                                    "entry": {
+                                        "playlist_index": "01",
+                                        "playlist_title": "Playlist",
+                                        "formats": [{"id": "huge"}],
+                                    },
+                                    "percent": 15,
+                                    "speed": 20,
+                                    "eta": 30,
+                                },
+                            }
+                        ],
+                    },
+                    f,
+                )
+
+            pq = PersistentQueue("queue", path)
+            pq.load()
+
+            with open(path + ".json", encoding="utf-8") as f:
+                payload = json.load(f)
+
+            record = payload["items"][0]["info"]
+            self.assertEqual(payload["schema_version"], 2)
+            self.assertEqual(record["entry"], {"playlist_index": "01", "playlist_title": "Playlist"})
+            self.assertNotIn("percent", record)
+            self.assertNotIn("speed", record)
+            self.assertNotIn("eta", record)
+
+    def test_put_rollbacks_in_memory_queue_when_state_write_fails(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = os.path.join(tmp, "queue")
+            pq = PersistentQueue("queue", path)
+            dl = _FakeDownload(_make_info("http://rollback.example"))
+            self.assertFalse(pq.exists("http://rollback.example"))
+
+            orig_save = __import__("state_store").AtomicJsonStore.save
+
+            def bad_save(store, data):
+                if store.path == path + ".json":
+                    raise OSError("simulated shelf failure")
+                return orig_save(store, data)
+
+            with patch("ytdl.AtomicJsonStore.save", bad_save):
+                with self.assertRaises(OSError):
+                    pq.put(dl)
+
+            self.assertFalse(pq.exists("http://rollback.example"))
+
+    def test_put_rollbacks_to_previous_download_when_replace_fails(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = os.path.join(tmp, "queue")
+            pq = PersistentQueue("queue", path)
+            first = _FakeDownload(_make_info("http://same.example"))
+            second = _FakeDownload(_make_info("http://same.example"))
+            second.info.title = "Replaced title"
+            pq.put(first)
+
+            orig_save = __import__("state_store").AtomicJsonStore.save
+
+            def bad_save(store, data):
+                if store.path == path + ".json":
+                    raise OSError("simulated shelf failure")
+                return orig_save(store, data)
+
+            with patch("ytdl.AtomicJsonStore.save", bad_save):
+                with self.assertRaises(OSError):
+                    pq.put(second)
+
+            self.assertEqual(pq.get("http://same.example").info.title, "Title")
+
+
+if __name__ == "__main__":
+    unittest.main()

app/tests/test_state_store.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import os
+import tempfile
+import unittest
+from datetime import datetime
+
+from state_store import AtomicJsonStore, from_json_compatible, to_json_compatible
+
+
+class StateStoreTests(unittest.TestCase):
+    def test_save_and_load_roundtrip(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = os.path.join(tmp, "queue.json")
+            store = AtomicJsonStore(path, kind="persistent_queue:queue")
+            store.save({"items": [{"key": "a", "info": {"title": "hello"}}]})
+
+            payload = store.load()
+
+            self.assertEqual(payload["kind"], "persistent_queue:queue")
+            self.assertEqual(payload["schema_version"], 2)
+            self.assertEqual(payload["items"][0]["info"]["title"], "hello")
+
+    def test_invalid_file_is_quarantined(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = os.path.join(tmp, "queue.json")
+            with open(path, "w", encoding="utf-8") as f:
+                f.write("{broken")
+
+            store = AtomicJsonStore(path, kind="persistent_queue:queue")
+            payload = store.load()
+
+            self.assertIsNone(payload)
+            self.assertTrue(
+                any(name.startswith("queue.json.invalid.") for name in os.listdir(tmp))
+            )
+
+    def test_json_compat_helpers_roundtrip_bytes_and_datetime(self):
+        raw = {
+            "payload": b"abc",
+            "timestamp": datetime(2024, 1, 2, 3, 4, 5),
+            "items": (1, 2, 3),
+        }
+
+        restored = from_json_compatible(to_json_compatible(raw))
+
+        self.assertEqual(restored["payload"], b"abc")
+        self.assertEqual(restored["timestamp"], datetime(2024, 1, 2, 3, 4, 5))
+        self.assertEqual(restored["items"], [1, 2, 3])
+
+
+if __name__ == "__main__":
+    unittest.main()

app/tests/test_subscriptions.py

@@ -0,0 +1,510 @@
+from __future__ import annotations
+
+import json
+import os
+import shelve
+import sys
+import tempfile
+import types
+import unittest
+from unittest.mock import patch
+
+fake_yt_dlp = types.ModuleType("yt_dlp")
+fake_networking = types.ModuleType("yt_dlp.networking")
+fake_impersonate = types.ModuleType("yt_dlp.networking.impersonate")
+
+
+class _ImpersonateTarget:
+    @staticmethod
+    def from_str(value):
+        return value
+
+
+fake_impersonate.ImpersonateTarget = _ImpersonateTarget
+fake_networking.impersonate = fake_impersonate
+fake_yt_dlp.networking = fake_networking
+fake_yt_dlp.utils = types.SimpleNamespace(YoutubeDLError=Exception)
+sys.modules.setdefault("yt_dlp", fake_yt_dlp)
+sys.modules.setdefault("yt_dlp.networking", fake_networking)
+sys.modules.setdefault("yt_dlp.networking.impersonate", fake_impersonate)
+
+from subscriptions import SubscriptionManager, extract_flat_playlist
+
+
+class _Config:
+    def __init__(self, state_dir: str):
+        self.STATE_DIR = state_dir
+        self.SUBSCRIPTION_SCAN_PLAYLIST_END = 50
+        self.SUBSCRIPTION_MAX_SEEN_IDS = 50000
+        self.DOWNLOAD_DIR = state_dir
+        self.TEMP_DIR = state_dir
+        self.YTDL_OPTIONS = {}
+
+
+class _Queue:
+    def __init__(self):
+        self.entries = []
+        self.fail = False
+
+    async def add(self, *args, **kwargs):
+        return None
+
+    async def add_entry(self, entry, *args, **kwargs):
+        if self.fail:
+            return {"status": "error", "msg": "queue failed"}
+        self.entries.append((entry, args, kwargs))
+        return {"status": "ok"}
+
+
+class _Notifier:
+    async def subscription_added(self, sub):
+        return None
+
+    async def subscription_updated(self, sub):
+        return None
+
+    async def subscription_removed(self, sub_id):
+        return None
+
+    async def subscriptions_all(self, subs):
+        return None
+
+
+def _create_legacy_shelf(path: str, record) -> None:
+    with shelve.open(path, "c") as shelf:
+        shelf["sub-1"] = record
+
+
+class SubscriptionPersistenceTests(unittest.IsolatedAsyncioTestCase):
+    def test_load_imports_legacy_subscription_shelf(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            legacy_path = os.path.join(tmp, "subscriptions")
+            json_path = os.path.join(tmp, "subscriptions.json")
+            _create_legacy_shelf(
+                legacy_path,
+                {
+                    "id": "sub-1",
+                    "name": "Channel",
+                    "url": "https://example.com/channel",
+                    "timestamp": 1.0,
+                },
+            )
+
+            mgr = SubscriptionManager(_Config(tmp), _Queue(), _Notifier())
+
+            self.assertEqual(len(mgr.list_all()), 1)
+            self.assertTrue(os.path.exists(json_path))
+            with open(json_path, encoding="utf-8") as f:
+                payload = json.load(f)
+            self.assertEqual(payload["schema_version"], 2)
+            self.assertNotIn("timestamp", payload["items"][0])
+
+    def test_invalid_json_is_quarantined_and_legacy_is_imported(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            legacy_path = os.path.join(tmp, "subscriptions")
+            json_path = os.path.join(tmp, "subscriptions.json")
+            _create_legacy_shelf(
+                legacy_path,
+                {
+                    "id": "sub-1",
+                    "name": "Channel",
+                    "url": "https://example.com/channel",
+                    "timestamp": 1.0,
+                },
+            )
+            with open(json_path, "w", encoding="utf-8") as f:
+                f.write("{not valid json")
+
+            mgr = SubscriptionManager(_Config(tmp), _Queue(), _Notifier())
+
+            self.assertEqual(len(mgr.list_all()), 1)
+            self.assertTrue(
+                any(name.startswith("subscriptions.json.invalid.") for name in os.listdir(tmp))
+            )
+
+    def test_load_rewrites_old_json_and_trims_seen_ids(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            json_path = os.path.join(tmp, "subscriptions.json")
+            cfg = _Config(tmp)
+            cfg.SUBSCRIPTION_MAX_SEEN_IDS = 2
+            with open(json_path, "w", encoding="utf-8") as f:
+                json.dump(
+                    {
+                        "schema_version": 1,
+                        "kind": "subscriptions",
+                        "items": [
+                            {
+                                "id": "sub-1",
+                                "name": "Channel",
+                                "url": "https://example.com/channel",
+                                "enabled": True,
+                                "check_interval_minutes": 60,
+                                "download_type": "video",
+                                "codec": "auto",
+                                "format": "any",
+                                "quality": "best",
+                                "folder": "",
+                                "custom_name_prefix": "",
+                                "auto_start": True,
+                                "playlist_item_limit": 0,
+                                "split_by_chapters": False,
+                                "chapter_template": "",
+                                "subtitle_language": "en",
+                                "subtitle_mode": "prefer_manual",
+                                "last_checked": None,
+                                "seen_ids": ["a", "b", "a", "c"],
+                                "error": None,
+                                "timestamp": 123,
+                            }
+                        ],
+                    },
+                    f,
+                )
+
+            mgr = SubscriptionManager(cfg, _Queue(), _Notifier())
+            self.assertEqual(mgr.list_all()[0].seen_ids, ["a", "b"])
+
+            with open(json_path, encoding="utf-8") as f:
+                payload = json.load(f)
+
+            self.assertEqual(payload["schema_version"], 2)
+            self.assertEqual(payload["items"][0]["seen_ids"], ["a", "b"])
+            self.assertNotIn("timestamp", payload["items"][0])
+
+    async def test_add_subscription_rolls_back_when_state_write_fails(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            mgr = SubscriptionManager(_Config(tmp), _Queue(), _Notifier())
+
+            orig_save = __import__("state_store").AtomicJsonStore.save
+
+            def bad_save(store, data):
+                if store.path == mgr._path:
+                    raise OSError("simulated shelf failure")
+                return orig_save(store, data)
+
+            with patch(
+                "subscriptions.extract_flat_playlist",
+                return_value=(
+                    {"_type": "channel", "title": "Channel"},
+                    [{"id": "v1", "webpage_url": "https://example.com/v1"}],
+                ),
+            ):
+                with patch("subscriptions.AtomicJsonStore.save", bad_save):
+                    with self.assertRaises(OSError):
+                        await mgr.add_subscription(
+                            "https://example.com/channel",
+                            check_interval_minutes=60,
+                            download_type="video",
+                            codec="auto",
+                            format="any",
+                            quality="best",
+                            folder="",
+                            custom_name_prefix="",
+                            auto_start=True,
+                            playlist_item_limit=0,
+                            split_by_chapters=False,
+                            chapter_template="",
+                            subtitle_language="en",
+                            subtitle_mode="prefer_manual",
+                        )
+
+            self.assertEqual(mgr.list_all(), [])
+            self.assertNotIn("https://example.com/channel", mgr._url_index)
+
+    async def test_add_subscription_marks_existing_videos_seen_without_queueing(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            queue = _Queue()
+            mgr = SubscriptionManager(_Config(tmp), queue, _Notifier())
+
+            with patch(
+                "subscriptions.extract_flat_playlist",
+                return_value=(
+                    {"_type": "channel", "title": "Channel"},
+                    [
+                        {"id": "v1", "title": "One", "webpage_url": "https://example.com/v1"},
+                        {"id": "v2", "title": "Two", "webpage_url": "https://example.com/v2"},
+                        {"id": "v3", "title": "Three", "webpage_url": "https://example.com/v3"},
+                    ],
+                ),
+            ):
+                result = await mgr.add_subscription(
+                    "https://example.com/channel",
+                    check_interval_minutes=60,
+                    download_type="video",
+                    codec="auto",
+                    format="any",
+                    quality="best",
+                    folder="",
+                    custom_name_prefix="",
+                    auto_start=True,
+                    playlist_item_limit=0,
+                    split_by_chapters=False,
+                    chapter_template="",
+                    subtitle_language="en",
+                    subtitle_mode="prefer_manual",
+                )
+
+            assert result["status"] == "ok"
+            sub = mgr.list_all()[0]
+            self.assertEqual(sub.seen_ids, ["v1", "v2", "v3"])
+            self.assertIsNone(sub.error)
+            self.assertEqual(queue.entries, [])
+
+    async def test_add_subscription_skips_collection_tab_entries(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            queue = _Queue()
+            mgr = SubscriptionManager(_Config(tmp), queue, _Notifier())
+
+            with patch(
+                "subscriptions.extract_flat_playlist",
+                return_value=(
+                    {"_type": "channel", "title": "Channel"},
+                    [
+                        {
+                            "_type": "url",
+                            "ie_key": "YoutubeTab",
+                            "title": "Channel - Live",
+                            "url": "https://example.com/live",
+                            "webpage_url": "https://example.com/live",
+                        },
+                        {
+                            "_type": "url",
+                            "ie_key": "Youtube",
+                            "id": "v1",
+                            "title": "One",
+                            "duration": 10,
+                            "webpage_url": "https://example.com/v1",
+                        },
+                    ],
+                ),
+            ):
+                result = await mgr.add_subscription(
+                    "https://example.com/channel",
+                    check_interval_minutes=60,
+                    download_type="video",
+                    codec="auto",
+                    format="any",
+                    quality="best",
+                    folder="",
+                    custom_name_prefix="",
+                    auto_start=True,
+                    playlist_item_limit=0,
+                    split_by_chapters=False,
+                    chapter_template="",
+                    subtitle_language="en",
+                    subtitle_mode="prefer_manual",
+                )
+
+            self.assertEqual(result["status"], "ok")
+            sub = mgr.list_all()[0]
+            self.assertEqual(sub.seen_ids, ["v1"])
+            self.assertEqual(queue.entries, [])
+
+    async def test_check_now_keeps_failed_queue_items_unseen_and_sets_error(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            queue = _Queue()
+            mgr = SubscriptionManager(_Config(tmp), queue, _Notifier())
+
+            with patch(
+                "subscriptions.extract_flat_playlist",
+                side_effect=[
+                    (
+                        {"_type": "channel", "title": "Channel"},
+                        [{"id": "v1", "title": "One", "webpage_url": "https://example.com/v1"}],
+                    ),
+                    (
+                        {"_type": "channel", "title": "Channel"},
+                        [{"id": "v2", "title": "Two", "webpage_url": "https://example.com/v2"}],
+                    ),
+                ],
+            ):
+                result = await mgr.add_subscription(
+                    "https://example.com/channel",
+                    check_interval_minutes=60,
+                    download_type="video",
+                    codec="auto",
+                    format="any",
+                    quality="best",
+                    folder="",
+                    custom_name_prefix="",
+                    auto_start=True,
+                    playlist_item_limit=0,
+                    split_by_chapters=False,
+                    chapter_template="",
+                    subtitle_language="en",
+                    subtitle_mode="prefer_manual",
+                )
+                queue.fail = True
+                await mgr.check_now([result["subscription"]["id"]])
+
+            sub = mgr.list_all()[0]
+            self.assertEqual(sub.error, "queue failed")
+            self.assertEqual(sub.seen_ids, ["v1"])
+
+    async def test_check_now_queues_new_video_and_updates_seen_ids(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            queue = _Queue()
+            mgr = SubscriptionManager(_Config(tmp), queue, _Notifier())
+
+            with patch(
+                "subscriptions.extract_flat_playlist",
+                side_effect=[
+                    (
+                        {"_type": "channel", "title": "Channel"},
+                        [{"id": "v1", "title": "One", "webpage_url": "https://example.com/v1"}],
+                    ),
+                    (
+                        {"_type": "channel", "title": "Channel"},
+                        [
+                            {"id": "v2", "title": "Two", "webpage_url": "https://example.com/v2"},
+                            {"id": "v1", "title": "One", "webpage_url": "https://example.com/v1"},
+                        ],
+                    ),
+                ],
+            ):
+                result = await mgr.add_subscription(
+                    "https://example.com/channel",
+                    check_interval_minutes=60,
+                    download_type="video",
+                    codec="auto",
+                    format="any",
+                    quality="best",
+                    folder="",
+                    custom_name_prefix="",
+                    auto_start=True,
+                    playlist_item_limit=0,
+                    split_by_chapters=False,
+                    chapter_template="",
+                    subtitle_language="en",
+                    subtitle_mode="prefer_manual",
+                )
+                await mgr.check_now([result["subscription"]["id"]])
+
+            sub = mgr.list_all()[0]
+            self.assertIsNotNone(sub.last_checked)
+            self.assertIsNone(sub.error)
+            self.assertEqual(sub.seen_ids[:2], ["v2", "v1"])
+            self.assertEqual([entry["webpage_url"] for entry, _, _ in queue.entries], ["https://example.com/v2"])
+
+    async def test_update_subscription_parses_string_false_enabled(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            queue = _Queue()
+            mgr = SubscriptionManager(_Config(tmp), queue, _Notifier())
+
+            with patch(
+                "subscriptions.extract_flat_playlist",
+                return_value=(
+                    {"_type": "channel", "title": "Channel"},
+                    [{"id": "v1", "title": "One", "webpage_url": "https://example.com/v1"}],
+                ),
+            ):
+                result = await mgr.add_subscription(
+                    "https://example.com/channel",
+                    check_interval_minutes=60,
+                    download_type="video",
+                    codec="auto",
+                    format="any",
+                    quality="best",
+                    folder="",
+                    custom_name_prefix="",
+                    auto_start=True,
+                    playlist_item_limit=0,
+                    split_by_chapters=False,
+                    chapter_template="",
+                    subtitle_language="en",
+                    subtitle_mode="prefer_manual",
+                )
+
+            sub_id = result["subscription"]["id"]
+            update = await mgr.update_subscription(sub_id, {"enabled": "false"})
+            self.assertEqual(update["status"], "ok")
+            self.assertFalse(mgr.list_all()[0].enabled)
+
+    async def test_update_subscription_rejects_invalid_enabled_value(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            queue = _Queue()
+            mgr = SubscriptionManager(_Config(tmp), queue, _Notifier())
+
+            with patch(
+                "subscriptions.extract_flat_playlist",
+                return_value=(
+                    {"_type": "channel", "title": "Channel"},
+                    [{"id": "v1", "title": "One", "webpage_url": "https://example.com/v1"}],
+                ),
+            ):
+                result = await mgr.add_subscription(
+                    "https://example.com/channel",
+                    check_interval_minutes=60,
+                    download_type="video",
+                    codec="auto",
+                    format="any",
+                    quality="best",
+                    folder="",
+                    custom_name_prefix="",
+                    auto_start=True,
+                    playlist_item_limit=0,
+                    split_by_chapters=False,
+                    chapter_template="",
+                    subtitle_language="en",
+                    subtitle_mode="prefer_manual",
+                )
+
+            sub_id = result["subscription"]["id"]
+            with self.assertRaises(ValueError):
+                await mgr.update_subscription(sub_id, {"enabled": "maybe"})
+
+class ExtractFlatPlaylistTests(unittest.TestCase):
+    def test_descends_one_level_when_root_entries_are_nested_collections(self):
+        responses = iter(
+            [
+                {
+                    "_type": "channel",
+                    "entries": [
+                        {
+                            "_type": "url",
+                            "ie_key": "YoutubeTab",
+                            "title": "Channel - Videos",
+                            "url": "https://example.com/videos",
+                            "webpage_url": "https://example.com/videos",
+                        }
+                    ],
+                },
+                {
+                    "_type": "playlist",
+                    "entries": [
+                        {
+                            "_type": "url",
+                            "ie_key": "Youtube",
+                            "id": "v1",
+                            "title": "One",
+                            "duration": 10,
+                            "webpage_url": "https://example.com/v1",
+                        }
+                    ],
+                },
+            ]
+        )
+
+        class _FakeYDL:
+            def __init__(self, params):
+                self.params = params
+
+            def __enter__(self):
+                return self
+
+            def __exit__(self, exc_type, exc, tb):
+                return False
+
+            def extract_info(self, url, download=False):
+                return next(responses)
+
+        cfg = _Config(tempfile.mkdtemp())
+        with patch("subscriptions.yt_dlp.YoutubeDL", _FakeYDL, create=True):
+            info, entries = extract_flat_playlist(cfg, "https://example.com/channel", 50)
+
+        self.assertEqual(info.get("_type"), "playlist")
+        self.assertEqual([entry["webpage_url"] for entry in entries], ["https://example.com/v1"])
+
+
+if __name__ == "__main__":
+    unittest.main()

app/tests/test_ytdl_utils.py

@@ -0,0 +1,313 @@
+"""Tests for pure helpers and migration logic in ``ytdl``."""
+
+from __future__ import annotations
+
+import pickle
+import sys
+import tempfile
+import threading
+import types
+import unittest
+from pathlib import Path
+
+fake_yt_dlp = types.ModuleType("yt_dlp")
+fake_networking = types.ModuleType("yt_dlp.networking")
+fake_impersonate = types.ModuleType("yt_dlp.networking.impersonate")
+fake_utils = types.ModuleType("yt_dlp.utils")
+
+
+class _ImpersonateTarget:
+    @staticmethod
+    def from_str(value):
+        return value
+
+
+fake_impersonate.ImpersonateTarget = _ImpersonateTarget
+fake_networking.impersonate = fake_impersonate
+# The inner ``key`` group mirrors the real ``STR_FORMAT_RE_TMPL`` so that
+# ``_OUTTMPL_FIELD_RE`` (compiled at import time) has the named group that
+# ``_resolve_outtmpl_fields`` reads via ``match.group('key')``.
+fake_utils.STR_FORMAT_RE_TMPL = r"(?P<prefix>)%\((?P<has_key>(?P<key>{}))\)(?P<format>[-0-9.]*{})"
+fake_utils.STR_FORMAT_TYPES = "diouxXeEfFgGcrsa"
+fake_yt_dlp.networking = fake_networking
+fake_yt_dlp.utils = fake_utils
+sys.modules.setdefault("yt_dlp", fake_yt_dlp)
+sys.modules.setdefault("yt_dlp.networking", fake_networking)
+sys.modules.setdefault("yt_dlp.networking.impersonate", fake_impersonate)
+sys.modules.setdefault("yt_dlp.utils", fake_utils)
+
+from ytdl import (
+    DownloadInfo,
+    _compact_persisted_entry,
+    _convert_srt_to_txt_file,
+    _resolve_outtmpl_fields,
+    _sanitize_entry_for_pickle,
+    _sanitize_path_component,
+)
+
+# Detect whether the real yt-dlp is loaded (as opposed to the minimal fake
+# shim above).  _resolve_outtmpl_fields needs YoutubeDL at runtime.
+_has_real_ytdlp = hasattr(sys.modules.get("yt_dlp"), "YoutubeDL")
+
+
+class SanitizePathComponentTests(unittest.TestCase):
+    def test_replaces_windows_invalid_chars(self):
+        self.assertEqual(_sanitize_path_component('a:b*c?d"e<f>g|h'), "a_b_c_d_e_f_g_h")
+
+    def test_non_string_passthrough(self):
+        self.assertIs(_sanitize_path_component(None), None)
+        self.assertEqual(_sanitize_path_component(42), 42)
+
+
+@unittest.skipUnless(_has_real_ytdlp, "requires real yt-dlp")
+class ResolveOuttmplFieldsTests(unittest.TestCase):
+    """Tests for _resolve_outtmpl_fields (delegates to yt-dlp's template engine)."""
+
+    def test_simple_playlist_substitution(self):
+        info = {"playlist_title": "My PL", "playlist_index": "03"}
+        result = _resolve_outtmpl_fields("%(playlist_title)s/%(title)s.%(ext)s", info, ("playlist",))
+        self.assertEqual(result, "My PL/%(title)s.%(ext)s")
+
+    def test_format_spec_int(self):
+        info = {"playlist_index": "3"}
+        result = _resolve_outtmpl_fields("%(playlist_index)02d-%(title)s", info, ("playlist",))
+        self.assertEqual(result, "03-%(title)s")
+
+    def test_non_targeted_fields_unchanged(self):
+        info = {"playlist_title": "PL"}
+        result = _resolve_outtmpl_fields("%(title)s/%(ext)s", info, ("playlist",))
+        self.assertEqual(result, "%(title)s/%(ext)s")
+
+    def test_default_value(self):
+        info = {"playlist_index": "1"}
+        result = _resolve_outtmpl_fields("%(playlist_title|Unknown)s/%(playlist_index)s", info, ("playlist",))
+        self.assertEqual(result, "Unknown/1")
+
+    def test_channel_prefix(self):
+        info = {"channel": "MyChan", "channel_index": "05"}
+        result = _resolve_outtmpl_fields("%(channel)s/%(channel_index)02d-%(title)s", info, ("channel",))
+        self.assertEqual(result, "MyChan/05-%(title)s")
+
+    def test_math_operation(self):
+        info = {"playlist_index": "3"}
+        result = _resolve_outtmpl_fields("%(playlist_index+100)d", info, ("playlist",))
+        self.assertEqual(result, "103")
+
+    def test_playlist_count_and_autonumber(self):
+        info = {
+            "playlist_title": "My PL",
+            "playlist_index": "03",
+            "playlist_count": 10,
+            "playlist_autonumber": 3,
+            "n_entries": 10,
+            "__last_playlist_index": 10,
+        }
+        result = _resolve_outtmpl_fields(
+            "%(playlist_title)s/%(playlist_autonumber)s of %(playlist_count)s - %(title)s.%(ext)s",
+            info,
+            ("playlist",),
+        )
+        # playlist_autonumber is auto-padded by yt-dlp using __last_playlist_index
+        self.assertEqual(result, "My PL/03 of 10 - %(title)s.%(ext)s")
+
+    def test_conditional_playlist_index(self):
+        info = {
+            "playlist_index": "5",
+            "playlist_count": 10,
+        }
+        result = _resolve_outtmpl_fields(
+            "%(playlist_index&{} - |)s%(title)s.%(ext)s",
+            info,
+            ("playlist",),
+        )
+        self.assertEqual(result, "5 - %(title)s.%(ext)s")
+
+
+class SanitizeEntryForPickleTests(unittest.TestCase):
+    def test_nested(self):
+        def g():
+            yield 1
+
+        obj = {"a": g(), "b": [g()]}
+        out = _sanitize_entry_for_pickle(obj)
+        self.assertEqual(out, {"a": [1], "b": [[1]]})
+        pickle.dumps(out)
+
+    def test_plain(self):
+        self.assertEqual(_sanitize_entry_for_pickle(5), 5)
+
+    def test_set_converted_to_list(self):
+        obj = {"s": {1, 2}}
+        out = _sanitize_entry_for_pickle(obj)
+        self.assertEqual(sorted(out["s"]), [1, 2])
+        pickle.dumps(out)
+
+    def test_map_iterator(self):
+        out = _sanitize_entry_for_pickle({"m": map(int, ["1", "2"])})
+        self.assertEqual(out, {"m": [1, 2]})
+
+    def test_lock_replaced_with_none(self):
+        lock = threading.Lock()
+        out = _sanitize_entry_for_pickle({"k": lock})
+        self.assertIsNone(out["k"])
+        pickle.dumps(out)
+
+    def test_ordered_dict(self):
+        from collections import OrderedDict
+
+        od = OrderedDict([("z", 1), ("a", 2)])
+        out = _sanitize_entry_for_pickle(od)
+        self.assertEqual(out, {"z": 1, "a": 2})
+
+
+class ConvertSrtToTxtTests(unittest.TestCase):
+    def test_basic_conversion(self):
+        srt = """1
+00:00:01,000 --> 00:00:02,000
+Hello <b>world</b>
+
+2
+00:00:03,000 --> 00:00:04,000
+Second line
+"""
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "sub.srt"
+            path.write_text(srt, encoding="utf-8")
+            txt_path = _convert_srt_to_txt_file(str(path))
+            self.assertIsNotNone(txt_path)
+            self.assertTrue(txt_path.endswith(".txt"))
+            content = Path(txt_path).read_text(encoding="utf-8")
+            self.assertIn("Hello world", content)
+            self.assertIn("Second line", content)
+
+
+class DownloadInfoSetstateTests(unittest.TestCase):
+    def _base_state(self, **kwargs):
+        base = {
+            "id": "id1",
+            "title": "t",
+            "url": "http://example.com/v",
+            "folder": "",
+            "custom_name_prefix": "",
+            "error": None,
+            "entry": None,
+            "playlist_item_limit": 0,
+            "split_by_chapters": False,
+            "chapter_template": "",
+            "msg": None,
+            "percent": None,
+            "speed": None,
+            "eta": None,
+            "status": "pending",
+            "size": None,
+            "timestamp": 0,
+        }
+        base.update(kwargs)
+        return base
+
+    def test_migrates_old_audio_format(self):
+        state = self._base_state(format="m4a", quality="best")
+        di = DownloadInfo.__new__(DownloadInfo)
+        di.__setstate__(state)
+        self.assertEqual(di.download_type, "audio")
+        self.assertEqual(di.codec, "auto")
+
+    def test_migrates_thumbnail(self):
+        state = self._base_state(format="thumbnail", quality="best")
+        di = DownloadInfo.__new__(DownloadInfo)
+        di.__setstate__(state)
+        self.assertEqual(di.download_type, "thumbnail")
+        self.assertEqual(di.format, "jpg")
+
+    def test_migrates_captions(self):
+        state = self._base_state(format="captions", subtitle_format="vtt", quality="best")
+        di = DownloadInfo.__new__(DownloadInfo)
+        di.__setstate__(state)
+        self.assertEqual(di.download_type, "captions")
+        self.assertEqual(di.format, "vtt")
+
+    def test_migrates_best_ios(self):
+        state = self._base_state(
+            format="any", quality="best_ios", video_codec="auto"
+        )
+        di = DownloadInfo.__new__(DownloadInfo)
+        di.__setstate__(state)
+        self.assertEqual(di.format, "ios")
+        self.assertEqual(di.quality, "best")
+
+    def test_migrates_quality_audio(self):
+        state = self._base_state(format="mp4", quality="audio", video_codec="h264")
+        di = DownloadInfo.__new__(DownloadInfo)
+        di.__setstate__(state)
+        self.assertEqual(di.download_type, "audio")
+        self.assertEqual(di.format, "m4a")
+
+    def test_new_state_has_subtitle_files(self):
+        state = self._base_state(
+            download_type="video",
+            codec="auto",
+            format="any",
+            quality="best",
+        )
+        di = DownloadInfo.__new__(DownloadInfo)
+        di.__setstate__(state)
+        self.assertEqual(di.subtitle_files, [])
+
+    def test_missing_optional_fields_are_defaulted(self):
+        state = self._base_state(
+            download_type="video",
+            codec="auto",
+            format="any",
+            quality="best",
+        )
+        state.pop("folder")
+        state.pop("custom_name_prefix")
+        state.pop("playlist_item_limit")
+        state.pop("split_by_chapters")
+        state.pop("chapter_template")
+        di = DownloadInfo.__new__(DownloadInfo)
+        di.__setstate__(state)
+        self.assertEqual(di.folder, "")
+        self.assertEqual(di.custom_name_prefix, "")
+        self.assertEqual(di.playlist_item_limit, 0)
+        self.assertFalse(di.split_by_chapters)
+        self.assertEqual(di.chapter_template, "")
+
+
+class CompactPersistedEntryTests(unittest.TestCase):
+    def test_keeps_only_playlist_and_channel_keys(self):
+        entry = {
+            "playlist_index": "01",
+            "playlist_title": "Playlist",
+            "playlist_count": 10,
+            "playlist_autonumber": 1,
+            "channel_index": "02",
+            "channel_title": "Channel",
+            "n_entries": 10,
+            "__last_playlist_index": 10,
+            "formats": [{"id": "huge"}],
+            "description": "big blob",
+        }
+
+        compact = _compact_persisted_entry(entry)
+
+        self.assertEqual(
+            compact,
+            {
+                "playlist_index": "01",
+                "playlist_title": "Playlist",
+                "playlist_count": 10,
+                "playlist_autonumber": 1,
+                "channel_index": "02",
+                "channel_title": "Channel",
+                "n_entries": 10,
+                "__last_playlist_index": 10,
+            },
+        )
+
+    def test_returns_none_when_no_restart_relevant_keys_exist(self):
+        self.assertIsNone(_compact_persisted_entry({"id": "x", "title": "y"}))
+
+
+if __name__ == "__main__":
+    unittest.main()

docker-entrypoint.sh

@@ -1,19 +1,28 @@
 #!/bin/sh
 
+PUID="${UID:-$PUID}"
+PGID="${GID:-$PGID}"
+
 echo "Setting umask to ${UMASK}"
 umask ${UMASK}
 echo "Creating download directory (${DOWNLOAD_DIR}), state directory (${STATE_DIR}), and temp dir (${TEMP_DIR})"
 mkdir -p "${DOWNLOAD_DIR}" "${STATE_DIR}" "${TEMP_DIR}"
 
 if [ `id -u` -eq 0 ] && [ `id -g` -eq 0 ]; then
-    if [ "${UID}" -eq 0 ]; then
-        echo "Warning: it is not recommended to run as root user, please check your setting of the UID environment variable"
+    if [ "${PUID}" -eq 0 ]; then
+        echo "Warning: it is not recommended to run as root user, please check your setting of the PUID/PGID (or legacy UID/GID) environment variables"
     fi
-    echo "Changing ownership of download and state directories to ${UID}:${GID}"
-    chown -R "${UID}":"${GID}" /app "${DOWNLOAD_DIR}" "${STATE_DIR}" "${TEMP_DIR}"
-    echo "Running MeTube as user ${UID}:${GID}"
-    exec su-exec "${UID}":"${GID}" python3 app/main.py
+    if [ "${CHOWN_DIRS:-true}" != "false" ]; then
+        echo "Changing ownership of download and state directories to ${PUID}:${PGID}"
+        chown -R "${PUID}":"${PGID}" /app "${DOWNLOAD_DIR}" "${STATE_DIR}" "${TEMP_DIR}"
+    fi
+    echo "Starting BgUtils POT Provider"
+    gosu "${PUID}":"${PGID}" bgutil-pot server >/tmp/bgutil-pot.log 2>&1 &
+    echo "Running MeTube as user ${PUID}:${PGID}"
+    exec gosu "${PUID}":"${PGID}" python3 app/main.py
 else
     echo "User set by docker; running MeTube as `id -u`:`id -g`"
+    echo "Starting BgUtils POT Provider"
+    bgutil-pot server >/tmp/bgutil-pot.log 2>&1 &
     exec python3 app/main.py
 fi

pyproject.toml

@@ -6,7 +6,7 @@ requires-python = ">=3.13"
 dependencies = [
     "aiohttp",
     "python-socketio>=5.0,<6.0",
-    "yt-dlp[default,curl-cffi]",
+    "yt-dlp[default,curl-cffi,deno]",
     "mutagen",
     "curl-cffi",
     "watchfiles",
@@ -15,4 +15,13 @@ dependencies = [
 [dependency-groups]
 dev = [
     "pylint",
+    "pytest>=8.0",
+    "pytest-aiohttp>=1.0",
+    "pytest-asyncio>=0.24",
 ]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["app/tests"]
+pythonpath = [".", "app"]
+addopts = "-v"

ui/angular.json

@@ -15,17 +15,13 @@
       "prefix": "app",
       "architect": {
         "build": {
-          "builder": "@angular-devkit/build-angular:application",
+          "builder": "@angular/build:application",
           "options": {
             "outputPath": {
               "base": "dist/metube"
             },
             "index": "src/index.html",
-            "polyfills": [
-              "src/polyfills.ts"
-            ],
             "tsConfig": "tsconfig.app.json",
-            "aot": true,
             "assets": [
               "src/favicon.ico",
               "src/assets",
@@ -37,21 +33,16 @@
               "node_modules/@ng-select/ng-select/themes/default.theme.css",
               "src/styles.sass"
             ],
-            "scripts": [
-              "node_modules/bootstrap/dist/js/bootstrap.bundle.min.js"
-            ],
+            "scripts": [],
             "serviceWorker": "ngsw-config.json",
-            "browser": "src/main.ts"
+            "browser": "src/main.ts",
+            "polyfills": [
+              "zone.js",
+              "@angular/localize/init"
+            ]
           },
           "configurations": {
             "production": {
-              "fileReplacements": [
-                {
-                  "replace": "src/environments/environment.ts",
-                  "with": "src/environments/environment.prod.ts"
-                }
-              ],
-              "optimization": true,
               "outputHashing": "all",
               "sourceMap": false,
               "namedChunks": false,
@@ -68,75 +59,46 @@
                   "maximumError": "10kb"
                 }
               ]
+            },
+            "development": {
+              "optimization": false,
+              "extractLicenses": false,
+              "sourceMap": true
             }
-          }
+          },
+          "defaultConfiguration": "production"
         },
         "serve": {
-          "builder": "@angular-devkit/build-angular:dev-server",
-          "options": {
-            "buildTarget": "metube:build"
-          },
+          "builder": "@angular/build:dev-server",
           "configurations": {
             "production": {
               "buildTarget": "metube:build:production"
+            },
+             "development": {
+              "buildTarget": "metube:build:development",
+              "proxyConfig": "proxy.conf.json"
             }
-          }
-        },
-        "extract-i18n": {
-          "builder": "@angular-devkit/build-angular:extract-i18n",
-          "options": {
-            "buildTarget": "metube:build"
-          }
+          },
+           "defaultConfiguration": "development"
         },
         "test": {
-          "builder": "@angular-devkit/build-angular:karma",
-          "options": {
-            "main": "src/test.ts",
-            "polyfills": "src/polyfills.ts",
-            "tsConfig": "tsconfig.spec.json",
-            "karmaConfig": "karma.conf.js",
-            "assets": [
-              "src/favicon.ico",
-              "src/assets",
-              "src/manifest.webmanifest",
-              "src/custom-service-worker.js"
-            ],
-            "styles": [
-              "src/styles.sass"
-            ],
-            "scripts": []
-          }
+          "builder": "@angular/build:unit-test"
         },
-        "lint": {
-          "builder": "@angular-devkit/build-angular:tslint",
+       "lint": {
+          "builder": "@angular-eslint/builder:lint",
           "options": {
-            "tsConfig": [
-              "tsconfig.app.json",
-              "tsconfig.spec.json",
-              "e2e/tsconfig.json"
-            ],
-            "exclude": [
-              "**/node_modules/**"
+            "lintFilePatterns": [
+              "src/**/*.ts",
+              "src/**/*.html"
             ]
           }
-        },
-        "e2e": {
-          "builder": "@angular-devkit/build-angular:protractor",
-          "options": {
-            "protractorConfig": "e2e/protractor.conf.js",
-            "devServerTarget": "metube:serve"
-          },
-          "configurations": {
-            "production": {
-              "devServerTarget": "metube:serve:production"
-            }
-          }
         }
       }
     }
   },
   "cli": {
-    "analytics": false
+    "analytics": false,
+    "packageManager": "pnpm"
   },
   "schematics": {
     "@schematics/angular:component": {

ui/e2e/protractor.conf.js

@@ -1,36 +0,0 @@
-// @ts-check
-// Protractor configuration file, see link for more information
-// https://github.com/angular/protractor/blob/master/lib/config.ts
-
-const { SpecReporter, StacktraceOption } = require('jasmine-spec-reporter');
-
-/**
- * @type { import("protractor").Config }
- */
-exports.config = {
-  allScriptsTimeout: 11000,
-  specs: [
-    './src/**/*.e2e-spec.ts'
-  ],
-  capabilities: {
-    browserName: 'chrome'
-  },
-  directConnect: true,
-  baseUrl: 'http://localhost:4200/',
-  framework: 'jasmine',
-  jasmineNodeOpts: {
-    showColors: true,
-    defaultTimeoutInterval: 30000,
-    print: function() {}
-  },
-  onPrepare() {
-    require('ts-node').register({
-      project: require('path').join(__dirname, './tsconfig.json')
-    });
-    jasmine.getEnv().addReporter(new SpecReporter({
-      spec: {
-        displayStacktrace: StacktraceOption.PRETTY
-      }
-    }));
-  }
-};

ui/e2e/src/app.e2e-spec.ts

@@ -1,23 +0,0 @@
-import { AppPage } from './app.po';
-import { browser, logging } from 'protractor';
-
-describe('workspace-project App', () => {
-  let page: AppPage;
-
-  beforeEach(() => {
-    page = new AppPage();
-  });
-
-  it('should display welcome message', () => {
-    page.navigateTo();
-    expect(page.getTitleText()).toEqual('metube app is running!');
-  });
-
-  afterEach(async () => {
-    // Assert that there are no errors emitted from the browser
-    const logs = await browser.manage().logs().get(logging.Type.BROWSER);
-    expect(logs).not.toContain(jasmine.objectContaining({
-      level: logging.Level.SEVERE,
-    } as logging.Entry));
-  });
-});

ui/e2e/src/app.po.ts

@@ -1,11 +0,0 @@
-import { browser, by, element } from 'protractor';
-
-export class AppPage {
-  navigateTo(): Promise<unknown> {
-    return browser.get(browser.baseUrl) as Promise<unknown>;
-  }
-
-  getTitleText(): Promise<string> {
-    return element(by.css('app-root .content span')).getText() as Promise<string>;
-  }
-}

ui/e2e/tsconfig.json

@@ -1,14 +0,0 @@
-/* To learn more about this file see: https://angular.io/config/tsconfig. */
-{
-  "extends": "../tsconfig.json",
-  "compilerOptions": {
-    "outDir": "../out-tsc/e2e",
-    "module": "commonjs",
-    "target": "es2018",
-    "types": [
-      "jasmine",
-      "jasminewd2",
-      "node"
-    ]
-  }
-}

ui/eslint.config.js

@@ -0,0 +1,44 @@
+// @ts-check
+const eslint = require("@eslint/js");
+const { defineConfig } = require("eslint/config");
+const tseslint = require("typescript-eslint");
+const angular = require("angular-eslint");
+
+module.exports = defineConfig([
+  {
+    files: ["**/*.ts"],
+    extends: [
+      eslint.configs.recommended,
+      tseslint.configs.recommended,
+      tseslint.configs.stylistic,
+      angular.configs.tsRecommended,
+    ],
+    processor: angular.processInlineTemplates,
+    rules: {
+      "@angular-eslint/directive-selector": [
+        "error",
+        {
+          type: "attribute",
+          prefix: "app",
+          style: "camelCase",
+        },
+      ],
+      "@angular-eslint/component-selector": [
+        "error",
+        {
+          type: "element",
+          prefix: "app",
+          style: "kebab-case",
+        },
+      ],
+    },
+  },
+  {
+    files: ["**/*.html"],
+    extends: [
+      angular.configs.templateRecommended,
+      angular.configs.templateAccessibility,
+    ],
+    rules: {},
+  }
+]);

ui/karma.conf.js

@@ -1,32 +0,0 @@
-// Karma configuration file, see link for more information
-// https://karma-runner.github.io/1.0/config/configuration-file.html
-
-module.exports = function (config) {
-  config.set({
-    basePath: '',
-    frameworks: ['jasmine', '@angular-devkit/build-angular'],
-    plugins: [
-      require('karma-jasmine'),
-      require('karma-chrome-launcher'),
-      require('karma-jasmine-html-reporter'),
-      require('karma-coverage-istanbul-reporter'),
-      require('@angular-devkit/build-angular/plugins/karma')
-    ],
-    client: {
-      clearContext: false // leave Jasmine Spec Runner output visible in browser
-    },
-    coverageIstanbulReporter: {
-      dir: require('path').join(__dirname, './coverage/metube'),
-      reports: ['html', 'lcovonly', 'text-summary'],
-      fixWebpackSourcePaths: true
-    },
-    reporters: ['progress', 'kjhtml'],
-    port: 9876,
-    colors: true,
-    logLevel: config.LOG_INFO,
-    autoWatch: true,
-    browsers: ['Chrome'],
-    singleRun: false,
-    restartOnFileChange: true
-  });
-};

ui/package.json

@@ -5,44 +5,59 @@
     "ng": "ng",
     "start": "ng serve",
     "build": "ng build",
+    "build:watch": "ng build --watch",
     "test": "ng test",
-    "lint": "ng lint",
-    "e2e": "ng e2e"
+    "lint": "ng lint"
+  },
+  "prettier": {
+    "printWidth": 100,
+    "singleQuote": true,
+    "overrides": [
+      {
+        "files": "*.html",
+        "options": {
+          "parser": "angular"
+        }
+      }
+    ]
   },
   "private": true,
   "dependencies": {
-    "@angular/animations": "^20.3.15",
-    "@angular/common": "^20.3.15",
-    "@angular/compiler": "^20.3.15",
-    "@angular/core": "^20.3.15",
-    "@angular/forms": "^20.3.15",
-    "@angular/localize": "^20.3.15",
-    "@angular/platform-browser": "^20.3.15",
-    "@angular/platform-browser-dynamic": "^20.3.15",
-    "@angular/router": "^20.3.15",
-    "@angular/service-worker": "^20.3.15",
-    "@fortawesome/angular-fontawesome": "~3.0.0",
-    "@fortawesome/fontawesome-svg-core": "^7.1.0",
-    "@fortawesome/free-brands-svg-icons": "^7.1.0",
-    "@fortawesome/free-regular-svg-icons": "^7.1.0",
-    "@fortawesome/free-solid-svg-icons": "^7.1.0",
-    "@ng-bootstrap/ng-bootstrap": "^19.0.0",
-    "@ng-select/ng-select": "^20.0.0",
-    "bootstrap": "^5.3.6",
-    "ngx-cookie-service": "^20.0.0",
-    "ngx-socket-io": "~4.9.0",
-    "rxjs": "~7.8.0",
+    "@angular/animations": "^21.2.9",
+    "@angular/common": "^21.2.9",
+    "@angular/compiler": "^21.2.9",
+    "@angular/core": "^21.2.9",
+    "@angular/forms": "^21.2.9",
+    "@angular/platform-browser": "^21.2.9",
+    "@angular/platform-browser-dynamic": "^21.2.9",
+    "@angular/service-worker": "^21.2.9",
+    "@fortawesome/angular-fontawesome": "~4.0.0",
+    "@fortawesome/fontawesome-svg-core": "^7.2.0",
+    "@fortawesome/free-brands-svg-icons": "^7.2.0",
+    "@fortawesome/free-regular-svg-icons": "^7.2.0",
+    "@fortawesome/free-solid-svg-icons": "^7.2.0",
+    "@ng-bootstrap/ng-bootstrap": "^20.0.0",
+    "@ng-select/ng-select": "^21.8.0",
+    "@popperjs/core": "^2.11.8",
+    "bootstrap": "^5.3.8",
+    "ngx-cookie-service": "^21.3.1",
+    "ngx-socket-io": "~4.10.0",
+    "rxjs": "~7.8.2",
     "tslib": "^2.8.1",
-    "zone.js": "~0.15.1"
+    "zone.js": "0.15.0"
   },
   "devDependencies": {
-    "@angular-devkit/build-angular": "^20.3.13",
-    "@angular/cli": "^20.3.13",
-    "@angular/compiler-cli": "^20.3.15",
-    "@types/node": "^22.15.29",
-    "codelyzer": "^6.0.2",
-    "ts-node": "~10.9.1",
-    "tslint": "~6.1.3",
-    "typescript": "~5.8.3"
+    "@angular-eslint/builder": "21.1.0",
+    "@angular/build": "^21.2.7",
+    "@angular/cli": "^21.2.7",
+    "@angular/compiler-cli": "^21.2.9",
+    "@angular/localize": "^21.2.9",
+    "@eslint/js": "^9.39.4",
+    "angular-eslint": "21.1.0",
+    "eslint": "^9.39.4",
+    "jsdom": "^27.4.0",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "8.47.0",
+    "vitest": "^4.1.4"
   }
 }

ui/pnpm-workspace.yaml

@@ -0,0 +1,6 @@
+allowBuilds:
+  '@parcel/watcher': true
+  core-js: true
+  esbuild: true
+  lmdb: true
+  msgpackr-extract: true

ui/src/app/app.component.html

@@ -1,402 +0,0 @@
-<nav class="navbar navbar-expand-md navbar-dark">
-  <div class="container-fluid">
-    <a class="navbar-brand d-flex align-items-center" href="#">
-      <img src="assets/icons/android-chrome-192x192.png" alt="MeTube Logo" height="32" class="me-2">
-      MeTube
-    </a>
-    <div class="download-metrics">
-      <div class="metric" *ngIf="activeDownloads > 0">
-        <fa-icon [icon]="faDownload" class="text-primary"></fa-icon>
-        <span>{{activeDownloads}} downloading</span>
-      </div>
-      <div class="metric" *ngIf="queuedDownloads > 0">
-        <fa-icon [icon]="faClock" class="text-warning"></fa-icon>
-        <span>{{queuedDownloads}} queued</span>
-      </div>
-      <div class="metric" *ngIf="completedDownloads > 0">
-        <fa-icon [icon]="faCheck" class="text-success"></fa-icon>
-        <span>{{completedDownloads}} completed</span>
-      </div>
-      <div class="metric" *ngIf="failedDownloads > 0">
-        <fa-icon [icon]="faTimesCircle" class="text-danger"></fa-icon>
-        <span>{{failedDownloads}} failed</span>
-      </div>
-      <div class="metric" *ngIf="(totalSpeed | speed) !== ''">
-        <fa-icon [icon]="faTachometerAlt" class="text-info"></fa-icon>
-        <span>{{totalSpeed | speed }}</span>
-      </div>
-    </div>
-    <!--
-    <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarsDefault" aria-controls="navbarsDefault" aria-expanded="false" aria-label="Toggle navigation">
-      <span class="navbar-toggler-icon"></span>
-    </button>
-    <div class="collapse navbar-collapse" id="navbarsDefault">
-      <ul class="navbar-nav mr-auto">
-        <li class="nav-item active">
-          <a class="nav-link" href="#">Home <span class="sr-only">(current)</span></a>
-        </li>
-      </ul>
-    </div>
-    -->
-    <div class="navbar-nav ms-auto">
-      <div class="nav-item dropdown">
-        <button class="btn btn-link nav-link py-2 px-0 px-sm-2 dropdown-toggle d-flex align-items-center"
-                id="theme-select"
-                type="button"
-                aria-expanded="false"
-                data-bs-toggle="dropdown"
-                data-bs-display="static">
-          <fa-icon [icon]="activeTheme.icon"></fa-icon>
-        </button>
-        <ul class="dropdown-menu dropdown-menu-end position-absolute" aria-labelledby="theme-select">
-          <li *ngFor="let theme of themes">
-            <button type="button" class="dropdown-item d-flex align-items-center" [ngClass]="{'active' : activeTheme == theme}" (click)="themeChanged(theme)">
-              <span class="me-2 opacity-50">
-                <fa-icon [icon]="theme.icon"></fa-icon>
-              </span>
-              {{ theme.displayName }}
-              <span class="ms-auto" [ngClass]="{'d-none' : activeTheme != theme}">
-                <fa-icon [icon]="faCheck"></fa-icon>
-              </span>
-            </button>
-          </li>
-        </ul>
-      </div>
-    </div>
-  </div>
-</nav>
-
-<main role="main" class="container container-xl">
-  <form #f="ngForm">
-    <div class="container add-url-box">
-      <!-- Main URL Input with Download Button -->
-      <div class="row mb-4">
-        <div class="col">
-          <div class="input-group input-group-lg shadow-sm">
-            <input type="text" 
-                   autocomplete="off" 
-                   spellcheck="false" 
-                   class="form-control form-control-lg" 
-                   placeholder="Enter video or playlist URL" 
-                   name="addUrl" 
-                   [(ngModel)]="addUrl" 
-                   [disabled]="addInProgress || downloads.loading">
-            <button class="btn btn-primary btn-lg px-4" 
-                    type="submit" 
-                    (click)="addDownload()" 
-                    [disabled]="addInProgress || downloads.loading">
-              <span class="spinner-border spinner-border-sm" role="status" id="add-spinner" *ngIf="addInProgress"></span>
-              {{ addInProgress ? "Adding..." : "Download" }}
-            </button>
-          </div>
-        </div>
-      </div>
-
-      <!-- Options Row -->
-      <div class="row mb-3 g-3">
-        <div class="col-md-4">
-          <div class="input-group">
-            <span class="input-group-text">Quality</span>
-            <select class="form-select" 
-                    name="quality" 
-                    [(ngModel)]="quality" 
-                    (change)="qualityChanged()" 
-                    [disabled]="addInProgress || downloads.loading">
-              <option *ngFor="let q of qualities" [ngValue]="q.id">{{ q.text }}</option>
-            </select>
-          </div>
-        </div>
-        <div class="col-md-4">
-          <div class="input-group">
-            <span class="input-group-text">Format</span>
-            <select class="form-select" 
-                    name="format" 
-                    [(ngModel)]="format" 
-                    (change)="formatChanged()" 
-                    [disabled]="addInProgress || downloads.loading">
-              <option *ngFor="let f of formats" [ngValue]="f.id">{{ f.text }}</option>
-            </select>
-          </div>
-        </div>
-        <div class="col-md-4">
-          <button type="button" 
-                  class="btn btn-outline-secondary w-100 h-100" 
-                  (click)="toggleAdvanced()">
-            Advanced Options
-          </button>
-        </div>
-      </div>
-
-      <!-- Advanced Options Panel -->
-      <div class="row">
-        <div class="col-12">
-          <div class="collapse show" id="advancedOptions" [ngbCollapse]="!isAdvancedOpen">
-            <div class="card card-body">
-              <!-- Advanced Settings -->
-              <div class="row g-3 mb-2">
-                <div class="col-md-6">
-                  <div class="input-group">
-                    <span class="input-group-text">Auto Start</span>
-                    <select class="form-select" 
-                            name="autoStart" 
-                            [(ngModel)]="autoStart" 
-                            (change)="autoStartChanged()" 
-                            [disabled]="addInProgress || downloads.loading"
-                            ngbTooltip="Automatically start downloads when added">
-                      <option [ngValue]="true">Yes</option>
-                      <option [ngValue]="false">No</option>
-                    </select>
-                  </div>
-                </div>
-                <div class="col-md-6">
-                  <div class="input-group">
-                    <span class="input-group-text">Download Folder</span>
-                    <ng-select [items]="customDirs$ | async" 
-                              placeholder="Default" 
-                              [addTag]="allowCustomDir.bind(this)" 
-                              addTagText="Create directory" 
-                              bindLabel="folder" 
-                              [(ngModel)]="folder" 
-                              [disabled]="addInProgress || downloads.loading"
-                              [virtualScroll]="true"
-                              [clearable]="true"
-                              [loading]="downloads.loading"
-                              [searchable]="true"
-                              [closeOnSelect]="true"
-                              ngbTooltip="Choose where to save downloads. Type to create a new folder.">
-                    </ng-select>
-                  </div>
-                </div>
-                <div class="col-md-6">
-                  <div class="input-group">
-                    <span class="input-group-text">Custom Name Prefix</span>
-                    <input type="text" 
-                           class="form-control" 
-                           placeholder="Default" 
-                           name="customNamePrefix" 
-                           [(ngModel)]="customNamePrefix" 
-                           [disabled]="addInProgress || downloads.loading"
-                           ngbTooltip="Add a prefix to downloaded filenames">
-                  </div>
-                </div>
-                <div class="col-md-6">
-                  <div class="input-group">
-                    <span class="input-group-text">Items Limit</span>
-                    <input type="number" 
-                           min="0" 
-                           class="form-control" 
-                           placeholder="Default" 
-                           name="playlistItemLimit" 
-                           (keydown)="isNumber($event)" 
-                           [(ngModel)]="playlistItemLimit" 
-                           [disabled]="addInProgress || downloads.loading"
-                           ngbTooltip="Maximum number of items to download from a playlist (0 = no limit)">
-                  </div>
-                </div>
-                <div class="col-12">
-                  <div class="form-check form-switch">
-                    <input class="form-check-input" 
-                           type="checkbox" 
-                           role="switch" 
-                           name="playlistStrictMode" 
-                           [(ngModel)]="playlistStrictMode" 
-                           [disabled]="addInProgress || downloads.loading"
-                           ngbTooltip="Only download playlists when URL explicitly points to a playlist">
-                    <label class="form-check-label">Strict Playlist Mode</label>
-                  </div>
-                </div>
-              </div>
-
-              <!-- Advanced Actions -->
-              <div class="row">
-                <div class="col-12">
-                  <hr class="my-3">
-                  <div class="row g-2">
-                    <div class="col-md-4">
-                      <button type="button" 
-                              class="btn btn-secondary w-100" 
-                              (click)="openBatchImportModal()">
-                        <fa-icon [icon]="faFileImport" class="me-2"></fa-icon>
-                        Import URLs
-                      </button>
-                    </div>
-                    <div class="col-md-4">
-                      <button type="button" 
-                              class="btn btn-secondary w-100" 
-                              (click)="exportBatchUrls('all')">
-                        <fa-icon [icon]="faFileExport" class="me-2"></fa-icon>
-                        Export URLs
-                      </button>
-                    </div>
-                    <div class="col-md-4">
-                      <button type="button" 
-                              class="btn btn-secondary w-100" 
-                              (click)="copyBatchUrls('all')">
-                        <fa-icon [icon]="faCopy" class="me-2"></fa-icon>
-                        Copy URLs
-                      </button>
-                    </div>
-                  </div>
-                </div>
-              </div>
-            </div>
-          </div>
-        </div>
-      </div>
-    </div>
-  </form>
-  
-  <!-- Batch Import Modal -->
-  <div class="modal fade" tabindex="-1" role="dialog" [ngClass]="{'show': batchImportModalOpen}" [ngStyle]="{'display': batchImportModalOpen ? 'block' : 'none'}">
-    <div class="modal-dialog" role="document">
-      <div class="modal-content">
-        <div class="modal-header">
-          <h5 class="modal-title">Batch Import URLs</h5>
-          <button type="button" class="btn-close" aria-label="Close" (click)="closeBatchImportModal()"></button>
-        </div>
-        <div class="modal-body">
-          <textarea [(ngModel)]="batchImportText" class="form-control" rows="6"
-            placeholder="Paste one video URL per line"></textarea>
-          <div class="mt-2">
-            <small *ngIf="batchImportStatus">{{ batchImportStatus }}</small>
-          </div>
-        </div>
-        <div class="modal-footer">
-          <button type="button" class="btn btn-danger me-auto" *ngIf="importInProgress" (click)="cancelBatchImport()">
-            Cancel Import
-          </button>
-          <button type="button" class="btn btn-secondary" (click)="closeBatchImportModal()">Close</button>
-          <button type="button" class="btn btn-primary" (click)="startBatchImport()" [disabled]="importInProgress">
-            Import URLs
-          </button>
-        </div>
-      </div>
-    </div>
-  </div>
-  
-
-  <div *ngIf="downloads.loading" class="alert alert-info" role="alert">
-    Connecting to server...
-  </div>
-  <div class="metube-section-header">Downloading</div>
-  <div class="px-2 py-3 border-bottom">
-    <button type="button" class="btn btn-link text-decoration-none px-0 me-4" disabled #queueDelSelected (click)="delSelectedDownloads('queue')"><fa-icon [icon]="faTrashAlt"></fa-icon>&nbsp; Cancel selected</button>
-    <button type="button" class="btn btn-link text-decoration-none px-0 me-4" disabled #queueDownloadSelected (click)="startSelectedDownloads('queue')"><fa-icon [icon]="faDownload"></fa-icon>&nbsp; Download selected</button>
-  </div>
-  <div class="overflow-auto">
-    <table class="table">
-      <thead>
-        <tr>
-          <th scope="col" style="width: 1rem;">
-            <app-master-checkbox #queueMasterCheckbox [id]="'queue'" [list]="downloads.queue" (changed)="queueSelectionChanged($event)"></app-master-checkbox>
-          </th>
-          <th scope="col">Video</th>
-          <th scope="col" style="width: 8rem;">Speed</th>
-          <th scope="col" style="width: 7rem;">ETA</th>
-          <th scope="col" style="width: 6rem;"></th>
-        </tr>
-      </thead>
-      <tbody>
-        <tr *ngFor="let download of downloads.queue | keyvalue: asIsOrder; trackBy: identifyDownloadRow" [class.disabled]='download.value.deleting'>
-          <td>
-            <app-slave-checkbox [id]="download.key" [master]="queueMasterCheckbox" [checkable]="download.value"></app-slave-checkbox>
-          </td>
-          <td title="{{ download.value.filename }}">
-            <div class="d-flex flex-column flex-sm-row align-items-center row-gap-2 column-gap-3">
-              <div>{{ download.value.title }}</div>
-              <ngb-progressbar height="1.5rem" [showValue]="download.value.status != 'preparing'" [striped]="download.value.status == 'preparing'" [animated]="download.value.status == 'preparing'" type="success" [value]="download.value.status == 'preparing' ? 100 : download.value.percent | number:'1.0-0'" class="download-progressbar"></ngb-progressbar>
-            </div>
-          </td>
-          <td>{{ download.value.speed | speed }}</td>
-          <td>{{ download.value.eta | eta }}</td>
-          <td>
-            <div class="d-flex">
-              <button *ngIf="download.value.status === 'pending'" type="button" class="btn btn-link" (click)="downloadItemByKey(download.key)"><fa-icon [icon]="faDownload"></fa-icon></button>
-              <button type="button" class="btn btn-link" (click)="delDownload('queue', download.key)"><fa-icon [icon]="faTrashAlt"></fa-icon></button>
-              <a href="{{download.value.url}}" target="_blank" class="btn btn-link"><fa-icon [icon]="faExternalLinkAlt"></fa-icon></a>
-            </div>
-          </td>
-        </tr>
-      </tbody>
-    </table>
-  </div>
-
-  <div class="metube-section-header">Completed</div>
-  <div class="px-2 py-3 border-bottom">
-    <button type="button" class="btn btn-link text-decoration-none px-0 me-4" disabled #doneDelSelected (click)="delSelectedDownloads('done')"><fa-icon [icon]="faTrashAlt"></fa-icon>&nbsp; Clear selected</button>
-    <button type="button" class="btn btn-link text-decoration-none px-0 me-4" disabled #doneClearCompleted (click)="clearCompletedDownloads()"><fa-icon [icon]="faCheckCircle"></fa-icon>&nbsp; Clear completed</button>
-    <button type="button" class="btn btn-link text-decoration-none px-0 me-4" disabled #doneClearFailed (click)="clearFailedDownloads()"><fa-icon [icon]="faTimesCircle"></fa-icon>&nbsp; Clear failed</button>
-    <button type="button" class="btn btn-link text-decoration-none px-0 me-4" disabled #doneRetryFailed (click)="retryFailedDownloads()"><fa-icon [icon]="faRedoAlt"></fa-icon>&nbsp; Retry failed</button>
-    <button type="button" class="btn btn-link text-decoration-none px-0 me-4" disabled #doneDownloadSelected (click)="downloadSelectedFiles()"><fa-icon [icon]="faDownload"></fa-icon>&nbsp; Download Selected</button>
-  </div>
-  <div class="overflow-auto">
-    <table class="table">
-      <thead>
-        <tr>
-          <th scope="col" style="width: 1rem;">
-            <app-master-checkbox #doneMasterCheckbox [id]="'done'" [list]="downloads.done" (changed)="doneSelectionChanged($event)"></app-master-checkbox>
-          </th>
-          <th scope="col">Video</th>
-          <th scope="col">File Size</th>
-          <th scope="col" style="width: 8rem;"></th>
-        </tr>
-      </thead>
-      <tbody>
-        <tr *ngFor="let download of downloads.done | keyvalue: asIsOrder; trackBy: identifyDownloadRow" [class.disabled]='download.value.deleting'>
-          <td>
-            <app-slave-checkbox [id]="download.key" [master]="doneMasterCheckbox" [checkable]="download.value"></app-slave-checkbox>
-          </td>
-          <td>
-            <div style="display: inline-block; width: 1.5rem;">
-              <fa-icon *ngIf="download.value.status == 'finished'" [icon]="faCheckCircle" class="text-success"></fa-icon>
-              <fa-icon *ngIf="download.value.status == 'error'" [icon]="faTimesCircle" class="text-danger"></fa-icon>
-            </div>
-            <span ngbTooltip="{{download.value.msg}} | {{download.value.error}}"><a *ngIf="!!download.value.filename; else noDownloadLink" href="{{buildDownloadLink(download.value)}}" target="_blank">{{ download.value.title }}</a></span>
-            <ng-template #noDownloadLink>
-              {{download.value.title}}
-              <span *ngIf="download.value.msg"><br>{{download.value.msg}}</span>
-              <span *ngIf="download.value.error"><br>Error: {{download.value.error}}</span>
-            </ng-template>
-          </td>
-          <td>
-            <span *ngIf="download.value.size">{{ download.value.size | fileSize }}</span>
-          </td>
-          <td>
-            <div class="d-flex">
-              <button *ngIf="download.value.status == 'error'" type="button" class="btn btn-link" (click)="retryDownload(download.key, download.value)"><fa-icon [icon]="faRedoAlt"></fa-icon></button>
-              <a *ngIf="download.value.filename" href="{{buildDownloadLink(download.value)}}" download class="btn btn-link"><fa-icon [icon]="faDownload"></fa-icon></a>
-              <a href="{{download.value.url}}" target="_blank" class="btn btn-link"><fa-icon [icon]="faExternalLinkAlt"></fa-icon></a>
-              <button type="button" class="btn btn-link" (click)="delDownload('done', download.key)"><fa-icon [icon]="faTrashAlt"></fa-icon></button>
-            </div>
-          </td>
-        </tr>
-      </tbody>
-    </table>
-  </div>
-</main><!-- /.container -->
-
-<footer class="footer navbar-dark bg-dark py-3 mt-5">
-  <div class="container text-center">
-    <div class="footer-content" *ngIf="ytDlpVersion && metubeVersion">
-      <div class="version-item">
-        <span class="version-label">yt-dlp</span>
-        <span class="version-value">{{ytDlpVersion}}</span>
-      </div>
-      <div class="version-separator"></div>
-      <div class="version-item">
-        <span class="version-label">MeTube</span>
-        <span class="version-value">{{metubeVersion}}</span>
-      </div>
-      <div class="version-separator"></div>
-      <div class="version-item" *ngIf="ytDlpOptionsUpdateTime">
-        <span class="version-label">yt-dlp-options</span>
-        <span class="version-value">{{ytDlpOptionsUpdateTime}}</span>
-      </div>
-      <div class="version-separator" *ngIf="ytDlpOptionsUpdateTime"></div>
-      <a href="https://github.com/alexta69/metube" target="_blank" class="github-link">
-        <fa-icon [icon]="faGithub"></fa-icon>
-        <span>GitHub</span>
-      </a>
-    </div>
-  </div>
-</footer>

ui/src/app/app.component.spec.ts

@@ -1,31 +0,0 @@
-import { TestBed } from '@angular/core/testing';
-import { AppComponent } from './app.component';
-
-describe('AppComponent', () => {
-  beforeEach(async () => {
-    await TestBed.configureTestingModule({
-      declarations: [
-        AppComponent
-      ],
-    }).compileComponents();
-  });
-
-  it('should create the app', () => {
-    const fixture = TestBed.createComponent(AppComponent);
-    const app = fixture.componentInstance;
-    expect(app).toBeTruthy();
-  });
-
-  it(`should have as title 'metube'`, () => {
-    const fixture = TestBed.createComponent(AppComponent);
-    const app = fixture.componentInstance;
-    expect(app.title).toEqual('metube');
-  });
-
-  it('should render title', () => {
-    const fixture = TestBed.createComponent(AppComponent);
-    fixture.detectChanges();
-    const compiled = fixture.nativeElement;
-    expect(compiled.querySelector('.content span').textContent).toContain('metube app is running!');
-  });
-});

ui/src/app/app.component.ts

@@ -1,519 +0,0 @@
-import { Component, ViewChild, ElementRef, AfterViewInit } from '@angular/core';
-import { HttpClient } from '@angular/common/http';
-import { faTrashAlt, faCheckCircle, faTimesCircle, IconDefinition } from '@fortawesome/free-regular-svg-icons';
-import { faRedoAlt, faSun, faMoon, faCircleHalfStroke, faCheck, faExternalLinkAlt, faDownload, faFileImport, faFileExport, faCopy, faClock, faTachometerAlt } from '@fortawesome/free-solid-svg-icons';
-import { faGithub } from '@fortawesome/free-brands-svg-icons';
-import { CookieService } from 'ngx-cookie-service';
-import { map, Observable, of, distinctUntilChanged } from 'rxjs';
-
-import { Download, DownloadsService, Status } from './downloads.service';
-import { MasterCheckboxComponent } from './master-checkbox.component';
-import { Formats, Format, Quality } from './formats';
-import { Theme, Themes } from './theme';
-import {KeyValue} from "@angular/common";
-
-@Component({
-    selector: 'app-root',
-    templateUrl: './app.component.html',
-    styleUrls: ['./app.component.sass'],
-    standalone: false
-})
-export class AppComponent implements AfterViewInit {
-  addUrl: string;
-  formats: Format[] = Formats;
-  qualities: Quality[];
-  quality: string;
-  format: string;
-  folder: string;
-  customNamePrefix: string;
-  autoStart: boolean;
-  playlistStrictMode: boolean;
-  playlistItemLimit: number;
-  addInProgress = false;
-  themes: Theme[] = Themes;
-  activeTheme: Theme;
-  customDirs$: Observable<string[]>;
-  showBatchPanel: boolean = false; 
-  batchImportModalOpen = false;
-  batchImportText = '';
-  batchImportStatus = '';
-  importInProgress = false;
-  cancelImportFlag = false;
-  ytDlpOptionsUpdateTime: string | null = null;
-  ytDlpVersion: string | null = null;
-  metubeVersion: string | null = null;
-  isAdvancedOpen = false;
-
-  // Download metrics
-  activeDownloads = 0;
-  queuedDownloads = 0;
-  completedDownloads = 0;
-  failedDownloads = 0;
-  totalSpeed = 0;
-
-  @ViewChild('queueMasterCheckbox') queueMasterCheckbox: MasterCheckboxComponent;
-  @ViewChild('queueDelSelected') queueDelSelected: ElementRef;
-  @ViewChild('queueDownloadSelected') queueDownloadSelected: ElementRef;
-  @ViewChild('doneMasterCheckbox') doneMasterCheckbox: MasterCheckboxComponent;
-  @ViewChild('doneDelSelected') doneDelSelected: ElementRef;
-  @ViewChild('doneClearCompleted') doneClearCompleted: ElementRef;
-  @ViewChild('doneClearFailed') doneClearFailed: ElementRef;
-  @ViewChild('doneRetryFailed') doneRetryFailed: ElementRef;
-  @ViewChild('doneDownloadSelected') doneDownloadSelected: ElementRef;
-
-  faTrashAlt = faTrashAlt;
-  faCheckCircle = faCheckCircle;
-  faTimesCircle = faTimesCircle;
-  faRedoAlt = faRedoAlt;
-  faSun = faSun;
-  faMoon = faMoon;
-  faCheck = faCheck;
-  faCircleHalfStroke = faCircleHalfStroke;
-  faDownload = faDownload;
-  faExternalLinkAlt = faExternalLinkAlt;
-  faFileImport = faFileImport;
-  faFileExport = faFileExport;
-  faCopy = faCopy;
-  faGithub = faGithub;
-  faClock = faClock;
-  faTachometerAlt = faTachometerAlt;
-
-  constructor(public downloads: DownloadsService, private cookieService: CookieService, private http: HttpClient) {
-    this.format = cookieService.get('metube_format') || 'any';
-    // Needs to be set or qualities won't automatically be set
-    this.setQualities()
-    this.quality = cookieService.get('metube_quality') || 'best';
-    this.autoStart = cookieService.get('metube_auto_start') !== 'false';
-
-    this.activeTheme = this.getPreferredTheme(cookieService);
-
-    // Subscribe to download updates
-    this.downloads.queueChanged.subscribe(() => {
-      this.updateMetrics();
-    });
-    this.downloads.doneChanged.subscribe(() => {
-      this.updateMetrics();
-    });
-    // Subscribe to real-time updates
-    this.downloads.updated.subscribe(() => {
-      this.updateMetrics();
-    });
-  }
-
-  ngOnInit() {
-    this.getConfiguration();
-    this.getYtdlOptionsUpdateTime();
-    this.customDirs$ = this.getMatchingCustomDir();
-    this.setTheme(this.activeTheme);
-
-    window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => {
-      if (this.activeTheme.id === 'auto') {
-         this.setTheme(this.activeTheme);
-      }
-    });
-  }
-
-  ngAfterViewInit() {
-    this.downloads.queueChanged.subscribe(() => {
-      this.queueMasterCheckbox.selectionChanged();
-    });
-    this.downloads.doneChanged.subscribe(() => {
-      this.doneMasterCheckbox.selectionChanged();
-      let completed: number = 0, failed: number = 0;
-      this.downloads.done.forEach(dl => {
-        if (dl.status === 'finished')
-          completed++;
-        else if (dl.status === 'error')
-          failed++;
-      });
-      this.doneClearCompleted.nativeElement.disabled = completed === 0;
-      this.doneClearFailed.nativeElement.disabled = failed === 0;
-      this.doneRetryFailed.nativeElement.disabled = failed === 0;
-    });
-    this.fetchVersionInfo();
-  }
-
-  // workaround to allow fetching of Map values in the order they were inserted
-  //  https://github.com/angular/angular/issues/31420
-  asIsOrder(a, b) {
-    return 1;
-  }
-
-  qualityChanged() {
-    this.cookieService.set('metube_quality', this.quality, { expires: 3650 });
-    // Re-trigger custom directory change
-    this.downloads.customDirsChanged.next(this.downloads.customDirs);
-  }
-
-  showAdvanced() {
-    return this.downloads.configuration['CUSTOM_DIRS'];
-  }
-
-  allowCustomDir(tag: string) {
-    if (this.downloads.configuration['CREATE_CUSTOM_DIRS']) {
-      return tag;
-    }
-    return false;
-  }
-
-  isAudioType() {
-    return this.quality == 'audio' || this.format == 'mp3'  || this.format == 'm4a' || this.format == 'opus' || this.format == 'wav' || this.format == 'flac';
-  }
-
-  getMatchingCustomDir() : Observable<string[]> {
-    return this.downloads.customDirsChanged.asObservable().pipe(
-      map((output) => {
-        // Keep logic consistent with app/ytdl.py
-        if (this.isAudioType()) {
-          console.debug("Showing audio-specific download directories");
-          return output["audio_download_dir"];
-        } else {
-          console.debug("Showing default download directories");
-          return output["download_dir"];
-        }
-      }),
-      distinctUntilChanged((prev, curr) => JSON.stringify(prev) === JSON.stringify(curr))
-    );
-  }
-
-  getYtdlOptionsUpdateTime() {
-    this.downloads.ytdlOptionsChanged.subscribe({
-      next: (data) => {
-        if (data['success']){
-          const date = new Date(data['update_time'] * 1000);
-          this.ytDlpOptionsUpdateTime=date.toLocaleString();
-        }else{
-          alert("Error reload yt-dlp options: "+data['msg']);
-        }
-      }
-    });
-  }
-  getConfiguration() {
-    this.downloads.configurationChanged.subscribe({
-      next: (config) => {
-        this.playlistStrictMode = config['DEFAULT_OPTION_PLAYLIST_STRICT_MODE'];
-        const playlistItemLimit = config['DEFAULT_OPTION_PLAYLIST_ITEM_LIMIT'];
-        if (playlistItemLimit !== '0') {
-          this.playlistItemLimit = playlistItemLimit;
-        }
-      }
-    });
-  }
-
-  getPreferredTheme(cookieService: CookieService) {
-    let theme = 'auto';
-    if (cookieService.check('metube_theme')) {
-      theme = cookieService.get('metube_theme');
-    }
-
-    return this.themes.find(x => x.id === theme) ?? this.themes.find(x => x.id === 'auto');
-  }
-
-  themeChanged(theme: Theme) {
-    this.cookieService.set('metube_theme', theme.id, { expires: 3650 });
-    this.setTheme(theme);
-  }
-
-  setTheme(theme: Theme) {
-    this.activeTheme = theme;
-    if (theme.id === 'auto' && window.matchMedia('(prefers-color-scheme: dark)').matches) {
-      document.documentElement.setAttribute('data-bs-theme', 'dark');
-    } else {
-      document.documentElement.setAttribute('data-bs-theme', theme.id);
-    }
-  }
-
-  formatChanged() {
-    this.cookieService.set('metube_format', this.format, { expires: 3650 });
-    // Updates to use qualities available
-    this.setQualities()
-    // Re-trigger custom directory change
-    this.downloads.customDirsChanged.next(this.downloads.customDirs);
-  }
-
-  autoStartChanged() {
-    this.cookieService.set('metube_auto_start', this.autoStart ? 'true' : 'false', { expires: 3650 });
-  }
-
-  queueSelectionChanged(checked: number) {
-    this.queueDelSelected.nativeElement.disabled = checked == 0;
-    this.queueDownloadSelected.nativeElement.disabled = checked == 0;
-  }
-
-  doneSelectionChanged(checked: number) {
-    this.doneDelSelected.nativeElement.disabled = checked == 0;
-    this.doneDownloadSelected.nativeElement.disabled = checked == 0;
-  }
-
-  setQualities() {
-    // qualities for specific format
-    this.qualities = this.formats.find(el => el.id == this.format).qualities
-    const exists = this.qualities.find(el => el.id === this.quality)
-    this.quality = exists ? this.quality : 'best'
-  }
-
-  addDownload(url?: string, quality?: string, format?: string, folder?: string, customNamePrefix?: string, playlistStrictMode?: boolean, playlistItemLimit?: number, autoStart?: boolean) {
-    url = url ?? this.addUrl
-    quality = quality ?? this.quality
-    format = format ?? this.format
-    folder = folder ?? this.folder
-    customNamePrefix = customNamePrefix ?? this.customNamePrefix
-    playlistStrictMode = playlistStrictMode ?? this.playlistStrictMode
-    playlistItemLimit = playlistItemLimit ?? this.playlistItemLimit
-    autoStart = autoStart ?? this.autoStart
-
-    console.debug('Downloading: url='+url+' quality='+quality+' format='+format+' folder='+folder+' customNamePrefix='+customNamePrefix+' playlistStrictMode='+playlistStrictMode+' playlistItemLimit='+playlistItemLimit+' autoStart='+autoStart);
-    this.addInProgress = true;
-    this.downloads.add(url, quality, format, folder, customNamePrefix, playlistStrictMode, playlistItemLimit, autoStart).subscribe((status: Status) => {
-      if (status.status === 'error') {
-        alert(`Error adding URL: ${status.msg}`);
-      } else {
-        this.addUrl = '';
-      }
-      this.addInProgress = false;
-    });
-  }
-
-  downloadItemByKey(id: string) {
-    this.downloads.startById([id]).subscribe();
-  }
-
-  retryDownload(key: string, download: Download) {
-    this.addDownload(download.url, download.quality, download.format, download.folder, download.custom_name_prefix, download.playlist_strict_mode, download.playlist_item_limit, true);
-    this.downloads.delById('done', [key]).subscribe();
-  }
-
-  delDownload(where: string, id: string) {
-    this.downloads.delById(where, [id]).subscribe();
-  }
-
-  startSelectedDownloads(where: string){
-    this.downloads.startByFilter(where, dl => dl.checked).subscribe();
-  }
-
-  delSelectedDownloads(where: string) {
-    this.downloads.delByFilter(where, dl => dl.checked).subscribe();
-  }
-
-  clearCompletedDownloads() {
-    this.downloads.delByFilter('done', dl => dl.status === 'finished').subscribe();
-  }
-
-  clearFailedDownloads() {
-    this.downloads.delByFilter('done', dl => dl.status === 'error').subscribe();
-  }
-
-  retryFailedDownloads() {
-    this.downloads.done.forEach((dl, key) => {
-      if (dl.status === 'error') {
-        this.retryDownload(key, dl);
-      }
-    });
-  }
-
-  downloadSelectedFiles() {
-    this.downloads.done.forEach((dl, key) => {
-      if (dl.status === 'finished' && dl.checked) {
-        const link = document.createElement('a');
-        link.href = this.buildDownloadLink(dl);
-        link.setAttribute('download', dl.filename);
-        link.setAttribute('target', '_self');
-        document.body.appendChild(link);
-        link.click();
-        document.body.removeChild(link);
-      }
-    });
-  }
-
-  buildDownloadLink(download: Download) {
-    let baseDir = this.downloads.configuration["PUBLIC_HOST_URL"];
-    if (download.quality == 'audio' || download.filename.endsWith('.mp3')) {
-      baseDir = this.downloads.configuration["PUBLIC_HOST_AUDIO_URL"];
-    }
-
-    if (download.folder) {
-      baseDir += download.folder + '/';
-    }
-
-    return baseDir + encodeURIComponent(download.filename);
-  }
-
-  identifyDownloadRow(index: number, row: KeyValue<string, Download>) {
-    return row.key;
-  }
-
-  isNumber(event) {
-    const charCode = (event.which) ? event.which : event.keyCode;
-    if (charCode > 31 && (charCode < 48 || charCode > 57)) {
-      event.preventDefault();
-    }
-  }
-
-  // Toggle inline batch panel (if you want to use an inline panel for export; not used for import modal)
-  toggleBatchPanel(): void {
-    this.showBatchPanel = !this.showBatchPanel;
-  }
-
-  // Open the Batch Import modal
-  openBatchImportModal(): void {
-    this.batchImportModalOpen = true;
-    this.batchImportText = '';
-    this.batchImportStatus = '';
-    this.importInProgress = false;
-    this.cancelImportFlag = false;
-  }
-
-  // Close the Batch Import modal
-  closeBatchImportModal(): void {
-    this.batchImportModalOpen = false;
-  }
-
-  // Start importing URLs from the batch modal textarea
-  startBatchImport(): void {
-    const urls = this.batchImportText
-      .split(/\r?\n/)
-      .map(url => url.trim())
-      .filter(url => url.length > 0);
-    if (urls.length === 0) {
-      alert('No valid URLs found.');
-      return;
-    }
-    this.importInProgress = true;
-    this.cancelImportFlag = false;
-    this.batchImportStatus = `Starting to import ${urls.length} URLs...`;
-    let index = 0;
-    const delayBetween = 1000;
-    const processNext = () => {
-      if (this.cancelImportFlag) {
-        this.batchImportStatus = `Import cancelled after ${index} of ${urls.length} URLs.`;
-        this.importInProgress = false;
-        return;
-      }
-      if (index >= urls.length) {
-        this.batchImportStatus = `Finished importing ${urls.length} URLs.`;
-        this.importInProgress = false;
-        return;
-      }
-      const url = urls[index];
-      this.batchImportStatus = `Importing URL ${index + 1} of ${urls.length}: ${url}`;
-      // Now pass the selected quality, format, folder, etc. to the add() method
-      this.downloads.add(url, this.quality, this.format, this.folder, this.customNamePrefix,
-        this.playlistStrictMode, this.playlistItemLimit, this.autoStart)
-        .subscribe({
-          next: (status: Status) => {
-            if (status.status === 'error') {
-              alert(`Error adding URL ${url}: ${status.msg}`);
-            }
-            index++;
-            setTimeout(processNext, delayBetween);
-          },
-          error: (err) => {
-            console.error(`Error importing URL ${url}:`, err);
-            index++;
-            setTimeout(processNext, delayBetween);
-          }
-        });
-    };
-    processNext();
-  }
-
-  // Cancel the batch import process
-  cancelBatchImport(): void {
-    if (this.importInProgress) {
-      this.cancelImportFlag = true;
-      this.batchImportStatus += ' Cancelling...';
-    }
-  }
-
-  // Export URLs based on filter: 'pending', 'completed', 'failed', or 'all'
-  exportBatchUrls(filter: 'pending' | 'completed' | 'failed' | 'all'): void {
-    let urls: string[];
-    if (filter === 'pending') {
-      urls = Array.from(this.downloads.queue.values()).map(dl => dl.url);
-    } else if (filter === 'completed') {
-      // Only finished downloads in the "done" Map
-      urls = Array.from(this.downloads.done.values()).filter(dl => dl.status === 'finished').map(dl => dl.url);
-    } else if (filter === 'failed') {
-      // Only error downloads from the "done" Map
-      urls = Array.from(this.downloads.done.values()).filter(dl => dl.status === 'error').map(dl => dl.url);
-    } else {
-      // All: pending + both finished and error in done
-      urls = [
-        ...Array.from(this.downloads.queue.values()).map(dl => dl.url),
-        ...Array.from(this.downloads.done.values()).map(dl => dl.url)
-      ];
-    }
-    if (!urls.length) {
-      alert('No URLs found for the selected filter.');
-      return;
-    }
-    const content = urls.join('\n');
-    const blob = new Blob([content], { type: 'text/plain' });
-    const downloadUrl = window.URL.createObjectURL(blob);
-    const a = document.createElement('a');
-    a.href = downloadUrl;
-    a.download = 'metube_urls.txt';
-    document.body.appendChild(a);
-    a.click();
-    document.body.removeChild(a);
-    window.URL.revokeObjectURL(downloadUrl);
-  }
-
-  // Copy URLs to clipboard based on filter: 'pending', 'completed', 'failed', or 'all'
-  copyBatchUrls(filter: 'pending' | 'completed' | 'failed' | 'all'): void {
-    let urls: string[];
-    if (filter === 'pending') {
-      urls = Array.from(this.downloads.queue.values()).map(dl => dl.url);
-    } else if (filter === 'completed') {
-      urls = Array.from(this.downloads.done.values()).filter(dl => dl.status === 'finished').map(dl => dl.url);
-    } else if (filter === 'failed') {
-      urls = Array.from(this.downloads.done.values()).filter(dl => dl.status === 'error').map(dl => dl.url);
-    } else {
-      urls = [
-        ...Array.from(this.downloads.queue.values()).map(dl => dl.url),
-        ...Array.from(this.downloads.done.values()).map(dl => dl.url)
-      ];
-    }
-    if (!urls.length) {
-      alert('No URLs found for the selected filter.');
-      return;
-    }
-    const content = urls.join('\n');
-    navigator.clipboard.writeText(content)
-      .then(() => alert('URLs copied to clipboard.'))
-      .catch(() => alert('Failed to copy URLs.'));
-  }
-
-  fetchVersionInfo(): void {
-    const baseUrl = `${window.location.origin}${window.location.pathname.replace(/\/[^\/]*$/, '/')}`;
-    const versionUrl = `${baseUrl}version`;
-    this.http.get<{ 'yt-dlp': string, version: string }>(versionUrl)
-      .subscribe({
-        next: (data) => {
-          this.ytDlpVersion = data['yt-dlp'];
-          this.metubeVersion = data.version;
-        },
-        error: () => {
-          this.ytDlpVersion = null;
-          this.metubeVersion = null;
-        }
-      });
-  }
-
-  toggleAdvanced() {
-    this.isAdvancedOpen = !this.isAdvancedOpen;
-  }
-
-  private updateMetrics() {
-    this.activeDownloads = Array.from(this.downloads.queue.values()).filter(d => d.status === 'downloading' || d.status === 'preparing').length;
-    this.queuedDownloads = Array.from(this.downloads.queue.values()).filter(d => d.status === 'pending').length;
-    this.completedDownloads = Array.from(this.downloads.done.values()).filter(d => d.status === 'finished').length;
-    this.failedDownloads = Array.from(this.downloads.done.values()).filter(d => d.status === 'error').length;
-    
-    // Calculate total speed from downloading items
-    const downloadingItems = Array.from(this.downloads.queue.values())
-      .filter(d => d.status === 'downloading');
-    
-    this.totalSpeed = downloadingItems.reduce((total, item) => total + (item.speed || 0), 0);
-  }
-}

ui/src/app/app.config.ts

@@ -0,0 +1,17 @@
+import { ApplicationConfig, provideBrowserGlobalErrorListeners, isDevMode, provideZoneChangeDetection } from '@angular/core';
+import { provideServiceWorker } from '@angular/service-worker';
+import { provideHttpClient, withInterceptorsFromDi } from '@angular/common/http';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideBrowserGlobalErrorListeners(),
+    provideZoneChangeDetection({ eventCoalescing: true }),
+    provideServiceWorker('custom-service-worker.js', {
+            enabled: !isDevMode(),
+            // Register the ServiceWorker as soon as the application is stable
+            // or after 30 seconds (whichever comes first).
+            registrationStrategy: 'registerWhenStable:30000'
+          }),
+    provideHttpClient(withInterceptorsFromDi()),
+  ]
+};

ui/src/app/app.html

@@ -0,0 +1,986 @@
+<nav class="navbar navbar-expand-md navbar-dark">
+  <div class="container-fluid">
+    <a class="navbar-brand d-flex align-items-center" href="#">
+      <img src="assets/icons/android-chrome-192x192.png" alt="MeTube Logo" height="32" class="me-2">
+      MeTube
+    </a>
+    <div class="download-metrics">
+      @if (activeDownloads > 0) {
+        <div class="metric">
+          <fa-icon [icon]="faDownload" class="text-primary" />
+          <span>{{activeDownloads}} downloading</span>
+        </div>
+      }
+      @if (queuedDownloads > 0) {
+        <div class="metric">
+          <fa-icon [icon]="faClock" class="text-warning" />
+          <span>{{queuedDownloads}} queued</span>
+        </div>
+      }
+      @if (completedDownloads > 0) {
+        <div class="metric">
+          <fa-icon [icon]="faCheck" class="text-success" />
+          <span>{{completedDownloads}} completed</span>
+        </div>
+      }
+      @if (failedDownloads > 0) {
+        <div class="metric">
+          <fa-icon [icon]="faTimesCircle" class="text-danger" />
+          <span>{{failedDownloads}} failed</span>
+        </div>
+      }
+      @if ((totalSpeed | speed) !== '') {
+        <div class="metric">
+          <fa-icon [icon]="faTachometerAlt" class="text-info" />
+          <span>{{totalSpeed | speed }}</span>
+        </div>
+      }
+    </div>
+    <!--
+    <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarsDefault" aria-controls="navbarsDefault" aria-expanded="false" aria-label="Toggle navigation">
+      <span class="navbar-toggler-icon"></span>
+    </button>
+    <div class="collapse navbar-collapse" id="navbarsDefault">
+      <ul class="navbar-nav mr-auto">
+        <li class="nav-item active">
+          <a class="nav-link" href="#">Home <span class="sr-only">(current)</span></a>
+        </li>
+      </ul>
+    </div>
+    -->
+    <div class="navbar-nav ms-auto">
+      <div class="nav-item dropdown" ngbDropdown placement="bottom-end">
+        <button class="btn btn-link nav-link py-2 px-0 px-sm-2 dropdown-toggle d-flex align-items-center"
+          id="theme-select"
+          type="button"
+          aria-expanded="false"
+          ngbDropdownToggle>
+          @if(activeTheme){
+          <fa-icon [icon]="activeTheme.icon" />
+          }
+        </button>
+        <ul class="dropdown-menu dropdown-menu-end position-absolute" aria-labelledby="theme-select" ngbDropdownMenu>
+          @for (theme of themes; track theme) {
+            <li>
+              <button type="button" class="dropdown-item d-flex align-items-center"
+              [class.active]="activeTheme === theme"
+              ngbDropdownItem
+              (click)="themeChanged(theme)">
+                <span class="me-2 opacity-50">
+                  <fa-icon [icon]="theme.icon" />
+                </span>
+                {{ theme.displayName }}
+                <span class="ms-auto"
+                [class.d-none]="activeTheme !== theme">
+                <fa-icon [icon]="faCheck" />
+                </span>
+              </button>
+            </li>
+          }
+        </ul>
+      </div>
+    </div>
+  </div>
+</nav>
+
+<main role="main" class="container container-xl">
+  <form #f="ngForm">
+    <div class="container add-url-box">
+      <!-- Main URL Input with Download Button -->
+      <div class="row mb-4">
+        <div class="col">
+          <ng-template #urlBarActions>
+            @if (addInProgress && cancelRequested) {
+              <button class="btn btn-warning btn-lg px-3" type="button" disabled>
+                <span class="spinner-border spinner-border-sm me-1" role="status"></span>
+                Canceling...
+              </button>
+            } @else if (addInProgress) {
+              <button class="btn btn-secondary btn-lg px-3 add-progress-btn" type="button" disabled>
+                <span class="spinner-border spinner-border-sm me-2" role="status"></span>
+                Adding...
+              </button>
+              <button class="btn btn-outline-danger btn-lg px-3 add-cancel-btn"
+                type="button"
+                (click)="cancelAdding()"
+                aria-label="Cancel adding URL"
+                title="Cancel adding URL">
+                <fa-icon [icon]="faTimesCircle" class="me-1" /> Cancel
+              </button>
+            } @else if (subscribeInProgress) {
+              <button class="btn btn-primary btn-lg px-4" type="button" disabled>
+                Download
+              </button>
+              <button class="btn btn-outline-secondary btn-lg px-3" type="button" disabled>
+                <span class="spinner-border spinner-border-sm me-2" role="status"></span>
+                Subscribing...
+              </button>
+            } @else {
+              <button class="btn btn-primary btn-lg px-4" type="submit"
+                (click)="addDownload()"
+                [disabled]="downloads.loading">
+                Download
+              </button>
+              <button class="btn btn-outline-secondary btn-lg px-3" type="button"
+                (click)="addSubscription()"
+                [disabled]="downloads.loading">
+                Subscribe
+              </button>
+            }
+          </ng-template>
+
+          <!-- Narrow viewports: full-width field, then Bootstrap btn-group (no faux input-group strip) -->
+          <div class="vstack gap-2 d-md-none">
+            <input type="text"
+              autocomplete="off"
+              spellcheck="false"
+              class="form-control form-control-lg"
+              placeholder="Enter video, channel, or playlist URL"
+              [(ngModel)]="addUrl"
+              [ngModelOptions]="{standalone: true}"
+              [disabled]="addInProgress || subscribeInProgress || downloads.loading">
+            <div class="btn-group w-100" role="group" aria-label="Download or subscribe">
+              <ng-container [ngTemplateOutlet]="urlBarActions" />
+            </div>
+          </div>
+
+          <!-- md and up: standard input-group so Bootstrap handles fused borders -->
+          <div class="input-group input-group-lg shadow-sm d-none d-md-flex">
+            <input type="text"
+              autocomplete="off"
+              spellcheck="false"
+              class="form-control form-control-lg"
+              placeholder="Enter video, channel, or playlist URL"
+              [(ngModel)]="addUrl"
+              [ngModelOptions]="{standalone: true}"
+              [disabled]="addInProgress || subscribeInProgress || downloads.loading">
+            <ng-container [ngTemplateOutlet]="urlBarActions" />
+          </div>
+        </div>
+      </div>
+
+      <!-- Options Row -->
+      <div class="row mb-3 g-3">
+        @if (downloadType === 'video') {
+          <div class="col-md-3">
+            <div class="input-group">
+              <span class="input-group-text">Type</span>
+              <select class="form-select"
+                name="downloadType"
+                [(ngModel)]="downloadType"
+                (change)="downloadTypeChanged()"
+                [disabled]="addInProgress || subscribeInProgress || downloads.loading">
+                @for (type of downloadTypes; track type.id) {
+                  <option [ngValue]="type.id">{{ type.text }}</option>
+                }
+              </select>
+            </div>
+          </div>
+          <div class="col-md-3">
+            <div class="input-group">
+              <span class="input-group-text">Codec</span>
+              <select class="form-select"
+                name="codec"
+                [(ngModel)]="codec"
+                (change)="codecChanged()"
+                [disabled]="addInProgress || subscribeInProgress || downloads.loading">
+                @for (vc of videoCodecs; track vc.id) {
+                  <option [ngValue]="vc.id">{{ vc.text }}</option>
+                }
+              </select>
+            </div>
+          </div>
+          <div class="col-md-3">
+            <div class="input-group">
+              <span class="input-group-text">Format</span>
+              <select class="form-select"
+                name="format"
+                [(ngModel)]="format"
+                (change)="formatChanged()"
+                [disabled]="addInProgress || subscribeInProgress || downloads.loading">
+                @for (f of formatOptions; track f.id) {
+                  <option [ngValue]="f.id">{{ f.text }}</option>
+                }
+              </select>
+            </div>
+          </div>
+          <div class="col-md-3">
+            <div class="input-group">
+              <span class="input-group-text">Quality</span>
+              <select class="form-select"
+                name="quality"
+                [(ngModel)]="quality"
+                (change)="qualityChanged()"
+                [disabled]="addInProgress || subscribeInProgress || downloads.loading || !showQualitySelector()">
+                @for (q of qualities; track q.id) {
+                  <option [ngValue]="q.id">{{ q.text }}</option>
+                }
+              </select>
+            </div>
+          </div>
+        } @else if (downloadType === 'audio') {
+          <div class="col-md-4">
+            <div class="input-group">
+              <span class="input-group-text">Type</span>
+              <select class="form-select"
+                name="downloadType"
+                [(ngModel)]="downloadType"
+                (change)="downloadTypeChanged()"
+                [disabled]="addInProgress || subscribeInProgress || downloads.loading">
+                @for (type of downloadTypes; track type.id) {
+                  <option [ngValue]="type.id">{{ type.text }}</option>
+                }
+              </select>
+            </div>
+          </div>
+          <div class="col-md-4">
+            <div class="input-group">
+              <span class="input-group-text">Format</span>
+              <select class="form-select"
+                name="format"
+                [(ngModel)]="format"
+                (change)="formatChanged()"
+                [disabled]="addInProgress || subscribeInProgress || downloads.loading">
+                @for (f of formatOptions; track f.id) {
+                  <option [ngValue]="f.id">{{ f.text }}</option>
+                }
+              </select>
+            </div>
+          </div>
+          <div class="col-md-4">
+            <div class="input-group">
+              <span class="input-group-text">Quality</span>
+              <select class="form-select"
+                name="quality"
+                [(ngModel)]="quality"
+                (change)="qualityChanged()"
+                [disabled]="addInProgress || subscribeInProgress || downloads.loading">
+                @for (q of qualities; track q.id) {
+                  <option [ngValue]="q.id">{{ q.text }}</option>
+                }
+              </select>
+            </div>
+          </div>
+        } @else if (downloadType === 'captions') {
+          <!-- 4× col-md-3 is too tight at ~768px (long addons wrap the 4th field); 2×2 md–lg, one row lg+ -->
+          <div class="col-12 col-md-6 col-lg-3">
+            <div class="input-group">
+              <span class="input-group-text">Type</span>
+              <select class="form-select"
+                name="downloadType"
+                [(ngModel)]="downloadType"
+                (change)="downloadTypeChanged()"
+                [disabled]="addInProgress || subscribeInProgress || downloads.loading">
+                @for (type of downloadTypes; track type.id) {
+                  <option [ngValue]="type.id">{{ type.text }}</option>
+                }
+              </select>
+            </div>
+          </div>
+          <div class="col-12 col-md-6 col-lg-3">
+            <div class="input-group">
+              <span class="input-group-text">Format</span>
+              <select class="form-select"
+                name="format"
+                [(ngModel)]="format"
+                (change)="formatChanged()"
+                [disabled]="addInProgress || subscribeInProgress || downloads.loading"
+                ngbTooltip="Subtitle output format for captions mode">
+                @for (f of formatOptions; track f.id) {
+                  <option [ngValue]="f.id">{{ f.text }}</option>
+                }
+              </select>
+            </div>
+          </div>
+          <div class="col-12 col-md-6 col-lg-3">
+            <div class="input-group">
+              <span class="input-group-text">Language</span>
+              <input class="form-control"
+                type="text"
+                list="subtitleLanguageOptions"
+                name="subtitleLanguage"
+                [(ngModel)]="subtitleLanguage"
+                (change)="subtitleLanguageChanged()"
+                [disabled]="addInProgress || subscribeInProgress || downloads.loading"
+                placeholder="e.g. en, es, zh-Hans"
+                ngbTooltip="Subtitle language (you can type any language code)">
+              <datalist id="subtitleLanguageOptions">
+                @for (lang of subtitleLanguages; track lang.id) {
+                  <option [value]="lang.id">{{ lang.text }}</option>
+                }
+              </datalist>
+            </div>
+          </div>
+          <div class="col-12 col-md-6 col-lg-3">
+            <div class="input-group">
+              <span class="input-group-text">Subtitle Source</span>
+              <select class="form-select"
+                name="subtitleMode"
+                [(ngModel)]="subtitleMode"
+                (change)="subtitleModeChanged()"
+                [disabled]="addInProgress || subscribeInProgress || downloads.loading"
+                ngbTooltip="Choose manual, auto, or fallback preference for captions mode">
+                @for (mode of subtitleModes; track mode.id) {
+                  <option [ngValue]="mode.id">{{ mode.text }}</option>
+                }
+              </select>
+            </div>
+          </div>
+        } @else {
+          <div class="col-md-6">
+            <div class="input-group">
+              <span class="input-group-text">Type</span>
+              <select class="form-select"
+                name="downloadType"
+                [(ngModel)]="downloadType"
+                (change)="downloadTypeChanged()"
+                [disabled]="addInProgress || subscribeInProgress || downloads.loading">
+                @for (type of downloadTypes; track type.id) {
+                  <option [ngValue]="type.id">{{ type.text }}</option>
+                }
+              </select>
+            </div>
+          </div>
+          <div class="col-md-6">
+            <div class="input-group">
+              <span class="input-group-text">Format</span>
+              <input class="form-control" value="JPG" disabled>
+            </div>
+          </div>
+        }
+      </div>
+
+      <div class="row mb-3 g-3">
+        <div class="col-12 text-start">
+          <button type="button"
+            class="btn btn-link p-0 text-decoration-none"
+            (click)="toggleAdvanced()"
+            [attr.aria-expanded]="isAdvancedOpen"
+            aria-controls="advancedOptions">
+            Advanced Options
+            <fa-icon
+              [icon]="isAdvancedOpen ? faChevronDown : faChevronRight"
+              class="ms-1" />
+          </button>
+        </div>
+      </div>
+
+      <!-- Advanced Options Panel -->
+      <div class="row">
+        <div class="col-12">
+          <div class="collapse show" id="advancedOptions" [ngbCollapse]="!isAdvancedOpen">
+            <div class="pt-1 pb-2">
+              <!-- Output -->
+              <div class="settings-section-label">Output</div>
+              <div class="row g-3">
+                <div class="col-md-6">
+                  <div class="input-group">
+                    <span class="input-group-text">Download Folder</span>
+                    @if (customDirs$ | async; as customDirs) {
+                    <ng-select [items]="customDirs"
+                      placeholder="Default"
+                      [addTag]="allowCustomDir.bind(this)"
+                      addTagText="Create directory"
+                      bindLabel="folder"
+                      [(ngModel)]="folder"
+                      [disabled]="addInProgress || subscribeInProgress || downloads.loading"
+                      [virtualScroll]="true"
+                      [clearable]="true"
+                      [loading]="downloads.loading"
+                      [searchable]="true"
+                      [closeOnSelect]="true"
+                      ngbTooltip="Choose where to save downloads. Type to create a new folder." />
+                  }
+                  </div>
+                </div>
+                <div class="col-md-6">
+                  <div class="input-group">
+                    <span class="input-group-text">Custom Name Prefix</span>
+                    <input type="text"
+                      class="form-control"
+                      placeholder="Default"
+                      name="customNamePrefix"
+                      [(ngModel)]="customNamePrefix"
+                      [disabled]="addInProgress || subscribeInProgress || downloads.loading"
+                      ngbTooltip="Add a prefix to downloaded filenames">
+                  </div>
+                </div>
+                <div class="col-12">
+                  <div class="row g-2 align-items-center">
+                    <div class="col-auto">
+                      <div class="form-check form-switch">
+                        <input class="form-check-input" type="checkbox" role="switch" id="checkbox-split-chapters"
+                          name="splitByChapters" [(ngModel)]="splitByChapters" (change)="splitByChaptersChanged()"
+                          [disabled]="addInProgress || subscribeInProgress || downloads.loading"
+                          ngbTooltip="Split video into separate files by chapters">
+                        <label class="form-check-label" for="checkbox-split-chapters">Split by chapters</label>
+                      </div>
+                    </div>
+                    @if (splitByChapters) {
+                    <div class="col">
+                      <div class="input-group">
+                        <span class="input-group-text">Template</span>
+                        <input type="text" class="form-control" name="chapterTemplate" [(ngModel)]="chapterTemplate"
+                          (change)="chapterTemplateChanged()" [disabled]="addInProgress || subscribeInProgress || downloads.loading"
+                          ngbTooltip="Output template for chapter files">
+                      </div>
+                    </div>
+                    }
+                  </div>
+                </div>
+              </div>
+
+              <!-- Behavior -->
+              <div class="settings-section-label">Behavior</div>
+              <div class="row g-3">
+                <div class="col-md-6">
+                  <div class="input-group">
+                    <span class="input-group-text">Auto Start</span>
+                    <select class="form-select"
+                      name="autoStart"
+                      [(ngModel)]="autoStart"
+                      (change)="autoStartChanged()"
+                      [disabled]="addInProgress || subscribeInProgress || downloads.loading"
+                      ngbTooltip="Automatically start downloads when added">
+                      <option [ngValue]="true">Yes</option>
+                      <option [ngValue]="false">No</option>
+                    </select>
+                  </div>
+                </div>
+                <div class="col-md-6">
+                  <div class="input-group">
+                    <span class="input-group-text">Items Limit</span>
+                    <input type="number"
+                      min="0"
+                      class="form-control"
+                      placeholder="Default"
+                      name="playlistItemLimit"
+                      (keydown)="isNumber($event)"
+                      [(ngModel)]="playlistItemLimit"
+                      [disabled]="addInProgress || subscribeInProgress || downloads.loading"
+                      ngbTooltip="Maximum number of items to download from a playlist or channel (0 = no limit)">
+                  </div>
+                </div>
+                <div class="col-md-6">
+                  <div class="input-group">
+                    <span class="input-group-text">Subscription Check (min)</span>
+                    <input type="number"
+                      min="1"
+                      class="form-control"
+                      name="checkIntervalMinutes"
+                      (keydown)="isNumber($event)"
+                      [(ngModel)]="checkIntervalMinutes"
+                      (ngModelChange)="checkIntervalChanged()"
+                      [disabled]="addInProgress || subscribeInProgress || downloads.loading"
+                      ngbTooltip="How often to poll subscriptions for new videos">
+                  </div>
+                </div>
+              </div>
+
+              <!-- yt-dlp -->
+              <div class="settings-section-label">yt-dlp</div>
+              <div class="row g-3">
+                <div class="col-12" [class.col-md-6]="allowYtdlOptionsOverrides()">
+                  <div class="input-group">
+                    <span class="input-group-text">Option Presets</span>
+                    <ng-select
+                      class="flex-grow-1"
+                      name="ytdlOptionsPresets"
+                      [items]="ytdlOptionPresetNames"
+                      [multiple]="true"
+                      [closeOnSelect]="false"
+                      placeholder="Default"
+                      [(ngModel)]="ytdlOptionsPresets"
+                      (ngModelChange)="ytdlOptionsPresetsChanged()"
+                      [disabled]="addInProgress || subscribeInProgress || downloads.loading"
+                      ngbTooltip="Choose one or more yt-dlp option presets configured on the server (applied in order)" />
+                  </div>
+                </div>
+                @if (allowYtdlOptionsOverrides()) {
+                <div class="col-md-6">
+                  <div class="input-group">
+                    <span class="input-group-text">Custom yt-dlp Options</span>
+                    <input type="text"
+                      class="form-control"
+                      placeholder='e.g. {"writesubtitles": true}'
+                      name="ytdlOptionsOverrides"
+                      [(ngModel)]="ytdlOptionsOverrides"
+                      (change)="ytdlOptionsOverridesChanged()"
+                      [disabled]="addInProgress || subscribeInProgress || downloads.loading"
+                      ngbTooltip="Optional per-download yt-dlp overrides as a JSON object">
+                  </div>
+                </div>
+                }
+              </div>
+
+              <!-- Tools -->
+              <div class="settings-section-label">Tools</div>
+              <div class="row g-3">
+                <div class="col-md-4">
+                  <div class="action-group-label">Cookies</div>
+                  <input type="file" id="cookie-upload" class="d-none" accept=".txt"
+                    (change)="onCookieFileSelect($event)"
+                    [disabled]="cookieUploadInProgress || addInProgress">
+                  <div class="btn-group w-100" role="group">
+                    <label class="btn mb-0"
+                      [class]="hasCookies ? 'btn cookie-active-btn mb-0' : 'btn cookie-btn mb-0'"
+                      [class.disabled]="cookieUploadInProgress || addInProgress"
+                      for="cookie-upload"
+                      ngbTooltip="Upload a cookies.txt file for authenticated downloads">
+                      @if (cookieUploadInProgress) {
+                        <span class="spinner-border spinner-border-sm me-2" role="status"></span>
+                      } @else {
+                        <fa-icon [icon]="faUpload" class="me-2" />
+                      }
+                      {{ hasCookies ? 'Replace Cookies' : 'Upload Cookies' }}
+                    </label>
+                    @if (hasCookies) {
+                      <button type="button" class="btn btn-outline-danger"
+                        (click)="deleteCookies()"
+                        [disabled]="cookieUploadInProgress || addInProgress"
+                        ngbTooltip="Remove uploaded cookies">
+                        <fa-icon [icon]="faTrashAlt" />
+                      </button>
+                    }
+                  </div>
+                  <div class="cookie-status" [class.active]="hasCookies">
+                    @if (hasCookies) {
+                      <fa-icon [icon]="faCheckCircle" class="me-1" />
+                      Cookies active
+                    } @else {
+                      No cookies configured
+                    }
+                  </div>
+                </div>
+                <div class="col-md-8">
+                  <div class="action-group-label">Bulk Actions</div>
+                  <div class="row g-2">
+                    <div class="col-4">
+                      <button type="button"
+                        class="btn btn-secondary w-100"
+                        (click)="openBatchImportModal()">
+                        <fa-icon [icon]="faFileImport" class="me-2" />
+                        Import URLs
+                      </button>
+                    </div>
+                    <div class="col-4">
+                      <button type="button"
+                        class="btn btn-secondary w-100"
+                        (click)="exportBatchUrls('all')">
+                        <fa-icon [icon]="faFileExport" class="me-2" />
+                        Export URLs
+                      </button>
+                    </div>
+                    <div class="col-4">
+                      <button type="button"
+                        class="btn btn-secondary w-100"
+                        (click)="copyBatchUrls('all')">
+                        <fa-icon [icon]="faCopy" class="me-2" />
+                        Copy URLs
+                      </button>
+                    </div>
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </form>
+
+  <!-- Batch Import Modal -->
+  <div class="modal fade" tabindex="-1" role="dialog"
+  aria-modal="true"
+  aria-labelledby="batch-import-modal-title"
+  [class.show]="batchImportModalOpen"
+  [style.display]="batchImportModalOpen ? 'block' : 'none'">
+    <div class="modal-dialog" role="document">
+      <div class="modal-content">
+        <div class="modal-header">
+          <h5 id="batch-import-modal-title" class="modal-title">Batch Import URLs</h5>
+          <button type="button" class="btn-close" aria-label="Close" (click)="closeBatchImportModal()"></button>
+        </div>
+        <div class="modal-body">
+          <textarea id="batch-import-textarea" [(ngModel)]="batchImportText" class="form-control" rows="6"
+          placeholder="Paste one video URL per line"></textarea>
+          <div class="mt-2">
+            @if (batchImportStatus) {
+              <small>{{ batchImportStatus }}</small>
+            }
+          </div>
+        </div>
+        <div class="modal-footer">
+          @if (importInProgress) {
+            <button type="button" class="btn btn-danger me-auto" (click)="cancelBatchImport()">
+              Cancel Import
+            </button>
+          }
+          <button type="button" class="btn btn-secondary" (click)="closeBatchImportModal()">Close</button>
+          <button type="button" class="btn btn-primary" (click)="startBatchImport()" [disabled]="importInProgress">
+            Import URLs
+          </button>
+        </div>
+      </div>
+    </div>
+  </div>
+
+
+  @if (downloads.loading) {
+    <div class="alert alert-info" role="alert">
+      Connecting to server...
+    </div>
+  }
+  <div class="metube-section-header">Downloading</div>
+  <div class="px-2 py-3 border-bottom">
+    <button type="button" class="btn btn-link text-decoration-none px-0 me-4" disabled #queueDelSelected (click)="delSelectedDownloads('queue')"><fa-icon [icon]="faTrashAlt" />&nbsp; Cancel selected</button>
+    <button type="button" class="btn btn-link text-decoration-none px-0 me-4" disabled #queueDownloadSelected (click)="startSelectedDownloads('queue')"><fa-icon [icon]="faDownload" />&nbsp; Download selected</button>
+  </div>
+  <div class="overflow-auto">
+    <table class="table">
+      <thead>
+        <tr>
+          <th scope="col" style="width: 1rem;">
+            <app-select-all-checkbox #queueMasterCheckboxRef [id]="'queue'" [list]="downloads.queue" (changed)="queueSelectionChanged($event)" />
+          </th>
+          <th scope="col">Video</th>
+          <th scope="col" style="width: 8rem;">Speed</th>
+          <th scope="col" style="width: 7rem;">ETA</th>
+          <th scope="col" style="width: 6rem;"></th>
+        </tr>
+      </thead>
+      <tbody>
+        @for (download of downloads.queue | keyvalue: asIsOrder; track download.value.id) {
+          <tr [class.disabled]='download.value.deleting'>
+            <td>
+              <app-item-checkbox [id]="download.key" [master]="queueMasterCheckboxRef" [checkable]="download.value" />
+            </td>
+            <td title="{{ download.value.filename }}">
+              <div class="d-flex flex-column flex-sm-row align-items-center row-gap-2 column-gap-3">
+                <div>{{ download.value.title }} </div>
+                <ngb-progressbar height="1.5rem" [showValue]="download.value.status !== 'preparing'" [striped]="download.value.status === 'preparing'" [animated]="download.value.status === 'preparing'" type="success"
+                [value]="download.value.status === 'preparing' ? 100 : download.value.percent" class="download-progressbar" />
+              </div>
+            </td>
+            <td>{{ download.value.speed | speed }}</td>
+            <td>{{ download.value.eta | eta }}</td>
+            <td>
+              <div class="d-flex">
+                @if (download.value.status === 'pending') {
+                  <button type="button" class="btn btn-link" [attr.aria-label]="'Start download for ' + download.value.title" (click)="downloadItemByKey(download.key)"><fa-icon [icon]="faDownload" /></button>
+                }
+                <button type="button" class="btn btn-link" [attr.aria-label]="'Remove ' + download.value.title + ' from queue'" (click)="delDownload('queue', download.key)"><fa-icon [icon]="faTrashAlt" /></button>
+                <a href="{{download.value.url}}" target="_blank" class="btn btn-link" [attr.aria-label]="'Open source URL for ' + download.value.title"><fa-icon [icon]="faExternalLinkAlt" /></a>
+              </div>
+            </td>
+          </tr>
+        }
+      </tbody>
+    </table>
+  </div>
+
+  <div class="metube-section-header">Completed</div>
+  <div class="px-2 py-3 border-bottom">
+    <button type="button" class="btn btn-link text-decoration-none px-0 me-4" (click)="toggleSortOrder()" ngbTooltip="{{ sortAscending ? 'Oldest first' : 'Newest first' }}"><fa-icon [icon]="sortAscending ? faSortAmountUp : faSortAmountDown" />&nbsp; {{ sortAscending ? 'Oldest first' : 'Newest first' }}</button>
+    <button type="button" class="btn btn-link text-decoration-none px-0 me-4" disabled #doneDelSelected (click)="delSelectedDownloads('done')"><fa-icon [icon]="faTrashAlt" />&nbsp; Clear selected</button>
+    <button type="button" class="btn btn-link text-decoration-none px-0 me-4" [disabled]="!hasCompletedDone" (click)="clearCompletedDownloads()"><fa-icon [icon]="faCheckCircle" />&nbsp; Clear completed</button>
+    <button type="button" class="btn btn-link text-decoration-none px-0 me-4" [disabled]="!hasFailedDone" (click)="clearFailedDownloads()"><fa-icon [icon]="faTimesCircle" />&nbsp; Clear failed</button>
+    <button type="button" class="btn btn-link text-decoration-none px-0 me-4" [disabled]="!hasFailedDone" (click)="retryFailedDownloads()"><fa-icon [icon]="faRedoAlt" />&nbsp; Retry failed</button>
+    <button type="button" class="btn btn-link text-decoration-none px-0 me-4" disabled #doneDownloadSelected (click)="downloadSelectedFiles()"><fa-icon [icon]="faDownload" />&nbsp; Download Selected</button>
+  </div>
+  <div class="overflow-auto">
+    <table class="table">
+      <thead>
+        <tr>
+          <th scope="col" style="width: 1rem;">
+            <app-select-all-checkbox #doneMasterCheckboxRef [id]="'done'" [list]="downloads.done" (changed)="doneSelectionChanged($event)" />
+          </th>
+          <th scope="col">Video</th>
+          <th scope="col">Type</th>
+          <th scope="col">Quality</th>
+          <th scope="col">Codec / Format</th>
+          <th scope="col">File Size</th>
+          <th scope="col">Downloaded</th>
+          <th scope="col" style="width: 8rem;"></th>
+        </tr>
+      </thead>
+      <tbody>
+        @for (entry of cachedSortedDone; track entry[1].id) {
+          <tr [class.disabled]='entry[1].deleting'>
+            <td>
+              <app-item-checkbox [id]="entry[0]" [master]="doneMasterCheckboxRef" [checkable]="entry[1]" />
+            </td>
+            <td>
+              <div style="display: inline-block; width: 1.5rem;">
+                @if (entry[1].status === 'finished') {
+                  <fa-icon [icon]="faCheckCircle" class="text-success" />
+                }
+                @if (entry[1].status === 'error') {
+                  <button type="button" class="btn btn-link p-0"
+                    (click)="toggleErrorDetail(entry[0])"
+                    [attr.aria-label]="'Toggle error details for ' + entry[1].title"
+                    [attr.aria-expanded]="isErrorExpanded(entry[0])">
+                    <fa-icon [icon]="faTimesCircle" class="text-danger" />
+                  </button>
+                }
+              </div>
+              <span ngbTooltip="{{buildResultItemTooltip(entry[1])}}">@if (!!entry[1].filename) {
+                <a href="{{buildDownloadLink(entry[1])}}" target="_blank">{{ entry[1].title }}</a>
+              } @else {
+                @if (entry[1].status === 'error') {
+                  <button type="button" class="btn btn-link p-0 text-start align-baseline" (click)="toggleErrorDetail(entry[0])">
+                    {{entry[1].title}}
+                    @if (!isErrorExpanded(entry[0])) {
+                      <small class="text-danger ms-2">
+                        <fa-icon [icon]="faChevronRight" size="xs" class="me-1" />Click for details
+                      </small>
+                    }
+                  </button>
+                } @else {
+                  <span>{{entry[1].title}}</span>
+                }
+              }</span>
+              @if (entry[1].status === 'error' && isErrorExpanded(entry[0])) {
+                <div class="alert alert-danger py-2 px-3 mt-2 mb-0 small" style="border-left: 4px solid var(--bs-danger);">
+                  <div class="d-flex justify-content-between align-items-start">
+                    <div class="flex-grow-1">
+                      @if (entry[1].msg) {
+                        <div class="mb-1"><strong>Message:</strong> {{entry[1].msg}}</div>
+                      }
+                      @if (entry[1].error) {
+                        <div class="mb-1"><strong>Error:</strong> {{entry[1].error}}</div>
+                      }
+                      <div class="text-muted" style="word-break: break-all;"><strong>URL:</strong> {{entry[1].url}}</div>
+                    </div>
+                    <button type="button" class="btn btn-sm btn-outline-danger ms-2 flex-shrink-0"
+                      (click)="copyErrorMessage(entry[0], entry[1]); $event.stopPropagation()"
+                      ngbTooltip="Copy error details to clipboard">
+                      @if (lastCopiedErrorId === entry[0]) {
+                        <span class="text-success">Copied!</span>
+                      } @else {
+                        <fa-icon [icon]="faCopy" />
+                      }
+                    </button>
+                  </div>
+                </div>
+              }
+            </td>
+            <td class="text-nowrap">
+              {{ downloadTypeLabel(entry[1]) }}
+            </td>
+            <td class="text-nowrap">
+              {{ formatQualityLabel(entry[1]) }}
+            </td>
+            <td class="text-nowrap">
+              {{ formatCodecLabel(entry[1]) }}
+            </td>
+            <td>
+              @if (entry[1].size) {
+                <span>{{ entry[1].size | fileSize }}</span>
+              }
+            </td>
+            <td class="text-nowrap">
+              @if (entry[1].timestamp) {
+                <span>{{ entry[1].timestamp / 1000000 | date:'yyyy-MM-dd HH:mm' }}</span>
+              }
+            </td>
+            <td>
+              <div class="d-flex">
+                @if (entry[1].status === 'error') {
+                  <button type="button" class="btn btn-link" [attr.aria-label]="'Retry download for ' + entry[1].title" (click)="retryDownload(entry[0], entry[1])"><fa-icon [icon]="faRedoAlt" /></button>
+                }
+                @if (entry[1].filename) {
+                  <a href="{{buildDownloadLink(entry[1])}}" download class="btn btn-link" [attr.aria-label]="'Download result file for ' + entry[1].title"><fa-icon [icon]="faDownload" /></a>
+                }
+                <a href="{{entry[1].url}}" target="_blank" class="btn btn-link" [attr.aria-label]="'Open source URL for ' + entry[1].title"><fa-icon [icon]="faExternalLinkAlt" /></a>
+                <button type="button" class="btn btn-link" [attr.aria-label]="'Delete completed item ' + entry[1].title" (click)="delDownload('done', entry[0])"><fa-icon [icon]="faTrashAlt" /></button>
+              </div>
+            </td>
+          </tr>
+        @if (entry[1].chapter_files && entry[1].chapter_files.length > 0) {
+          @for (chapterFile of entry[1].chapter_files; track chapterFile.filename) {
+            <tr [class.disabled]='entry[1].deleting'>
+              <td></td>
+              <td>
+                <div style="padding-left: 2rem;">
+              <fa-icon [icon]="faCheckCircle" class="text-success me-2" />
+              <a href="{{buildChapterDownloadLink(entry[1], chapterFile.filename)}}" target="_blank" [attr.aria-label]="'Open chapter file ' + getChapterFileName(chapterFile.filename)">{{
+                getChapterFileName(chapterFile.filename) }}</a>
+            </div>
+          </td>
+          <td></td>
+          <td></td>
+          <td></td>
+          <td>
+            @if (chapterFile.size) {
+            <span>{{ chapterFile.size | fileSize }}</span>
+            }
+          </td>
+          <td></td>
+          <td>
+            <div class="d-flex">
+              <a href="{{buildChapterDownloadLink(entry[1], chapterFile.filename)}}" download [attr.aria-label]="'Download chapter file ' + getChapterFileName(chapterFile.filename)"
+                class="btn btn-link"><fa-icon [icon]="faDownload" /></a>
+            </div>
+          </td>
+        </tr>
+        }
+      }
+    }
+      </tbody>
+    </table>
+  </div>
+
+  <div class="metube-section-header">Subscriptions</div>
+  <div class="px-2 py-3 border-bottom">
+    @if (checkingAllSubscriptions) {
+      <button type="button" class="btn btn-link text-decoration-none px-0 me-4" disabled>
+        <span class="spinner-border spinner-border-sm me-2" role="status" aria-hidden="true"></span>Check all now
+      </button>
+    } @else {
+      <button type="button" class="btn btn-link text-decoration-none px-0 me-4"
+        (click)="checkAllSubscriptions()"
+        [disabled]="downloads.loading || cachedSubs.length === 0 || checkingSelectedSubscriptions">
+        <fa-icon [icon]="faRedoAlt" />&nbsp; Check all now
+      </button>
+    }
+    @if (checkingSelectedSubscriptions) {
+      <button type="button" class="btn btn-link text-decoration-none px-0 me-4" disabled>
+        <span class="spinner-border spinner-border-sm me-2" role="status" aria-hidden="true"></span>Check selected
+      </button>
+    } @else {
+      <button type="button" class="btn btn-link text-decoration-none px-0 me-4"
+        (click)="checkSelectedSubscriptions()"
+        [disabled]="downloads.loading || selectedSubscriptionIds.size === 0 || checkingAllSubscriptions">
+        <fa-icon [icon]="faRedoAlt" />&nbsp; Check selected
+      </button>
+    }
+    <button type="button" class="btn btn-link text-decoration-none px-0 me-4"
+      (click)="deleteSelectedSubscriptions()"
+      [disabled]="downloads.loading || selectedSubscriptionIds.size === 0">
+      <fa-icon [icon]="faTrashAlt" />&nbsp; Delete selected
+    </button>
+  </div>
+  <div class="overflow-auto">
+    <table class="table">
+      <thead>
+        <tr>
+          <th scope="col" style="width: 1rem;">
+            <input type="checkbox" class="form-check-input"
+              [checked]="allSubsSelected()"
+              (change)="toggleSubMaster($event)"
+              [disabled]="downloads.loading || cachedSubs.length === 0"
+              aria-label="Select all subscriptions" />
+          </th>
+          <th scope="col">Name</th>
+          <th scope="col">URL</th>
+          <th scope="col" class="text-nowrap">Interval (min)</th>
+          <th scope="col" class="text-nowrap">Last checked</th>
+          <th scope="col">Status</th>
+          <th scope="col" style="width: 8rem;"></th>
+        </tr>
+      </thead>
+      <tbody>
+        @for (entry of cachedSubs; track entry[0]) {
+          <tr>
+            <td>
+              <input type="checkbox" class="form-check-input"
+                [checked]="isSubSelected(entry[0])"
+                (change)="toggleSubSelected(entry[0])"
+                [disabled]="downloads.loading"
+                [attr.aria-label]="'Select subscription ' + entry[1].name" />
+            </td>
+            <td>{{ entry[1].name }}</td>
+            <td class="text-break"><a [href]="entry[1].url" target="_blank" rel="noopener">{{ entry[1].url }}</a></td>
+            <td>{{ entry[1].check_interval_minutes }}</td>
+            <td class="text-nowrap">
+              @if (entry[1].last_checked !== null) {
+                <span>{{ entry[1].last_checked! * 1000 | date:'yyyy-MM-dd HH:mm:ss' }}</span>
+              } @else {
+                <span class="text-muted">—</span>
+              }
+            </td>
+            <td>
+              @if (entry[1].error) {
+                <span class="text-danger small">{{ entry[1].error }}</span>
+              } @else if (entry[1].enabled) {
+                <span class="text-success">Active</span>
+              } @else {
+                <span class="text-secondary">Paused</span>
+              }
+            </td>
+            <td>
+              <div class="d-flex flex-wrap gap-1">
+                @if (isSubscriptionChecking(entry[0])) {
+                  <button type="button" class="btn btn-link btn-sm p-0 me-2"
+                    disabled
+                    [attr.aria-label]="'Checking ' + entry[1].name"
+                    ngbTooltip="Checking now">
+                    <span class="spinner-border spinner-border-sm" role="status" aria-hidden="true"></span>
+                  </button>
+                } @else {
+                  <button type="button" class="btn btn-link btn-sm p-0 me-2"
+                    (click)="checkSubscriptionNow(entry[0])"
+                    [disabled]="downloads.loading"
+                    [attr.aria-label]="'Check now ' + entry[1].name"
+                    ngbTooltip="Check now">
+                    <fa-icon [icon]="faRedoAlt" />
+                  </button>
+                }
+                <button type="button" class="btn btn-link btn-sm p-0 me-2"
+                  (click)="toggleSubscriptionEnabled(entry[1])"
+                  [disabled]="downloads.loading"
+                  [attr.aria-label]="(entry[1].enabled ? 'Pause ' : 'Resume ') + entry[1].name"
+                  [ngbTooltip]="entry[1].enabled ? 'Pause' : 'Resume'">
+                  @if (entry[1].enabled) {
+                    <fa-icon [icon]="faPause" />
+                  } @else {
+                    <fa-icon [icon]="faPlay" />
+                  }
+                </button>
+                <button type="button" class="btn btn-link btn-sm p-0 text-danger"
+                  (click)="deleteSubscription(entry[0])"
+                  [disabled]="downloads.loading"
+                  [attr.aria-label]="'Delete subscription ' + entry[1].name">
+                  <fa-icon [icon]="faTrashAlt" />
+                </button>
+              </div>
+            </td>
+          </tr>
+        }
+      </tbody>
+    </table>
+  </div>
+</main><!-- /.container -->
+
+<footer class="footer navbar-dark bg-dark py-3 mt-5">
+  <div class="container text-center">
+    @if (ytDlpVersion && metubeVersion) {
+      <div class="footer-content">
+        <div class="version-item">
+          <span class="version-label">yt-dlp</span>
+          <span class="version-value">{{ytDlpVersion}}</span>
+        </div>
+        <div class="version-separator"></div>
+        <div class="version-item">
+          <span class="version-label">MeTube</span>
+          <span class="version-value">{{metubeVersion}}</span>
+        </div>
+        <div class="version-separator"></div>
+        @if (ytDlpOptionsUpdateTime) {
+          <div class="version-item">
+            <span class="version-label">yt-dlp-options</span>
+            <span class="version-value">{{ytDlpOptionsUpdateTime}}</span>
+          </div>
+        }
+        @if (ytDlpOptionsUpdateTime) {
+          <div class="version-separator"></div>
+        }
+        <a href="https://github.com/alexta69/metube" target="_blank" class="github-link">
+          <fa-icon [icon]="faGithub" />
+          <span>GitHub</span>
+        </a>
+      </div>
+    }
+  </div>
+</footer>

ui/src/app/app.module.ts

@@ -1,36 +0,0 @@
-import { BrowserModule } from '@angular/platform-browser';
-import { NgModule, isDevMode } from '@angular/core';
-import { FormsModule } from '@angular/forms';
-import { NgbModule } from '@ng-bootstrap/ng-bootstrap';
-import { provideHttpClient, withInterceptorsFromDi } from '@angular/common/http';
-import { FontAwesomeModule } from '@fortawesome/angular-fontawesome';
-import { CookieService } from 'ngx-cookie-service';
-
-import { AppComponent } from './app.component';
-import { EtaPipe, SpeedPipe, EncodeURIComponent, FileSizePipe } from './downloads.pipe';
-import { MasterCheckboxComponent, SlaveCheckboxComponent } from './master-checkbox.component';
-import { MeTubeSocket } from './metube-socket';
-import { NgSelectModule } from '@ng-select/ng-select';
-import { ServiceWorkerModule } from '@angular/service-worker';
-
-@NgModule({ declarations: [
-        AppComponent,
-        EtaPipe,
-        SpeedPipe,
-        FileSizePipe,
-        EncodeURIComponent,
-        MasterCheckboxComponent,
-        SlaveCheckboxComponent
-    ],
-    bootstrap: [AppComponent], imports: [BrowserModule,
-        FormsModule,
-        NgbModule,
-        FontAwesomeModule,
-        NgSelectModule,
-        ServiceWorkerModule.register('custom-service-worker.js', {
-            enabled: !isDevMode(),
-            // Register the ServiceWorker as soon as the application is stable
-            // or after 30 seconds (whichever comes first).
-            registrationStrategy: 'registerWhenStable:30000'
-        })], providers: [CookieService, MeTubeSocket, provideHttpClient(withInterceptorsFromDi())] })
-export class AppModule { }

ui/src/app/app.sass

@@ -1,211 +1,210 @@
-.button-toggle-theme:focus, .button-toggle-theme:active
-    box-shadow: none
-    outline: 0px
-
-.add-url-box
-    max-width: 960px
-    margin: 4rem auto
-
-.add-url-component
-    margin: 0.5rem auto
-
-.add-url-group
-    width: 100%
-
-button.add-url
-    width: 100%
-
-.folder-dropdown-menu
-    width: 500px
-    max-width: calc(100vw - 3rem)
-
-.folder-dropdown-menu .input-group
-    display: flex
-    padding-left: 5px
-    padding-right: 5px
-
-.metube-section-header
-    font-size: 1.8rem
-    font-weight: 300
-    position: relative
-    background: var(--bs-secondary-bg)
-    padding: 0.5rem 0
-    margin-top: 3.5rem
-
-.metube-section-header:before
-    content: ""
-    position: absolute
-    top: 0
-    bottom: 0
-    left: -9999px
-    right: 0
-    border-left: 9999px solid var(--bs-secondary-bg)
-    box-shadow: 9999px 0 0 var(--bs-secondary-bg)
-
-button:hover
-    text-decoration: none
-
-th
-    border-top: 0
-    border-bottom-width: 3px !important
-    vertical-align: middle !important
-    white-space: nowrap
-
-td
-    vertical-align: middle
-
-.disabled
-    opacity: 0.5
-    pointer-events: none
-
-.form-switch
-  input
-    margin-top: 5px
-
-.download-progressbar
-    width: 12rem
-    margin-left: auto
-
-.batch-panel
-  margin-top: 15px
-  border: 1px solid #ccc
-  border-radius: 8px
-  padding: 15px
-  background-color: #fff
-  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1)
-
-.batch-panel-header
-  border-bottom: 1px solid #eee
-  padding-bottom: 8px
-  margin-bottom: 15px
-  h4
-    font-size: 1.5rem
-    margin: 0
-
-.batch-panel-body
-  textarea.form-control
-    resize: vertical
-
-.batch-status
-  font-size: 0.9rem
-  color: #555
-
-.d-flex.my-3
-  margin-top: 1rem
-  margin-bottom: 1rem
-
-.modal.fade.show
-  background-color: rgba(0, 0, 0, 0.5)
-
-.modal-header
-  border-bottom: 1px solid #eee
-
-.modal-body
-  textarea.form-control
-    resize: vertical
-
-.add-url
-  display: inline-flex
-  align-items: center
-  justify-content: center
-
-  .spinner-border
-    margin-right: 0.5rem
-
-::ng-deep .ng-select
-    flex: 1
-    .ng-select-container
-        min-height: 38px
-    .ng-value
-        white-space: nowrap
-        overflow: visible
-    .ng-dropdown-panel
-        .ng-dropdown-panel-items
-            max-height: 300px
-            .ng-option
-                white-space: nowrap
-                overflow: visible
-                text-overflow: ellipsis
-
-:host
-  display: flex
-  flex-direction: column
-  min-height: 100vh
-
-main
-  flex-grow: 1
-
-.footer
-  width: 100%
-  padding: 10px 0
-  background: linear-gradient(to bottom, rgba(0,0,0,0.2), rgba(0,0,0,0.1))
-
-  .footer-content
-    display: flex
-    justify-content: center
-    align-items: center
-    gap: 20px
-    color: #fff
-    font-size: 0.9rem
-
-    .version-item
-      display: flex
-      align-items: center
-      gap: 8px
-
-      .version-label
-        font-size: 0.75rem
-        text-transform: uppercase
-        letter-spacing: 0.5px
-        opacity: 0.7
-
-      .version-value
-        font-family: monospace
-        font-size: 0.85rem
-        padding: 2px 6px
-        background: rgba(255,255,255,0.1)
-        border-radius: 4px
-
-    .version-separator
-      width: 1px
-      height: 16px
-      background: rgba(255,255,255,0.2)
-      margin: 0 4px
-
-    .github-link
-      display: flex
-      align-items: center
-      gap: 6px
-      color: #fff
-      text-decoration: none
-      font-size: 0.85rem
-      padding: 2px 8px
-      border-radius: 4px
-      transition: background-color 0.2s ease
-
-      &:hover
-        background: rgba(255,255,255,0.1)
-        color: #fff
-        text-decoration: none
-
-      i
-        font-size: 1rem
-
-.download-metrics
-  display: flex
-  align-items: center
-  gap: 16px
-  margin-left: 24px
-
-  .metric
-    display: flex
-    align-items: center
-    gap: 6px
-    font-size: 0.9rem
-    color: #adb5bd
-
-    fa-icon
-      font-size: 1rem
-
-    span
-      white-space: nowrap
+.add-url-box
+    max-width: 960px
+    margin: 4rem auto
+
+.metube-section-header
+    font-size: 1.8rem
+    font-weight: 300
+    position: relative
+    background: var(--bs-secondary-bg)
+    padding: 0.5rem 0
+    margin-top: 3.5rem
+
+.metube-section-header:before
+    content: ""
+    position: absolute
+    top: 0
+    bottom: 0
+    left: -9999px
+    right: 0
+    border-left: 9999px solid var(--bs-secondary-bg)
+    box-shadow: 9999px 0 0 var(--bs-secondary-bg)
+
+button:hover
+    text-decoration: none
+
+th
+    border-top: 0
+    border-bottom-width: 3px !important
+    vertical-align: middle !important
+    white-space: nowrap
+
+td
+    vertical-align: middle
+
+.disabled
+    opacity: 0.5
+    pointer-events: none
+
+.form-switch
+  input
+    margin-top: 5px
+
+.download-progressbar
+    width: 12rem
+    margin-left: auto
+
+.modal.fade.show
+  background-color: rgba(0, 0, 0, 0.5)
+
+.modal-header
+  border-bottom: 1px solid var(--bs-border-color)
+
+.modal-body
+  textarea.form-control
+    resize: vertical
+
+.add-url
+  display: inline-flex
+  align-items: center
+  justify-content: center
+
+  .spinner-border
+    margin-right: 0.5rem
+
+.add-progress-btn
+  min-width: 9.5rem
+  cursor: default
+
+.add-cancel-btn
+  min-width: 3.25rem
+
+:host
+  display: flex
+  flex-direction: column
+  min-height: 100vh
+
+main
+  flex-grow: 1
+
+.footer
+  width: 100%
+  padding: 10px 0
+  background: linear-gradient(to bottom, rgba(0,0,0,0.2), rgba(0,0,0,0.1))
+
+  .footer-content
+    display: flex
+    justify-content: center
+    align-items: center
+    gap: 20px
+    color: #fff
+    font-size: 0.9rem
+
+    .version-item
+      display: flex
+      align-items: center
+      gap: 8px
+
+      .version-label
+        font-size: 0.75rem
+        text-transform: uppercase
+        letter-spacing: 0.5px
+        opacity: 0.7
+
+      .version-value
+        font-family: monospace
+        font-size: 0.85rem
+        padding: 2px 6px
+        background: rgba(255,255,255,0.1)
+        border-radius: 4px
+
+    .version-separator
+      width: 1px
+      height: 16px
+      background: rgba(255,255,255,0.2)
+      margin: 0 4px
+
+    .github-link
+      display: flex
+      align-items: center
+      gap: 6px
+      color: #fff
+      text-decoration: none
+      font-size: 0.85rem
+      padding: 2px 8px
+      border-radius: 4px
+      transition: background-color 0.2s ease
+
+      &:hover
+        background: rgba(255,255,255,0.1)
+        color: #fff
+        text-decoration: none
+
+      i
+        font-size: 1rem
+
+.download-metrics
+  display: flex
+  align-items: center
+  gap: 16px
+  margin-left: 24px
+
+  .metric
+    display: flex
+    align-items: center
+    gap: 6px
+    font-size: 0.9rem
+    color: #adb5bd
+
+    fa-icon
+      font-size: 1rem
+
+    span
+      white-space: nowrap
+
+.cookie-btn
+  flex: 1 1 auto
+  background-color: var(--bs-secondary-bg)
+  border-color: var(--bs-border-color)
+  color: var(--bs-emphasis-color)
+
+  &:hover
+    background-color: var(--bs-tertiary-bg)
+    border-color: var(--bs-secondary)
+    color: var(--bs-emphasis-color)
+
+  &.disabled
+    opacity: 0.65
+    pointer-events: none
+
+.cookie-active-btn
+  flex: 1 1 auto
+  background-color: var(--bs-success-bg-subtle)
+  border-color: var(--bs-success-border-subtle)
+  color: var(--bs-success-text-emphasis)
+
+  &:hover
+    background-color: var(--bs-success-bg-subtle)
+    border-color: var(--bs-success)
+    color: var(--bs-success-text-emphasis)
+
+  &.disabled
+    opacity: 0.65
+    pointer-events: none
+
+.settings-section-label
+  font-size: 0.8rem
+  text-transform: uppercase
+  letter-spacing: 0.1em
+  font-weight: 600
+  color: var(--bs-body-color)
+  margin-top: 1.75rem
+  margin-bottom: 0.75rem
+
+  &:first-child
+    margin-top: 0
+
+.action-group-label
+  font-size: 0.7rem
+  text-transform: uppercase
+  letter-spacing: 0.05em
+  color: var(--bs-secondary-color)
+  margin-bottom: 0.4rem
+
+.cookie-status
+  font-size: 0.8rem
+  margin-top: 0.35rem
+  color: var(--bs-secondary-color)
+
+  &.active
+    color: var(--bs-success-text-emphasis)

ui/src/app/app.spec.ts

@@ -0,0 +1,178 @@
+import { TestBed } from '@angular/core/testing';
+import { HttpClient } from '@angular/common/http';
+import { Subject, of } from 'rxjs';
+import { App } from './app';
+import { DownloadsService } from './services/downloads.service';
+import { SubscriptionsService } from './services/subscriptions.service';
+import { CookieService } from 'ngx-cookie-service';
+
+class DownloadsServiceStub {
+  loading = false;
+  queue = new Map();
+  done = new Map();
+  configuration: Record<string, unknown> = { CUSTOM_DIRS: true, CREATE_CUSTOM_DIRS: true, ALLOW_YTDL_OPTIONS_OVERRIDES: false };
+  customDirs = { download_dir: [], audio_download_dir: [] };
+  queueChanged = new Subject<void>();
+  doneChanged = new Subject<void>();
+  configurationChanged = new Subject<Record<string, unknown>>();
+  customDirsChanged = new Subject<Record<string, string[]>>();
+  ytdlOptionsChanged = new Subject<Record<string, unknown>>();
+  updated = new Subject<void>();
+
+  getCookieStatus() {
+    return of({ status: 'ok', has_cookies: false });
+  }
+
+  getPresets() {
+    return of({ presets: ['Preset A'] });
+  }
+
+  add() {
+    return of({ status: 'ok' as const });
+  }
+
+  cancelAdd() {
+    return of({ status: 'ok' as const });
+  }
+
+  startById() {
+    return of({});
+  }
+
+  delById() {
+    return of({});
+  }
+
+  delByFilter() {
+    return of({});
+  }
+
+  startByFilter() {
+    return of({});
+  }
+
+  uploadCookies() {
+    return of({ status: 'ok' });
+  }
+
+  deleteCookies() {
+    return of({ status: 'ok' });
+  }
+}
+
+class SubscriptionsServiceStub {
+  subscriptions = new Map();
+  subscriptionsChanged = new Subject<void>();
+
+  subscribe() {
+    return of({ status: 'ok' as const });
+  }
+
+  delete() {
+    return of({});
+  }
+
+  refreshList() {
+    return of([]);
+  }
+}
+
+class CookieServiceStub {
+  private cookies = new Map<string, string>();
+
+  get(name: string) {
+    return this.cookies.get(name) ?? '';
+  }
+
+  set(name: string, value: string) {
+    this.cookies.set(name, value);
+  }
+
+  check(name: string) {
+    return this.cookies.has(name);
+  }
+}
+
+describe('App', () => {
+  let downloads: DownloadsServiceStub;
+
+  beforeEach(async () => {
+    Object.defineProperty(window, 'matchMedia', {
+      writable: true,
+      enumerable: true,
+      value: vi.fn().mockImplementation((query: string) => ({
+        matches: false,
+        media: query,
+        onchange: null,
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+        dispatchEvent: vi.fn(),
+      })),
+    });
+    downloads = new DownloadsServiceStub();
+    await TestBed.configureTestingModule({
+      imports: [App],
+      providers: [
+        { provide: DownloadsService, useValue: downloads },
+        { provide: SubscriptionsService, useClass: SubscriptionsServiceStub },
+        { provide: CookieService, useClass: CookieServiceStub },
+        {
+          provide: HttpClient,
+          useValue: {
+            get: vi.fn().mockReturnValue(of({ 'yt-dlp': 'test', version: 'test' })),
+          },
+        },
+      ],
+    }).compileComponents();
+  });
+
+  it('should create the app', () => {
+    const fixture = TestBed.createComponent(App);
+    const app = fixture.componentInstance;
+    expect(app).toBeTruthy();
+  });
+
+  it('hides manual override input when disabled', () => {
+    const fixture = TestBed.createComponent(App);
+    fixture.componentInstance.isAdvancedOpen = true;
+    fixture.detectChanges();
+
+    const root = fixture.nativeElement as HTMLElement;
+    expect(root.querySelector('input[name="ytdlOptionsOverrides"]')).toBeNull();
+
+    const presetWrapper = root.querySelector('ng-select[name="ytdlOptionsPresets"]')?.closest('.col-12');
+    expect(presetWrapper?.classList.contains('col-md-6')).toBe(false);
+
+    const presetRow = root.querySelector('ng-select[name="ytdlOptionsPresets"]')?.closest('.row');
+    expect(presetRow?.querySelector('input[name="checkIntervalMinutes"]')).toBeNull();
+  });
+
+  it('shows manual override input when enabled', () => {
+    downloads.configuration['ALLOW_YTDL_OPTIONS_OVERRIDES'] = true;
+
+    const fixture = TestBed.createComponent(App);
+    fixture.componentInstance.isAdvancedOpen = true;
+    fixture.detectChanges();
+
+    const root = fixture.nativeElement as HTMLElement;
+    expect(root.querySelector('input[name="ytdlOptionsOverrides"]')).not.toBeNull();
+
+    const presetWrapper = root.querySelector('ng-select[name="ytdlOptionsPresets"]')?.closest('.col-12');
+    expect(presetWrapper?.classList.contains('col-md-6')).toBe(true);
+
+    const presetRow = root.querySelector('ng-select[name="ytdlOptionsPresets"]')?.closest('.row');
+    expect(presetRow?.querySelector('input[name="checkIntervalMinutes"]')).toBeNull();
+    expect(presetRow?.querySelector('input[name="ytdlOptionsOverrides"]')).not.toBeNull();
+  });
+
+  it('does not submit manual overrides when disabled', () => {
+    const fixture = TestBed.createComponent(App);
+    const app = fixture.componentInstance;
+
+    app.ytdlOptionsOverrides = '{"exec":"echo hi"}';
+
+    const payload = app['buildAddPayload']();
+
+    expect(payload.ytdlOptionsOverrides).toBe('');
+  });
+});

ui/src/app/components/index.ts

@@ -0,0 +1,2 @@
+export { SelectAllCheckboxComponent } from './master-checkbox.component';
+export { ItemCheckboxComponent } from './slave-checkbox.component';

ui/src/app/components/master-checkbox.component.spec.ts

@@ -0,0 +1,23 @@
+import { TestBed } from '@angular/core/testing';
+import { SelectAllCheckboxComponent } from './master-checkbox.component';
+import { Checkable } from '../interfaces';
+
+describe('SelectAllCheckboxComponent', () => {
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [SelectAllCheckboxComponent],
+    }).compileComponents();
+  });
+
+  it('clicked sets checked on all list items', () => {
+    const fixture = TestBed.createComponent(SelectAllCheckboxComponent);
+    const list = new Map<string, Checkable>();
+    list.set('u1', { checked: false });
+    fixture.componentRef.setInput('id', 'queue');
+    fixture.componentRef.setInput('list', list);
+    fixture.componentInstance.selected = true;
+    fixture.detectChanges();
+    fixture.componentInstance.clicked();
+    expect(list.get('u1')?.checked).toBe(true);
+  });
+});

ui/src/app/components/master-checkbox.component.ts

@@ -0,0 +1,40 @@
+import { Component, ElementRef, viewChild, output, input } from "@angular/core";
+import { Checkable } from "../interfaces";
+import { FormsModule } from "@angular/forms";
+
+@Component({
+    selector: 'app-select-all-checkbox',
+    template: `
+  <div class="form-check">
+    <input type="checkbox" class="form-check-input" id="{{id()}}-select-all" #masterCheckbox [(ngModel)]="selected" (change)="clicked()" [attr.aria-label]="'Select all ' + id() + ' items'">
+    <label class="form-check-label visually-hidden" for="{{id()}}-select-all">Select all</label>
+  </div>
+`,
+imports: [
+  FormsModule
+]
+})
+export class SelectAllCheckboxComponent {
+  readonly id = input.required<string>();
+  readonly list = input.required<Map<string, Checkable>>();
+  readonly changed = output<number>();
+
+  readonly masterCheckbox = viewChild.required<ElementRef>('masterCheckbox');
+  selected!: boolean;
+
+  clicked() {
+    this.list().forEach(item => item.checked = this.selected);
+    this.selectionChanged();
+  }
+
+  selectionChanged() {
+    const masterCheckbox = this.masterCheckbox();
+    if (!masterCheckbox)
+      return;
+    let checked = 0;
+    this.list().forEach(item => { if(item.checked) checked++ });
+    this.selected = checked > 0 && checked === this.list().size;
+    masterCheckbox.nativeElement.indeterminate = checked > 0 && checked < this.list().size;
+    this.changed.emit(checked);
+  }
+}

ui/src/app/components/slave-checkbox.component.spec.ts

@@ -0,0 +1,25 @@
+import { TestBed } from '@angular/core/testing';
+import { SelectAllCheckboxComponent } from './master-checkbox.component';
+import { ItemCheckboxComponent } from './slave-checkbox.component';
+
+describe('ItemCheckboxComponent', () => {
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [ItemCheckboxComponent, SelectAllCheckboxComponent],
+    }).compileComponents();
+  });
+
+  it('creates with master and checkable inputs', () => {
+    const masterFixture = TestBed.createComponent(SelectAllCheckboxComponent);
+    masterFixture.componentRef.setInput('id', 'q');
+    masterFixture.componentRef.setInput('list', new Map());
+    masterFixture.detectChanges();
+
+    const itemFixture = TestBed.createComponent(ItemCheckboxComponent);
+    itemFixture.componentRef.setInput('id', 'row1');
+    itemFixture.componentRef.setInput('master', masterFixture.componentInstance);
+    itemFixture.componentRef.setInput('checkable', { checked: false });
+    itemFixture.detectChanges();
+    expect(itemFixture.componentInstance).toBeTruthy();
+  });
+});

ui/src/app/components/slave-checkbox.component.ts

@@ -0,0 +1,22 @@
+import { Component, input } from '@angular/core';
+import { SelectAllCheckboxComponent } from './master-checkbox.component';
+import { Checkable } from '../interfaces';
+import { FormsModule } from '@angular/forms';
+
+@Component({
+    selector: 'app-item-checkbox',
+    template: `
+  <div class="form-check">
+    <input type="checkbox" class="form-check-input" id="{{master().id()}}-{{id()}}-select" [(ngModel)]="checkable().checked" (change)="master().selectionChanged()" [attr.aria-label]="'Select item ' + id()">
+    <label class="form-check-label visually-hidden" for="{{master().id()}}-{{id()}}-select">Select item</label>
+  </div>
+`,
+imports: [  
+  FormsModule
+]
+})
+export class ItemCheckboxComponent {
+  readonly id = input.required<string>();
+  readonly master = input.required<SelectAllCheckboxComponent>();
+  readonly checkable = input.required<Checkable>();
+}

ui/src/app/downloads.pipe.ts

@@ -1,93 +0,0 @@
-import { Pipe, PipeTransform } from '@angular/core';
-import { SpeedService } from './speed.service';
-import { BehaviorSubject } from 'rxjs';
-import { throttleTime } from 'rxjs/operators';
-
-@Pipe({
-    name: 'eta',
-    standalone: false
-})
-export class EtaPipe implements PipeTransform {
-  transform(value: number, ...args: any[]): any {
-    if (value === null) {
-      return null;
-    }
-    if (value < 60) {
-      return `${Math.round(value)}s`;
-    }
-    if (value < 3600) {
-      return `${Math.floor(value/60)}m ${Math.round(value%60)}s`;
-    }
-    const hours = Math.floor(value/3600)
-    const minutes = value % 3600
-    return `${hours}h ${Math.floor(minutes/60)}m ${Math.round(minutes%60)}s`;
-  }
-}
-
-@Pipe({
-    name: 'speed',
-    standalone: false,
-    pure: false // Make the pipe impure so it can handle async updates
-})
-export class SpeedPipe implements PipeTransform {
-  private speedSubject = new BehaviorSubject<number>(0);
-  private formattedSpeed: string = '';
-
-  constructor(private speedService: SpeedService) {
-    // Throttle updates to once per second
-    this.speedSubject.pipe(
-      throttleTime(1000)
-    ).subscribe(speed => {
-      // If speed is invalid or 0, return empty string
-      if (speed === null || speed === undefined || isNaN(speed) || speed <= 0) {
-        this.formattedSpeed = '';
-        return;
-      }
-      
-      const k = 1024;
-      const dm = 2;
-      const sizes = ['B/s', 'KB/s', 'MB/s', 'GB/s', 'TB/s', 'PB/s', 'EB/s', 'ZB/s', 'YB/s'];
-      const i = Math.floor(Math.log(speed) / Math.log(k));
-      this.formattedSpeed = parseFloat((speed / Math.pow(k, i)).toFixed(dm)) + ' ' + sizes[i];
-    });
-  }
-
-  transform(value: number, ...args: any[]): any {
-    // If speed is invalid or 0, return empty string
-    if (value === null || value === undefined || isNaN(value) || value <= 0) {
-      return '';
-    }
-    
-    // Update the speed subject
-    this.speedSubject.next(value);
-    
-    // Return the last formatted speed
-    return this.formattedSpeed;
-  }
-}
-
-@Pipe({
-    name: 'encodeURIComponent',
-    standalone: false
-})
-export class EncodeURIComponent implements PipeTransform {
-  transform(value: string, ...args: any[]): any {
-    return encodeURIComponent(value);
-  }
-}
-
-@Pipe({
-    name: 'fileSize',
-    standalone: false
-})
-export class FileSizePipe implements PipeTransform {
-  transform(value: number): string {
-      if (isNaN(value) || value === 0) return '0 Bytes';
-
-      const units = ['Bytes', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'];
-      const unitIndex = Math.floor(Math.log(value) / Math.log(1000)); // Use 1000 for common units
-
-      const unitValue = value / Math.pow(1000, unitIndex);
-      return `${unitValue.toFixed(2)} ${units[unitIndex]}`;
-  }
-}

ui/src/app/downloads.service.ts

@@ -1,161 +0,0 @@
-import { Injectable } from '@angular/core';
-import { HttpClient, HttpErrorResponse } from '@angular/common/http';
-import { Observable, of, Subject } from 'rxjs';
-import { catchError } from 'rxjs/operators';
-import { MeTubeSocket } from './metube-socket';
-
-export interface Status {
-  status: string;
-  msg?: string;
-}
-
-export interface Download {
-  id: string;
-  title: string;
-  url: string;
-  quality: string;
-  format: string;
-  folder: string;
-  custom_name_prefix: string;
-  playlist_strict_mode: boolean;
-  playlist_item_limit: number;
-  status: string;
-  msg: string;
-  percent: number;
-  speed: number;
-  eta: number;
-  filename: string;
-  checked?: boolean;
-  deleting?: boolean;
-}
-
-@Injectable({
-  providedIn: 'root'
-})
-export class DownloadsService {
-  loading = true;
-  queue = new Map<string, Download>();
-  done = new Map<string, Download>();
-  queueChanged = new Subject();
-  doneChanged = new Subject();
-  customDirsChanged = new Subject();
-  ytdlOptionsChanged = new Subject();
-  configurationChanged = new Subject();
-  updated = new Subject();
-
-  configuration = {};
-  customDirs = {};
-
-  constructor(private http: HttpClient, private socket: MeTubeSocket) {
-    socket.fromEvent('all').subscribe((strdata: string) => {
-      this.loading = false;
-      let data: [[[string, Download]], [[string, Download]]] = JSON.parse(strdata);
-      this.queue.clear();
-      data[0].forEach(entry => this.queue.set(...entry));
-      this.done.clear();
-      data[1].forEach(entry => this.done.set(...entry));
-      this.queueChanged.next(null);
-      this.doneChanged.next(null);
-    });
-    socket.fromEvent('added').subscribe((strdata: string) => {
-      let data: Download = JSON.parse(strdata);
-      this.queue.set(data.url, data);
-      this.queueChanged.next(null);
-    });
-    socket.fromEvent('updated').subscribe((strdata: string) => {
-      let data: Download = JSON.parse(strdata);
-      let dl: Download = this.queue.get(data.url);
-      data.checked = dl.checked;
-      data.deleting = dl.deleting;
-      this.queue.set(data.url, data);
-      this.updated.next(null);
-    });
-    socket.fromEvent('completed').subscribe((strdata: string) => {
-      let data: Download = JSON.parse(strdata);
-      this.queue.delete(data.url);
-      this.done.set(data.url, data);
-      this.queueChanged.next(null);
-      this.doneChanged.next(null);
-    });
-    socket.fromEvent('canceled').subscribe((strdata: string) => {
-      let data: string = JSON.parse(strdata);
-      this.queue.delete(data);
-      this.queueChanged.next(null);
-    });
-    socket.fromEvent('cleared').subscribe((strdata: string) => {
-      let data: string = JSON.parse(strdata);
-      this.done.delete(data);
-      this.doneChanged.next(null);
-    });
-    socket.fromEvent('configuration').subscribe((strdata: string) => {
-      let data = JSON.parse(strdata);
-      console.debug("got configuration:", data);
-      this.configuration = data;
-      this.configurationChanged.next(data);
-    });
-    socket.fromEvent('custom_dirs').subscribe((strdata: string) => {
-      let data = JSON.parse(strdata);
-      console.debug("got custom_dirs:", data);
-      this.customDirs = data;
-      this.customDirsChanged.next(data);
-    });
-    socket.fromEvent('ytdl_options_changed').subscribe((strdata: string) => {
-      let data = JSON.parse(strdata);
-      this.ytdlOptionsChanged.next(data);
-    });
-  }
-
-  handleHTTPError(error: HttpErrorResponse) {
-    var msg = error.error instanceof ErrorEvent ? error.error.message : error.error;
-    return of({status: 'error', msg: msg})
-  }
-
-  public add(url: string, quality: string, format: string, folder: string, customNamePrefix: string, playlistStrictMode: boolean, playlistItemLimit: number, autoStart: boolean) {
-    return this.http.post<Status>('add', {url: url, quality: quality, format: format, folder: folder, custom_name_prefix: customNamePrefix, playlist_strict_mode: playlistStrictMode, playlist_item_limit: playlistItemLimit, auto_start: autoStart}).pipe(
-      catchError(this.handleHTTPError)
-    );
-  }
-
-  public startById(ids: string[]) {
-    return this.http.post('start', {ids: ids});
-  }
-
-  public delById(where: string, ids: string[]) {
-    ids.forEach(id => this[where].get(id).deleting = true);
-    return this.http.post('delete', {where: where, ids: ids});
-  }
-
-  public startByFilter(where: string, filter: (dl: Download) => boolean) {
-    let ids: string[] = [];
-    this[where].forEach((dl: Download) => { if (filter(dl)) ids.push(dl.url) });
-    return this.startById(ids);
-  }
-
-  public delByFilter(where: string, filter: (dl: Download) => boolean) {
-    let ids: string[] = [];
-    this[where].forEach((dl: Download) => { if (filter(dl)) ids.push(dl.url) });
-    return this.delById(where, ids);
-  }
-  public addDownloadByUrl(url: string): Promise<any> {
-    const defaultQuality = 'best';
-    const defaultFormat = 'mp4';
-    const defaultFolder = ''; 
-    const defaultCustomNamePrefix = '';
-    const defaultPlaylistStrictMode = false;
-    const defaultPlaylistItemLimit = 0;
-    const defaultAutoStart = true;
-    
-    return new Promise((resolve, reject) => {
-      this.add(url, defaultQuality, defaultFormat, defaultFolder, defaultCustomNamePrefix, defaultPlaylistStrictMode, defaultPlaylistItemLimit, defaultAutoStart)
-        .subscribe(
-          response => resolve(response),
-          error => reject(error)
-        );
-    });
-  }
-  public exportQueueUrls(): string[] {
-    return Array.from(this.queue.values()).map(download => download.url);
-  }
-  
-  
-}

ui/src/app/formats.ts

@@ -1,84 +0,0 @@
-export interface Format {
-  id: string;
-  text: string;
-  qualities: Quality[];
-}
-
-export interface Quality {
-  id: string;
-  text: string;
-}
-
-export const Formats: Format[] = [
-  {
-    id: 'any',
-    text: 'Any',
-    qualities: [
-      { id: 'best', text: 'Best' },
-      { id: '2160', text: '2160p' },
-      { id: '1440', text: '1440p' },
-      { id: '1080', text: '1080p' },
-      { id: '720', text: '720p' },
-      { id: '480', text: '480p' },
-      { id: '360', text: '360p' },
-      { id: '240', text: '240p' },
-      { id: 'worst', text: 'Worst' },
-      { id: 'audio', text: 'Audio Only' },
-    ],
-  },
-  {
-    id: 'mp4',
-    text: 'MP4',
-    qualities: [
-      { id: 'best', text: 'Best' },
-      { id: 'best_ios', text: 'Best (iOS)' },
-      { id: '2160', text: '2160p' },
-      { id: '1440', text: '1440p' },
-      { id: '1080', text: '1080p' },
-      { id: '720', text: '720p' },
-      { id: '480', text: '480p' },
-      { id: '360', text: '360p' },
-      { id: '240', text: '240p' },
-      { id: 'worst', text: 'Worst' },
-    ],
-  },
-  {
-    id: 'm4a',
-    text: 'M4A',
-    qualities: [
-      { id: 'best', text: 'Best' },
-      { id: '192', text: '192 kbps' },
-      { id: '128', text: '128 kbps' },
-    ],
-  },
-  {
-    id: 'mp3',
-    text: 'MP3',
-    qualities: [
-      { id: 'best', text: 'Best' },
-      { id: '320', text: '320 kbps' },
-      { id: '192', text: '192 kbps' },
-      { id: '128', text: '128 kbps' },
-    ],
-  },
-  {
-    id: 'opus',
-    text: 'OPUS',
-    qualities: [{ id: 'best', text: 'Best' }],
-  },
-  {
-    id: 'wav',
-    text: 'WAV',
-    qualities: [{ id: 'best', text: 'Best' }],
-  },
-  {
-    id: 'flac',
-    text: 'FLAC',
-    qualities: [{ id: 'best', text: 'Best' }],
-  },
-  {
-    id: 'thumbnail',
-    text: 'Thumbnail',
-    qualities: [{ id: 'best', text: 'Best' }],
-  },
-];

ui/src/app/interfaces/checkable.ts

@@ -0,0 +1,3 @@
+export interface Checkable {
+  checked: boolean;
+}

ui/src/app/interfaces/download.ts

@@ -0,0 +1,31 @@
+
+export interface Download {
+  id: string;
+  title: string;
+  url: string;
+  download_type: string;
+  codec?: string;
+  quality: string;
+  format: string;
+  folder: string;
+  custom_name_prefix: string;
+  playlist_item_limit: number;
+  split_by_chapters?: boolean;
+  chapter_template?: string;
+  subtitle_language?: string;
+  subtitle_mode?: string;
+  ytdl_options_presets?: string[];
+  ytdl_options_overrides?: Record<string, unknown>;
+  status: string;
+  msg: string;
+  percent: number;
+  speed: number;
+  eta: number;
+  filename: string;
+  checked: boolean;
+  timestamp?: number;
+  size?: number;
+  error?: string;
+  deleting?: boolean;
+  chapter_files?: { filename: string, size: number }[];
+}

ui/src/app/interfaces/format.ts

@@ -0,0 +1,7 @@
+import { Quality } from "./quality";
+
+export interface Format {
+  id: string;
+  text: string;
+  qualities: Quality[];
+}

ui/src/app/interfaces/formats.ts

@@ -0,0 +1,77 @@
+import { Quality } from "./quality";
+
+export interface Option {
+  id: string;
+  text: string;
+}
+
+export interface AudioFormatOption extends Option {
+  qualities: Quality[];
+}
+
+export const DOWNLOAD_TYPES: Option[] = [
+  { id: "video", text: "Video" },
+  { id: "audio", text: "Audio" },
+  { id: "captions", text: "Captions" },
+  { id: "thumbnail", text: "Thumbnail" },
+];
+
+export const VIDEO_CODECS: Option[] = [
+  { id: "auto", text: "Auto" },
+  { id: "h264", text: "H.264" },
+  { id: "h265", text: "H.265 (HEVC)" },
+  { id: "av1", text: "AV1" },
+  { id: "vp9", text: "VP9" },
+];
+
+export const VIDEO_FORMATS: Option[] = [
+  { id: "any", text: "Auto" },
+  { id: "mp4", text: "MP4" },
+  { id: "ios", text: "iOS Compatible" },
+];
+
+export const VIDEO_QUALITIES: Quality[] = [
+  { id: "best", text: "Best" },
+  { id: "2160", text: "2160p" },
+  { id: "1440", text: "1440p" },
+  { id: "1080", text: "1080p" },
+  { id: "720", text: "720p" },
+  { id: "480", text: "480p" },
+  { id: "360", text: "360p" },
+  { id: "240", text: "240p" },
+  { id: "worst", text: "Worst" },
+];
+
+export const AUDIO_FORMATS: AudioFormatOption[] = [
+  {
+    id: "m4a",
+    text: "M4A",
+    qualities: [
+      { id: "best", text: "Best" },
+      { id: "192", text: "192 kbps" },
+      { id: "128", text: "128 kbps" },
+    ],
+  },
+  {
+    id: "mp3",
+    text: "MP3",
+    qualities: [
+      { id: "best", text: "Best" },
+      { id: "320", text: "320 kbps" },
+      { id: "192", text: "192 kbps" },
+      { id: "128", text: "128 kbps" },
+    ],
+  },
+  { id: "opus", text: "OPUS", qualities: [{ id: "best", text: "Best" }] },
+  { id: "wav", text: "WAV", qualities: [{ id: "best", text: "Best" }] },
+  { id: "flac", text: "FLAC", qualities: [{ id: "best", text: "Best" }] },
+];
+
+export const CAPTION_FORMATS: Option[] = [
+  { id: "srt", text: "SRT" },
+  { id: "txt", text: "TXT (Text only)" },
+  { id: "vtt", text: "VTT" },
+  { id: "ttml", text: "TTML" },
+];
+
+export const THUMBNAIL_FORMATS: Option[] = [{ id: "jpg", text: "JPG" }];

ui/src/app/interfaces/index.ts

@@ -0,0 +1,9 @@
+export * from './theme';
+export * from './status';
+export * from './quality';
+export * from './state';    
+export * from './download'; 
+export * from './checkable';
+export * from './format';
+export * from './formats';
+export * from './subscription';

ui/src/app/interfaces/quality.ts

@@ -0,0 +1,5 @@
+
+export interface Quality {
+  id: string;
+  text: string;
+}

ui/src/app/interfaces/state.ts

@@ -0,0 +1 @@
+export type State =  'queue' | 'done';

ui/src/app/interfaces/status.ts

@@ -0,0 +1,4 @@
+export interface Status {
+  status: string;
+  msg?: string;
+}

ui/src/app/interfaces/subscription.ts

@@ -0,0 +1,15 @@
+export interface SubscriptionRow {
+  id: string;
+  name: string;
+  url: string;
+  enabled: boolean;
+  check_interval_minutes: number;
+  download_type: string;
+  codec: string;
+  format: string;
+  quality: string;
+  folder: string;
+  last_checked: number | null;
+  seen_count: number;
+  error: string | null;
+}

ui/src/app/interfaces/theme.ts

@@ -0,0 +1,7 @@
+import { IconDefinition } from "@fortawesome/fontawesome-svg-core";
+
+export interface Theme {
+  id: string;
+  displayName: string;
+  icon: IconDefinition;
+}

ui/src/app/master-checkbox.component.ts

@@ -1,55 +0,0 @@
-import { Component, Input, ViewChild, ElementRef, Output, EventEmitter } from '@angular/core';
-
-interface Checkable {
-  checked: boolean;
-}
-
-@Component({
-    selector: 'app-master-checkbox',
-    template: `
-  <div class="form-check">
-    <input type="checkbox" class="form-check-input" id="{{id}}-select-all" #masterCheckbox [(ngModel)]="selected" (change)="clicked()">
-    <label class="form-check-label" for="{{id}}-select-all"></label>
-  </div>
-`,
-    standalone: false
-})
-export class MasterCheckboxComponent {
-  @Input() id: string;
-  @Input() list: Map<String, Checkable>;
-  @Output() changed = new EventEmitter<number>();
-
-  @ViewChild('masterCheckbox') masterCheckbox: ElementRef;
-  selected: boolean;
-
-  clicked() {
-    this.list.forEach(item => item.checked = this.selected);
-    this.selectionChanged();
-  }
-
-  selectionChanged() {
-    if (!this.masterCheckbox)
-      return;
-    let checked: number = 0;
-    this.list.forEach(item => { if(item.checked) checked++ });
-    this.selected = checked > 0 && checked == this.list.size;
-    this.masterCheckbox.nativeElement.indeterminate = checked > 0 && checked < this.list.size;
-    this.changed.emit(checked);
-  }
-}
-
-@Component({
-    selector: 'app-slave-checkbox',
-    template: `
-  <div class="form-check">
-    <input type="checkbox" class="form-check-input" id="{{master.id}}-{{id}}-select" [(ngModel)]="checkable.checked" (change)="master.selectionChanged()">
-    <label class="form-check-label" for="{{master.id}}-{{id}}-select"></label>
-  </div>
-`,
-    standalone: false
-})
-export class SlaveCheckboxComponent {
-  @Input() id: string;
-  @Input() master: MasterCheckboxComponent;
-  @Input() checkable: Checkable;
-}

ui/src/app/pipes/eta.pipe.spec.ts

@@ -0,0 +1,26 @@
+import { EtaPipe } from './eta.pipe';
+
+describe('EtaPipe', () => {
+  it('returns null for null input', () => {
+    const pipe = new EtaPipe();
+    expect(pipe.transform(null as unknown as number)).toBeNull();
+  });
+
+  it('formats seconds under one minute', () => {
+    const pipe = new EtaPipe();
+    expect(pipe.transform(0)).toBe('0s');
+    expect(pipe.transform(59)).toBe('59s');
+  });
+
+  it('formats minutes and seconds', () => {
+    const pipe = new EtaPipe();
+    expect(pipe.transform(60)).toBe('1m 0s');
+    expect(pipe.transform(90)).toBe('1m 30s');
+  });
+
+  it('formats hours', () => {
+    const pipe = new EtaPipe();
+    expect(pipe.transform(3600)).toBe('1h 0m 0s');
+    expect(pipe.transform(3661)).toBe('1h 1m 1s');
+  });
+});

ui/src/app/pipes/eta.pipe.ts

@@ -0,0 +1,21 @@
+import { Pipe, PipeTransform } from "@angular/core";
+
+@Pipe({
+    name: 'eta',
+})
+export class EtaPipe implements PipeTransform {
+  transform(value: number): string | null {
+    if (value === null) {
+      return null;
+    }
+    if (value < 60) {
+      return `${Math.round(value)}s`;
+    }
+    if (value < 3600) {
+      return `${Math.floor(value/60)}m ${Math.round(value%60)}s`;
+    }
+    const hours = Math.floor(value/3600)
+    const minutes = value % 3600
+    return `${hours}h ${Math.floor(minutes/60)}m ${Math.round(minutes%60)}s`;
+  }
+}

ui/src/app/pipes/file-size.pipe.spec.ts

@@ -0,0 +1,24 @@
+import { FileSizePipe } from './file-size.pipe';
+
+describe('FileSizePipe', () => {
+  it('returns 0 Bytes for zero or NaN', () => {
+    const pipe = new FileSizePipe();
+    expect(pipe.transform(0)).toBe('0 Bytes');
+    expect(pipe.transform(Number.NaN)).toBe('0 Bytes');
+  });
+
+  it('formats bytes and larger units', () => {
+    const pipe = new FileSizePipe();
+    expect(pipe.transform(500)).toContain('Bytes');
+    expect(pipe.transform(1000)).toContain('KB');
+    expect(pipe.transform(1000 * 1000)).toContain('MB');
+    expect(pipe.transform(1000 ** 3)).toContain('GB');
+  });
+
+  it('handles boundaries between units', () => {
+    const pipe = new FileSizePipe();
+    expect(pipe.transform(999)).toContain('Bytes');
+    expect(pipe.transform(1000)).toContain('KB');
+    expect(pipe.transform(1001)).toContain('KB');
+  });
+});

ui/src/app/pipes/file-size.pipe.ts

@@ -0,0 +1,16 @@
+import { Pipe, PipeTransform } from "@angular/core";
+
+@Pipe({
+    name: 'fileSize',
+})
+export class FileSizePipe implements PipeTransform {
+  transform(value: number): string {
+      if (isNaN(value) || value === 0) return '0 Bytes';
+
+      const units = ['Bytes', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'];
+      const unitIndex = Math.floor(Math.log(value) / Math.log(1000)); // Use 1000 for common units
+
+      const unitValue = value / Math.pow(1000, unitIndex);
+      return `${unitValue.toFixed(2)} ${units[unitIndex]}`;
+  }
+}

ui/src/app/pipes/index.ts

@@ -0,0 +1,3 @@
+export { EtaPipe } from './eta.pipe';
+export { SpeedPipe } from './speed.pipe';
+export { FileSizePipe } from './file-size.pipe';

ui/src/app/pipes/speed.pipe.spec.ts

@@ -0,0 +1,21 @@
+import { SpeedPipe } from './speed.pipe';
+
+describe('SpeedPipe', () => {
+  it('returns empty string for non-positive speed values', () => {
+    const pipe = new SpeedPipe();
+    expect(pipe.transform(0)).toBe('');
+    expect(pipe.transform(-1)).toBe('');
+  });
+
+  it('formats bytes per second values', () => {
+    const pipe = new SpeedPipe();
+    expect(pipe.transform(1024)).toBe('1 KB/s');
+    expect(pipe.transform(1536)).toBe('1.5 KB/s');
+  });
+
+  it('formats MB/s and GB/s', () => {
+    const pipe = new SpeedPipe();
+    expect(pipe.transform(1024 * 1024)).toBe('1 MB/s');
+    expect(pipe.transform(1024 * 1024 * 1024)).toBe('1 GB/s');
+  });
+});

ui/src/app/pipes/speed.pipe.ts

@@ -0,0 +1,19 @@
+import { Pipe, PipeTransform } from "@angular/core";
+
+@Pipe({
+    name: 'speed',
+    pure: true
+})
+export class SpeedPipe implements PipeTransform {
+  transform(value: number): string {
+    if (value === null || value === undefined || isNaN(value) || value <= 0) {
+      return '';
+    }
+
+    const k = 1024;
+    const decimals = 2;
+    const sizes = ['B/s', 'KB/s', 'MB/s', 'GB/s', 'TB/s', 'PB/s', 'EB/s', 'ZB/s', 'YB/s'];
+    const i = Math.floor(Math.log(value) / Math.log(k));
+    return `${parseFloat((value / Math.pow(k, i)).toFixed(decimals))} ${sizes[i]}`;
+  }
+}

ui/src/app/services/downloads.service.spec.ts

@@ -0,0 +1,292 @@
+import { TestBed } from '@angular/core/testing';
+import { provideHttpClient, HttpErrorResponse } from '@angular/common/http';
+import { provideHttpClientTesting, HttpTestingController } from '@angular/common/http/testing';
+import { Subject } from 'rxjs';
+import { DownloadsService, AddDownloadPayload } from './downloads.service';
+import { MeTubeSocket } from './metube-socket.service';
+import { Download } from '../interfaces';
+
+class MeTubeSocketStub {
+  private subjects: Record<string, Subject<string>> = {};
+
+  fromEvent(event: string) {
+    if (!this.subjects[event]) {
+      this.subjects[event] = new Subject<string>();
+    }
+    return this.subjects[event].asObservable();
+  }
+
+  emit(event: string, data: string) {
+    if (!this.subjects[event]) {
+      this.subjects[event] = new Subject<string>();
+    }
+    this.subjects[event].next(data);
+  }
+}
+
+function basePayload(): AddDownloadPayload {
+  return {
+    url: 'https://example.com/v',
+    downloadType: 'video',
+    codec: 'auto',
+    quality: 'best',
+    format: 'any',
+    folder: '',
+    customNamePrefix: '',
+    playlistItemLimit: 0,
+    autoStart: true,
+    splitByChapters: false,
+    chapterTemplate: '',
+    subtitleLanguage: 'en',
+    subtitleMode: 'prefer_manual',
+    ytdlOptionsPresets: [],
+    ytdlOptionsOverrides: '',
+  };
+}
+
+describe('DownloadsService', () => {
+  let socket: MeTubeSocketStub;
+  let httpMock: HttpTestingController;
+  let service: DownloadsService;
+
+  beforeEach(async () => {
+    socket = new MeTubeSocketStub();
+    await TestBed.configureTestingModule({
+      providers: [
+        DownloadsService,
+        provideHttpClient(),
+        provideHttpClientTesting(),
+        { provide: MeTubeSocket, useValue: socket },
+      ],
+    }).compileComponents();
+
+    service = TestBed.inject(DownloadsService);
+    httpMock = TestBed.inject(HttpTestingController);
+  });
+
+  it('add() posts snake_case fields matching backend', () => {
+    service.add(basePayload()).subscribe();
+    const req = httpMock.expectOne('add');
+    expect(req.request.method).toBe('POST');
+    expect(req.request.body).toEqual(
+      expect.objectContaining({
+        url: 'https://example.com/v',
+        download_type: 'video',
+        codec: 'auto',
+        quality: 'best',
+        format: 'any',
+        playlist_item_limit: 0,
+        auto_start: true,
+        split_by_chapters: false,
+        chapter_template: '',
+        subtitle_language: 'en',
+        subtitle_mode: 'prefer_manual',
+        ytdl_options_presets: [],
+        ytdl_options_overrides: '',
+      }),
+    );
+    req.flush({ status: 'ok' });
+  });
+
+  it('getPresets() fetches configured preset names', () => {
+    service.getPresets().subscribe((result) => {
+      expect(result).toEqual({ presets: ['Preset A'] });
+    });
+    const req = httpMock.expectOne('presets');
+    expect(req.request.method).toBe('GET');
+    req.flush({ presets: ['Preset A'] });
+  });
+
+  it('cancelAdd posts to cancel-add', () => {
+    service.cancelAdd().subscribe();
+    const req = httpMock.expectOne('cancel-add');
+    expect(req.request.method).toBe('POST');
+    req.flush({ status: 'ok' });
+  });
+
+  it('startById posts ids', () => {
+    service.startById(['a', 'b']).subscribe();
+    const req = httpMock.expectOne('start');
+    expect(req.request.body).toEqual({ ids: ['a', 'b'] });
+    req.flush({});
+  });
+
+  it('delById marks items deleting and posts delete', () => {
+    const dl: Download = {
+      id: '1',
+      title: 't',
+      url: 'u1',
+      download_type: 'video',
+      quality: 'best',
+      format: 'any',
+      folder: '',
+      custom_name_prefix: '',
+      playlist_item_limit: 0,
+      status: 'finished',
+      msg: '',
+      percent: 0,
+      speed: 0,
+      eta: 0,
+      filename: '',
+      checked: false,
+      deleting: false,
+    };
+    service.queue.set('u1', dl);
+    service.delById('queue', ['u1']).subscribe();
+    expect(dl.deleting).toBe(true);
+    const req = httpMock.expectOne('delete');
+    expect(req.request.body).toEqual({ where: 'queue', ids: ['u1'] });
+    req.flush({});
+  });
+
+  it('handleHTTPError extracts msg from object body', async () => {
+    const err = new HttpErrorResponse({
+      error: { msg: 'bad' },
+      status: 400,
+    });
+    const res = await new Promise((resolve) => {
+      service.handleHTTPError(err).subscribe(resolve);
+    });
+    expect((res as { status: string }).status).toBe('error');
+    expect((res as { msg?: string }).msg).toBe('bad');
+  });
+
+  it('socket all updates queue and done', () => {
+    const row: Download = {
+      id: '1',
+      title: 't',
+      url: 'u1',
+      download_type: 'video',
+      quality: 'best',
+      format: 'any',
+      folder: '',
+      custom_name_prefix: '',
+      playlist_item_limit: 0,
+      status: 'pending',
+      msg: '',
+      percent: 0,
+      speed: 0,
+      eta: 0,
+      filename: '',
+      checked: false,
+    };
+    const q: [string, Download][] = [['u1', row]];
+    const d: [string, Download][] = [];
+    socket.emit('all', JSON.stringify([q, d]));
+    expect(service.loading).toBe(false);
+    expect(service.queue.has('u1')).toBe(true);
+  });
+
+  it('socket updated preserves checked and deleting', () => {
+    service.queue.set('u1', {
+      id: '1',
+      title: 't',
+      url: 'u1',
+      download_type: 'video',
+      quality: 'best',
+      format: 'any',
+      folder: '',
+      custom_name_prefix: '',
+      playlist_item_limit: 0,
+      status: 'pending',
+      msg: '',
+      percent: 0,
+      speed: 0,
+      eta: 0,
+      filename: '',
+      checked: true,
+      deleting: true,
+    });
+    socket.emit(
+      'updated',
+      JSON.stringify({ url: 'u1', title: 't', status: 'downloading' }),
+    );
+    const updated = service.queue.get('u1');
+    expect(updated?.checked).toBe(true);
+    expect(updated?.deleting).toBe(true);
+  });
+
+  it('socket completed moves entry to done', () => {
+    service.queue.set('u1', {
+      id: '1',
+      title: 't',
+      url: 'u1',
+      download_type: 'video',
+      quality: 'best',
+      format: 'any',
+      folder: '',
+      custom_name_prefix: '',
+      playlist_item_limit: 0,
+      status: 'pending',
+      msg: '',
+      percent: 0,
+      speed: 0,
+      eta: 0,
+      filename: '',
+      checked: false,
+    });
+    socket.emit('completed', JSON.stringify({ url: 'u1', title: 't', status: 'finished' }));
+    expect(service.queue.has('u1')).toBe(false);
+    expect(service.done.has('u1')).toBe(true);
+  });
+
+  it('socket canceled removes from queue', () => {
+    service.queue.set('u1', {
+      id: '1',
+      title: 't',
+      url: 'u1',
+      download_type: 'video',
+      quality: 'best',
+      format: 'any',
+      folder: '',
+      custom_name_prefix: '',
+      playlist_item_limit: 0,
+      status: 'pending',
+      msg: '',
+      percent: 0,
+      speed: 0,
+      eta: 0,
+      filename: '',
+      checked: false,
+    });
+    socket.emit('canceled', JSON.stringify('u1'));
+    expect(service.queue.has('u1')).toBe(false);
+  });
+
+  it('socket cleared removes from done', () => {
+    service.done.set('u1', {
+      id: '1',
+      title: 't',
+      url: 'u1',
+      download_type: 'video',
+      quality: 'best',
+      format: 'any',
+      folder: '',
+      custom_name_prefix: '',
+      playlist_item_limit: 0,
+      status: 'finished',
+      msg: '',
+      percent: 0,
+      speed: 0,
+      eta: 0,
+      filename: '',
+      checked: false,
+    });
+    socket.emit('cleared', JSON.stringify('u1'));
+    expect(service.done.has('u1')).toBe(false);
+  });
+
+  it('socket configuration updates configuration', () => {
+    socket.emit('configuration', JSON.stringify({ CUSTOM_DIRS: true }));
+    expect(service.configuration['CUSTOM_DIRS']).toBe(true);
+  });
+
+  it('socket custom_dirs updates customDirs', () => {
+    socket.emit('custom_dirs', JSON.stringify({ download_dir: [''] }));
+    expect(service.customDirs['download_dir']).toEqual(['']);
+  });
+
+  afterEach(() => {
+    httpMock.verify();
+  });
+});

ui/src/app/services/downloads.service.ts

@@ -0,0 +1,212 @@
+import { inject, Injectable } from '@angular/core';
+import { HttpClient, HttpErrorResponse } from '@angular/common/http';
+import { of, Subject } from 'rxjs';
+import { catchError } from 'rxjs/operators';
+import { MeTubeSocket } from './metube-socket.service';
+import { Download, Status, State } from '../interfaces';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+
+export interface AddDownloadPayload {
+  url: string;
+  downloadType: string;
+  codec: string;
+  quality: string;
+  format: string;
+  folder: string;
+  customNamePrefix: string;
+  playlistItemLimit: number;
+  autoStart: boolean;
+  splitByChapters: boolean;
+  chapterTemplate: string;
+  subtitleLanguage: string;
+  subtitleMode: string;
+  ytdlOptionsPresets: string[];
+  ytdlOptionsOverrides: string;
+}
+@Injectable({
+  providedIn: 'root'
+})
+export class DownloadsService {
+  private http = inject(HttpClient);
+  private socket = inject(MeTubeSocket);
+  loading = true;
+  queue = new Map<string, Download>();
+  done = new Map<string, Download>();
+  queueChanged = new Subject<void>();
+  doneChanged = new Subject<void>();
+  customDirsChanged = new Subject<Record<string, string[]>>();
+  ytdlOptionsChanged = new Subject<Record<string, unknown>>();
+  configurationChanged = new Subject<Record<string, unknown>>();
+  updated = new Subject<void>();
+
+  configuration: Record<string, unknown> = {};
+  customDirs: Record<string, string[]> = {};
+
+  constructor() {
+    this.socket.fromEvent('all')
+    .pipe(takeUntilDestroyed())
+    .subscribe((strdata: string) => {
+      this.loading = false;
+      const data: [[[string, Download]], [[string, Download]]] = JSON.parse(strdata);
+      this.queue.clear();
+      data[0].forEach(entry => this.queue.set(...entry));
+      this.done.clear();
+      data[1].forEach(entry => this.done.set(...entry));
+      this.queueChanged.next();
+      this.doneChanged.next();
+    });
+    this.socket.fromEvent('added')
+    .pipe(takeUntilDestroyed())
+    .subscribe((strdata: string) => {
+      const data: Download = JSON.parse(strdata);
+      this.queue.set(data.url, data);
+      this.queueChanged.next();
+    });
+    this.socket.fromEvent('updated')
+    .pipe(takeUntilDestroyed())
+    .subscribe((strdata: string) => {
+      const data: Download = JSON.parse(strdata);
+      const dl: Download | undefined  = this.queue.get(data.url);
+      data.checked = !!dl?.checked;
+      data.deleting = !!dl?.deleting;
+      this.queue.set(data.url, data);
+      this.updated.next();
+    });
+    this.socket.fromEvent('completed')
+    .pipe(takeUntilDestroyed())
+    .subscribe((strdata: string) => {
+      const data: Download = JSON.parse(strdata);
+      this.queue.delete(data.url);
+      this.done.set(data.url, data);
+      this.queueChanged.next();
+      this.doneChanged.next();
+    });
+    this.socket.fromEvent('canceled')
+    .pipe(takeUntilDestroyed())
+    .subscribe((strdata: string) => {
+      const data: string = JSON.parse(strdata);
+      this.queue.delete(data);
+      this.queueChanged.next();
+    });
+    this.socket.fromEvent('cleared')
+    .pipe(takeUntilDestroyed())
+    .subscribe((strdata: string) => {
+      const data: string = JSON.parse(strdata);
+      this.done.delete(data);
+      this.doneChanged.next();
+    });
+    this.socket.fromEvent('configuration')
+    .pipe(takeUntilDestroyed())
+    .subscribe((strdata: string) => {
+      const data = JSON.parse(strdata);
+      console.debug("got configuration:", data);
+      this.configuration = data;
+      this.configurationChanged.next(data);
+    });
+    this.socket.fromEvent('custom_dirs')
+    .pipe(takeUntilDestroyed())
+    .subscribe((strdata: string) => {
+      const data = JSON.parse(strdata);
+      console.debug("got custom_dirs:", data);
+      this.customDirs = data;
+      this.customDirsChanged.next(data);
+    });
+    this.socket.fromEvent('ytdl_options_changed')
+    .pipe(takeUntilDestroyed())
+    .subscribe((strdata: string) => {
+      const data = JSON.parse(strdata);
+      this.ytdlOptionsChanged.next(data);
+    });
+  }
+
+  handleHTTPError(error: HttpErrorResponse) {
+    const msg = error.error instanceof ErrorEvent
+      ? error.error.message
+      : (typeof error.error === 'string'
+          ? error.error
+          : (error.error?.msg || error.message || 'Request failed'));
+    return of({ status: 'error', msg });
+  }
+
+  public add(payload: AddDownloadPayload) {
+    return this.http.post<Status>('add', {
+      url: payload.url,
+      download_type: payload.downloadType,
+      codec: payload.codec,
+      quality: payload.quality,
+      format: payload.format,
+      folder: payload.folder,
+      custom_name_prefix: payload.customNamePrefix,
+      playlist_item_limit: payload.playlistItemLimit,
+      auto_start: payload.autoStart,
+      split_by_chapters: payload.splitByChapters,
+      chapter_template: payload.chapterTemplate,
+      subtitle_language: payload.subtitleLanguage,
+      subtitle_mode: payload.subtitleMode,
+      ytdl_options_presets: payload.ytdlOptionsPresets,
+      ytdl_options_overrides: payload.ytdlOptionsOverrides,
+    }).pipe(
+      catchError(this.handleHTTPError)
+    );
+  }
+
+  public getPresets() {
+    return this.http.get<{ presets: string[] }>('presets').pipe(
+      catchError(() => of({ presets: [] }))
+    );
+  }
+
+  public startById(ids: string[]) {
+    return this.http.post('start', {ids: ids});
+  }
+
+  public delById(where: State, ids: string[]) {
+    const map = this[where];
+    if (map) {
+      for (const id of ids) {
+        const obj = map.get(id);
+        if (obj) {
+          obj.deleting = true;
+        }
+      }
+    }
+    return this.http.post('delete', {where: where, ids: ids});
+  }
+
+  public startByFilter(where: State, filter: (dl: Download) => boolean) {
+    const ids: string[] = [];
+    this[where].forEach((dl: Download) => { if (filter(dl)) ids.push(dl.url) });
+    return this.startById(ids);
+  }
+
+  public delByFilter(where: State, filter: (dl: Download) => boolean) {
+    const ids: string[] = [];
+    this[where].forEach((dl: Download) => { if (filter(dl)) ids.push(dl.url) });
+    return this.delById(where, ids);
+  }
+  public cancelAdd() {
+    return this.http.post<Status>('cancel-add', {}).pipe(
+      catchError(this.handleHTTPError)
+    );
+  }
+
+  uploadCookies(file: File) {
+    const formData = new FormData();
+    formData.append('cookies', file);
+    return this.http.post<{ status: string; msg?: string }>('upload-cookies', formData).pipe(
+      catchError(this.handleHTTPError)
+    );
+  }
+
+  deleteCookies() {
+    return this.http.post<{ status: string; msg?: string }>('delete-cookies', {}).pipe(
+      catchError(this.handleHTTPError)
+    );
+  }
+
+  getCookieStatus() {
+    return this.http.get<{ status: string; has_cookies: boolean }>('cookie-status').pipe(
+      catchError(this.handleHTTPError)
+    );
+  }
+}

ui/src/app/services/index.ts

@@ -0,0 +1,2 @@
+export { DownloadsService } from './downloads.service';
+export { MeTubeSocket } from './metube-socket.service';

ui/src/app/services/metube-socket.service.ts

@@ -1,10 +1,15 @@
-import { Injectable } from '@angular/core';
+import { Injectable, inject } from '@angular/core';
 import { ApplicationRef } from '@angular/core';
 import { Socket } from 'ngx-socket-io';
 
-@Injectable()
+@Injectable(
+  { providedIn: 'root' }
+)
 export class MeTubeSocket extends Socket {
-  constructor(appRef: ApplicationRef) {
+
+  constructor() {
+    const appRef = inject(ApplicationRef);
+
     const path =
       document.location.pathname.replace(/share-target/, '') + 'socket.io';
     super({ url: '', options: { path } }, appRef);

ui/src/app/services/subscriptions.service.ts

@@ -0,0 +1,130 @@
+import { DestroyRef, inject, Injectable } from '@angular/core';
+import { HttpClient, HttpErrorResponse } from '@angular/common/http';
+import { of, Subject } from 'rxjs';
+import { catchError, tap } from 'rxjs/operators';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { MeTubeSocket } from './metube-socket.service';
+import { SubscriptionRow } from '../interfaces/subscription';
+import { Status } from '../interfaces';
+import { AddDownloadPayload } from './downloads.service';
+
+export interface SubscribePayload extends AddDownloadPayload {
+  checkIntervalMinutes: number;
+}
+
+@Injectable({
+  providedIn: 'root',
+})
+export class SubscriptionsService {
+  private http = inject(HttpClient);
+  private socket = inject(MeTubeSocket);
+  private destroyRef = inject(DestroyRef);
+
+  subscriptions = new Map<string, SubscriptionRow>();
+  subscriptionsChanged = new Subject<void>();
+
+  private publishList(rows: SubscriptionRow[]) {
+    this.subscriptions.clear();
+    for (const row of rows) {
+      this.subscriptions.set(row.id, row);
+    }
+    this.subscriptionsChanged.next();
+  }
+
+  constructor() {
+    this.socket
+      .fromEvent('subscriptions_all')
+      .pipe(takeUntilDestroyed(this.destroyRef))
+      .subscribe((strdata: string) => {
+        const data: SubscriptionRow[] = JSON.parse(strdata);
+        this.publishList(data);
+      });
+
+    this.socket
+      .fromEvent('subscription_added')
+      .pipe(takeUntilDestroyed(this.destroyRef))
+      .subscribe((strdata: string) => {
+        const row: SubscriptionRow = JSON.parse(strdata);
+        this.subscriptions.set(row.id, row);
+        this.subscriptionsChanged.next();
+      });
+
+    this.socket
+      .fromEvent('subscription_updated')
+      .pipe(takeUntilDestroyed(this.destroyRef))
+      .subscribe((strdata: string) => {
+        const row: SubscriptionRow = JSON.parse(strdata);
+        this.subscriptions.set(row.id, row);
+        this.subscriptionsChanged.next();
+      });
+
+    this.socket
+      .fromEvent('subscription_removed')
+      .pipe(takeUntilDestroyed(this.destroyRef))
+      .subscribe((strdata: string) => {
+        const id: string = JSON.parse(strdata);
+        this.subscriptions.delete(id);
+        this.subscriptionsChanged.next();
+      });
+  }
+
+  handleHTTPError(error: HttpErrorResponse) {
+    const msg =
+      error.error instanceof ErrorEvent
+        ? error.error.message
+        : typeof error.error === 'string'
+          ? error.error
+          : error.error?.msg || error.message || 'Request failed';
+    return of({ status: 'error' as const, msg });
+  }
+
+  subscribe(payload: SubscribePayload) {
+    return this.http
+      .post<Status>('subscribe', {
+        url: payload.url,
+        download_type: payload.downloadType,
+        codec: payload.codec,
+        quality: payload.quality,
+        format: payload.format,
+        folder: payload.folder,
+        custom_name_prefix: payload.customNamePrefix,
+        playlist_item_limit: payload.playlistItemLimit,
+        auto_start: payload.autoStart,
+        split_by_chapters: payload.splitByChapters,
+        chapter_template: payload.chapterTemplate,
+        subtitle_language: payload.subtitleLanguage,
+        subtitle_mode: payload.subtitleMode,
+        ytdl_options_presets: payload.ytdlOptionsPresets,
+        ytdl_options_overrides: payload.ytdlOptionsOverrides,
+        check_interval_minutes: payload.checkIntervalMinutes,
+      })
+      .pipe(catchError((err) => this.handleHTTPError(err)));
+  }
+
+  delete(ids: string[]) {
+    return this.http.post('subscriptions/delete', { ids }).pipe(catchError((err) => this.handleHTTPError(err)));
+  }
+
+  update(id: string, changes: Partial<Pick<SubscriptionRow, 'enabled' | 'check_interval_minutes' | 'name'>>) {
+    return this.http
+      .post('subscriptions/update', { id, ...changes })
+      .pipe(catchError((err) => this.handleHTTPError(err)));
+  }
+
+  checkNow(ids?: string[]) {
+    return this.http
+      .post('subscriptions/check', ids?.length ? { ids } : {})
+      .pipe(catchError((err) => this.handleHTTPError(err)));
+  }
+
+  fetchList() {
+    return this.http.get<SubscriptionRow[]>('subscriptions').pipe(catchError(() => of([])));
+  }
+
+  refreshList() {
+    return this.http.get<SubscriptionRow[]>('subscriptions').pipe(
+      tap((rows) => this.publishList(rows)),
+      catchError((err) => this.handleHTTPError(err)),
+    );
+  }
+}

ui/src/app/speed.service.ts

@@ -1,39 +0,0 @@
-import { Injectable } from '@angular/core';
-import { BehaviorSubject, Observable, interval } from 'rxjs';
-import { map } from 'rxjs/operators';
-
-@Injectable({
-  providedIn: 'root'
-})
-export class SpeedService {
-  private speedBuffer = new BehaviorSubject<number[]>([]);
-  private readonly BUFFER_SIZE = 10; // Keep last 10 measurements (1 second at 100ms intervals)
-
-  // Observable that emits the mean speed every second
-  public meanSpeed$: Observable<number>;
-
-  constructor() {
-    // Calculate mean speed every second
-    this.meanSpeed$ = interval(1000).pipe(
-      map(() => {
-        const speeds = this.speedBuffer.value;
-        if (speeds.length === 0) return 0;
-        return speeds.reduce((sum, speed) => sum + speed, 0) / speeds.length;
-      })
-    );
-  }
-
-  // Add a new speed measurement
-  public addSpeedMeasurement(speed: number) {
-    const currentBuffer = this.speedBuffer.value;
-    const newBuffer = [...currentBuffer, speed].slice(-this.BUFFER_SIZE);
-    this.speedBuffer.next(newBuffer);
-  }
-
-  // Get the current mean speed
-  public getCurrentMeanSpeed(): number {
-    const speeds = this.speedBuffer.value;
-    if (speeds.length === 0) return 0;
-    return speeds.reduce((sum, speed) => sum + speed, 0) / speeds.length;
-  }
-} 

ui/src/app/theme.ts

@@ -1,11 +1,6 @@
-import { IconDefinition } from "@fortawesome/fontawesome-svg-core";
 import { faCircleHalfStroke, faMoon, faSun  } from "@fortawesome/free-solid-svg-icons";
+import { Theme } from "./interfaces/theme";
 
-export interface Theme {
-  id: string;
-  displayName: string;
-  icon: IconDefinition;
-}
 
 export const Themes: Theme[] = [
   {

ui/src/environments/environment.prod.ts

@@ -1,3 +0,0 @@
-export const environment = {
-  production: true
-};

ui/src/environments/environment.ts

@@ -1,16 +0,0 @@
-// This file can be replaced during build by using the `fileReplacements` array.
-// `ng build --prod` replaces `environment.ts` with `environment.prod.ts`.
-// The list of file replacements can be found in `angular.json`.
-
-export const environment = {
-  production: false
-};
-
-/*
- * For easier debugging in development mode, you can import the following file
- * to ignore zone related error stack frames such as `zone.run`, `zoneDelegate.invokeTask`.
- *
- * This import should be commented out in production mode because it will have a negative impact
- * on performance if an error is thrown.
- */
-// import 'zone.js/dist/zone-error';  // Included with Angular CLI.

ui/src/main.ts

@@ -1,12 +1,9 @@
-import { enableProdMode } from '@angular/core';
-import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
+/// <reference types="@angular/localize" />
 
-import { AppModule } from './app/app.module';
-import { environment } from './environments/environment';
+import { bootstrapApplication } from '@angular/platform-browser';
+import { appConfig } from './app/app.config';
+import { App } from './app/app';
 
-if (environment.production) {
-  enableProdMode();
-}
 
-platformBrowserDynamic().bootstrapModule(AppModule)
-  .catch(err => console.error(err));
+bootstrapApplication(App, appConfig)
+  .catch((err) => console.error(err));

ui/src/polyfills.ts

@@ -1,69 +0,0 @@
-/***************************************************************************************************
- * Load `$localize` onto the global scope - used if i18n tags appear in Angular templates.
- */
-import '@angular/localize/init';
-/**
- * This file includes polyfills needed by Angular and is loaded before the app.
- * You can add your own extra polyfills to this file.
- *
- * This file is divided into 2 sections:
- *   1. Browser polyfills. These are applied before loading ZoneJS and are sorted by browsers.
- *   2. Application imports. Files imported after ZoneJS that should be loaded before your main
- *      file.
- *
- * The current setup is for so-called "evergreen" browsers; the last versions of browsers that
- * automatically update themselves. This includes Safari >= 10, Chrome >= 55 (including Opera),
- * Edge >= 13 on the desktop, and iOS 10 and Chrome on mobile.
- *
- * Learn more in https://angular.io/guide/browser-support
- */
-
-/***************************************************************************************************
- * BROWSER POLYFILLS
- */
-
-/**
- * IE11 requires the following for NgClass support on SVG elements
- */
-// import 'classlist.js';  // Run `npm install --save classlist.js`.
-
-/**
- * Web Animations `@angular/platform-browser/animations`
- * Only required if AnimationBuilder is used within the application and using IE/Edge or Safari.
- * Standard animation support in Angular DOES NOT require any polyfills (as of Angular 6.0).
- */
-// import 'web-animations-js';  // Run `npm install --save web-animations-js`.
-
-/**
- * By default, zone.js will patch all possible macroTask and DomEvents
- * user can disable parts of macroTask/DomEvents patch by setting following flags
- * because those flags need to be set before `zone.js` being loaded, and webpack
- * will put import in the top of bundle, so user need to create a separate file
- * in this directory (for example: zone-flags.ts), and put the following flags
- * into that file, and then add the following code before importing zone.js.
- * import './zone-flags';
- *
- * The flags allowed in zone-flags.ts are listed here.
- *
- * The following flags will work for all browsers.
- *
- * (window as any).__Zone_disable_requestAnimationFrame = true; // disable patch requestAnimationFrame
- * (window as any).__Zone_disable_on_property = true; // disable patch onProperty such as onclick
- * (window as any).__zone_symbol__UNPATCHED_EVENTS = ['scroll', 'mousemove']; // disable patch specified eventNames
- *
- *  in IE/Edge developer tools, the addEventListener will also be wrapped by zone.js
- *  with the following flag, it will bypass `zone.js` patch for IE/Edge
- *
- *  (window as any).__Zone_enable_cross_context_check = true;
- *
- */
-
-/***************************************************************************************************
- * Zone JS is required by default for Angular itself.
- */
-import 'zone.js';  // Included with Angular CLI.
-
-
-/***************************************************************************************************
- * APPLICATION IMPORTS
- */

ui/src/styles.sass

@@ -5,3 +5,22 @@
 
     [data-bs-theme="dark"] &
         background-color: var(--bs-dark-bg-subtle) !important
+
+.ng-select
+    flex: 1
+
+    .ng-select-container
+        min-height: 38px
+
+    .ng-value
+        white-space: nowrap
+        overflow: visible
+
+    .ng-dropdown-panel
+        .ng-dropdown-panel-items
+            max-height: 300px
+
+            .ng-option
+                white-space: nowrap
+                overflow: visible
+                text-overflow: ellipsis

ui/src/test.ts

@@ -1,14 +0,0 @@
-// This file is required by karma.conf.js and loads recursively all the .spec and framework files
-
-import 'zone.js/dist/zone-testing';
-import { getTestBed } from '@angular/core/testing';
-import {
-  BrowserDynamicTestingModule,
-  platformBrowserDynamicTesting
-} from '@angular/platform-browser-dynamic/testing';
-
-// First, initialize the Angular testing environment.
-getTestBed().initTestEnvironment(
-  BrowserDynamicTestingModule,
-  platformBrowserDynamicTesting()
-);

ui/tsconfig.app.json

@@ -3,13 +3,14 @@
   "extends": "./tsconfig.json",
   "compilerOptions": {
     "outDir": "./out-tsc/app",
-    "types": []
+    "types": [
+      "@angular/localize"
+    ]
   },
-  "files": [
-    "src/main.ts",
-    "src/polyfills.ts"
-  ],
   "include": [
-    "src/**/*.d.ts"
+    "src/**/*.ts"
+  ],
+    "exclude": [
+    "src/**/*.spec.ts"
   ]
 }

ui/tsconfig.json

@@ -2,20 +2,30 @@
 {
   "compileOnSave": false,
   "compilerOptions": {
-    "baseUrl": "./",
-    "outDir": "./dist/out-tsc",
-    "sourceMap": true,
-    "esModuleInterop": true,
-    "declaration": false,
+    "strict": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
     "experimentalDecorators": true,
-    "moduleResolution": "bundler",
     "importHelpers": true,
     "target": "ES2022",
-    "module": "es2020",
-    "lib": [
-      "es2018",
-      "dom"
-    ],
-    "useDefineForClassFields": false
-  }
+    "module": "preserve"
+  },
+  "angularCompilerOptions": {
+    "strictInjectionParameters": true,
+    "strictInputAccessModifiers": true,
+    "strictTemplates": true
+  },
+  "files": [],
+  "references": [
+    {
+      "path": "./tsconfig.app.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
 }

ui/tsconfig.spec.json

@@ -4,13 +4,9 @@
   "compilerOptions": {
     "outDir": "./out-tsc/spec",
     "types": [
-      "jasmine"
+      "vitest/globals"
     ]
   },
-  "files": [
-    "src/test.ts",
-    "src/polyfills.ts"
-  ],
   "include": [
     "src/**/*.spec.ts",
     "src/**/*.d.ts"

ui/tslint.json

@@ -1,152 +0,0 @@
-{
-  "extends": "tslint:recommended",
-  "rulesDirectory": [
-    "codelyzer"
-  ],
-  "rules": {
-    "align": {
-      "options": [
-        "parameters",
-        "statements"
-      ]
-    },
-    "array-type": false,
-    "arrow-return-shorthand": true,
-    "curly": true,
-    "deprecation": {
-      "severity": "warning"
-    },
-    "eofline": true,
-    "import-blacklist": [
-      true,
-      "rxjs/Rx"
-    ],
-    "import-spacing": true,
-    "indent": {
-      "options": [
-        "spaces"
-      ]
-    },
-    "max-classes-per-file": false,
-    "max-line-length": [
-      true,
-      140
-    ],
-    "member-ordering": [
-      true,
-      {
-        "order": [
-          "static-field",
-          "instance-field",
-          "static-method",
-          "instance-method"
-        ]
-      }
-    ],
-    "no-console": [
-      true,
-      "debug",
-      "info",
-      "time",
-      "timeEnd",
-      "trace"
-    ],
-    "no-empty": false,
-    "no-inferrable-types": [
-      true,
-      "ignore-params"
-    ],
-    "no-non-null-assertion": true,
-    "no-redundant-jsdoc": true,
-    "no-switch-case-fall-through": true,
-    "no-var-requires": false,
-    "object-literal-key-quotes": [
-      true,
-      "as-needed"
-    ],
-    "quotemark": [
-      true,
-      "single"
-    ],
-    "semicolon": {
-      "options": [
-        "always"
-      ]
-    },
-    "space-before-function-paren": {
-      "options": {
-        "anonymous": "never",
-        "asyncArrow": "always",
-        "constructor": "never",
-        "method": "never",
-        "named": "never"
-      }
-    },
-    "typedef": [
-      true,
-      "call-signature"
-    ],
-    "typedef-whitespace": {
-      "options": [
-        {
-          "call-signature": "nospace",
-          "index-signature": "nospace",
-          "parameter": "nospace",
-          "property-declaration": "nospace",
-          "variable-declaration": "nospace"
-        },
-        {
-          "call-signature": "onespace",
-          "index-signature": "onespace",
-          "parameter": "onespace",
-          "property-declaration": "onespace",
-          "variable-declaration": "onespace"
-        }
-      ]
-    },
-    "variable-name": {
-      "options": [
-        "ban-keywords",
-        "check-format",
-        "allow-pascal-case"
-      ]
-    },
-    "whitespace": {
-      "options": [
-        "check-branch",
-        "check-decl",
-        "check-operator",
-        "check-separator",
-        "check-type",
-        "check-typecast"
-      ]
-    },
-    "component-class-suffix": true,
-    "contextual-lifecycle": true,
-    "directive-class-suffix": true,
-    "no-conflicting-lifecycle": true,
-    "no-host-metadata-property": true,
-    "no-input-rename": true,
-    "no-inputs-metadata-property": true,
-    "no-output-native": true,
-    "no-output-on-prefix": true,
-    "no-output-rename": true,
-    "no-outputs-metadata-property": true,
-    "template-banana-in-box": true,
-    "template-no-negated-async": true,
-    "use-lifecycle-interface": true,
-    "use-pipe-transform-interface": true,
-    "directive-selector": [
-      true,
-      "attribute",
-      "app",
-      "camelCase"
-    ],
-    "component-selector": [
-      true,
-      "element",
-      "app",
-      "kebab-case"
-    ]
-  }
-}