deploy: nexstream backend (experiment)

.dockerignore

@@ -0,0 +1,20 @@
+# build context lean; never ship host modules or secrets
+**/node_modules
+**/dist
+**/.env
+**/.env.*
+**/*.log
+**/*.rdb
+backend/temp
+backend/*cookies*.txt
+
+# unused by the backend image
+.git
+frontend
+mobile
+engine
+temp_refs
+temp_refs2
+BTC-ISMIR19
+bin
+*.md

.gitattributes

@@ -1,35 +0,0 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,48 @@
+# Hugging Face Spaces (Docker SDK) build.
+# Place this file as ./Dockerfile at the Space repo root,
+# alongside shared/ and backend/ (build context = repo root).
+FROM node:22-slim
+
+SHELL ["/bin/bash", "-o", "pipefail", "-c"]
+# hadolint ignore=DL3008
+RUN set -ex; \
+    export DEBIAN_FRONTEND=noninteractive; \
+    apt-get update; \
+    apt-get install -y --no-install-recommends \
+    python3 python3-pip python3-full ffmpeg curl unzip; \
+    rm -rf /var/lib/apt/lists/*
+
+# yt-dlp toolchain in a world-readable venv
+RUN python3 -m venv /opt/tool-venv \
+    && /opt/tool-venv/bin/pip install --no-cache-dir --upgrade pip \
+    && /opt/tool-venv/bin/pip install --no-cache-dir --upgrade --pre \
+    yt-dlp kaggle yt-dlp-getpot-wpc
+
+# hf runs containers as uid 1000
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.deno/bin:/opt/tool-venv/bin:/home/user/.local/bin:$PATH
+WORKDIR $HOME/app
+
+RUN curl -fsSL https://deno.land/install.sh | sh
+
+# shared has its own deps (zod) the schemas need
+COPY --chown=user shared/ ./shared/
+RUN npm install --prefix shared
+
+COPY --chown=user backend/package*.json ./backend/
+WORKDIR $HOME/app/backend
+RUN npm install
+
+COPY --chown=user backend/ ./
+RUN npx tsc
+
+RUN mkdir -p temp
+
+ENV PORT=7860 \
+    API_ONLY=true \
+    NODE_ENV=production
+EXPOSE 7860
+
+CMD ["node", "--import", "./dist/backend/src/instrument.js", "dist/backend/src/app.js"]

README.md

@@ -1,10 +1,33 @@
 ---
-title: Nexstream Api
-emoji: 📉
-colorFrom: pink
-colorTo: red
+title: NexStream Backend
+emoji: 🎬
+colorFrom: blue
+colorTo: indigo
 sdk: docker
+app_port: 7860
 pinned: false
+short_description: NexStream media backend (experimental)
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# NexStream Backend — Hugging Face Space
+
+Experimental Docker deployment of the NexStream Express backend.
+
+This Space serves the API only (`API_ONLY=true`). The container listens on
+`7860` (matching `app_port`).
+
+## Required Space secrets
+
+Set these in **Settings → Variables and secrets** (they are injected as env
+at runtime):
+
+- `PROXY_SIGNING_SECRET` — pin it so signed `/proxy` links survive restarts
+- `COOKIES_URL` — remote cookies source (storage here is ephemeral)
+- `ALLOWED_ORIGINS` — your frontend origin(s), comma-separated
+- Redis connection vars (e.g. `REDIS_URL`)
+- Turso vars (`TURSO_DATABASE_URL`, `TURSO_AUTH_TOKEN`)
+- `GEMINI_API_KEY`, `GROQ_API_KEY`
+- `YT_PROXY` — optional; residential proxy for YouTube (experiment branch)
+
+`NODE_ENV` is already set to `production` in the Dockerfile (must not be
+`test`, or the server won't start).

backend/.dockerignore

@@ -0,0 +1,20 @@
+.env
+.env.local
+.env.*.local
+
+# Ignore build artifacts and nodes
+node_modules
+dist
+node_modules
+temp
+temp_cookies.txt
+
+# Ignore logs and large files
+*.log
+*.mp4
+*.webm
+*.mp3
+
+# Ignore git
+.git
+.gitignore

backend/.env.example

@@ -0,0 +1,58 @@
+# full reference: docs/env-variables.md.
+# none of these are strictly required — each enables a feature.
+
+# Spotify resolution
+# as of now, requires premium acc. but dont worry; will works without it
+SPOTIFY_CLIENT_ID=
+SPOTIFY_CLIENT_SECRET=
+
+# AI fallback for query synthesis — set at least one.
+GEMINI_API_KEY=
+GROQ_API_KEY=
+
+# data layer
+REDIS_URL=redis://127.0.0.1:6379
+TURSO_URL=
+TURSO_AUTH_TOKEN=
+
+# ISRC fallback
+SOUNDCHARTS_APP_ID=
+SOUNDCHARTS_API_KEY=
+
+# yt-dlp cookies — improves YouTube reliability
+COOKIES_URL=
+
+# observability
+SENTRY_DSN=
+
+
+# ─── advanced / situational — most users won't need these ───
+
+# core overrides
+# PORT=5000
+# LOG_LEVEL=info
+# max simultaneous downloads/muxes; defaults to cpu count
+# MAX_CONCURRENT_MEDIA=
+# youtube client refresh interval (ms); defaults to 4h
+# YOUTUBE_CLIENT_TTL_MS=
+API_ONLY=false
+
+# alternative gateway to GEMINI
+VERTEX_API_KEY=
+
+# yt-dlp tweaks
+YTDLP_COOKIES_FILE=
+ENABLE_POT_PLUGIN=0
+
+# Remix Lab > Kaggle sync
+KAGGLE_USERNAME=
+KAGGLE_KEY=
+
+# public-instance hardening (see docs/protect-an-instance.md)
+API_KEY=
+# comma-separated cors allowlist; empty = reflect origin without credentials
+ALLOWED_ORIGINS=
+PROXY_SIGNING_SECRET=
+PROXY_URL_TTL_SECONDS=
+# set true ONLY if a cdn's tls breaks the proxy (disables cert checks for cdns)
+PROXY_ALLOW_INSECURE_TLS=

backend/.gitignore

@@ -0,0 +1,4 @@
+\n# Ignore sensitive cookie files\nfacebook_cookies.txt\nyoutube_cookies.txt\n*.txt
+.npmrc
+test-results.xml
+coverage/

backend/Dockerfile

@@ -0,0 +1,45 @@
+FROM node:22-slim
+
+WORKDIR /app
+
+SHELL ["/bin/bash", "-o", "pipefail", "-c"]
+# hadolint ignore=DL3008
+RUN set -ex; \
+    export DEBIAN_FRONTEND=noninteractive; \
+    apt-get update; \
+    apt-get install -y --no-install-recommends \
+    python3 \
+    python3-pip \
+    python3-full \
+    ffmpeg \
+    curl \
+    unzip; \
+    curl -fsSL https://deno.land/install.sh | sh; \
+    rm -rf /var/lib/apt/lists/*
+
+ENV DENO_INSTALL="/root/.deno"
+ENV PATH="$DENO_INSTALL/bin:$PATH"
+
+RUN python3 -m venv /opt/tool-venv \
+    && /opt/tool-venv/bin/pip install --upgrade pip \
+    && /opt/tool-venv/bin/pip install --upgrade --pre yt-dlp kaggle yt-dlp-getpot-wpc
+ENV PATH="/opt/tool-venv/bin:$PATH"
+
+# shared has its own deps (zod) the schemas need
+COPY shared/ ./shared/
+RUN npm install --prefix shared
+
+COPY backend/package*.json ./backend/
+WORKDIR /app/backend
+RUN npm install
+
+COPY backend/ ./
+RUN npx tsc
+
+RUN mkdir -p temp && chmod 777 temp
+
+ENV PORT=8000
+ENV API_ONLY=true
+EXPOSE 8000
+
+CMD ["node", "--import", "./dist/backend/src/instrument.js", "dist/backend/src/app.js"]

backend/README.md

@@ -0,0 +1,100 @@
+# Backend
+
+the Express 5 + TypeScript service that powers stream resolution, muxing, the Spotify resolution race, and the Remix Lab API. for the project overview see [`../README.md`](../README.md). for self-hosting see [`../docs/run-an-instance.md`](../docs/run-an-instance.md).
+
+## Layout
+
+```text
+backend/
+├── src/
+│   ├── app.ts              # Express setup, middleware, route wiring, lifecycle
+│   ├── instrument.ts       # Sentry instrumentation — must load before app.ts
+│   ├── controllers/
+│   │   ├── video.controller.ts       # /info, /convert, /stream-urls handlers
+│   │   └── keychanger.controller.ts  # pitch-shift / key-change uploads
+│   ├── routes/
+│   │   ├── video.routes.ts           # core video / stream endpoints
+│   │   ├── remix.routes.ts           # Remix Lab kernel proxy + results
+│   │   └── keychanger.routes.ts      # key-changer route
+│   ├── services/
+│   │   ├── spotify/        # ISRC race, Turso registry, AI query synthesis
+│   │   ├── ytdlp/          # yt-dlp integration: streamer, info, turbo-mux, config
+│   │   ├── extractors/     # pure-JS extractors (YouTube/FB/IG/TikTok/SoundCloud)
+│   │   ├── extract.service.ts        # generic metadata extractor
+│   │   ├── seeder.service.ts         # background catalog seeder
+│   │   ├── social.service.ts         # metascraper-based social-link metadata
+│   │   ├── ug-grounding.service.ts   # Ultimate Guitar tab lookup
+│   │   ├── spotify.service.ts        # Spotify facade
+│   │   └── ytdlp.service.ts          # yt-dlp facade
+│   ├── utils/
+│   │   ├── api/            # controller, response helpers
+│   │   ├── infra/          # db (Turso), logger, queue, redis, trace
+│   │   ├── media/          # format, fsm, metadata, spotify, stream, video
+│   │   └── network/        # auth, cipher, cookie, proxy, secrets, security, sse, validation
+│   └── types/              # shared TS types
+├── tests/                  # Vitest suites + e2e helpers
+├── scripts/                # test orchestration, benchmarks, Termux shim
+└── Dockerfile              # container build (node:22-slim base)
+```
+
+## Routes
+
+`video.routes.ts`:
+
+| Method | Path | Purpose |
+|---|---|---|
+| `GET` | `/events` | SSE telemetry stream. |
+| `GET` | `/info` | resolve a URL → metadata + format list. |
+| `GET` | `/stream-urls` | refresh CDN URLs for a known video. |
+| `POST` | `/telemetry` | frontend → backend telemetry ingest. |
+| `ALL` | `/convert` | stream / download a chosen format. |
+| `GET` | `/proxy` | authenticated stream proxy. |
+| `GET` | `/seed-intelligence` | trigger the background catalog seeder. |
+
+`remix.routes.ts` proxies the Python Remix Lab kernel and serves stem/chord/beat results. `keychanger.routes.ts` handles pitch-shift uploads. `/convert` and `/proxy` are gated by `concurrencyGuard(2)` (`utils/network/security.util.ts`) to keep memory bounded on Termux and free-tier hosts.
+
+response shapes for `/info` and `/convert` are documented in [`../docs/api.md`](../docs/api.md).
+
+## Environment
+
+configure via `backend/.env`. the full reference is in [`../docs/env-variables.md`](../docs/env-variables.md). the backend boots without most of these — they enable optional features and degrade gracefully when unset. minimum to get something useful:
+
+- `REDIS_URL` — Redis for the metadata cache and BullMQ job queue (defaults to `redis://127.0.0.1:6379`).
+- `GEMINI_API_KEY` and/or `GROQ_API_KEY` — at least one for the AI fallback in Spotify resolution.
+- `SPOTIFY_CLIENT_ID` + `SPOTIFY_CLIENT_SECRET` — Spotify Web API for ISRC and metadata.
+- `TURSO_URL` + `TURSO_AUTH_TOKEN` — global edge registry. unset is fine for local dev (falls back to an in-memory mock).
+- `COOKIES_URL` — remote `yt-dlp` cookie sync. improves YouTube reliability.
+- `API_ONLY=true` — disable serving the bundled `frontend/dist` (split deployments).
+
+## Running
+
+```bash
+npm install
+npm run dev          # tsc + node, listens on :5000 (or $PORT)
+```
+
+other scripts:
+
+- `npm run build` — TypeScript compile to `dist/`.
+- `npm test` — full Vitest suite (sequential, Termux-friendly).
+- `npm run test:fast` — core regression tests only.
+- `npm run test:lite` — node `--test` lite suite (no transpile).
+- `npm run lint` — ESLint on changed files (`npm run lint:all` for the whole package).
+- `npm run bench:convert` — convert-pipeline benchmark.
+
+## Requirements
+
+- Node.js ≥ 22 — matches the Dockerfile and the project root.
+- `yt-dlp` and `ffmpeg` on `PATH`. `yt-dlp` is the fallback for sources without a native extractor; `ffmpeg` 7.x or 8.x handles muxing and audio transcoding.
+- Redis. an in-process mock is used in tests when none is reachable.
+
+## Notes
+
+- **YouTube player clients**: `services/ytdlp/turbo-mux.ts` passes `--extractor-args youtube:player-client=...` to obtain DASH manifests and bypass the 360p limit on the default web client. the client list is chosen per request based on the requested format.
+- **Concurrency**: `concurrencyGuard(limit)` (`utils/network/security.util.ts`) caps in-flight downloads at `limit=2` per process to prevent OOM on small hosts.
+- **Cookie sync**: `utils/network/cookie.util.ts` pulls `youtube_cookies.txt` and `facebook_cookies.txt` from `COOKIES_URL` at boot when the variable is set.
+- **MP3 transcoding**: `services/ytdlp/streamer.ts` pipes raw audio through `ffmpeg -vn -ab 192k -f mp3 pipe:1` straight to the client — no temp files.
+- **MP4 finalization**: `-movflags +faststart` is set on finalized MP4 downloads so playback can start before the file finishes.
+- **SSE**: `/events` is the canonical telemetry channel. resolvers, downloaders, and the seeder push progress through `utils/network/sse.util.ts`.
+
+before putting an instance on the public internet, read [`../docs/protect-an-instance.md`](../docs/protect-an-instance.md).

backend/deno-wrapper

@@ -0,0 +1,2 @@
+#!/data/data/com.termux/files/usr/bin/bash
+/data/data/com.termux/files/usr/bin/deno "$@" --allow-all

backend/eslint.config.js

@@ -0,0 +1,114 @@
+import js from '@eslint/js';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+import sonarjs from 'eslint-plugin-sonarjs';
+import prettierConfig from 'eslint-config-prettier';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import process from 'node:process';
+
+const pluginPath = join(process.cwd(), '../scripts/eslint-plugin-nexstream.js');
+const hasPlugin = existsSync(pluginPath);
+const nexstreamPlugin = hasPlugin ? (await import('../scripts/eslint-plugin-nexstream.js')).default : null;
+
+export default tseslint.config(
+  {
+    ignores: ['dist', 'node_modules', 'temp'],
+  },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  sonarjs.configs.recommended,
+  prettierConfig,
+  {
+    plugins: {
+      ...(nexstreamPlugin ? { nexstream: nexstreamPlugin } : {}),
+    },
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'module',
+      globals: {
+        ...globals.node,
+      },
+    },
+    rules: {
+      ...(nexstreamPlugin ? {
+        'nexstream/nexstream-comments': 'error',
+        'nexstream/no-raw-fetch': 'error',
+        'nexstream/no-raw-spawn': 'error',
+      } : {}),
+      complexity: ['error', 30],
+      'object-shorthand': ['error', 'always'],
+      'no-extra-boolean-cast': 'error',
+      'no-unneeded-ternary': 'error',
+      '@typescript-eslint/no-non-null-assertion': 'error',
+      'id-length': [
+        'error',
+        {
+          min: 2,
+          exceptions: ['i', 'j', '_', 'x', 'y', 'z', 'C', 'D', 'E', 'F', 'G', 'A', 'B', 'id', 'ip', 'cb', 'fs', 'db', 'ms', 'ok', 'err', 'req', 'res', 'url'],
+        },
+      ],
+      'sonarjs/cognitive-complexity': 'off',
+      'sonarjs/no-os-command-from-path': 'off',
+      'sonarjs/regex-complexity': 'off',
+      'sonarjs/slow-regex': 'off',
+      'sonarjs/no-nested-conditional': 'off',
+      'sonarjs/no-identical-expressions': 'off',
+      'sonarjs/duplicates-in-character-class': 'off',
+      'sonarjs/single-character-alternation': 'off',
+      'sonarjs/pseudo-random': 'off',
+      'sonarjs/content-length': 'off',
+      'sonarjs/void-use': 'off',
+      'sonarjs/unused-import': 'error',
+      'no-unused-vars': 'off',
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          varsIgnorePattern: '^[A-Z_]',
+          argsIgnorePattern: '^[A-Z_]',
+          caughtErrorsIgnorePattern: '^[A-Z_]',
+        },
+      ],
+      'require-await': 'error',
+      'prefer-template': 'error',
+      '@typescript-eslint/no-inferrable-types': 'error',
+      '@typescript-eslint/prefer-optional-chain': 'off',
+      '@typescript-eslint/no-explicit-any': 'error',
+      'prefer-const': 'error',
+      'no-template-curly-in-string': 'error',
+      'no-restricted-syntax': [
+        'error',
+        {
+          selector: 'ExportNamedDeclaration > VariableDeclaration[kind="let"]',
+          message: 'Use "const" instead of "let" for exports.',
+        },
+        {
+          selector: 'ExportNamedDeclaration > VariableDeclaration[kind="var"]',
+          message: 'Use "const" instead of "var" for exports.',
+        },
+      ],
+      'spaced-comment': ['error', 'always'],
+    },
+  },
+  {
+    files: ['tests/**/*.ts', 'tests/**/*.js', 'src/temp/**/*.ts', 'src/instrument.ts', 'scripts/**/*.ts', '../scripts/**/*.js'],
+    rules: {
+      'sonarjs/no-hardcoded-ip': 'off',
+      'sonarjs/no-clear-text-protocols': 'off',
+      complexity: 'off',
+      'sonarjs/no-duplicate-string': 'off',
+      'sonarjs/no-ignored-exceptions': 'off',
+      'sonarjs/no-commented-code': 'off',
+      'sonarjs/cors': 'off',
+      'sonarjs/x-powered-by': 'off',
+      'sonarjs/no-all-duplicated-branches': 'off',
+      'sonarjs/unused-import': 'off',
+      '@typescript-eslint/no-explicit-any': 'error',
+      ...(nexstreamPlugin ? {
+        'nexstream/nexstream-comments': 'error',
+        'nexstream/no-raw-fetch': 'error',
+        'nexstream/no-raw-spawn': 'error',
+      } : {}),
+    },
+  }
+);

backend/package.json

@@ -0,0 +1,113 @@
+{
+  "name": "backend",
+  "version": "1.0.0",
+  "description": "",
+  "main": "src/app.ts",
+  "scripts": {
+    "build": "npx tsc && cp -f .env dist/backend/.env || true",
+    "dev": "npx tsc && node --import ./dist/backend/src/instrument.js scripts/termux-shim.js",
+    "start": "node --import ./dist/backend/src/instrument.js scripts/termux-shim.js",
+    "test": "./scripts/test-sequential.sh",
+    "test:fast": "./scripts/test-sequential.sh 'tests/core/*.test.ts'",
+    "test:phase1": "./scripts/test-sequential.sh 'tests/core/cipher_randomization.test.ts tests/core/client_rotation.test.ts tests/core/throttle_bypass_args.test.ts tests/core/streamer_args.test.ts tests/core/retry_stream_lifecycle.test.ts tests/core/smart_client_pick.test.ts tests/core/temp_file_flow.test.ts tests/core/cookie_bootstrap.test.ts tests/core/cookie_deduplication.test.ts tests/core/format_string_fallback.test.ts tests/api/convert_temp_file_e2e.test.ts'",
+    "test:lite": "npx tsc && node --test tests/lite/*.lite.test.js",
+    "test:ci": "./scripts/ci-test.sh",
+    "test:ci:keep": "./scripts/ci-test.sh --keep",
+    "test:single": "NODE_OPTIONS='--import ./scripts/termux-shim.js --max-old-space-size=512' npx vitest run",
+    "verify:chunked": "VITEST_INCLUDE_MANUAL=1 SMOKE_TEST=1 npx vitest run tests/manual/chunked_fetcher_smoke.test.ts --no-coverage",
+    "bench:convert": "node scripts/bench-convert.js",
+    "lint": "bash ../scripts/lint-changed.sh",
+    "lint:all": "eslint .",
+    "format": "prettier --write ."
+  },
+  "keywords": [],
+  "author": "ejjays",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "dependencies": {
+    "@google/genai": "^1.35.0",
+    "@libsql/client": "^0.17.3",
+    "@sentry/node": "^10.53.1",
+    "@sentry/profiling-node": "^10.53.1",
+    "better-sse": "^0.16.1",
+    "bullmq": "^5.73.0",
+    "cheerio": "^1.2.0",
+    "compression": "^1.8.1",
+    "cors": "^2.8.5",
+    "dotenv": "^17.2.3",
+    "essentia.js": "^0.1.3",
+    "express": "^5.2.1",
+    "express-rate-limit": "^8.5.2",
+    "fluent-ffmpeg": "^2.1.3",
+    "form-data": "^4.0.5",
+    "fpcalc": "^1.3.0",
+    "got": "^11.8.6",
+    "helmet": "^8.2.0",
+    "ioredis": "^5.10.1",
+    "jiti": "^2.6.1",
+    "lru-cache": "^11.3.6",
+    "metascraper": "^5.50.3",
+    "metascraper-author": "^5.50.1",
+    "metascraper-description": "^5.50.1",
+    "metascraper-image": "^5.50.1",
+    "metascraper-instagram": "^5.50.3",
+    "metascraper-logo": "^5.50.1",
+    "metascraper-publisher": "^5.50.1",
+    "metascraper-soundcloud": "^5.50.1",
+    "metascraper-spotify": "^5.50.1",
+    "metascraper-tiktok": "^5.50.1",
+    "metascraper-title": "^5.50.1",
+    "metascraper-url": "^5.50.1",
+    "metascraper-youtube": "^5.50.1",
+    "multer": "^1.4.5-lts.1",
+    "node-shazam": "^1.2.7",
+    "pino": "^10.3.1",
+    "spotify-url-info": "^3.3.0",
+    "sucrase": "^3.35.1",
+    "ultimate-guitar": "^2.0.6",
+    "undici": "^8.3.0",
+    "wav-decoder": "^1.3.0",
+    "youtubei.js": "^17.0.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/compression": "^1.8.1",
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.0",
+    "@types/fluent-ffmpeg": "^2.1.27",
+    "@types/metascraper": "^5.14.3",
+    "@types/metascraper-author": "^5.14.5",
+    "@types/metascraper-description": "^5.14.5",
+    "@types/metascraper-image": "^5.14.5",
+    "@types/metascraper-logo": "^5.14.4",
+    "@types/metascraper-publisher": "^5.14.5",
+    "@types/metascraper-title": "^5.14.5",
+    "@types/metascraper-url": "^5.14.5",
+    "@types/multer": "^1.4.11",
+    "@types/node": "^22.19.19",
+    "@types/supertest": "^7.2.0",
+    "@vitest/coverage-v8": "^4.1.7",
+    "eslint": "^10.4.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-sonarjs": "^4.0.3",
+    "globals": "^17.6.0",
+    "ioredis-mock": "^8.13.1",
+    "msw": "^2.13.6",
+    "pino-pretty": "^13.1.3",
+    "prettier": "^3.8.3",
+    "puppeteer-core": "^25.0.4",
+    "supertest": "^7.2.2",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.4.0",
+    "typescript-eslint": "^8.59.4",
+    "vitest": "^4.1.5",
+    "zod": "^4.4.3"
+  },
+  "optionalDependencies": {
+    "@esbuild/android-arm64": "^0.28.0",
+    "@libsql/android-arm64": "npm:null@*",
+    "@rollup/rollup-android-arm64": "^4.60.3",
+    "@rollup/rollup-linux-x64-gnu": "^4.60.3"
+  }
+}

backend/scripts/bench-convert.js

@@ -0,0 +1,219 @@
+/**
+ * benchmark /convert endpoint performance
+ *
+ * usage:
+ * node scripts/bench-convert.js [URL]
+ *
+ * envs:
+ * BENCH_HOST: target server
+ * BENCH_URL: fallback URL
+ * BENCH_FORMAT: mp4|m4a|mp3
+ * BENCH_TIMEOUT_MS: request timeout
+ */
+
+import { request as httpRequest } from 'node:http';
+import { URL } from 'node:url';
+
+const MB = 1024 * 1024;
+
+const HOST = process.env.BENCH_HOST || 'http://localhost:5000';
+const URL_ARG =
+  process.argv[2] ||
+  process.env.BENCH_URL ||
+  'https://www.youtube.com/watch?v=jNQXAC9IVRw';
+const FORMAT = process.env.BENCH_FORMAT || 'mp4';
+const TIMEOUT_MS = parseInt(process.env.BENCH_TIMEOUT_MS || '180000', 10);
+const CLIENT_ID = `bench_${Date.now().toString(36)}`;
+
+async function resolveFormats(target, urlArg, clientId) {
+  const infoUrl = `${target.origin}/info?url=${encodeURIComponent(urlArg)}&id=${clientId}`;
+  const startedAt = Date.now();
+  const maxWaitMs = 30_000;
+  let attempt = 0;
+  let lastBody = null;
+
+  while (Date.now() - startedAt < maxWaitMs) {
+    attempt += 1;
+    const callStart = Date.now();
+    const info = await fetchJson(infoUrl);
+    console.log(
+      `[bench] /info attempt ${attempt} status=${info.status} (${Date.now() - callStart}ms)`
+    );
+
+    if (info.status !== 200) {
+      throw new Error(
+        `/info failed: status=${info.status} body=${JSON.stringify(info.body).slice(0, 200)}`
+      );
+    }
+
+    lastBody = info.body;
+    const audioFormats = info.body.audioFormats || [];
+    const videoFormats = info.body.formats || [];
+    const totalFormats = audioFormats.length + videoFormats.length;
+
+    if (totalFormats > 0) {
+      console.log(
+        `[bench] formats ready after ${Date.now() - startedAt}ms (audio=${audioFormats.length}, video=${videoFormats.length}, isPartial=${Boolean(info.body.isPartial)})`
+      );
+      return info.body;
+    }
+
+    console.log(
+      `[bench] partial: isPartial=${Boolean(info.body.isPartial)}, retrying in 500ms`
+    );
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+
+  throw new Error(
+    `timed out waiting for formats after ${maxWaitMs}ms; last=${JSON.stringify(lastBody).slice(0, 200)}`
+  );
+}
+
+function fetchJson(url) {
+  return new Promise((resolve, reject) => {
+    const req = httpRequest(url, { method: 'GET' }, (res) => {
+      const chunks = [];
+      res.on('data', (chunk) => chunks.push(chunk));
+      res.on('end', () => {
+        try {
+          resolve({
+            status: res.statusCode,
+            body: JSON.parse(Buffer.concat(chunks).toString('utf8')),
+          });
+        } catch (err) {
+          reject(err);
+        }
+      });
+    });
+    req.on('error', reject);
+    req.setTimeout(TIMEOUT_MS, () => req.destroy(new Error('info timeout')));
+    req.end();
+  });
+}
+
+function streamDownload(url) {
+  return new Promise((resolve, reject) => {
+    const t0 = Date.now();
+    let firstByteAt = 0;
+    let lastByteAt = 0;
+    let totalBytes = 0;
+
+    const req = httpRequest(url, { method: 'GET' }, (res) => {
+      if (res.statusCode !== 200) {
+        reject(new Error(`status ${res.statusCode}`));
+        return;
+      }
+      console.log(
+        `[bench] response: ${res.statusCode} ${res.headers['content-type']}`
+      );
+      console.log(
+        `[bench] disposition: ${res.headers['content-disposition'] || '(none)'}`
+      );
+
+      res.on('data', (chunk) => {
+        if (firstByteAt === 0) firstByteAt = Date.now();
+        lastByteAt = Date.now();
+        totalBytes += chunk.length;
+        if (totalBytes % (4 * MB) < chunk.length) {
+          process.stdout.write(
+            `[bench] progress: ${(totalBytes / MB).toFixed(1)} MB\r`
+          );
+        }
+      });
+      res.on('end', () => {
+        const totalMs = Math.max(1, Date.now() - t0);
+        const ttfbMs = firstByteAt > 0 ? firstByteAt - t0 : -1;
+        const streamingMs = Math.max(1, lastByteAt - firstByteAt);
+        const wallMbps = totalBytes / MB / (totalMs / 1000);
+        const streamMbps = totalBytes / MB / (streamingMs / 1000);
+
+        process.stdout.write('\n');
+        resolve({
+          totalBytes,
+          totalMs,
+          ttfbMs,
+          streamingMs,
+          wallMbps,
+          streamMbps,
+        });
+      });
+      res.on('error', reject);
+    });
+    req.on('error', reject);
+    req.setTimeout(TIMEOUT_MS, () =>
+      req.destroy(new Error('download timeout'))
+    );
+    req.end();
+  });
+}
+
+async function main() {
+  const target = new URL(HOST);
+  console.log(`[bench] host: ${target.origin}`);
+  console.log(`[bench] url: ${URL_ARG}`);
+  console.log(`[bench] format: ${FORMAT}`);
+
+  console.log('[bench] resolving /info (will await prefetch if partial)...');
+  const body = await resolveFormats(target, URL_ARG, CLIENT_ID);
+
+  const audioFormats = body.audioFormats || [];
+  const videoFormats = body.formats || [];
+  const isAudioRequest = ['m4a', 'mp3', 'audio'].includes(FORMAT);
+
+  let pick = process.env.BENCH_FORMAT_ID;
+  if (!pick) {
+    if (isAudioRequest) {
+      pick = audioFormats[0]?.formatId || videoFormats[0]?.formatId;
+    } else {
+      // prefer 720p mp4 video
+      const candidates = videoFormats.filter(
+        (fmt) => fmt.height && fmt.height <= 1080 && fmt.height >= 360
+      );
+      pick =
+        candidates.find((fmt) => fmt.height === 720)?.formatId ||
+        candidates[0]?.formatId ||
+        videoFormats[0]?.formatId ||
+        audioFormats[0]?.formatId;
+    }
+  }
+
+  if (!pick) {
+    throw new Error(
+      `no format available even after wait (audio=${audioFormats.length}, video=${videoFormats.length})`
+    );
+  }
+  console.log(`[bench] selected formatId=${pick}`);
+
+  const params = new URLSearchParams({
+    url: URL_ARG,
+    format: FORMAT,
+    formatId: String(pick),
+    id: CLIENT_ID,
+    token: CLIENT_ID,
+    title: body.title || 'Bench',
+    artist: body.uploader || 'Bench',
+  });
+  const convertUrl = `${target.origin}/convert?${params.toString()}`;
+
+  console.log('[bench] hitting /convert...');
+  const result = await streamDownload(convertUrl);
+
+  console.log('');
+  const sizeMB = result.totalBytes / MB;
+  console.log(`[bench][/convert] size=${sizeMB.toFixed(2)}MB`);
+  console.log(`[bench][/convert] total=${result.totalMs}ms`);
+  console.log(`[bench][/convert] TTFB=${result.ttfbMs}ms`);
+  console.log(`[bench][/convert] streamingOnly=${result.streamingMs}ms`);
+  console.log('');
+  console.log(
+    `[bench][calc] wall  = ${sizeMB.toFixed(2)}MB / ${(result.totalMs / 1000).toFixed(2)}s = ${result.wallMbps.toFixed(2)} MB/s (${(result.wallMbps * 8).toFixed(1)} Mbps)`
+  );
+  console.log(
+    `[bench][calc] stream= ${sizeMB.toFixed(2)}MB / ${(result.streamingMs / 1000).toFixed(2)}s = ${result.streamMbps.toFixed(2)} MB/s (${(result.streamMbps * 8).toFixed(1)} Mbps)`
+  );
+}
+
+main().catch((err) => {
+  console.error('[bench] failed:', err.message);
+  process.exitCode = 1;
+});

backend/scripts/ci-test.sh

@@ -0,0 +1,129 @@
+#!/bin/bash
+
+# termux cant run vitest (Signal 9, phantom killing).
+# so use circleci alternative, runs full test suite by creating temp branch,
+# then fetch JUnit results back to ci-results/ locally.
+
+# push to temp branch > circleci tests > download junit > cleanup
+
+set -e
+cd "$(dirname "$0")/.."
+
+KEEP_BRANCH=false
+POLL=true
+for arg in "$@"; do
+  case $arg in
+    --keep) KEEP_BRANCH=true ;;
+    --no-poll) POLL=false ;;
+  esac
+done
+
+if [ -z "$CIRCLECI_TOKEN" ]; then
+  echo "error: CIRCLECI_TOKEN not set"
+  exit 1
+fi
+
+# circleci standalone project slug (found via /me/collaborations)
+PROJECT_SLUG="circleci/9BjBRRbsXUjJueU2cq7uGg/YU36DWYQs3RevrR3a2o1CN"
+ORG_SLUG="circleci/9BjBRRbsXUjJueU2cq7uGg"
+
+ARTIFACT_DIR="$(pwd)/ci-results"
+mkdir -p "$ARTIFACT_DIR"
+
+api() { curl --noproxy '*' -s -H "Circle-Token: $CIRCLECI_TOKEN" "$1"; }
+
+cleanup_branch() {
+  echo "cleaning up branch: $1"
+  git push origin --delete "$1" 2>/dev/null || true
+  git branch -D "$1" 2>/dev/null || true
+}
+
+BRANCH="ci-test/$(date +%Y%m%d-%H%M%S)"
+ORIG_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+echo "branch: $BRANCH (from $ORIG_BRANCH)"
+
+# commit all local changes to temp branch without losing them
+git stash --include-untracked -q 2>/dev/null || true
+git checkout -b "$BRANCH"
+git stash pop -q 2>/dev/null || true
+git add -A
+git commit -m "ci-test: ephemeral" --no-verify --allow-empty
+
+echo "pushing..."
+PUSH_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+git push -u origin "$BRANCH" --no-verify 2>&1 | tail -3
+
+# go back — restore working tree
+git checkout "$ORIG_BRANCH" 2>/dev/null
+git cherry-pick --no-commit "$BRANCH" 2>/dev/null || true
+git reset HEAD 2>/dev/null || true
+
+[ "$POLL" = false ] && { echo "check: https://app.circleci.com/pipelines/$ORG?branch=$BRANCH"; exit 0; }
+
+echo "waiting for pipeline (2 min)..."
+PIPELINE_ID=""
+for _ in $(seq 1 60); do
+  # only match pipelines created AFTER our push
+  PIPELINE_ID=$(api "https://circleci.com/api/v2/pipeline?org-slug=$ORG_SLUG" \
+    | jq -r --arg ts "$PUSH_TIME" '[.items[] | select(.created_at > $ts)][0].id // empty' 2>/dev/null)
+  [ -n "$PIPELINE_ID" ] && [ "$PIPELINE_ID" != "null" ] && break
+  sleep 2
+done
+
+if [ -z "$PIPELINE_ID" ] || [ "$PIPELINE_ID" = "null" ]; then
+  echo "⏳ no pipeline yet — circleci may still be processing."
+  echo "   check: https://app.circleci.com/pipelines/$ORG_SLUG"
+  echo "   branch kept: $BRANCH (run 'git push origin --delete $BRANCH' to cleanup)"
+  exit 0
+fi
+
+echo "pipeline: $PIPELINE_ID"
+
+# poll workflow
+while true; do
+  WF=$(api "https://circleci.com/api/v2/pipeline/$PIPELINE_ID/workflow")
+  WF_ID=$(echo "$WF" | jq -r '.items[0].id // empty')
+  STATUS=$(echo "$WF" | jq -r '.items[0].status // "pending"')
+  case "$STATUS" in
+    success|failed|error|canceled) break ;;
+    *) printf "  %s...\r" "$STATUS"; sleep 10 ;;
+  esac
+done
+
+echo ""
+[ "$STATUS" = "success" ] && echo "✅ passed" || echo "❌ failed ($STATUS)"
+
+# download artifacts
+if [ -n "$WF_ID" ] && [ "$WF_ID" != "null" ]; then
+  JOBS=$(api "https://circleci.com/api/v2/workflow/$WF_ID/job")
+  for jn in $(echo "$JOBS" | jq -r '.items[] | select(.job_number != null) | .job_number'); do
+    JOB_NAME=$(echo "$JOBS" | jq -r ".items[] | select(.job_number == $jn) | .name")
+    JOB_STATUS=$(echo "$JOBS" | jq -r ".items[] | select(.job_number == $jn) | .status")
+    echo "  $JOB_NAME: $JOB_STATUS"
+
+    # fetch test results
+    TESTS=$(api "https://circleci.com/api/v2/project/$PROJECT_SLUG/$jn/tests")
+    TOTAL=$(echo "$TESTS" | jq '.items | length')
+    FAILED=$(echo "$TESTS" | jq '[.items[] | select(.result == "failure")] | length')
+    echo "    tests: $TOTAL | failed: $FAILED"
+
+    if [ "$FAILED" -gt 0 ] 2>/dev/null; then
+      echo "    failures:"
+      echo "$TESTS" | jq -r '.items[] | select(.result == "failure") | "      ✗ \(.name)"'
+    fi
+
+    # save test results as json
+    echo "$TESTS" | jq '.' > "$ARTIFACT_DIR/${JOB_NAME}-tests.json" 2>/dev/null
+
+    # download test-results.xml artifact if available
+    ARTS=$(api "https://circleci.com/api/v2/project/$PROJECT_SLUG/$jn/artifacts")
+    XML_URL=$(echo "$ARTS" | jq -r '.items[] | select(.path | test("test-results")) | .url' 2>/dev/null)
+    if [ -n "$XML_URL" ] && [ "$XML_URL" != "null" ]; then
+      curl --noproxy '*' -sL -H "Circle-Token: $CIRCLECI_TOKEN" "$XML_URL" -o "$ARTIFACT_DIR/${JOB_NAME}-test-results.xml"
+      echo "  ${JOB_NAME}-test-results.xml"
+    fi
+  done
+fi
+
+[ "$KEEP_BRANCH" = false ] && cleanup_branch "$BRANCH"
+[ "$STATUS" = "success" ] && exit 0 || exit 1

backend/scripts/termux-shim.js

@@ -0,0 +1,35 @@
+import { Module, createRequire } from 'module';
+
+createRequire(import.meta.url);
+
+// mock native modules
+const originalRequire = Module.prototype.require;
+Module.prototype.require = function (name, ...args) {
+  if (name.includes('libsql') || name === '@libsql/client') {
+    try {
+      return originalRequire.apply(this, [name, ...args]);
+    } catch (err) {
+      // bypass native noise
+      const msg = err instanceof Error ? err.message : String(err);
+      console.debug('[System] LibSQL unavailable:', msg);
+      return {
+        createClient: () => ({
+          execute: () => Promise.resolve({ rows: [] }),
+          batch: () => Promise.resolve([]),
+          close: () => {
+            /* no-op */
+          },
+        }),
+      };
+    }
+  }
+  if (name === '@ffmpeg-installer/ffmpeg') {
+    return { path: 'ffmpeg', version: 'system', url: 'https://ffmpeg.org/' };
+  }
+  return originalRequire.apply(this, [name, ...args]);
+};
+
+console.log('[env] termux bypass active');
+
+// load main app
+await import('../dist/backend/src/app.js');

backend/scripts/test-sequential.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+# Sequential test runner for low-memory environments (Termux)
+# Runs each test file in isolation, freeing memory between them.
+# Usage: ./scripts/test-sequential.sh [pattern]
+
+set -e
+
+cd "$(dirname "$0")/.."
+
+PATTERN="${1:-tests/core/*.test.ts tests/api/*.test.ts}"
+PASS=0
+FAIL=0
+FAILED_FILES=()
+
+# expand glob pattern
+shopt -s nullglob
+FILES=()
+for pat in $PATTERN; do
+  for file in $pat; do
+    [ -f "$file" ] && FILES+=("$file")
+  done
+done
+
+TOTAL=${#FILES[@]}
+echo "Running $TOTAL test files sequentially..."
+echo ""
+
+for i in "${!FILES[@]}"; do
+  FILE="${FILES[$i]}"
+  IDX=$((i + 1))
+  printf "[%d/%d] %s ... " "$IDX" "$TOTAL" "$FILE"
+
+  if NODE_OPTIONS='--import ./scripts/termux-shim.js --max-old-space-size=384' \
+     npx vitest run "$FILE" --reporter=dot --no-coverage > /tmp/vitest-out.log 2>&1; then
+    echo "PASS"
+    PASS=$((PASS + 1))
+  else
+    echo "FAIL"
+    FAIL=$((FAIL + 1))
+    FAILED_FILES+=("$FILE")
+    tail -20 /tmp/vitest-out.log
+  fi
+
+  # let the OS reclaim memory between runs
+  sleep 1
+done
+
+echo ""
+echo "=========================================="
+echo "Total: $TOTAL | Passed: $PASS | Failed: $FAIL"
+echo "=========================================="
+
+if [ ${#FAILED_FILES[@]} -gt 0 ]; then
+  echo ""
+  echo "Failed files:"
+  printf '  %s\n' "${FAILED_FILES[@]}"
+  exit 1
+fi

backend/src/app.ts

@@ -0,0 +1,548 @@
+import './instrument.js';
+import 'dotenv/config';
+import dns from 'node:dns';
+import { startCipherRotation } from './utils/network/cipher.util.js';
+
+startCipherRotation();
+import express, { Request, Response, NextFunction } from 'express';
+import compression from 'compression';
+import helmet from 'helmet';
+import { rateLimit } from 'express-rate-limit';
+import * as Sentry from '@sentry/node'; // skipcq: JS-C1003
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { traceContext } from './utils/infra/trace.util.js';
+import { randomUUID } from 'node:crypto';
+import db from './utils/infra/db.util.js';
+import videoRoutes from './routes/video.routes.js';
+import keyChangerRoutes from './routes/keychanger.routes.js';
+import remixRoutes from './routes/remix.routes.js';
+import {
+  requireApiKey,
+  requireLocalOrApiKey,
+  assertProdConfig,
+} from './utils/network/auth.util.js';
+import { logger } from './utils/infra/logger.util.js';
+import { setupGracefulShutdown } from './utils/infra/shutdown.util.js';
+import { configureServerTimeouts } from './utils/infra/server-timeouts.util.js';
+import { closeAllRedis } from './utils/infra/redis.util.js';
+import {
+  metricsMiddleware,
+  getMetrics,
+  recordFailure,
+} from './utils/infra/metrics.util.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const fsPromises = fs.promises;
+const STEMS_BASE_DIR = path.join(__dirname, '../temp/remix_stems');
+
+// termux bypass
+if (process.platform === 'android') {
+  try {
+    const { Module } = await import('module');
+    const originalRequire = Module.prototype.require;
+    Module.prototype.require = function (
+      this: unknown,
+      name: string,
+      ...args: unknown[]
+    ) {
+      if (name === '@ffmpeg-installer/ffmpeg') {
+        return {
+          path: 'ffmpeg',
+          version: 'system',
+          url: 'https://ffmpeg.org/',
+        };
+      }
+      if (name.includes('libsql')) {
+        try {
+          return (
+            originalRequire as (...innerArgs: unknown[]) => unknown
+          ).apply(this, [name, ...args]);
+        } catch (_ERROR) {
+          console.debug('[System] LibSQL bypass error:', _ERROR);
+          console.warn(
+            `[System] LibSQL native library '${name}' not found, bypassing...`
+          );
+          return {
+            createClient: () => ({
+              execute: () => Promise.resolve({ rows: [] }),
+              batch: () => Promise.resolve([]),
+              close: () => {},
+            }),
+          };
+        }
+      }
+      if (name === 'msgpackr-extract' || name === 'cpu-features') {
+        return null;
+      }
+      return (originalRequire as (...innerArgs: unknown[]) => unknown).apply(
+        this,
+        [name, ...args]
+      );
+    };
+    console.log('[System] Mocked native modules for Termux compatibility');
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(
+      `[System] Failed to mock @ffmpeg-installer/ffmpeg: ${message}`
+    );
+  }
+}
+
+const dnsModule = dns as unknown as {
+  setDefaultResultOrder?: (order: 'ipv4first' | 'ipv6first') => void;
+};
+if (dnsModule.setDefaultResultOrder) {
+  dnsModule.setDefaultResultOrder('ipv4first');
+}
+
+// global errors
+process.on('unhandledRejection', (reason: unknown) => {
+  const message = reason instanceof Error ? reason.message : String(reason);
+  console.error(`[Unhandled] reason: ${message}`);
+});
+process.on('uncaughtException', (err: unknown) => {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(`[Uncaught] error: ${message}`);
+  if (err instanceof Error && err.stack) console.error(err.stack);
+});
+
+const app = express();
+app.set('trust proxy', 1);
+
+// observe latency + outcomes
+app.use(metricsMiddleware);
+
+const PORT = Number(process.env.PORT) || 5000;
+
+app.use(
+  helmet({
+    crossOriginResourcePolicy: { policy: 'cross-origin' },
+    contentSecurityPolicy: {
+      directives: {
+        defaultSrc: ["'self'"],
+        scriptSrc: ["'self'", "'unsafe-inline'"],
+        styleSrc: ["'self'", "'unsafe-inline'"],
+        imgSrc: ["'self'", 'data:', 'https:'],
+        connectSrc: ["'self'", 'https:', 'wss:'],
+      },
+    },
+  })
+);
+
+const globalLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max: 100,
+  standardHeaders: true,
+  legacyHeaders: false,
+  message: { error: 'Too many requests, please try again later.' },
+});
+
+app.use('/api/', globalLimiter);
+
+const infoLimiter = rateLimit({
+  windowMs: 1 * 60 * 1000,
+  max: 15,
+  standardHeaders: true,
+  legacyHeaders: false,
+  message: { error: 'Extraction rate limit exceeded. Slow down!' },
+});
+
+app.use(['/info', '/stream-urls'], infoLimiter);
+
+// disable SSE compression
+app.use(
+  compression({
+    filter: (req, res) => {
+      if (req.path === '/events') return false;
+      if (res.getHeader('Content-Type') === 'text/event-stream') return false;
+      return compression.filter(req, res);
+    },
+  })
+);
+
+app.use((req: Request, res: Response, next: NextFunction) => {
+  const traceId =
+    (req.headers['x-correlation-id'] as string) ||
+    (req.query.id as string) ||
+    randomUUID().split('-')[0];
+
+  res.setHeader('X-Trace-Id', traceId);
+
+  Sentry.withIsolationScope((scope) => {
+    if (process.env.SENTRY_DSN) {
+      scope.setTag('traceId', traceId);
+    }
+
+    traceContext.run({ traceId }, () => {
+      next();
+    });
+  });
+});
+
+app.use((req: Request, res: Response, next: NextFunction) => {
+  if (req.path === '/ping' || req.method === 'OPTIONS') {
+    next();
+    return;
+  }
+  const timestamp = new Date().toLocaleTimeString('en-US', {
+    hour12: false,
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+  });
+  const traceId =
+    (traceContext.getStore() as { traceId?: string })?.traceId || 'global';
+  console.log(
+    `[${timestamp}] [${traceId}] ${req.method} ${req.originalUrl || req.url}`
+  );
+  next();
+});
+
+// cors middleware
+app.use((req: Request, res: Response, next: NextFunction) => {
+  const origin = req.headers.origin as string | undefined;
+  const allowlist = (process.env.ALLOWED_ORIGINS || '')
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  if (origin) {
+    const openMode = allowlist.length === 0;
+    if (openMode || allowlist.includes(origin)) {
+      res.header('Access-Control-Allow-Origin', origin);
+      res.header('Vary', 'Origin');
+      // credentials unsafe with reflected origin
+      if (!openMode) res.header('Access-Control-Allow-Credentials', 'true');
+    }
+  }
+  res.header(
+    'Access-Control-Allow-Methods',
+    'GET, POST, PUT, DELETE, OPTIONS, PATCH'
+  );
+  res.header(
+    'Access-Control-Allow-Headers',
+    'Origin, X-Requested-With, Content-Type, Accept, Authorization, Cache-Control, Last-Event-ID, ngrok-skip-browser-warning, bypass-tunnel-reminder, sentry-trace, baggage'
+  );
+
+  if (req.method === 'OPTIONS') {
+    res.status(200).end();
+    return;
+  }
+  next();
+});
+
+console.log('--- Environment Check ---');
+console.log(`PORT: ${PORT}`);
+console.log(
+  `COOKIES_URL: ${process.env.COOKIES_URL ? '✅ LOADED' : '❌ MISSING'}`
+);
+console.log(
+  `GEMINI_API_KEY: ${process.env.GEMINI_API_KEY ? '✅ LOADED' : '❌ MISSING'}`
+);
+console.log(
+  `GROQ_API_KEY: ${process.env.GROQ_API_KEY ? '✅ LOADED' : '❌ MISSING'}`
+);
+console.log(
+  `INFO CACHE: ${process.env.DISABLE_INFO_CACHE && process.env.DISABLE_INFO_CACHE !== '0' ? '🚫 DISABLED (testing)' : '✅ ENABLED'}`
+);
+
+dns.lookup('google.com', { family: 4 }, (err, addr) => {
+  const status = err ? '❌ FAILED' : `✅ ${addr}`;
+  console.log(`DNS google.com: ${status}`);
+});
+dns.lookup('youtube.com', { family: 4 }, (err, addr) => {
+  const status = err ? '❌ FAILED' : `✅ ${addr}`;
+  console.log(`DNS youtube.com: ${status}`);
+});
+console.log('-------------------------');
+
+app.use((_req: Request, res: Response, next: NextFunction) => {
+  res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
+  res.setHeader('Cross-Origin-Embedder-Policy', 'credentialless');
+  res.setHeader('Cross-Origin-Resource-Policy', 'cross-origin');
+  next();
+});
+
+app.use(express.json({ limit: '1mb' }));
+app.use(express.urlencoded({ limit: '1mb', extended: true }));
+
+// core routes
+const TEMP_DIR = path.join(__dirname, 'temp');
+const CACHE_DIR = path.join(TEMP_DIR, 'yt-dlp-cache');
+
+[TEMP_DIR, CACHE_DIR].forEach((dir) => {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+});
+
+console.log('[System] Initializing routes...');
+app.get('/ping', (_req: Request, res: Response) => {
+  res.status(200).send('pong');
+});
+
+app.get('/api/get-url', async (_req: Request, res: Response) => {
+  try {
+    if (db) {
+      const result = (await db.execute({
+        sql: "SELECT value FROM configs WHERE key = 'BACKEND_URL' LIMIT 1",
+        args: [],
+      })) as unknown as { rows: Array<{ value: string }> };
+      if (result.rows.length > 0) {
+        res.json({ url: result.rows[0].value });
+        return;
+      }
+    }
+  } catch (error) {
+    console.error('[Discovery] Error fetching URL:', error);
+  }
+  res.json({ url: null });
+});
+
+// opt-in auth; off unless API_KEY set
+app.use(
+  [
+    '/info',
+    '/stream-urls',
+    '/convert',
+    '/proxy',
+    '/api/remix',
+    '/api/key-changer',
+  ],
+  requireApiKey
+);
+app.use('/', videoRoutes);
+app.use('/api/key-changer', keyChangerRoutes);
+app.use('/api/remix', remixRoutes);
+console.log('[System] Routes ready');
+
+if (process.env.SENTRY_DSN) {
+  Sentry.setupExpressErrorHandler(app);
+}
+
+app.get('/health', (_req: Request, res: Response) => {
+  res.status(200).json({
+    status: 'ok',
+    port: PORT,
+  });
+});
+
+// gated: localhost or API_KEY only
+app.get('/metrics', requireLocalOrApiKey, (_req: Request, res: Response) => {
+  res.status(200).json(getMetrics());
+});
+
+// global error handler
+app.use((err: unknown, req: Request, res: Response, _next: NextFunction) => {
+  const reason = err instanceof Error ? err.name : 'UnknownError';
+  recordFailure(reason);
+  logger.error({ err, path: req.path, method: req.method }, 'request error');
+  if (!res.headersSent) {
+    // hide internals from clients in production
+    const details =
+      process.env.NODE_ENV === 'production'
+        ? undefined
+        : err instanceof Error
+          ? err.message
+          : typeof err === 'string'
+            ? err
+            : JSON.stringify(err);
+    res.status(500).json({ error: 'Internal Server Error', details });
+  }
+});
+
+const distPath = path.join(__dirname, '../../frontend/dist');
+
+if (fs.existsSync(distPath) && process.env.API_ONLY !== 'true') {
+  app.use(express.static(distPath));
+  app.get(/.*/u, (req: Request, res: Response, next: NextFunction) => {
+    if (
+      req.path.startsWith('/events') ||
+      req.path.startsWith('/info') ||
+      req.path.startsWith('/convert') ||
+      req.path.startsWith('/stream-urls') ||
+      req.path.startsWith('/proxy') ||
+      req.path.startsWith('/api') ||
+      req.path.includes('/EME_STREAM_DOWNLOAD/')
+    ) {
+      next();
+      return;
+    }
+
+    res.sendFile(path.join(distPath, 'index.html'));
+  });
+} else {
+  app.get('/', (_req: Request, res: Response) => {
+    res.send('YouTube to MP4 Backend is running!');
+  });
+}
+
+export default app;
+
+if (process.env.NODE_ENV !== 'test') {
+  assertProdConfig();
+  const server = app.listen(PORT, '0.0.0.0', () => {
+    console.log(`Server is running on port ${PORT}`);
+
+    configureServerTimeouts(server);
+
+    setupGracefulShutdown(server, { onClose: closeAllRedis });
+
+    import('./services/ytdlp/config.js').then(({ bootstrapCookies }) =>
+      bootstrapCookies()
+    );
+
+    import('node:child_process').then(({ exec, spawn: spawnChild }) => {
+      exec('yt-dlp --version', (err, stdout) => {
+        if (err) console.error(`yt-dlp check failed: ${err.message}`);
+        else console.log(`yt-dlp: ${stdout.trim()}`);
+      });
+
+      exec('ffmpeg -version', (err, stdout) => {
+        if (err) console.error(`FFmpeg check failed: ${err.message}`);
+        else console.log(`FFmpeg: ${stdout.split('\n')[0]}`);
+      });
+
+      // pot opt-in; bgutil currently fails botguard
+      const potEnabled = process.env.ENABLE_POT_PLUGIN === '1';
+      if (!potEnabled) {
+        console.log('[PO Token] disabled; set ENABLE_POT_PLUGIN=1 to enable');
+      } else {
+        const potCandidates = [
+          process.env.HOME
+            ? path.resolve(
+                process.env.HOME,
+                'bgutil-ytdlp-pot-provider/server/build/main.js'
+              )
+            : null,
+          '/root/bgutil-ytdlp-pot-provider/server/build/main.js',
+          '/data/data/com.termux/files/home/bgutil-ytdlp-pot-provider/server/build/main.js',
+        ].filter((candidate): candidate is string => Boolean(candidate));
+        try {
+          const potScript = potCandidates.find((candidate) =>
+            fs.existsSync(candidate)
+          );
+          if (potScript) {
+            const pot = spawnChild('node', [potScript], {
+              stdio: 'ignore',
+              detached: true,
+            });
+            pot.unref();
+            console.log(
+              `PO Token server started (pid: ${pot.pid}, port: 4416)`
+            );
+          } else {
+            console.log(
+              `[PO Token] Server script not found in: ${potCandidates.join(', ')}`
+            );
+          }
+        } catch (error: unknown) {
+          console.error('[PO Token] Spawn failed:', (error as Error).message);
+        }
+      }
+    });
+
+    // warm YT client
+    (async () => {
+      const warmStart = Date.now();
+      try {
+        const { getYoutubeClient } =
+          await import('./services/extractors/youtube/client.js');
+        await getYoutubeClient();
+        console.log(
+          `[Warmup] Innertube client ready in ${Date.now() - warmStart}ms`
+        );
+      } catch (error) {
+        console.warn(
+          '[Warmup] Innertube pre-warm failed (will retry on first request):',
+          error instanceof Error ? error.message : error
+        );
+      }
+    })();
+
+    // avoid first request lazy load delay
+    (async () => {
+      const warmStart = Date.now();
+      try {
+        await Promise.all([
+          import('./services/extractors/index.js'),
+          import('./utils/api/response.util.js'),
+          import('./services/ytdlp/config.js'),
+          import('./utils/network/cookie.util.js'),
+        ]);
+        console.log(
+          `[Warmup] Hot-path modules ready in ${Date.now() - warmStart}ms`
+        );
+      } catch (error) {
+        console.warn(
+          '[Warmup] Hot-path module prewarm failed:',
+          error instanceof Error ? error.message : error
+        );
+      }
+    })();
+  });
+}
+
+interface DBExecutor {
+  execute: (options: {
+    sql: string;
+    args: unknown[];
+  }) => Promise<{ rows: { id: string }[] }>;
+}
+
+async function cleanupTempFiles(): Promise<void> {
+  try {
+    const files: string[] = await fsPromises.readdir(TEMP_DIR);
+    const now: number = Date.now();
+
+    for (const file of files) {
+      const filePath: string = path.join(TEMP_DIR, file);
+      const stats: fs.Stats = await fsPromises.lstat(filePath);
+
+      if (stats.isFile() && now - stats.mtimeMs > 3600000) {
+        await fsPromises.unlink(filePath).catch(() => {
+          /* ignore */
+        });
+      }
+    }
+
+    const threeDaysMs: number = 3 * 24 * 60 * 60 * 1000;
+    if (db) {
+      const executor = db as unknown as DBExecutor;
+      const expired = await executor.execute({
+        sql: 'SELECT id FROM remix_history WHERE created_at < ?',
+        args: [now - threeDaysMs],
+      });
+
+      for (const row of expired.rows) {
+        const dirPath: string = path.join(STEMS_BASE_DIR, row.id);
+        if (fs.existsSync(dirPath)) {
+          await fsPromises
+            .rm(dirPath, { recursive: true, force: true })
+            .catch(() => {
+              /* ignore */
+            });
+        }
+        await executor.execute({
+          sql: 'DELETE FROM remix_history WHERE id = ?',
+          args: [row.id],
+        });
+        console.log(`[Janitor] Cleaned up expired remix: ${row.id}`);
+      }
+    }
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`[Cleanup] Error reading temp directory: ${message}`);
+  }
+}
+
+const tempCleanupInterval = setInterval(() => {
+  cleanupTempFiles().catch(() => {
+    /* ignore */
+  });
+}, 3600000);
+// allow process exit
+tempCleanupInterval.unref?.();

backend/src/controllers/keychanger.controller.ts

@@ -0,0 +1,346 @@
+import multer from 'multer';
+import ffmpeg from 'fluent-ffmpeg';
+import { dirname, join, extname, basename } from 'node:path';
+import { resolveWithin } from '../utils/network/security.util.js';
+import { existsSync, mkdirSync, readFileSync, unlink } from 'node:fs';
+import wav from 'wav-decoder';
+import { fileURLToPath } from 'node:url';
+import { Request, Response } from 'express';
+import { randomBytes } from 'node:crypto';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const TEMP_DIR = join(__dirname, '../../temp');
+const uploadDir = join(TEMP_DIR, 'uploads');
+const processedDir = join(TEMP_DIR, 'processed');
+
+import { ChordsResult } from '../types/index.js';
+
+interface EssentiaVector {
+  delete: () => void;
+}
+
+interface EssentiaPCVVector extends EssentiaVector {
+  push_back: (val: EssentiaVector) => void;
+}
+
+interface EssentiaInstance {
+  arrayToVector: (arr: Float32Array) => EssentiaVector;
+  vectorToArray: (vec: EssentiaVector) => string[] | number[];
+  KeyExtractor: (vec: EssentiaVector) => { key: string; scale: string };
+  Windowing: (vec: EssentiaVector) => { frame: EssentiaVector };
+  Spectrum: (vec: EssentiaVector) => { spectrum: EssentiaVector };
+  SpectralPeaks: (vec: EssentiaVector) => {
+    frequencies: EssentiaVector;
+    magnitudes: EssentiaVector;
+  };
+  HPCP: (
+    freqs: EssentiaVector,
+    mags: EssentiaVector
+  ) => { hpcp: EssentiaVector };
+  ChordsDetection: (vec: EssentiaPCVVector) => { chords: EssentiaVector };
+  module: {
+    VectorVectorFloat: new () => EssentiaPCVVector;
+  };
+}
+
+let essentia: EssentiaInstance | null = null;
+
+async function getEssentia(): Promise<EssentiaInstance | null> {
+  if (essentia) return essentia;
+  try {
+    const { default: EssentiaModule } =
+      await (import('essentia.js') as unknown as {
+        default: {
+          Essentia: new (wasm: unknown) => EssentiaInstance;
+          EssentiaWASM: unknown;
+        };
+      });
+    essentia = new EssentiaModule.Essentia(EssentiaModule.EssentiaWASM);
+    return essentia;
+  } catch (error: unknown) {
+    console.error('❌ Essentia WASM failed', (error as Error).message);
+    return null;
+  }
+}
+
+[uploadDir, processedDir].forEach((dir) => {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+});
+
+const storage = multer.diskStorage({
+  destination: (_req, _file, callback) => {
+    callback(null, uploadDir);
+  },
+  filename: (_req, file, callback) => {
+    const safeName = file.originalname.replace(/[^a-zA-Z0-9.-]/gu, '_');
+    callback(null, `${Date.now()}-${safeName}`);
+  },
+});
+
+export const upload = multer({
+  storage,
+  limits: { fileSize: 100 * 1024 * 1024 }, // max 100mb
+});
+
+const keyMap: Record<string, number> = {
+  C: 0,
+  'C#': 1,
+  Db: 1,
+  D: 2,
+  'D#': 3,
+  Eb: 3,
+  E: 4,
+  F: 5,
+  'F#': 6,
+  Gb: 6,
+  G: 7,
+  'G#': 8,
+  Ab: 8,
+  A: 9,
+  'A#': 10,
+  Bb: 10,
+  B: 11,
+};
+
+const _generateChords = (
+  essentiaInstance: EssentiaInstance,
+  signal: Float32Array
+) => {
+  const frameSize = 4096;
+  const hopSize = 2048;
+  const pcpVector = new essentiaInstance.module.VectorVectorFloat();
+
+  for (let i = 0; i < Math.min(signal.length, 44100 * 30); i += hopSize) {
+    if (i + frameSize > signal.length) break;
+    const frame = signal.slice(i, i + frameSize);
+    const frameVec = essentiaInstance.arrayToVector(frame);
+    const windowed = essentiaInstance.Windowing(frameVec).frame;
+    const spectrum = essentiaInstance.Spectrum(windowed).spectrum;
+    const peaks = essentiaInstance.SpectralPeaks(spectrum);
+    const hpcp = essentiaInstance.HPCP(
+      peaks.frequencies,
+      peaks.magnitudes
+    ).hpcp;
+    pcpVector.push_back(hpcp);
+    frameVec.delete();
+  }
+
+  const chordsResult = essentiaInstance.ChordsDetection(pcpVector);
+  const uniqueChords: string[] = [];
+
+  if (chordsResult?.chords) {
+    const chordsArray = essentiaInstance.vectorToArray(
+      chordsResult.chords
+    ) as string[];
+    chordsArray.forEach((chord: string) => {
+      if (uniqueChords[uniqueChords.length - 1] !== chord) {
+        uniqueChords.push(chord);
+      }
+    });
+  }
+
+  pcpVector.delete();
+  return uniqueChords;
+};
+
+const _handleAudioDecoding = (
+  essentiaInstance: EssentiaInstance,
+  buffer: Buffer,
+  tempWavPath: string,
+  resolve: (value: ChordsResult | PromiseLike<ChordsResult>) => void,
+  reject: (reason?: unknown) => void
+) => {
+  wav
+    .decode(buffer)
+    .then((audioData: { channelData: Float32Array[] }) => {
+      const signal = audioData.channelData[0];
+      const audioVector = essentiaInstance.arrayToVector(signal);
+      const keyResult = essentiaInstance.KeyExtractor(audioVector);
+
+      const uniqueChords = _generateChords(essentiaInstance, signal);
+
+      audioVector.delete();
+      unlink(tempWavPath, (_error) => {});
+
+      resolve({
+        key: keyResult.key,
+        scale: keyResult.scale,
+        chords: uniqueChords.filter((chord) => chord !== 'N').slice(0, 12),
+      });
+    })
+    .catch((error: Error) => {
+      unlink(tempWavPath, (_error) => {});
+      reject(error);
+    });
+};
+
+const detectKeyFromFile = async (filePath: string): Promise<ChordsResult> => {
+  const essentiaInstance = await getEssentia();
+  if (!essentiaInstance) throw new Error('Essentia engine not available');
+
+  return new Promise((resolve, reject) => {
+    const randomId = randomBytes(4).toString('hex');
+    const tempWavPath = join(uploadDir, `temp-${Date.now()}-${randomId}.wav`);
+
+    ffmpeg(filePath)
+      .toFormat('wav')
+      .audioChannels(1)
+      .audioFrequency(44100)
+      .on('end', () => {
+        const buffer = readFileSync(tempWavPath);
+        _handleAudioDecoding(
+          essentiaInstance,
+          buffer,
+          tempWavPath,
+          resolve,
+          reject
+        );
+      })
+      .on('error', (error: Error) => {
+        unlink(tempWavPath, (_error) => {});
+        reject(error);
+      })
+      .save(tempWavPath);
+  });
+};
+
+export const detectKey = async (req: Request, res: Response): Promise<void> => {
+  if (!req.file) {
+    res.status(400).json({ error: 'No file uploaded' });
+    return;
+  }
+
+  try {
+    const result = await detectKeyFromFile(req.file.path);
+    res.json(result);
+  } catch (error) {
+    console.error('[KeyChanger] Detection Error:', error);
+    res.status(500).json({ error: 'Audio analysis failed' });
+  } finally {
+    unlink(req.file.path, (_error) => {});
+  }
+};
+
+export const detectProcessedKey = async (
+  req: Request,
+  res: Response
+): Promise<void> => {
+  const filename = String(req.params.filename);
+  const filePath = resolveWithin(processedDir, filename);
+
+  if (!filePath) {
+    res.status(400).json({ error: 'Invalid path' });
+    return;
+  }
+  if (!existsSync(filePath)) {
+    res.status(404).json({ error: 'File not found' });
+    return;
+  }
+
+  try {
+    const result = await detectKeyFromFile(filePath);
+    res.json(result);
+  } catch (error) {
+    console.error('[KeyChanger] Processed Detection Error:', error);
+    res.status(500).json({ error: 'Analysis failed' });
+  }
+};
+
+export const convertKey = (req: Request, res: Response): void => {
+  if (!req.file) {
+    res.status(400).json({ error: 'No file uploaded' });
+    return;
+  }
+
+  const { originalKey, targetKey } = req.body;
+
+  if (
+    !originalKey ||
+    !targetKey ||
+    keyMap[originalKey] === undefined ||
+    keyMap[targetKey] === undefined
+  ) {
+    unlink(req.file.path, (_error) => {});
+    res.status(400).json({ error: 'Invalid keys provided' });
+    return;
+  }
+
+  const originalVal = keyMap[originalKey];
+  const targetVal = keyMap[targetKey];
+  let semitones = targetVal - originalVal;
+  if (semitones > 6) semitones -= 12;
+  if (semitones < -6) semitones += 12;
+
+  const pitchScale = Math.pow(2, semitones / 12);
+  const inputPath = req.file.path;
+  const extension = extname(req.file.originalname);
+  const baseNamePart = basename(req.file.originalname, extension).replace(
+    /[^a-zA-Z0-9\s.-]/gu,
+    '_'
+  );
+  const outputFilename = `${Date.now()}__${targetKey}__${baseNamePart}${extension}`;
+  const outputPath = join(processedDir, outputFilename);
+
+  ffmpeg(inputPath)
+    .audioFilters(`rubberband=pitch=${pitchScale}`)
+    .on('end', () => {
+      const protocol =
+        (req.headers['x-forwarded-proto'] as string) || req.protocol;
+      const host = req.headers.host;
+      res.json({
+        success: true,
+        filename: outputFilename,
+        downloadUrl: `${protocol}://${host}/api/key-changer/download/${outputFilename}`,
+      });
+      unlink(inputPath, (_error) => {});
+    })
+    .on('error', (error: unknown) => {
+      const errorObj = error as Error;
+      console.error('[KeyChanger] Conversion Error:', errorObj.message);
+      if (!res.headersSent)
+        res
+          .status(500)
+          .json({ error: 'Conversion failed.', details: errorObj.message });
+      unlink(inputPath, (_error) => {});
+    })
+    .save(outputPath);
+};
+
+export const downloadFile = (req: Request, res: Response): void => {
+  const filename = String(req.params.filename);
+  const filePath = resolveWithin(processedDir, filename);
+
+  if (!filePath) {
+    res.status(400).json({ error: 'Invalid path' });
+    return;
+  }
+  if (existsSync(filePath)) {
+    let prettyName = filename;
+    const parts = filename.split('__');
+    if (parts.length >= 3) {
+      const key = parts[1];
+      const nameWithExt = parts.slice(2).join('__');
+      const extension = extname(nameWithExt);
+      const baseNamePart = basename(nameWithExt, extension);
+      const cleanName = baseNamePart.replace(/_+/gu, ' ').trim();
+      prettyName = `(${key}) ${cleanName}${extension}`;
+    }
+
+    res.download(filePath, prettyName, (error) => {
+      if (error) {
+        const errorWithCode = error as Error & { code?: string };
+        if (
+          errorWithCode.code === 'ECONNABORTED' ||
+          errorWithCode.code === 'EPIPE'
+        ) {
+          return;
+        }
+        console.error('[KeyChanger] Download Error:', error);
+      }
+    });
+  } else {
+    res.status(404).json({ error: 'File not found' });
+  }
+};

backend/src/controllers/remix.controller.ts

@@ -0,0 +1,703 @@
+import { Request, Response } from 'express';
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'node:url';
+import db from '../utils/infra/db.util.js';
+import { extractSongData } from '../services/extract.service.js';
+import { spawn } from 'child_process';
+import { randomUUID } from 'node:crypto';
+import { Readable } from 'node:stream';
+import os from 'node:os';
+import { z } from 'zod';
+import { secureFetch, resolveWithin } from '../utils/network/security.util.js';
+
+const EngineStartResponseSchema = z
+  .object({
+    task_id: z.string().optional(),
+    message: z.string().optional(),
+  })
+  .catchall(z.unknown());
+
+const EngineStatusResponseSchema = z
+  .object({
+    status: z.string(),
+    message: z.string().optional(),
+    data: z
+      .object({
+        stems: z
+          .record(z.string(), z.string().nullable().optional())
+          .optional(),
+        package: z.string().nullable().optional(),
+      })
+      .catchall(z.unknown())
+      .optional(),
+  })
+  .catchall(z.unknown());
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const STEMS_BASE_DIR = path.join(__dirname, '../../temp/remix_stems');
+if (!fs.existsSync(STEMS_BASE_DIR)) {
+  fs.mkdirSync(STEMS_BASE_DIR, { recursive: true });
+}
+
+const sessionEngines = new Map<string, string>();
+
+export const registerEngine = (req: Request, res: Response): void => {
+  const { url, session_id } = req.body || {};
+  console.log(
+    `[Engine] Registration attempt: session=${session_id} url=${url}`
+  );
+
+  if (!url || !session_id) {
+    console.error('[Engine] Registration failed: Missing url or session_id');
+    res.status(400).json({ error: 'URL and session_id required' });
+    return;
+  }
+  sessionEngines.set(session_id, url);
+  console.log(`[Engine] Successfully registered: ${session_id} -> ${url}`);
+  res.json({ success: true, url, session_id });
+};
+
+export const getEngineStatus = (req: Request, res: Response): void => {
+  const sessionId = req.query.session_id as string;
+  if (!sessionId) {
+    res.json({ url: null, error: 'session_id required' });
+    return;
+  }
+  const url = sessionEngines.get(sessionId) || null;
+  if (url)
+    console.log(`[Engine] Status check: session=${sessionId} found=${url}`);
+  res.json({ url });
+};
+
+export const processAudio = async (
+  req: Request,
+  res: Response
+): Promise<void> => {
+  const { engine, stems, session_id } = req.body;
+  console.log(
+    `[Process] Request received: engine=${engine} stems=${stems} session_id=${session_id}`
+  );
+
+  const engineUrlRaw = session_id ? sessionEngines.get(session_id) : null;
+  console.log(
+    `[Process] Engine lookup: session_id=${session_id} -> url=${engineUrlRaw}`
+  );
+
+  if (!engineUrlRaw) {
+    console.error(
+      `[Process] Failed: No engine mapped for session ${session_id}`
+    );
+    res.status(400).json({ error: 'Engine not connected or session expired' });
+    return;
+  }
+  if (!req.file) {
+    console.error('[Process] Failed: No file uploaded');
+    res.status(400).json({ error: 'No file uploaded' });
+    return;
+  }
+
+  try {
+    const form = new FormData();
+    const fileBuffer = fs.readFileSync(req.file.path);
+    const fileBlob = new Blob([fileBuffer], { type: req.file.mimetype });
+    form.append('file', fileBlob, req.file.originalname);
+    form.append('engine', engine || 'Demucs');
+    form.append('stems', stems || '4 Stems');
+
+    const engineUrl = engineUrlRaw.replace(/\/$/, '');
+    console.log(`[Process] Forwarding to engine: ${engineUrl}/process`);
+
+    const startRes = await secureFetch(`${engineUrl}/process`, {
+      method: 'POST',
+      body: form,
+    });
+
+    console.log(`[Process] Engine response status: ${startRes.status}`);
+
+    if (!startRes.ok) {
+      const rawErr = await startRes.json().catch(() => ({}));
+      console.error('[Process] Engine error response:', rawErr);
+      const startData = EngineStartResponseSchema.safeParse(rawErr);
+      const errMessage = startData.success
+        ? startData.data.message
+        : undefined;
+      throw new Error(errMessage || `Engine error ${startRes.status}`);
+    }
+
+    const rawStartData = await startRes.json();
+    const startData = EngineStartResponseSchema.safeParse(rawStartData);
+    if (!startData.success || !startData.data.task_id) {
+      throw new Error('Failed to get task_id from engine');
+    }
+    const task_id = startData.data.task_id;
+
+    let attempts = 0;
+    const maxAttempts = 240;
+    const poll = async () => {
+      attempts++;
+      try {
+        const statusRes = await secureFetch(`${engineUrl}/status/${task_id}`);
+        if (!statusRes.ok)
+          throw new Error(`Status check failed: ${statusRes.status}`);
+        const rawTaskData = await statusRes.json();
+        const taskParsed = EngineStatusResponseSchema.safeParse(rawTaskData);
+        if (!taskParsed.success) {
+          throw new Error(
+            `Engine status parse error: ${taskParsed.error.message}`
+          );
+        }
+        const task = taskParsed.data;
+        if (task.status === 'success') {
+          const finalData = task.data;
+          if (!finalData || !finalData.stems)
+            throw new Error('Missing stems data');
+          Object.keys(finalData.stems).forEach((key) => {
+            if (finalData.stems?.[key]) {
+              finalData.stems[key] =
+                `${engineUrl}/download?path=${encodeURIComponent(finalData.stems[key])}`;
+            }
+          });
+          if (finalData.package) {
+            finalData.package = `${engineUrl}/download?path=${encodeURIComponent(finalData.package)}`;
+          }
+          res.json(finalData);
+          return;
+        } else if (task.status === 'error') {
+          throw new Error(task.message || 'Unknown engine error');
+        }
+        if (attempts >= maxAttempts) throw new Error('Processing timed out');
+        setTimeout(poll, 5000);
+      } catch (error: unknown) {
+        if (!res.headersSent)
+          res.status(500).json({
+            error: `polling failed: ${error instanceof Error ? error.message : String(error)}`,
+          });
+      }
+    };
+    setTimeout(poll, 5000);
+  } catch (error: unknown) {
+    if (!res.headersSent)
+      res.status(500).json({
+        error: `engine failed: ${error instanceof Error ? error.message : String(error)}`,
+      });
+  } finally {
+    if (req.file && fs.existsSync(req.file.path)) fs.unlinkSync(req.file.path);
+  }
+};
+
+export const wakeEngine = async (
+  req: Request,
+  res: Response
+): Promise<void> => {
+  const { kaggleUsername, kaggleKey } = req.body;
+  let { backendUrl } = req.body;
+
+  // fallback to DB
+  if (
+    !backendUrl ||
+    backendUrl.includes('localhost') ||
+    backendUrl.includes('127.0.0.1')
+  ) {
+    try {
+      const dbResult = await db?.execute({
+        sql: "SELECT value FROM configs WHERE key = 'BACKEND_URL' LIMIT 1",
+        args: [],
+      });
+      const rows = dbResult?.rows;
+      if (rows && rows.length > 0) {
+        console.log(
+          `[Engine] Overriding localhost with public URL from DB: ${rows[0].value}`
+        );
+        backendUrl = rows[0].value as string;
+      }
+    } catch (error) {
+      console.error('[Engine] DB URL lookup failed:', error);
+    }
+  }
+
+  console.log(
+    `[Engine] Wake-engine request: user=${kaggleUsername} backendUrl=${backendUrl}`
+  );
+
+  const finalUsername = kaggleUsername || process.env.KAGGLE_USERNAME;
+  const finalKey = kaggleKey || process.env.KAGGLE_KEY;
+
+  if (!finalUsername || !finalKey) {
+    res.status(401).json({ error: 'Kaggle credentials required' });
+    return;
+  }
+
+  const sessionId = randomUUID();
+  const tmpBase = os.tmpdir();
+  const KAGGLE_TMP_DIR = path.join(tmpBase, `.kaggle-${sessionId}`);
+  const WORKSPACE_DIR = path.join(tmpBase, `workspace-${sessionId}`);
+
+  try {
+    // isolate auth
+    if (!fs.existsSync(KAGGLE_TMP_DIR))
+      fs.mkdirSync(KAGGLE_TMP_DIR, { recursive: true });
+    fs.writeFileSync(
+      path.join(KAGGLE_TMP_DIR, 'kaggle.json'),
+      JSON.stringify({ username: finalUsername, key: finalKey })
+    );
+
+    // ephemeral metadata
+    if (!fs.existsSync(WORKSPACE_DIR))
+      fs.mkdirSync(WORKSPACE_DIR, { recursive: true });
+
+    const scriptsDir = path.join(__dirname, '../../../scripts');
+    const metadataPath = path.join(scriptsDir, 'kernel-metadata.json');
+    const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+
+    // update metadata
+    metadata.id = `${finalUsername}/nexstream-engine-${sessionId.substring(0, 8)}`;
+    metadata.title = `NexStream Engine ${sessionId.substring(0, 8)}`;
+    metadata.code_file = 'run_engine.py';
+    metadata.accelerator = 'NvidiaTeslaT4'; // set accelerator
+
+    fs.writeFileSync(
+      path.join(WORKSPACE_DIR, 'kernel-metadata.json'),
+      JSON.stringify(metadata)
+    );
+
+    // inject env
+    const engineScriptPath = path.join(scriptsDir, 'remix_lab_btc.py');
+    const baseScript = fs.readFileSync(engineScriptPath, 'utf-8');
+    const safeBackendUrl = JSON.stringify(backendUrl);
+    const safeSessionId = JSON.stringify(sessionId);
+    const injectedScript = `
+import os
+os.environ["NEXSTREAM_BACKEND_URL"] = ${safeBackendUrl}
+os.environ["NEXSTREAM_SESSION_ID"] = ${safeSessionId}
+
+${baseScript}
+    `;
+    fs.writeFileSync(path.join(WORKSPACE_DIR, 'run_engine.py'), injectedScript);
+
+    // dispatch kaggle
+    const kaggleProcess = spawn(
+      'kaggle',
+      [
+        'kernels',
+        'push',
+        '-p',
+        WORKSPACE_DIR,
+        '--accelerator',
+        'NvidiaTeslaT4',
+      ],
+      {
+        detached: true,
+        env: { ...process.env, KAGGLE_CONFIG_DIR: KAGGLE_TMP_DIR },
+      }
+    );
+
+    kaggleProcess.on('error', (error) => {
+      console.error('Failed to spawn kaggle process:', error);
+    });
+
+    // cleanup dirs
+    setTimeout(() => {
+      try {
+        if (fs.existsSync(KAGGLE_TMP_DIR))
+          fs.rmSync(KAGGLE_TMP_DIR, { recursive: true, force: true });
+        if (fs.existsSync(WORKSPACE_DIR))
+          fs.rmSync(WORKSPACE_DIR, { recursive: true, force: true });
+      } catch (error) {
+        console.error('Cleanup failed:', error);
+      }
+    }, 30000); // wait for push
+
+    res.json({ success: true, status: 'waking', session_id: sessionId });
+  } catch (error) {
+    console.error('Kernel dispatch failed:', error);
+    res.status(500).json({ error: 'Kernel dispatch failed' });
+  }
+};
+
+async function downloadStem(
+  url: string,
+  id: string,
+  stemName: string
+): Promise<void> {
+  const dir = resolveWithin(STEMS_BASE_DIR, id);
+  if (!dir) throw new Error('Invalid stem path');
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const localPath = path.join(dir, `${stemName}.wav`);
+  const writer = fs.createWriteStream(localPath);
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), 300000);
+  try {
+    const response = await secureFetch(url, { signal: controller.signal });
+    if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);
+    if (!response.body) throw new Error('No response body');
+    const stream = Readable.fromWeb(
+      response.body as import('stream/web').ReadableStream
+    );
+    stream.pipe(writer);
+    return new Promise<void>((resolve, reject) => {
+      writer.on('finish', () => {
+        clearTimeout(timeoutId);
+        resolve();
+      });
+      writer.on('error', (error: Error) => {
+        clearTimeout(timeoutId);
+        reject(error);
+      });
+    });
+  } catch (error: unknown) {
+    clearTimeout(timeoutId);
+    throw error;
+  }
+}
+
+export const saveRemix = async (
+  req: Request<
+    Record<string, unknown>,
+    Record<string, unknown>,
+    {
+      id: string;
+      name: string;
+      stems: Record<string, string>;
+      chords: string[];
+      beats: number[];
+      tempo: number;
+      engine?: string;
+    }
+  >,
+  res: Response
+): Promise<void> => {
+  const { id, name, stems, chords, beats, tempo, engine } = req.body;
+  try {
+    const localStems: Record<string, string> = {};
+    const downloadTasks: Promise<void>[] = [];
+    for (const [key, url] of Object.entries(stems)) {
+      if (url) {
+        downloadTasks.push(
+          (async () => {
+            await downloadStem(url, id, key);
+            localStems[key] = `/api/remix/stems/${id}/${key}.wav`;
+          })()
+        );
+      }
+    }
+    await Promise.all(downloadTasks);
+    if (db) {
+      const database = db as {
+        execute: (options: {
+          sql: string;
+          args: (string | number)[];
+        }) => Promise<unknown>;
+      };
+      await database.execute({
+        sql: 'INSERT INTO remix_history (id, name, stems, chords, beats, tempo, engine, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+        args: [
+          id,
+          name,
+          JSON.stringify(localStems),
+          JSON.stringify(chords),
+          JSON.stringify(beats),
+          tempo,
+          engine || 'Demucs',
+          Date.now(),
+        ],
+      });
+    }
+    res.json({ success: true, localStems });
+  } catch (error: unknown) {
+    console.error('[Save] Remix persistence failed:', error);
+    res.status(500).json({ error: 'Failed to persist remix data' });
+  }
+};
+
+export const serveStem = (req: Request, res: Response): void => {
+  const id = String(req.params.id);
+  const fileName = String(req.params.file);
+  const filePath = resolveWithin(STEMS_BASE_DIR, id, fileName);
+  if (!filePath) {
+    res.status(400).send('Invalid path');
+    return;
+  }
+  if (fs.existsSync(filePath)) {
+    const extension = path.extname(filePath).toLowerCase();
+    res.setHeader(
+      'Content-Type',
+      extension === '.wav'
+        ? 'audio/wav'
+        : extension === '.ogg'
+          ? 'audio/ogg'
+          : 'audio/mpeg'
+    );
+    res.sendFile(filePath);
+    return;
+  }
+  res.status(404).send('Stem not found');
+};
+
+export const getHistory = async (
+  _req: Request,
+  res: Response
+): Promise<void> => {
+  if (!db) {
+    res.json([]);
+    return;
+  }
+  try {
+    const result = await (
+      db as unknown as {
+        execute(query: string): Promise<{
+          rows: {
+            id: number;
+            name: string;
+            stems: string;
+            chords: string;
+            beats: string;
+            tempo: number;
+            engine: string;
+            created_at: string;
+          }[];
+        }>;
+      }
+    ).execute('SELECT * FROM remix_history ORDER BY created_at DESC LIMIT 15');
+    const history = result.rows.map((row) => ({
+      id: row.id,
+      name: row.name,
+      stems: JSON.parse(row.stems),
+      chords: JSON.parse(row.chords),
+      beats: JSON.parse(row.beats),
+      tempo: row.tempo,
+      engine: row.engine,
+      date: new Date(row.created_at).toLocaleDateString(),
+    }));
+    res.json(history);
+  } catch (error) {
+    console.error('[History] Fetch failed:', error);
+    res.status(500).json({ error: 'Failed to fetch history' });
+  }
+};
+
+export const renameRemix = async (
+  req: Request,
+  res: Response
+): Promise<void> => {
+  const { id, name } = req.body as { id: string; name: string };
+  if (!db) {
+    res.status(500).json({ error: 'DB not initialized' });
+    return;
+  }
+  try {
+    await db.execute({
+      sql: 'UPDATE remix_history SET name = ? WHERE id = ?',
+      args: [name, id],
+    });
+    res.json({ success: true });
+  } catch (error) {
+    console.error('[Rename] Operation failed:', error);
+    res.status(500).json({ error: 'Failed to rename' });
+  }
+};
+
+export const deleteRemix = async (
+  req: Request,
+  res: Response
+): Promise<void> => {
+  const id = String(req.params.id);
+  if (!db) {
+    res.status(500).json({ error: 'DB not initialized' });
+    return;
+  }
+  try {
+    await db.execute({
+      sql: 'DELETE FROM remix_history WHERE id = ?',
+      args: [id],
+    });
+    const targetDir = resolveWithin(STEMS_BASE_DIR, id);
+    if (targetDir && fs.existsSync(targetDir))
+      fs.rmSync(targetDir, { recursive: true, force: true });
+    res.json({ success: true });
+  } catch (error: unknown) {
+    console.error('[Delete] Operation failed:', error);
+    res.status(500).json({ error: 'Failed to delete' });
+  }
+};
+
+export const exportRemix = async (
+  req: Request,
+  res: Response
+): Promise<void> => {
+  const id = String(req.params.id);
+  if (!db) {
+    res.status(500).json({ error: 'DB not initialized' });
+    return;
+  }
+  try {
+    const result = await (
+      db as unknown as {
+        execute: (options: { sql: string; args: string[] }) => Promise<{
+          rows: Array<{
+            id: string;
+            name: string;
+            stems: string;
+            chords: string;
+            beats: string;
+            tempo: number;
+            engine: string;
+          }>;
+        }>;
+      }
+    ).execute({ sql: 'SELECT * FROM remix_history WHERE id = ?', args: [id] });
+    if (result.rows.length === 0) {
+      res.status(404).send('Not found');
+      return;
+    }
+    const row = result.rows[0];
+    const targetDir = resolveWithin(STEMS_BASE_DIR, id);
+
+    if (!targetDir || !fs.existsSync(targetDir)) {
+      res.status(404).send('Project directory not found on server');
+      return;
+    }
+
+    const metadata = {
+      id: row.id,
+      name: row.name,
+      stems: JSON.parse(row.stems),
+      chords: JSON.parse(row.chords),
+      beats: JSON.parse(row.beats),
+      tempo: row.tempo,
+      engine: row.engine,
+    };
+
+    fs.writeFileSync(
+      path.join(targetDir, 'project.json'),
+      JSON.stringify(metadata, null, 2)
+    );
+
+    const safeName = (row.name || row.id).replace(/["\r\n]/gu, '_');
+    res.setHeader('Content-Type', 'application/zip');
+    res.setHeader(
+      'Content-Disposition',
+      `attachment; filename="${safeName}.zip"`
+    );
+
+    const zipProcess = spawn('zip', ['-q', '-r', '-', '.'], {
+      cwd: targetDir,
+      detached: true,
+    });
+
+    req.on('close', () => {
+      if (zipProcess.pid) {
+        try {
+          process.kill(-zipProcess.pid, 'SIGKILL');
+        } catch (error) {
+          console.debug('[Export] Cleanup failed:', error);
+        }
+      }
+    });
+
+    zipProcess.stdout.pipe(res);
+
+    zipProcess.stderr.on('data', (data) => {
+      console.error(`zip stderr: ${data}`);
+    });
+
+    zipProcess.on('close', (code) => {
+      if (code !== 0) {
+        console.error(`zip process exited with code ${code}`);
+        if (!res.headersSent) res.status(500).send('Zip generation failed');
+      }
+    });
+  } catch (error) {
+    console.error('Export exception:', error);
+    if (!res.headersSent) res.status(500).send('Export failed');
+  }
+};
+
+export const extractRemix = async (
+  req: Request,
+  res: Response
+): Promise<void> => {
+  const id = String(req.params.id);
+  const projectDir = resolveWithin(STEMS_BASE_DIR, id);
+  if (!projectDir) {
+    res.status(400).json({ error: 'Invalid path' });
+    return;
+  }
+  const mixPath = path.join(projectDir, 'temp_mix.wav');
+  if (!fs.existsSync(mixPath)) {
+    const stemsToMix = ['vocals', 'drums', 'bass', 'other', 'guitar', 'piano']
+      .map((stemId) => path.join(projectDir, `${stemId}.wav`))
+      .filter((filePath) => fs.existsSync(filePath));
+    if (stemsToMix.length === 0) {
+      res.status(404).json({ error: 'Audio not found' });
+      return;
+    }
+    try {
+      await new Promise<void>((resolve, reject) => {
+        const ffmpegArgs: string[] = [];
+        stemsToMix.forEach((stemPath) => {
+          ffmpegArgs.push('-i', stemPath);
+        });
+        ffmpegArgs.push(
+          '-filter_complex',
+          `amix=inputs=${stemsToMix.length}:duration=longest`,
+          '-y',
+          mixPath
+        );
+        const ffmpegProcess = spawn('ffmpeg', ffmpegArgs, { detached: true });
+
+        const cleanup = () => {
+          if (ffmpegProcess.pid) {
+            try {
+              process.kill(-ffmpegProcess.pid, 'SIGKILL');
+            } catch (error) {
+              console.debug('[Extract] Cleanup failed:', error);
+            }
+          }
+        };
+        req.on('close', cleanup);
+
+        ffmpegProcess.on('close', (code) => {
+          req.off('close', cleanup);
+          if (code === 0) {
+            resolve();
+          } else {
+            reject(new Error('FFmpeg failed'));
+          }
+        });
+      });
+    } catch (error: unknown) {
+      console.error('[Extract] Audio preparation failed:', error);
+      res.status(500).json({ error: 'Failed to prepare audio' });
+      return;
+    }
+  }
+  try {
+    type DbResult = { rows: { chords: string }[] };
+    type DbClient = {
+      execute(opts: { sql: string; args: string[] }): Promise<DbResult>;
+    };
+    const dbClient = db as unknown as DbClient;
+    let engineChords: string[] = [];
+    const dbResult = await dbClient.execute({
+      sql: 'SELECT chords FROM remix_history WHERE id = ?',
+      args: [id],
+    });
+    if (dbResult.rows.length > 0)
+      engineChords = JSON.parse(dbResult.rows[0].chords) as string[];
+    const songData = await extractSongData(
+      mixPath,
+      engineChords.map((chordStr) => ({
+        chord: String(chordStr),
+        is_passing: false,
+      }))
+    );
+    res.json(songData);
+  } catch (error: unknown) {
+    res
+      .status(500)
+      .json({ error: error instanceof Error ? error.message : String(error) });
+  }
+};

backend/src/controllers/video.controller.ts

@@ -0,0 +1,401 @@
+import { Request, Response } from 'express';
+import * as Sentry from '@sentry/node'; // skipcq: JS-C1003
+import {
+  addClient,
+  removeClient,
+  sendEvent,
+} from '../utils/network/sse.util.js';
+import {
+  isSupportedUrl,
+  isValidSpotifyUrl,
+  decodeUrlIfNeeded,
+} from '../utils/network/validation.util.js';
+import { pipeWebStream } from '../utils/network/proxy.util.js';
+import { verifyProxyParams } from '../utils/network/secrets.util.js';
+import { recordFailure } from '../utils/infra/metrics.util.js';
+import {
+  detectService,
+  getSanitizedFilename,
+} from '../utils/media/video.util.js';
+import { prepareFinalResponse } from '../utils/api/response.util.js';
+import { getCookieArgs, initializeSession } from '../utils/api/controller.util.js';
+import {
+  processBackgroundTracks,
+  resolveSeedTracks,
+  type SeedTrack,
+} from '../services/seeder.service.js';
+import {
+  fetchMediaInfo,
+  handleSpotifyRegistry,
+} from '../services/video/info.js';
+import {
+  parseRequestParams,
+  resolveManifests,
+  buildStreamResponse,
+} from '../services/video/stream-resolver.js';
+import {
+  executeDownload,
+  streamViaYtdlp,
+} from '../services/video/download.js';
+import { SpotifyMetadata } from '../types/index.js';
+
+export const streamEvents = async (
+  req: Request,
+  res: Response
+): Promise<void> => {
+  const id = (req.query.id as string) || undefined;
+  console.log(`[SSE] Client connecting: ${id}`);
+  if (!id) {
+    res.status(400).end();
+    return;
+  }
+  await addClient(id, res);
+};
+
+export const getVideoInformation = async (
+  req: Request,
+  res: Response
+): Promise<void> => {
+  res.setHeader(
+    'Cache-Control',
+    'no-store, no-cache, must-revalidate, proxy-revalidate'
+  );
+  let videoURL = decodeUrlIfNeeded(req.query.url as string);
+  const clientId = (req.query.id as string) || undefined;
+
+  if (videoURL) {
+    videoURL = videoURL.split('&id=')[0].split('?id=')[0];
+  }
+
+  if (!videoURL || !isSupportedUrl(videoURL)) {
+    res.status(400).json({ error: 'No valid URL provided' });
+    return;
+  }
+
+  const serviceName = detectService(videoURL);
+  await initializeSession(clientId);
+
+  try {
+    const cookieArgs = await getCookieArgs(videoURL, clientId);
+    const isSpotify = videoURL.includes('spotify.com');
+
+    const info = await fetchMediaInfo(
+      videoURL,
+      clientId,
+      serviceName,
+      cookieArgs
+    );
+
+    // fast partial hit
+    if (!info || (!info.formats?.length && !info.isPartial)) {
+      res.json({
+        title: info?.title || 'Unknown',
+        thumbnail: info?.thumbnail || '',
+        formats: [],
+        audioFormats: [],
+      });
+      return;
+    }
+
+    const spotifyData = isSpotify
+      ? ({ ...info, type: 'spotify' } as unknown as SpotifyMetadata)
+      : null;
+    const targetURL = isSpotify ? info.targetUrl || videoURL : videoURL;
+
+    const finalResponse = await prepareFinalResponse(
+      info,
+      isSpotify,
+      spotifyData,
+      videoURL
+    );
+    if (isSpotify) {
+      handleSpotifyRegistry(info, finalResponse, videoURL, targetURL);
+    }
+
+    res.json(finalResponse);
+  } catch (error: unknown) {
+    recordFailure('info');
+    console.error('[VideoInfo] Error:', (error as Error).message);
+    Sentry.captureException(error);
+    if (clientId) removeClient(clientId);
+    if (!res.headersSent)
+      res.status(500).json({ error: 'Failed to fetch video info' });
+  }
+};
+
+export const getStreamUrls = async (
+  req: Request,
+  res: Response
+): Promise<void> => {
+  const { videoURL, clientId, formatId } = parseRequestParams(req);
+  const timestamp = new Date().toLocaleTimeString('en-US', {
+    hour12: true,
+    hour: 'numeric',
+    minute: '2-digit',
+    second: '2-digit',
+  });
+
+  if (!videoURL || !isSupportedUrl(videoURL)) {
+    res.status(400).json({ error: 'No valid URL provided' });
+    return;
+  }
+
+  console.log(`[${timestamp}] [EME] Resolving manifests for Edge Muxing...`);
+
+  try {
+    const {
+      info,
+      videoTunnel,
+      audioTunnel,
+      isAudioOnly,
+      filename,
+      totalSize,
+      outputMeta,
+    } = await resolveManifests(req, videoURL, clientId, formatId);
+    res.json(
+      buildStreamResponse(
+        info,
+        videoTunnel,
+        audioTunnel,
+        isAudioOnly,
+        filename,
+        totalSize,
+        outputMeta as Record<string, unknown>
+      )
+    );
+  } catch (error: unknown) {
+    recordFailure('stream_urls');
+    console.error('[StreamUrls] Error:', (error as Error).message);
+    Sentry.captureException(error);
+    if (!res.headersSent)
+      res.status(500).json({ error: 'Failed to resolve stream URLs' });
+  }
+};
+
+export const proxyStream = async (
+  req: Request,
+  res: Response
+): Promise<void> => {
+  const queryData = req.query as Record<string, string | string[] | undefined>;
+  let { targetUrl, formatId, url: rawFallbackUrl, filename } = queryData;
+  if (Array.isArray(targetUrl)) targetUrl = targetUrl[0];
+  if (Array.isArray(formatId)) formatId = formatId[0];
+  if (Array.isArray(rawFallbackUrl)) rawFallbackUrl = rawFallbackUrl[0];
+  if (Array.isArray(filename)) filename = filename[0];
+
+  let rawUrl = queryData.rawUrl;
+  if (Array.isArray(rawUrl)) rawUrl = rawUrl[0];
+
+  // refuse forged or expired signed links
+  if (
+    !verifyProxyParams({
+      targetUrl: targetUrl as string | undefined,
+      rawUrl: rawUrl as string | undefined,
+      formatId: formatId as string | undefined,
+      exp: Number(req.query.exp),
+      sig: req.query.sig as string | undefined,
+    })
+  ) {
+    res.status(403).json({ error: 'Invalid or expired proxy signature' });
+    return;
+  }
+
+  const urlToFetch = rawFallbackUrl || (req.query.rawUrl as string);
+
+  if (urlToFetch) {
+    const abortController = new AbortController();
+    req.on('close', () => abortController.abort());
+    try {
+      await pipeWebStream(
+        urlToFetch,
+        res,
+        filename as string,
+        req.headers as unknown as Record<string, string | undefined>,
+        0,
+        abortController.signal
+      );
+      return;
+    } catch (error: unknown) {
+      recordFailure('proxy');
+      console.error('[Proxy] Raw Pipe Error:', (error as Error).message);
+      Sentry.captureException(error);
+      if (!res.headersSent)
+        res.status(500).json({ error: 'Proxy fetch failed' });
+      res.end();
+      return;
+    }
+  }
+
+  if (targetUrl && formatId) {
+    await streamViaYtdlp(req, res, targetUrl, formatId, filename);
+    return;
+  }
+
+  res.status(400).end();
+};
+
+export const reportTelemetry = (req: Request, res: Response): void => {
+  const { event } = req.body;
+  const timestamp = new Date().toLocaleTimeString('en-US', {
+    hour12: true,
+    hour: 'numeric',
+    minute: '2-digit',
+    second: '2-digit',
+  });
+  const safeEvent = String(event || 'unknown').replaceAll(/[^\w]/gu, '_');
+  console.log(`[${timestamp}] [EME] Client-Side Handshake: ${safeEvent}`);
+  res.status(204).end();
+};
+
+export const convertVideo = (req: Request, res: Response): void => {
+  if (req.method === 'HEAD') {
+    res.status(200).end();
+    return;
+  }
+  res.setHeader(
+    'Cache-Control',
+    'no-store, no-cache, must-revalidate, proxy-revalidate'
+  );
+
+  const requestData = { ...req.query, ...req.body } as {
+    url?: string;
+    id?: string;
+    format?: string;
+    formatId?: string;
+    token?: string;
+    title?: string;
+    artist?: string;
+    targetUrl?: string;
+  };
+
+  const {
+    url: videoURL,
+    id: clientIdStr,
+    format = 'mp4',
+    formatId,
+  } = requestData;
+  const clientId = clientIdStr || undefined;
+
+  console.log(`[Convert] Request received for: ${videoURL} (ID: ${clientId})`);
+
+  if (!videoURL || !isSupportedUrl(videoURL)) {
+    console.warn(`[Convert] Invalid URL: ${videoURL}`);
+    res.status(400).json({ error: 'No valid URL provided' });
+    return;
+  }
+
+  const token = requestData.token || clientId;
+  if (token) {
+    res.setHeader('Set-Cookie', `download_token=${token}; Path=/; Max-Age=60`);
+  }
+
+  const isSpotifyRequest = videoURL.includes('spotify.com');
+  const timestamp = new Date().toLocaleTimeString('en-US', {
+    hour12: true,
+    hour: 'numeric',
+    minute: '2-digit',
+    second: '2-digit',
+  });
+
+  let finalFormat = format;
+  if (formatId?.startsWith('photo')) finalFormat = 'jpg';
+
+  const filename = getSanitizedFilename(
+    requestData.title || 'video',
+    requestData.artist,
+    finalFormat,
+    isSpotifyRequest
+  );
+
+  console.log(
+    `[${timestamp}] [Turbo] Starting Server-Side muxing for: ${filename}`
+  );
+
+  if (clientId) {
+    sendEvent(clientId, {
+      status: 'initializing',
+      progress: 5,
+      subStatus: 'syncing core...',
+      text: 'initiating jump',
+    });
+  }
+
+  (async () => {
+    const result = await executeDownload(
+      res,
+      clientId,
+      videoURL as string,
+      requestData,
+      timestamp,
+      filename,
+      format,
+      formatId,
+      isSpotifyRequest
+    );
+    if (result) {
+      const { videoProcess, hardTimeoutId } = result;
+      req.on('close', () => {
+        clearTimeout(hardTimeoutId);
+        if (typeof videoProcess.kill === 'function') {
+          console.log(
+            `[${timestamp}] [Turbo] Client disconnected. Cleaning up stream for: ${clientId}`
+          );
+          videoProcess.kill();
+        }
+        if (!res.writableEnded) res.end();
+      });
+    }
+  })().catch((error) => {
+    console.error(
+      `[${timestamp}] [ConvertVideo] Unhandled exception in download workflow:`,
+      error
+    );
+    Sentry.captureException(error);
+    if (!res.headersSent)
+      res
+        .status(500)
+        .json({ error: 'Internal server error during processing' });
+    if (!res.writableEnded) res.end();
+  });
+};
+
+export const seedIntelligence = async (
+  req: Request,
+  res: Response
+): Promise<void> => {
+  const { url, id: clientIdStr } = req.query as { url: string; id: string };
+  const clientId = clientIdStr || 'admin-seeder';
+  if (!url || !isValidSpotifyUrl(url)) {
+    res
+      .status(400)
+      .json({ error: 'Invalid Spotify Artist/Album URL provided' });
+    return;
+  }
+
+  try {
+    const tracks = await resolveSeedTracks(url);
+
+    if (!tracks || tracks.length === 0) throw new Error('No tracks found.');
+
+    res.json({
+      message: 'Intelligence Gathering Started in Background',
+      trackCount: tracks.length,
+      target: url,
+    });
+    processBackgroundTracks(tracks as SeedTrack[], clientId).catch(
+      (error: Error) => {
+        console.error('[Seeder] Background Process Crashed:', error.message);
+        Sentry.captureException(error);
+      }
+    );
+  } catch (error: unknown) {
+    if (!res.headersSent) {
+      Sentry.captureException(error);
+      res
+        .status(500)
+        .json({
+          error: (error as Error).message || 'An unknown error occurred',
+        });
+    }
+  }
+};

backend/src/instrument.ts

@@ -0,0 +1,37 @@
+import * as Sentry from '@sentry/node'; // skipcq: JS-C1003
+
+type ProfilingIntegration = ReturnType<
+  (typeof import('@sentry/profiling-node'))['nodeProfilingIntegration']
+>;
+
+// skip profiler if native binding missing
+const integrations: ProfilingIntegration[] = [];
+try {
+  const { nodeProfilingIntegration } = await import('@sentry/profiling-node');
+  integrations.push(nodeProfilingIntegration());
+} catch (error) {
+  console.warn(
+    '[Sentry] CPU profiler unavailable:',
+    error instanceof Error ? error.message : String(error)
+  );
+}
+
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+  integrations,
+  tracesSampleRate: 0.1,
+  profilesSampleRate: 0.1,
+  sendDefaultPii: false,
+});
+
+process.on('uncaughtException', async (error) => {
+  console.error('[Uncaught Exception]', error);
+  Sentry.captureException(error);
+  await Sentry.close(2000);
+  throw error;
+});
+
+process.on('unhandledRejection', (reason) => {
+  console.error('[Unhandled Rejection]', reason);
+  Sentry.captureException(reason);
+});

backend/src/routes/keychanger.routes.ts

@@ -0,0 +1,17 @@
+import { Router } from 'express';
+import {
+  upload,
+  detectKey,
+  detectProcessedKey,
+  convertKey,
+  downloadFile,
+} from '../controllers/keychanger.controller.js';
+
+const router = Router();
+
+router.post('/detect', upload.single('song'), detectKey);
+router.get('/detect-processed/:filename', detectProcessedKey);
+router.post('/convert', upload.single('song'), convertKey);
+router.get('/download/:filename', downloadFile);
+
+export default router;

backend/src/routes/remix.routes.ts

@@ -0,0 +1,29 @@
+import express from 'express';
+import multer from 'multer';
+import path from 'path';
+import { fileURLToPath } from 'node:url';
+import * as remixController from '../controllers/remix.controller.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const router = express.Router();
+
+const upload = multer({
+  dest: path.join(__dirname, '../../temp/uploads'),
+  limits: { fileSize: 100 * 1024 * 1024 }, // 100mb limit
+});
+
+router.post('/register-engine', remixController.registerEngine);
+router.get('/engine-status', remixController.getEngineStatus);
+router.post('/process', upload.single('file'), remixController.processAudio);
+router.post('/wake-engine', remixController.wakeEngine);
+router.post('/save', remixController.saveRemix);
+router.get('/stems/:id/:file', remixController.serveStem);
+router.get('/history', remixController.getHistory);
+router.post('/rename', remixController.renameRemix);
+router.delete('/delete/:id', remixController.deleteRemix);
+router.get('/export/:id', remixController.exportRemix);
+router.get('/extract/:id', remixController.extractRemix);
+
+export default router;

backend/src/routes/video.routes.ts

@@ -0,0 +1,26 @@
+import { Router } from 'express';
+import {
+  streamEvents,
+  getVideoInformation,
+  getStreamUrls,
+  reportTelemetry,
+  convertVideo,
+  proxyStream,
+  seedIntelligence,
+} from '../controllers/video.controller.js';
+import {
+  concurrencyGuard,
+  globalMediaGuard,
+} from '../utils/network/security.util.js';
+
+const router = Router();
+
+router.get('/events', streamEvents);
+router.get('/info', getVideoInformation);
+router.get('/stream-urls', getStreamUrls);
+router.post('/telemetry', reportTelemetry);
+router.all('/convert', globalMediaGuard(), concurrencyGuard(2), convertVideo);
+router.get('/proxy', globalMediaGuard(), concurrencyGuard(2), proxyStream);
+router.get('/seed-intelligence', seedIntelligence);
+
+export default router;

backend/src/services/extract.service.ts

@@ -0,0 +1,390 @@
+import fpcalc from 'fpcalc';
+import * as Sentry from '@sentry/node'; // skipcq: JS-C1003
+import { Shazam } from 'node-shazam';
+import { getUgChords } from './ug-grounding.service.js';
+import { z } from 'zod';
+import { secureFetch } from '../utils/network/security.util.js';
+
+const ACOUSTID_API_KEY = 'vdzQhu1sWI';
+
+const AcoustidResponseSchema = z
+  .object({
+    results: z
+      .array(
+        z.object({
+          recordings: z
+            .array(
+              z.object({
+                id: z.string(),
+              })
+            )
+            .optional(),
+        })
+      )
+      .optional(),
+  })
+  .catchall(z.unknown());
+
+const MusicBrainzResponseSchema = z
+  .object({
+    isrcs: z.array(z.string()).optional(),
+  })
+  .catchall(z.unknown());
+
+const DeezerResponseSchema = z
+  .object({
+    error: z
+      .object({
+        type: z.string(),
+        message: z.string(),
+        code: z.number(),
+      })
+      .optional(),
+    artist: z.object({ name: z.string() }).optional(),
+    title: z.string().optional(),
+  })
+  .catchall(z.unknown());
+
+type LyricsData = {
+  plainLyrics?: string;
+  syncedLyrics?: string;
+  [key: string]: unknown;
+};
+
+type SongData = {
+  artist: string;
+  title: string;
+  isrc: string | null;
+  lyrics: string | null;
+  chordsSheet: string | null;
+  chordsLink: string;
+  grounded: boolean;
+};
+
+async function getGeminiChords(
+  artist: string,
+  title: string,
+  syncedLyrics: string | null,
+  engineChords: { is_passing: boolean; time: number; chord: string }[]
+): Promise<string | null> {
+  const apiKey = process.env.GEMINI_API_KEY || process.env.VERTEX_API_KEY;
+  if (!apiKey) return null;
+
+  try {
+    const { GoogleGenAI } = await import('@google/genai');
+
+    interface IGoogleGenAI {
+      getGenerativeModel: (options: { model: string }) => {
+        generateContent: (prompt: string) => Promise<{
+          response: { text: () => string };
+        }>;
+      };
+    }
+
+    type IGoogleGenAIConstructor = new (key: string) => IGoogleGenAI;
+
+    const GenAIClass = GoogleGenAI as unknown as IGoogleGenAIConstructor;
+    const genAIInstance = new GenAIClass(apiKey);
+
+    let prompt = `Act as an expert music transcriber. Your task is to merge raw audio-extracted chords with synchronized lyrics to create a highly accurate Ultimate-Guitar style chord sheet.\n\nSong: "${title}" by "${artist}"\n\n`;
+
+    if (syncedLyrics && engineChords?.length > 0) {
+      prompt += `Here are the timestamped lyrics (in [mm:ss.xx] format):\n${syncedLyrics}\n\n`;
+
+      const chordsSummary = engineChords
+        .filter((chord) => !chord.is_passing)
+        .map((chord) => `[${formatTime(chord.time)}] ${chord.chord}`)
+        .join('\n');
+
+      prompt += `Here are the exact chords detected in the audio by our engine at specific timestamps:\n${chordsSummary}\n\n`;
+      prompt +=
+        'CRITICAL INSTRUCTIONS:\n1. You MUST format this EXACTLY like an Ultimate Guitar text file.\n2. Chords MUST be placed on their own dedicated line directly ABOVE the lyrics, NOT inline with the text.\n3. Example of correct formatting:\n[ch]C[/ch]                  [ch]G[/ch]\nLet it be, let it be\n4. You MUST wrap every single chord in [ch] brackets (e.g., [ch]Am7[/ch]).\n5. Use the timestamps provided to figure out exactly which word the chord falls on, and space the chords out on the top line accordingly.\n6. Ignore long repetitive blocks of chords at the end (outros) if there are no lyrics. Keep it clean.\n7. ONLY output the final formatted chord sheet text. No markdown blocks, no conversational text.';
+    } else {
+      prompt +=
+        'Since exact audio data is missing, return the most highly-rated guitar chords and lyrics available for this song. \nCRITICAL: Chords MUST be placed on their own line directly ABOVE the lyrics. Wrap every single chord in [ch] brackets (e.g., [ch]Am7[/ch]).\nProvide ONLY the song text with chords. No markdown code blocks or extra text.';
+    }
+
+    const model = genAIInstance.getGenerativeModel({
+      model: 'gemini-3-flash-preview',
+    });
+    const result = await model.generateContent(prompt);
+    const text = result.response.text();
+    return text || null;
+  } catch (error: unknown) {
+    const errorObj = error as Error;
+    console.error('Gemini Chords Error:', errorObj.message);
+    Sentry.captureException(error);
+    return null;
+  }
+}
+
+function formatTime(seconds: number): string {
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = (seconds % 60).toFixed(2);
+  return `${minutes < 10 ? '0' : ''}${minutes}:${remainingSeconds.padStart(5, '0')}`;
+}
+
+async function getLyrics(
+  artist: string,
+  title: string
+): Promise<LyricsData | null> {
+  const cleanTitle = title.split(/[([]/u)[0].trim();
+
+  const fetchExact = async (trackName: string): Promise<LyricsData | null> => {
+    try {
+      const url = `https://lrclib.net/api/get?artist_name=${encodeURIComponent(artist)}&track_name=${encodeURIComponent(trackName)}`;
+      const response = await secureFetch(url);
+      if (!response.ok) return null;
+      const json = (await response.json()) as LyricsData;
+      return json;
+    } catch (error) {
+      console.debug('[ExtractService] lyrics fetch exact failed:', error);
+      return null;
+    }
+  };
+
+  const fetchSearch = async (trackName: string): Promise<LyricsData | null> => {
+    try {
+      const query = encodeURIComponent(`${artist} ${trackName}`);
+      const url = `https://lrclib.net/api/search?q=${query}`;
+      const response = await secureFetch(url);
+      if (!response.ok) return null;
+      const data = (await response.json()) as LyricsData[];
+      if (data.length > 0) {
+        return (
+          data.find(
+            (result) =>
+              result.plainLyrics !== undefined ||
+              result.syncedLyrics !== undefined
+          ) || null
+        );
+      }
+    } catch (error) {
+      console.debug('[ExtractService] lyrics fetch search failed:', error);
+      return null;
+    }
+    return null;
+  };
+
+  let data = await fetchExact(title);
+  if (data) return data;
+  if (title !== cleanTitle) {
+    data = await fetchExact(cleanTitle);
+    if (data) return data;
+  }
+  data = await fetchSearch(title);
+  if (data) return data;
+  if (title !== cleanTitle) {
+    data = await fetchSearch(cleanTitle);
+    if (data) return data;
+  }
+  return null;
+}
+
+async function processSong(
+  artist: string,
+  title: string,
+  isrc: string | null,
+  engineChords: Array<{ chord: string; is_passing: boolean; time?: number }>
+): Promise<SongData> {
+  const lrclibData = await getLyrics(artist, title);
+  const plainLyrics = lrclibData?.plainLyrics || null;
+  const syncedLyrics = lrclibData?.syncedLyrics || null;
+
+  const groundingRes = await getUgChords(artist, title);
+  let chordsSheet = groundingRes?.chordsSheet || null;
+  const usedGrounding = Boolean(chordsSheet);
+
+  if (!chordsSheet) {
+    const validChords = engineChords.filter(
+      (chord): chord is { chord: string; is_passing: boolean; time: number } =>
+        typeof chord.time === 'number'
+    );
+    chordsSheet = await getGeminiChords(
+      artist,
+      title,
+      syncedLyrics,
+      validChords
+    );
+  }
+
+  const cleanTitle = title.split('(')[0].trim();
+  const query = `${artist} ${cleanTitle}`;
+  const ugLink = `https://www.ultimate-guitar.com/search.php?search_type=title&value=${encodeURIComponent(query)}`;
+
+  return {
+    artist,
+    title,
+    isrc: isrc || null,
+    lyrics: plainLyrics,
+    chordsSheet,
+    chordsLink: ugLink,
+    grounded: usedGrounding,
+  };
+}
+
+async function fallbackToShazam(
+  filePath: string,
+  engineChords: Array<{ chord: string; is_passing: boolean }>
+): Promise<SongData> {
+  try {
+    const shazam = new Shazam();
+    const response = (await shazam.recognise(filePath, 'en-US')) as {
+      track?: { subtitle: string; title: string; isrc: string };
+    };
+    if (response?.track) {
+      const track = response.track;
+
+      const artist = track.subtitle;
+      const title = track.title;
+      const isrc = track.isrc;
+      if (artist && title)
+        return await processSong(artist, title, isrc, engineChords);
+    }
+    throw new Error('Shazam failed');
+  } catch (error: unknown) {
+    const err = error as Error;
+    throw new Error(`Shazam error: ${err.message}`, { cause: error });
+  }
+}
+
+export function extractSongData(
+  filePath: string,
+  engineChords: Array<{ chord: string; is_passing: boolean }> = []
+): Promise<SongData> {
+  return new Promise((resolve, reject) => {
+    fpcalc(
+      filePath,
+      async (
+        error: Error | null,
+        result: { fingerprint: string; duration: number } | undefined
+      ) => {
+        if (error || !result) {
+          try {
+            const fallbackResult = await fallbackToShazam(
+              filePath,
+              engineChords
+            );
+            resolve(fallbackResult);
+            return;
+          } catch (fallbackErr) {
+            reject(fallbackErr);
+            return;
+          }
+        }
+
+        const acoustidUrl = `https://api.acoustid.org/v2/lookup?client=${ACOUSTID_API_KEY}&meta=recordingids&fingerprint=${result.fingerprint}&duration=${result.duration}`;
+
+        try {
+          const response = await secureFetch(acoustidUrl);
+          const rawAcoustidData = await response.json();
+          const parsedAcoustid =
+            AcoustidResponseSchema.safeParse(rawAcoustidData);
+          if (!parsedAcoustid.success) {
+            console.debug(
+              '[ExtractService] Acoustid validation failed:',
+              parsedAcoustid.error.message
+            );
+            const fallbackResult = await fallbackToShazam(
+              filePath,
+              engineChords
+            );
+            resolve(fallbackResult);
+            return;
+          }
+          const data = parsedAcoustid.data;
+          const recording = data.results?.[0]?.recordings?.[0];
+
+          if (!recording) {
+            const fallbackResult = await fallbackToShazam(
+              filePath,
+              engineChords
+            );
+            resolve(fallbackResult);
+            return;
+          }
+
+          const mbid = recording.id;
+          const mbUrl = `https://musicbrainz.org/ws/2/recording/${mbid}?inc=isrcs&fmt=json`;
+          const mbRes = await secureFetch(mbUrl, {
+            headers: { 'User-Agent': 'ISRC_Finder/1.0' },
+          });
+          const rawMbData = await mbRes.json();
+          const parsedMb = MusicBrainzResponseSchema.safeParse(rawMbData);
+          if (!parsedMb.success) {
+            console.debug(
+              '[ExtractService] MusicBrainz validation failed:',
+              parsedMb.error.message
+            );
+            const fallbackResult = await fallbackToShazam(
+              filePath,
+              engineChords
+            );
+            resolve(fallbackResult);
+            return;
+          }
+          const mbData = parsedMb.data;
+          const isrc = mbData.isrcs?.[0];
+
+          if (!isrc) {
+            const fallbackResult = await fallbackToShazam(
+              filePath,
+              engineChords
+            );
+            resolve(fallbackResult);
+            return;
+          }
+
+          const deezerRes = await secureFetch(
+            `https://api.deezer.com/track/isrc:${isrc}`
+          );
+          const rawDeezerData = await deezerRes.json();
+          const parsedDeezer = DeezerResponseSchema.safeParse(rawDeezerData);
+          if (!parsedDeezer.success) {
+            console.debug(
+              '[ExtractService] Deezer validation failed:',
+              parsedDeezer.error.message
+            );
+            const fallbackResult = await fallbackToShazam(
+              filePath,
+              engineChords
+            );
+            resolve(fallbackResult);
+            return;
+          }
+          const deezerData = parsedDeezer.data;
+          if (deezerData.error || !deezerData.artist || !deezerData.title) {
+            const fallbackResult = await fallbackToShazam(
+              filePath,
+              engineChords
+            );
+            resolve(fallbackResult);
+            return;
+          }
+
+          const finalResult = await processSong(
+            deezerData.artist.name,
+            deezerData.title,
+            isrc,
+            engineChords
+          );
+          resolve(finalResult);
+          return;
+        } catch (error) {
+          console.debug('[ExtractService] Acoustid match failed, falling back:', error);
+          try {
+            const fallbackResult = await fallbackToShazam(
+              filePath,
+              engineChords
+            );
+            resolve(fallbackResult);
+            return;
+          } catch (fallbackErr) {
+            reject(fallbackErr);
+            return;
+          }
+        }
+      }
+    );
+  });
+}

backend/src/services/extractors/bluesky.ts

@@ -0,0 +1,170 @@
+import { secureFetch } from '../../utils/network/security.util.js';
+import { getQuantumStream } from '../../utils/network/proxy.util.js';
+import { VideoInfo, Format, ExtractorOptions } from '../../types/index.js';
+import { Readable } from 'node:stream';
+import { normalizeTitle, normalizeArtist } from '../social.service.js';
+
+const APPVIEW = 'https://public.api.bsky.app/xrpc';
+
+interface BlobRef {
+  ref?: { $link?: string };
+  size?: number;
+}
+interface AspectRatio {
+  width?: number;
+  height?: number;
+}
+interface BskyEmbed {
+  video?: BlobRef;
+  aspectRatio?: AspectRatio;
+  media?: { video?: BlobRef; aspectRatio?: AspectRatio };
+}
+interface BskyView {
+  thumbnail?: string;
+  aspectRatio?: AspectRatio;
+  media?: { thumbnail?: string; aspectRatio?: AspectRatio };
+}
+interface BskyPost {
+  record?: { text?: string; embed?: BskyEmbed };
+  embed?: BskyView;
+  author?: { displayName?: string; handle?: string };
+}
+interface VideoData {
+  cid: string;
+  size?: number;
+  width?: number;
+  height?: number;
+  thumbnail?: string;
+}
+
+async function fetchJson<T>(url: string): Promise<T | null> {
+  const res = await secureFetch(url);
+  if (!res.ok) return null;
+  return (await res.json()) as T;
+}
+
+// resolve the user's PDS from DID
+async function resolvePds(did: string): Promise<string | null> {
+  let docUrl: string | null = null;
+  if (did.startsWith('did:plc:')) docUrl = `https://plc.directory/${did}`;
+  else if (did.startsWith('did:web:'))
+    docUrl = `https://${did.slice(8).replace(/:/gu, '/')}/.well-known/did.json`;
+  if (!docUrl) return null;
+
+  const doc = await fetchJson<{
+    service?: { type?: string; serviceEndpoint?: string }[];
+  }>(docUrl);
+  const svc = (doc?.service || []).find(
+    (entry) => entry.type === 'AtprotoPersonalDataServer'
+  );
+  return svc?.serviceEndpoint ?? null;
+}
+
+function pickVideo(post: BskyPost | undefined): VideoData | null {
+  const embed = post?.record?.embed;
+  const blob = embed?.video ?? embed?.media?.video;
+  const cid = blob?.ref?.$link;
+  if (!cid) return null;
+
+  const aspect =
+    embed?.aspectRatio ??
+    embed?.media?.aspectRatio ??
+    post?.embed?.aspectRatio ??
+    post?.embed?.media?.aspectRatio;
+  return {
+    cid,
+    size: blob?.size,
+    width: aspect?.width,
+    height: aspect?.height,
+    thumbnail: post?.embed?.thumbnail ?? post?.embed?.media?.thumbnail,
+  };
+}
+
+function buildFormat(blobUrl: string, video: VideoData): Format {
+  const { width, height } = video;
+  const short = width && height ? Math.min(width, height) : undefined;
+  return {
+    formatId: short ? `${short}p` : 'source',
+    url: blobUrl,
+    extension: 'mp4',
+    width,
+    height,
+    resolution: width && height ? `${width}x${height}` : undefined,
+    quality: short ? `${short}p` : 'Source',
+    vcodec: 'h264',
+    acodec: 'aac',
+    filesize: typeof video.size === 'number' ? video.size : undefined,
+    isMuxed: true,
+    isVideo: true,
+    isAudio: false,
+  };
+}
+
+export async function getInfo(
+  url: string,
+  _options: ExtractorOptions = {}
+): Promise<VideoInfo | null> {
+  try {
+    const match = url.match(/profile\/([^/]+)\/post\/([^/?#]+)/u);
+    if (!match) return null;
+    const [, handle, rkey] = match;
+
+    const resolved = await fetchJson<{ did?: string }>(
+      `${APPVIEW}/com.atproto.identity.resolveHandle?handle=${encodeURIComponent(handle)}`
+    );
+    const did = resolved?.did;
+    if (!did) return null;
+
+    const uri = `at://${did}/app.bsky.feed.post/${rkey}`;
+    const thread = await fetchJson<{ thread?: { post?: BskyPost } }>(
+      `${APPVIEW}/app.bsky.feed.getPostThread?uri=${encodeURIComponent(uri)}`
+    );
+    const post = thread?.thread?.post;
+
+    const video = pickVideo(post);
+    if (!video) return null; // no video -> yt-dlp fallback
+
+    const pds = await resolvePds(did);
+    if (!pds) return null;
+    const blobUrl = `${pds}/xrpc/com.atproto.sync.getBlob?did=${did}&cid=${video.cid}`;
+
+    const info: VideoInfo = {
+      type: 'video',
+      id: rkey,
+      title: post?.record?.text || 'Bluesky Video',
+      uploader:
+        post?.author?.displayName || post?.author?.handle || 'Bluesky User',
+      webpageUrl: url,
+      thumbnail: video.thumbnail,
+      formats: [buildFormat(blobUrl, video)],
+      extractorKey: 'bluesky',
+      isJsInfo: true,
+      fromBrain: false,
+      isPartial: false,
+      isIsrcMatch: false,
+      isFullData: true,
+    };
+
+    info.title = normalizeTitle(info as unknown as Record<string, unknown>);
+    info.uploader = normalizeArtist(info as unknown as Record<string, unknown>);
+
+    return info;
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[JS-Bluesky] Error extracting ${url}: ${message}`);
+    return null;
+  }
+}
+
+export function getStream(
+  videoInfo: VideoInfo,
+  options: ExtractorOptions = {}
+): Promise<Readable> {
+  const selected =
+    videoInfo.formats.find(
+      (format) => String(format.formatId) === String(options.formatId)
+    ) || videoInfo.formats[0];
+  if (!selected?.url) throw new Error('No stream URL found');
+
+  return Promise.resolve(getQuantumStream(selected.url, {}));
+}

backend/src/services/extractors/facebook/constants.ts

@@ -0,0 +1,80 @@
+export const DESKTOP_UA =
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36';
+
+export const HEADERS = {
+  'User-Agent': DESKTOP_UA,
+  Accept:
+    'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8',
+  'Accept-Language': 'en-US,en;q=0.5',
+  'Sec-Fetch-Mode': 'navigate',
+  'Sec-Fetch-Site': 'none',
+  'Sec-Fetch-Dest': 'document',
+  'Sec-Fetch-User': '?1',
+  'Upgrade-Insecure-Requests': '1',
+};
+
+export const ID_REGEX =
+  /(?:v=|fbid=|videos\/|reel\/|reels\/|share\/r\/|stories\/)([a-zA-Z0-9_-]+)/u;
+
+export const STORY_PATTERNS = [
+  /"unified_video_url"\s*:\s*"([^"]+)"/u,
+  /"playable_url"\s*:\s*"([^"]+)"/u,
+  /"playable_url_quality_hd"\s*:\s*"([^"]+)"/u,
+];
+
+export const PHOTO_PATTERNS = [
+  /"media"\s*:\s*\{"__typename"\s*:\s*"Photo",.*?"image"\s*:\s*\{"uri"\s*:\s*"([^"]+)"\}/u,
+  /"story_card_info"\s*:\s*\{.*?"story_thumbnail"\s*:\s*\{"uri"\s*:\s*"([^"]+)"\}/u,
+  /"image"\s*:\s*\{"uri"\s*:\s*"([^"]+)"\}/u,
+];
+
+export const THUMB_PATTERNS = [
+  /"preferred_thumbnail"\s*:\s*\{"image"\s*:\s*\{"uri"\s*:\s*"([^"]+)"\}/u,
+  /"preview_image"\s*:\s*\{"uri"\s*:\s*"([^"]+)"\}/u,
+];
+
+export const DASH_PATTERNS = [
+  /"browser_native_hd_url":\s*"([^"]+)"[^{}]*?"audioUrl":\s*"([^"]+)"/gu,
+  /"audioUrl":\s*"([^"]+)"[^{}]*?"browser_native_hd_url":\s*"([^"]+)"/gu,
+  /FBQualityClass=\\"hd\\"[^>]*BaseURL>(.*?)</gsu,
+  /representation_id=\\"\d+v\\"[^>]*base_url\\":\\"(.*?)\\"/gsu,
+];
+
+export const HD_FALLBACK_PATTERNS = [
+  /"browser_native_hd_url"\s*:\s*"([^"]+)"/u,
+  /"playable_url_quality_hd"\s*:\s*"([^"]+)"/u,
+  /hd_src\s*:\s*"([^"]+)"/u,
+];
+
+export const SD_FALLBACK_PATTERNS = [
+  /"browser_native_sd_url"\s*:\s*"([^"]+)"/u,
+  /"playable_url"\s*:\s*"([^"]+)"/u,
+  /sd_src\s*:\s*"([^"]+)"/u,
+  /"video_url"\s*:\s*"([^"]+)"/u,
+];
+
+export const RECOVERY_PATTERNS = [
+  {
+    type: 'author',
+    pattern:
+      /"(?:owner|author)":\{"__typename":"(?:User|Page)","name":"([^"]+)"/u,
+  },
+  {
+    type: 'author',
+    pattern: /"(?:story_bucket_owner_name|ownerName|author_name)":"([^"]+)"/u,
+  },
+  { type: 'author', pattern: /"story_bucket_owner":\{"name":"([^"]+)"/u },
+  { type: 'author', pattern: /"owner_as_page":\{"name":"([^"]+)"/u },
+  {
+    type: 'author',
+    pattern: /"comet_sections":\{"title":\{"text":"([^"]+)"\}/u,
+  },
+  { type: 'title', pattern: /"message":\s*\{"text":"([^"]+)"\}/u },
+  { type: 'title', pattern: /"video_title":"([^"]+)"/u },
+  { type: 'title', pattern: /"accessibility_caption":"([^"]+)"/u },
+  {
+    type: 'title',
+    pattern:
+      /"(?:message|node|accessibility_caption)":\s*\{"text":"([^"]+)"\}/u,
+  },
+];

backend/src/services/extractors/facebook/fetcher.ts

@@ -0,0 +1,46 @@
+import { HEADERS, DESKTOP_UA } from './constants.js';
+import { secureFetch } from '../../../utils/network/security.util.js';
+
+type FetchHtmlOptions = {
+  cookie?: string;
+};
+
+export async function fetchHtml(
+  url: string,
+  options: FetchHtmlOptions
+): Promise<{ html: string; targetUrl: string; res: Response } | null> {
+  const cookie = typeof options.cookie === 'string' ? options.cookie : null;
+  const response = await secureFetch(url, {
+    headers: {
+      ...HEADERS,
+      ...(cookie && { Cookie: cookie }),
+    },
+    signal: AbortSignal.timeout(10000),
+  });
+
+  if (!response.ok) return null;
+  const targetUrl = response.url;
+  const html = await response.text();
+  return { html, targetUrl, res: response as unknown as Response };
+}
+
+export async function fetchFileSize(url: string): Promise<number | undefined> {
+  try {
+    const headResponse = await secureFetch(url, {
+      method: 'HEAD',
+      headers: { 'User-Agent': DESKTOP_UA },
+      signal: AbortSignal.timeout(5000),
+    });
+    if (headResponse.ok) {
+      const contentLength = headResponse.headers.get('content-length');
+      if (contentLength) return parseInt(contentLength, 10);
+    }
+  } catch (error: unknown) {
+    if (error instanceof Error) {
+      console.debug('[FacebookExtractor] Size fetch error:', error.message);
+    } else {
+      console.debug('[FacebookExtractor] Size fetch error:', String(error));
+    }
+  }
+  return undefined;
+}

backend/src/services/extractors/facebook/index.ts

@@ -0,0 +1,86 @@
+import { getQuantumStream } from '../../../utils/network/proxy.util.js';
+import { VideoInfo, Format, ExtractorOptions } from '../../../types/index.js';
+import { Readable } from 'node:stream';
+import { DESKTOP_UA } from './constants.js';
+import { fetchHtml, fetchFileSize } from './fetcher.js';
+import { parseHtml } from './parser.js';
+import { normalizeVideoInfo } from './normalizer.js';
+
+export async function getInfo(
+  url: string,
+  _options: ExtractorOptions = {}
+): Promise<VideoInfo | null> {
+  try {
+    const fetchResult = await fetchHtml(url, _options);
+    if (!fetchResult) return null;
+
+    const { html, targetUrl } = fetchResult;
+
+    const parsedData = parseHtml(html, targetUrl);
+
+    let videoInfo = normalizeVideoInfo(targetUrl, parsedData);
+    if (!videoInfo) return null;
+
+    // retry lean page for caption
+    for (
+      let attempt = 0;
+      attempt < 2 && videoInfo.title === videoInfo.uploader;
+      attempt += 1
+    ) {
+      const retry = await fetchHtml(url, _options);
+      const alt = retry
+        ? normalizeVideoInfo(
+            retry.targetUrl,
+            parseHtml(retry.html, retry.targetUrl)
+          )
+        : null;
+      if (!alt || alt.formats.length === 0) break;
+      videoInfo = alt;
+    }
+
+    // fetch size
+    for (let i = 0; i < videoInfo.formats.length; i += 3) {
+      const batch = videoInfo.formats.slice(i, i + 3);
+      await Promise.all(
+        batch.map(async (format: Format) => {
+          if (format.url) {
+            const size = await fetchFileSize(format.url);
+            if (size) format.filesize = size;
+          }
+        })
+      );
+    }
+
+    return videoInfo;
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[JS-FB] Error extracting ${url}: ${message}`);
+    return null;
+  }
+}
+
+export function getStream(
+  videoInfo: VideoInfo,
+  options: ExtractorOptions = {}
+): Promise<Readable> {
+  const targetFormat =
+    videoInfo.formats.find(
+      (formatItem: Format) =>
+        String(formatItem.formatId) === String(options.formatId)
+    ) || videoInfo.formats[0];
+  if (!targetFormat?.url) throw new Error('No stream URL found');
+
+  return Promise.resolve(
+    getQuantumStream(targetFormat.url, {
+      'User-Agent': DESKTOP_UA,
+      Referer: 'https://www.facebook.com/',
+      Accept: '*/*',
+      'Accept-Language': 'en-US,en;q=0.9',
+      Range: 'bytes=0-',
+      Origin: 'https://www.facebook.com',
+      'Sec-Fetch-Dest': 'video',
+      'Sec-Fetch-Mode': 'cors',
+      'Sec-Fetch-Site': 'cross-site',
+    })
+  );
+}

backend/src/services/extractors/facebook/json-extractor.ts

@@ -0,0 +1,90 @@
+// json-block parse; regex stays as fallback
+import { FbRawFormat, FbParsed } from './types.js';
+
+type Obj = Record<string, unknown>;
+
+// no id here; parser adds it
+type FbJsonResult = Omit<FbParsed, 'id'>;
+
+const str = (value: unknown): string | undefined =>
+  typeof value === 'string' && value ? value : undefined;
+
+// walk every object node in parsed json
+function walk(node: unknown, visit: (obj: Obj) => void): void {
+  if (!node || typeof node !== 'object') return;
+  if (Array.isArray(node)) {
+    for (const item of node) walk(item, visit);
+    return;
+  }
+  visit(node as Obj);
+  for (const value of Object.values(node)) walk(value, visit);
+}
+
+// pull text/uri from nested {text}/{uri} node
+function nestedText(value: unknown, key: 'text' | 'uri'): string | undefined {
+  if (value && typeof value === 'object') {
+    return str((value as Obj)[key]);
+  }
+  return undefined;
+}
+
+export function extractFromJson(html: string): FbJsonResult | null {
+  const blocks = html.matchAll(
+    /<script[^>]+type="application\/json"[^>]*>([\s\S]*?)<\/script>/gu
+  );
+
+  const formats: FbRawFormat[] = [];
+  const seen = new Set<string>();
+  let title = '';
+  let uploader = '';
+  let thumbnail = '';
+  const photos = new Set<string>();
+
+  const addUrl = (url: string | undefined, id: string) => {
+    if (!url || seen.has(url)) return;
+    if (formats.some((format) => format.format_id === id)) return;
+    seen.add(url);
+    formats.push({ url, format_id: id, ext: 'mp4', vcodec: 'h264', acodec: 'aac' });
+  };
+
+  for (const block of blocks) {
+    let data: unknown;
+    try {
+      data = JSON.parse(block[1]);
+    } catch {
+      continue;
+    }
+    walk(data, (obj) => {
+      addUrl(str(obj.browser_native_hd_url) ?? str(obj.playable_url_quality_hd), 'hd');
+      addUrl(str(obj.browser_native_sd_url) ?? str(obj.playable_url), 'sd');
+      if (!title) title = nestedText(obj.message, 'text') ?? str(obj.video_title) ?? '';
+      if (!uploader) {
+        const owner = (obj.owner ?? obj.owner_as_page) as Obj | undefined;
+        uploader = str(owner?.name) ?? str(obj.ownerName) ?? '';
+      }
+      if (!thumbnail) {
+        const thumb = obj.preferred_thumbnail as Obj | undefined;
+        thumbnail = nestedText(thumb?.image, 'uri') ?? '';
+      }
+      const photoUri = nestedText(obj.viewer_image, 'uri');
+      if (photoUri) photos.add(photoUri);
+    });
+  }
+
+  // photo post: no video found, use images
+  if (formats.length === 0 && photos.size > 0) {
+    const single = photos.size === 1;
+    let index = 0;
+    for (const uri of photos) {
+      formats.push({
+        url: uri,
+        format_id: single ? 'photo' : `photo_${index}`,
+        ext: 'jpeg',
+      });
+      index += 1;
+    }
+  }
+
+  if (formats.length === 0) return null;
+  return { formats, title, uploader, thumbnail };
+}

backend/src/services/extractors/facebook/normalizer.ts

@@ -0,0 +1,71 @@
+import { VideoInfo, Format } from '../../../types/index.js';
+import { normalizeTitle, normalizeArtist } from '../../social.service.js';
+import { FbParsed } from './types.js';
+
+export function normalizeVideoInfo(
+  url: string,
+  parsedData: FbParsed | null
+): VideoInfo | null {
+  if (!parsedData) return null;
+
+  const formats: Format[] = parsedData.formats.map((formatItem, index) => {
+    const vcodec =
+      formatItem.vcodec ?? (formatItem.ext === 'mp4' ? 'h264' : undefined);
+    const acodec =
+      formatItem.acodec ??
+      (formatItem.ext === 'mp4' || formatItem.ext === 'm4a'
+        ? 'aac'
+        : undefined);
+
+    const tier =
+      formatItem.format_id === 'hd'
+        ? 'HD'
+        : formatItem.format_id === 'sd'
+          ? 'SD'
+          : formatItem.format_id?.startsWith('photo')
+            ? 'Photo'
+            : undefined;
+
+    return {
+      formatId: formatItem.format_id || `fb_${index}`,
+      url: formatItem.url,
+      extension: formatItem.ext ?? 'mp4',
+      resolution: tier ?? 'Source',
+      quality: tier,
+      acodec,
+      vcodec,
+      isAudio: Boolean(acodec && acodec !== 'none'),
+      isVideo: Boolean(vcodec && vcodec !== 'none'),
+      isMuxed: Boolean(
+        acodec && acodec !== 'none' && vcodec && vcodec !== 'none'
+      ),
+    };
+  });
+
+  if (formats.length === 0) return null;
+
+  const info: VideoInfo = {
+    type: 'video',
+    id: parsedData.id || url,
+    title: parsedData.title || 'Facebook Video',
+    uploader: parsedData.uploader || 'Facebook User',
+    webpageUrl: url,
+    formats,
+    extractorKey: 'facebook',
+    isJsInfo: true,
+    fromBrain: false,
+    isPartial: false,
+    isIsrcMatch: false,
+    isFullData: false,
+  };
+
+  // make caption authoritative over og:title
+  if (parsedData.title) {
+    info.metascraper = { title: parsedData.title };
+  }
+
+  info.title = normalizeTitle(info as unknown as Record<string, unknown>);
+  info.uploader = normalizeArtist(info as unknown as Record<string, unknown>);
+
+  return info;
+}

backend/src/services/extractors/facebook/parser.ts

@@ -0,0 +1,158 @@
+import {
+  ID_REGEX,
+  THUMB_PATTERNS,
+  DASH_PATTERNS,
+  RECOVERY_PATTERNS,
+  STORY_PATTERNS,
+  PHOTO_PATTERNS,
+  HD_FALLBACK_PATTERNS,
+  SD_FALLBACK_PATTERNS,
+} from './constants.js';
+import { decode, decodeHtmlEntities } from './utils.js';
+import { extractFromJson } from './json-extractor.js';
+import { FbRawFormat, FbParsed } from './types.js';
+
+// first decoded capture across patterns
+function firstCapture(html: string, patterns: RegExp[]): string | null {
+  for (const pattern of patterns) {
+    const match = html.match(pattern);
+    if (match) return decode(match[1]);
+  }
+  return null;
+}
+
+function extractMeta(html: string): { title: string; uploader: string } {
+  let title = '';
+  let uploader = '';
+  for (const recovery of RECOVERY_PATTERNS) {
+    const match = html.match(recovery.pattern);
+    if (!match) continue;
+    if (recovery.type === 'title' && !title) title = decode(match[1]);
+    if (recovery.type === 'author' && !uploader) uploader = decode(match[1]);
+  }
+  return { title, uploader };
+}
+
+function extractDashFormats(html: string): FbRawFormat[] {
+  const formats: FbRawFormat[] = [];
+  for (const pattern of DASH_PATTERNS) {
+    for (const match of html.matchAll(pattern)) {
+      if (match[1] && match[2]) {
+        formats.push({ url: decode(match[1]), format_id: 'hd', ext: 'mp4' });
+        formats.push({
+          url: decode(match[2]),
+          format_id: 'audio',
+          ext: 'm4a',
+          acodec: 'aac',
+        });
+      } else if (match[1]) {
+        formats.push({ url: decode(match[1]), format_id: 'sd', ext: 'mp4' });
+      }
+    }
+  }
+  return formats;
+}
+
+function extractFallbackFormats(html: string): FbRawFormat[] {
+  const formats: FbRawFormat[] = [];
+  // hd: browser_native first, else story
+  const hd =
+    firstCapture(html, HD_FALLBACK_PATTERNS) ??
+    firstCapture(html, STORY_PATTERNS);
+  if (hd) formats.push({ url: hd, format_id: 'hd', ext: 'mp4' });
+
+  // sd also covers story playable_url
+  const sd = firstCapture(html, SD_FALLBACK_PATTERNS);
+  if (sd) formats.push({ url: sd, format_id: 'sd', ext: 'mp4' });
+
+  // photo only when no video found
+  if (formats.length === 0) {
+    const photo = firstCapture(html, PHOTO_PATTERNS);
+    if (photo) formats.push({ url: photo, format_id: 'photo', ext: 'jpeg' });
+  }
+  return formats;
+}
+
+// parse caption/author from og:title
+function parseOgTitle(html: string): { caption?: string; author?: string } {
+  const match = html.match(/<meta property="og:title" content="([^"]*)"/u);
+  if (!match) return {};
+  const parts = decodeHtmlEntities(match[1])
+    .split('|')
+    .map((part) => part.trim())
+    .filter(Boolean);
+  if (parts.length === 0) return {};
+  const author = parts[parts.length - 1].replace(
+    /^(?:Reel|Video)\s+by\s+/iu,
+    ''
+  );
+  const caption = parts
+    .slice(0, -1)
+    .find(
+      (part) =>
+        !/\b(?:views?|reactions?|likes?|shares?|comments?)\b/iu.test(part)
+    );
+  return { caption, author };
+}
+
+function parseOgImage(html: string): string | undefined {
+  const match = html.match(/<meta property="og:image" content="([^"]+)"/u);
+  return match ? decodeHtmlEntities(match[1]) : undefined;
+}
+
+// fb auto-generated alt-text, not a caption
+function isAltText(text: string): boolean {
+  return /^May be a/iu.test(text) || /^No photo description/iu.test(text);
+}
+
+// og:description holds the post caption
+function parseOgDescription(html: string): string {
+  const match = html.match(
+    /<meta property="og:description" content="([^"]*)"/u
+  );
+  if (!match) return '';
+  const text = decodeHtmlEntities(match[1]).trim();
+  if (isAltText(text)) return '';
+  if (text.length <= 120) return text;
+  return text.slice(0, 120).replace(/\s+\S*$/u, '');
+}
+
+export function parseHtml(html: string, url: string): FbParsed {
+  const idMatch = url.match(ID_REGEX);
+  const videoId = idMatch ? idMatch[1] : null;
+  const og = parseOgTitle(html);
+  const ogDesc = parseOgDescription(html);
+
+  // json-first; regex fallback
+  const json = extractFromJson(html);
+  if (json) {
+    const meta = extractMeta(html);
+    return {
+      id: videoId,
+      title: json.title || og.caption || ogDesc || (isAltText(meta.title) ? '' : meta.title),
+      uploader: json.uploader || og.author || meta.uploader,
+      thumbnail: json.thumbnail || firstCapture(html, THUMB_PATTERNS) || '',
+      formats: json.formats,
+    };
+  }
+
+  const { title, uploader } = extractMeta(html);
+  const thumbnail = firstCapture(html, THUMB_PATTERNS) ?? '';
+
+  let formats = extractDashFormats(html);
+  if (formats.length === 0) formats = extractFallbackFormats(html);
+
+  // gated page: og:image fallback
+  if (formats.length === 0) {
+    const ogImage = parseOgImage(html);
+    if (ogImage) formats = [{ url: ogImage, format_id: 'photo', ext: 'jpeg' }];
+  }
+
+  return {
+    id: videoId,
+    title: og.caption || ogDesc || (isAltText(title) ? '' : title) || '',
+    uploader: uploader || og.author || '',
+    thumbnail,
+    formats,
+  };
+}

backend/src/services/extractors/facebook/types.ts

@@ -0,0 +1,19 @@
+// shared contract across parse + normalize
+
+// snake_case mirrors fb wire keys
+export interface FbRawFormat {
+  url: string;
+  format_id?: string;
+  ext?: string;
+  vcodec?: string;
+  acodec?: string;
+}
+
+// parsed media and page meta
+export interface FbParsed {
+  id: string | null;
+  title: string;
+  uploader: string;
+  thumbnail: string;
+  formats: FbRawFormat[];
+}

backend/src/services/extractors/facebook/utils.ts

@@ -0,0 +1,32 @@
+// decode numeric + named HTML entities
+export function decodeHtmlEntities(text: string): string {
+  return text
+    .replace(/&#x([0-9a-fA-F]+);/gu, (_match, hex) =>
+      String.fromCodePoint(parseInt(hex, 16))
+    )
+    .replace(/&#(\d+);/gu, (_match, dec) =>
+      String.fromCodePoint(parseInt(dec, 10))
+    )
+    .replace(/&/gu, '&')
+    .replace(/"/gu, '"')
+    .replace(/&lt;/gu, '<')
+    .replace(/&gt;/gu, '>');
+}
+
+// decode js-escaped json-in-html capture
+export function decode(text: string): string {
+  try {
+    if (text.startsWith('"') && text.endsWith('"')) return JSON.parse(text);
+    const unescaped = text
+      .replace(/\\u([0-9a-fA-F]{4})/gu, (_match, group) =>
+        String.fromCharCode(parseInt(group, 16))
+      )
+      .replace(/\\\//gu, '/')
+      .replace(/\\"/gu, '"')
+      .replace(/\\\\/gu, '\\');
+    return decodeHtmlEntities(unescaped);
+  } catch (error) {
+    console.debug('Ignored:', (error as Error).message);
+    return text.replace(/\\/gu, '').replace(/&amp;/gu, '&');
+  }
+}

backend/src/services/extractors/index.ts

@@ -0,0 +1,320 @@
+import {
+  getInfo as ytGetInfo,
+  getStream as ytGetStream,
+} from './youtube/index.js';
+import {
+  getInfo as igGetInfo,
+  getStream as igGetStream,
+} from './instagram/index.js';
+import {
+  getInfo as fbGetInfo,
+  getStream as fbGetStream,
+} from './facebook/index.js';
+import { getInfo as tkGetInfo, getStream as tkGetStream } from './tiktok.js';
+import { getInfo as spGetInfo, getStream as spGetStream } from './spotify.js';
+import {
+  getInfo as scGetInfo,
+  getStream as scGetStream,
+} from './soundcloud.js';
+import { getInfo as xGetInfo, getStream as xGetStream } from './x.js';
+import {
+  getInfo as bsGetInfo,
+  getStream as bsGetStream,
+} from './bluesky.js';
+import {
+  getInfo as thGetInfo,
+  getStream as thGetStream,
+} from './threads/index.js';
+import { Extractor, ExtractorOptions, VideoInfo } from '../../types/index.js';
+import {
+  fetchMetadata,
+  fetchYoutubeOEmbed,
+} from '../../utils/media/metadata.util.js';
+import { recordFailure } from '../../utils/infra/metrics.util.js';
+
+const youtube: Extractor = { getInfo: ytGetInfo, getStream: ytGetStream };
+const instagram: Extractor = { getInfo: igGetInfo, getStream: igGetStream };
+const facebook: Extractor = { getInfo: fbGetInfo, getStream: fbGetStream };
+const tiktok: Extractor = { getInfo: tkGetInfo, getStream: tkGetStream };
+const spotify: Extractor = { getInfo: spGetInfo, getStream: spGetStream };
+const soundcloud: Extractor = { getInfo: scGetInfo, getStream: scGetStream };
+const x: Extractor = { getInfo: xGetInfo, getStream: xGetStream };
+const bluesky: Extractor = { getInfo: bsGetInfo, getStream: bsGetStream };
+const threads: Extractor = { getInfo: thGetInfo, getStream: thGetStream };
+
+// reverse lookup for failure labels
+const extractorNames = new Map<Extractor, string>([
+  [youtube, 'youtube'],
+  [instagram, 'instagram'],
+  [facebook, 'facebook'],
+  [tiktok, 'tiktok'],
+  [spotify, 'spotify'],
+  [soundcloud, 'soundcloud'],
+  [x, 'x'],
+  [bluesky, 'bluesky'],
+  [threads, 'threads'],
+]);
+
+// map in-flight JS
+const inFlightJsTasks = new Map<string, Promise<VideoInfo | null>>();
+
+/**
+ * Returns the in-flight (or recently completed) JS extraction promise for a URL.
+ * Used by handleYoutubeTiktokInfo to skip yt-dlp deep-scan when JS already has formats.
+ */
+export function getInFlightJsResult(
+  url: string
+): Promise<VideoInfo | null> | undefined {
+  return inFlightJsTasks.get(url);
+}
+
+const genericExtractor: Extractor = {
+  getInfo: async (url: string) => {
+    const meta = await fetchMetadata(url);
+    if (!meta) return null;
+    return {
+      type: 'video',
+      id: `gen_${Buffer.from(url).toString('base64').substring(0, 10)}`,
+      title: meta.title || 'Unknown Video',
+      uploader: meta.author || meta.publisher || 'Unknown',
+      thumbnail: meta.image || undefined,
+      webpageUrl: url,
+      formats: [],
+      metascraper: meta,
+      fromBrain: false,
+      isPartial: false,
+      isIsrcMatch: false,
+      isJsInfo: true,
+      isFullData: false,
+    };
+  },
+  getStream: () => {
+    throw new Error(
+      'Streaming not supported for generic URLs. Please provide a supported platform link.'
+    );
+  },
+};
+
+export function getExtractor(url: string): Extractor | null {
+  if (url.includes('youtube.com') || url.includes('youtu.be')) return youtube;
+  if (url.includes('instagram.com')) return instagram;
+  if (url.includes('facebook.com') || url.includes('fb.watch')) return facebook;
+  if (url.includes('threads.net') || url.includes('threads.com'))
+    return threads;
+  if (url.includes('tiktok.com')) return tiktok;
+  if (url.includes('spotify.com')) return spotify;
+  if (url.includes('soundcloud.com')) return soundcloud;
+  if (url.includes('twitter.com') || /\/\/(?:www\.|mobile\.)?x\.com\//u.test(url))
+    return x;
+  if (url.includes('bsky.app')) return bluesky;
+  return genericExtractor;
+}
+
+// platform label, not a real author
+function isLowValueEarlyAuthor(name: string | undefined): boolean {
+  if (!name) return true;
+  const value = name.trim().toLowerCase();
+  return [
+    'facebook',
+    'instagram',
+    'threads',
+    'tiktok',
+    'x',
+    'twitter',
+    'bluesky',
+    'social media',
+    'make your day',
+    'unknown',
+  ].includes(value);
+}
+
+export async function getInfo(
+  url: string,
+  options: ExtractorOptions = {}
+): Promise<VideoInfo | null> {
+  const extractor = getExtractor(url);
+  if (!extractor) return null;
+
+  const getInfoStart = Date.now();
+  const isYouTube = url.includes('youtube.com') || url.includes('youtu.be');
+
+  // use oEmbed/metascraper
+  const metaFetcher = isYouTube ? fetchYoutubeOEmbed : fetchMetadata;
+
+  // define metascraper promise
+  const metaFetchStart = Date.now();
+  const metascraperTask = metaFetcher(url)
+    .catch(() => null)
+    .then(async (meta) => {
+      const metaFetchMs = Date.now() - metaFetchStart;
+      console.log(
+        `[Timing] ${isYouTube ? 'oEmbed' : 'metascraper'} fetch took ${metaFetchMs}ms (returned ${meta ? 'data' : 'null'})`
+      );
+
+      if (meta && (meta.author || meta.publisher) && options.onProgress) {
+        try {
+          const dispatchStart = Date.now();
+          const { prepareFinalResponse } =
+            await import('../../utils/api/response.util.js');
+          const earlyInfo: VideoInfo = {
+            type: 'video',
+            id: `early_${Buffer.from(url).toString('base64').substring(0, 10)}`,
+            title: meta.title || 'Unknown Video',
+            uploader: meta.author || meta.publisher || 'Unknown',
+            thumbnail: meta.image || undefined,
+            webpageUrl: url,
+            formats: [],
+            metascraper: meta,
+            fromBrain: false,
+            isPartial: true,
+            isIsrcMatch: false,
+            isJsInfo: true,
+            isFullData: false,
+          };
+
+          const finalEarlyData = await prepareFinalResponse(
+            earlyInfo,
+            false,
+            null,
+            url
+          );
+          finalEarlyData.isPartial = true;
+
+          // skip flickery paint for platform labels
+          if (isLowValueEarlyAuthor(finalEarlyData.artist)) {
+            console.log(
+              `[Metadata] Skipped low-value early hit (author "${finalEarlyData.artist}")`
+            );
+            return meta;
+          }
+
+          const totalEarlyHitMs = Date.now() - getInfoStart;
+          const wallClockMs = options.requestT0
+            ? Date.now() - options.requestT0
+            : null;
+          // track total request execution time
+          const wallClockSuffix =
+            wallClockMs !== null ? `, wall-clock ${wallClockMs}ms` : '';
+          console.log(
+            `[Metadata] Early hit: "${finalEarlyData.title}" by "${finalEarlyData.artist}" (T+${totalEarlyHitMs}ms from getInfo start, dispatch prep ${Date.now() - dispatchStart}ms${wallClockSuffix})`
+          );
+
+          options.onProgress(
+            'extracting',
+            45,
+            'Metadata found',
+            JSON.stringify({ early_metadata: finalEarlyData })
+          );
+        } catch (err) {
+          console.error('[Metadata] Early dispatch failed:', err);
+        }
+      }
+      return meta;
+    });
+
+  // js extraction
+  const jsTask = (async () => {
+    try {
+      const res = await extractor.getInfo(url, options);
+      return res;
+    } catch {
+      recordFailure(`extract:${extractorNames.get(extractor) ?? 'generic'}`);
+      return null;
+    }
+  })();
+
+  // cache JS task
+  inFlightJsTasks.set(url, jsTask);
+  jsTask.finally(() => {
+    const cleanupTimer = setTimeout(() => {
+      if (inFlightJsTasks.get(url) === jsTask) {
+        inFlightJsTasks.delete(url);
+      }
+    }, 30000);
+    // allow process exit
+    cleanupTimer.unref?.();
+  });
+
+  const fastResult = await Promise.race([
+    jsTask.then((res) => ({
+      type: 'js' as const,
+      data: res as VideoInfo | null,
+    })),
+    metascraperTask.then((meta) => ({ type: 'meta' as const, data: meta })),
+    new Promise<{ type: 'timeout'; data: null }>((resolve) =>
+      setTimeout(() => resolve({ type: 'timeout', data: null }), 8000)
+    ),
+  ]);
+
+  if (
+    fastResult.type === 'js' &&
+    fastResult.data &&
+    Array.isArray(fastResult.data.formats) &&
+    fastResult.data.formats.length > 0
+  ) {
+    const meta = await metascraperTask;
+    // extractor thumbnail wins; metascraper only fills gaps
+    if (meta && !fastResult.data.thumbnail) {
+      fastResult.data.metascraper = { image: meta.image };
+    }
+    return fastResult.data as VideoInfo;
+  }
+
+  // js slow/empty: metascraper fallback
+  if (fastResult.type === 'meta' && fastResult.data) {
+    const meta = fastResult.data;
+    return {
+      type: 'video',
+      id: `meta_${Buffer.from(url).toString('base64').substring(0, 10)}`,
+      title: meta.title || 'Unknown Video',
+      uploader: meta.author || meta.publisher || 'Unknown',
+      webpageUrl: url,
+      formats: [],
+      thumbnail: meta.image || undefined,
+      metascraper: { image: meta.image },
+      fromBrain: false,
+      isPartial: true,
+      isIsrcMatch: false,
+      isJsInfo: false,
+      isFullData: false,
+    } as VideoInfo;
+  }
+
+  // fallback to js
+  return await jsTask;
+}
+
+export function shouldJSStream(url: string, quality: string, format: string) {
+  if (url.includes('youtube.com') || url.includes('youtu.be')) {
+    return false;
+  }
+
+  if (
+    url.includes('facebook.com') ||
+    url.includes('instagram.com') ||
+    url.includes('threads.net') ||
+    url.includes('threads.com') ||
+    url.includes('spotify.com') ||
+    url.includes('soundcloud.com')
+  )
+    return true;
+
+  if (url.includes('tiktok.com')) return false; // download issues
+
+  if (['mp3', 'm4a', 'audio'].includes(format)) return true;
+
+  const res = parseInt(quality);
+  return !isNaN(res) && res <= 720;
+}
+
+export {
+  youtube,
+  instagram,
+  facebook,
+  tiktok,
+  spotify,
+  soundcloud,
+  x,
+  bluesky,
+  threads,
+};

backend/src/services/extractors/instagram/fetcher.ts

@@ -0,0 +1,61 @@
+import { secureFetch } from '../../../utils/network/security.util.js';
+
+export async function fetchJson(
+  url: string,
+  options: { cookie?: string } = {}
+): Promise<unknown> {
+  const cookie = typeof options.cookie === 'string' ? options.cookie : null;
+  const response = await secureFetch(url, {
+    headers: {
+      'User-Agent':
+        'Mozilla/5.0 (iPhone; CPU iPhone OS 14_8 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1',
+      Accept: '*/*',
+      'Accept-Language': 'en-US,en;q=0.5',
+      'X-Requested-With': 'XMLHttpRequest',
+      ...(cookie && { Cookie: cookie }),
+    },
+    signal: AbortSignal.timeout(10000),
+  });
+
+  if (!response.ok) return null;
+  return await response.json();
+}
+
+export async function fetchEmbed(
+  url: string,
+  options: { cookie?: string } = {}
+): Promise<string | null> {
+  const cookie = typeof options.cookie === 'string' ? options.cookie : null;
+  const response = await secureFetch(`${url}embed/captioned/`, {
+    headers: {
+      'User-Agent':
+        'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+      ...(cookie && { Cookie: cookie }),
+    },
+    signal: AbortSignal.timeout(10000),
+  });
+
+  if (!response.ok) return null;
+  return await response.text();
+}
+
+export async function fetchFileSize(url: string): Promise<number | undefined> {
+  try {
+    const headResponse = await secureFetch(url, {
+      method: 'HEAD',
+      headers: {
+        'User-Agent':
+          'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+      },
+      signal: AbortSignal.timeout(5000),
+    });
+    if (headResponse.ok) {
+      const contentLengthHeader = headResponse.headers.get('content-length');
+      if (contentLengthHeader) return parseInt(contentLengthHeader, 10);
+    }
+  } catch (error: unknown) {
+    const errorObj = error as Error;
+    console.debug(`[Instagram] Size fetch failed: ${errorObj.message}`);
+  }
+  return undefined;
+}

backend/src/services/extractors/instagram/index.ts

@@ -0,0 +1,75 @@
+import { getQuantumStream } from '../../../utils/network/proxy.util.js';
+import { VideoInfo, Format, ExtractorOptions } from '../../../types/index.js';
+import { Readable } from 'node:stream';
+import { fetchJson, fetchEmbed, fetchFileSize } from './fetcher.js';
+import { parseJson, parseEmbed } from './parser.js';
+import { normalizeVideoInfo } from './normalizer.js';
+
+export async function getInfo(
+  url: string,
+  options: ExtractorOptions = {}
+): Promise<VideoInfo | null> {
+  try {
+    // try JSON
+    let rawData = null;
+    const jsonUrl = url.includes('?')
+      ? `${url.split('?')[0]}?__a=1&__d=dis`
+      : `${url}?__a=1&__d=dis`;
+    const jsonData = await fetchJson(jsonUrl, options);
+    if (jsonData) {
+      rawData = parseJson(jsonData);
+    }
+
+    if (!rawData) {
+      const embedHtml = await fetchEmbed(url, options);
+      if (embedHtml) {
+        rawData = parseEmbed(embedHtml);
+      }
+    }
+
+    if (!rawData) return null;
+
+    const videoInfo = normalizeVideoInfo(url, rawData);
+    if (!videoInfo) return null;
+
+    // fetch size
+    for (let index = 0; index < videoInfo.formats.length; index += 2) {
+      const batch = videoInfo.formats.slice(index, index + 2);
+      await Promise.all(
+        batch.map(async (formatItem: Format) => {
+          if (formatItem.url) {
+            const size = await fetchFileSize(formatItem.url);
+            if (size) formatItem.filesize = size;
+          }
+        })
+      );
+    }
+
+    return videoInfo;
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[JS-IG] Error extracting ${url}: ${message}`);
+    return null;
+  }
+}
+
+export function getStream(
+  videoInfo: VideoInfo,
+  options: ExtractorOptions = {}
+): Promise<Readable> {
+  const targetFormat =
+    videoInfo.formats.find(
+      (formatItem: Format) =>
+        String(formatItem.formatId) === String(options.formatId)
+    ) || videoInfo.formats[0];
+  if (!targetFormat?.url) throw new Error('No stream URL found');
+
+  return Promise.resolve(
+    getQuantumStream(targetFormat.url, {
+      'User-Agent':
+        'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+      Referer: 'https://www.instagram.com/',
+      Accept: '*/*',
+    })
+  );
+}

backend/src/services/extractors/instagram/normalizer.ts

@@ -0,0 +1,50 @@
+import { VideoInfo } from '../../../types/index.js';
+import { normalizeTitle, normalizeArtist } from '../../social.service.js';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export function normalizeVideoInfo(
+  url: string,
+  parsedData: any
+): VideoInfo | null {
+  if (!parsedData) return null;
+
+  const rawFormats = (parsedData.formats || []) as any[];
+  const formats = rawFormats.map((formatItem) => {
+    return {
+      formatId: formatItem.id || `ig_${Math.random().toString(36).slice(2, 7)}`,
+      url: formatItem.video_url || formatItem.display_url,
+      extension: 'mp4',
+      resolution: formatItem.width
+        ? `${formatItem.width}x${formatItem.height}`
+        : 'Source',
+      width: formatItem.width,
+      height: formatItem.height,
+      filesize: formatItem.filesize,
+      acodec: 'aac',
+      vcodec: 'h264',
+      isAudio: true,
+      isVideo: true,
+      isMuxed: true,
+    };
+  });
+
+  const info: VideoInfo = {
+    type: 'video',
+    id: parsedData.id || url,
+    title: parsedData.title || 'Instagram Video',
+    uploader: parsedData.uploader || 'Instagram User',
+    webpageUrl: url,
+    formats,
+    extractorKey: 'instagram',
+    isJsInfo: true,
+    fromBrain: false,
+    isPartial: false,
+    isIsrcMatch: false,
+    isFullData: false,
+  };
+
+  info.title = normalizeTitle(info as unknown as Record<string, unknown>);
+  info.uploader = normalizeArtist(info as unknown as Record<string, unknown>);
+
+  return info;
+}

backend/src/services/extractors/instagram/parser.ts

@@ -0,0 +1,70 @@
+import { load, CheerioAPI } from 'cheerio';
+import { decode } from '../facebook/utils.js';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export function parseJson(jsonData: any): unknown {
+  const items = (jsonData?.items || []) as any[];
+  if (items.length === 0) return null;
+
+  const item = items[0];
+  const videoVersions = (item.video_versions || []) as any[];
+  const user = item.user;
+
+  return {
+    id: item.pk || item.id,
+    title: item.caption?.text || 'Instagram Post',
+    uploader: user?.full_name || user?.username,
+    thumbnail: item.image_versions2?.candidates?.[0]?.url,
+    formats: videoVersions.map((version) => ({
+      id: version.id,
+      video_url: version.url,
+      width: version.width,
+      height: version.height,
+    })),
+  };
+}
+
+const _extractThumbnailFromCheerio = (cheerioInstance: CheerioAPI) => {
+  return (
+    cheerioInstance('meta[property="og:image"]').attr('content') ||
+    cheerioInstance('img.EmbeddedMediaImage').attr('src')
+  );
+};
+
+const _extractVideoUrlFromHtml = (html: string) => {
+  const videoMatch = html.match(/"video_url"\s*:\s*"([^"]+)"/u);
+  return videoMatch ? decode(videoMatch[1]) : null;
+};
+
+export function parseEmbed(html: string): unknown {
+  const cheerioInstance = load(html);
+  const title =
+    cheerioInstance('meta[property="og:title"]').attr('content') ||
+    cheerioInstance('.Caption').text() ||
+    'Instagram Video';
+
+  const uploader =
+    cheerioInstance('.Username').text() ||
+    cheerioInstance('.UsernameText').text() ||
+    'Instagram User';
+
+  const thumbnail = _extractThumbnailFromCheerio(cheerioInstance);
+  const videoUrl = _extractVideoUrlFromHtml(html);
+
+  const formats = videoUrl
+    ? [
+        {
+          id: 'hd',
+          video_url: videoUrl,
+        },
+      ]
+    : [];
+
+  return {
+    id: null,
+    title,
+    uploader,
+    thumbnail,
+    formats,
+  };
+}

backend/src/services/extractors/soundcloud.ts

@@ -0,0 +1,187 @@
+import { Readable } from 'node:stream';
+import { VideoInfo, ExtractorOptions } from '../../types/index.js';
+import { secureFetch } from '../../utils/network/security.util.js';
+
+let cachedClientId: string | null = null;
+let lastClientIdFetch = 0;
+const CLIENT_ID_EXPIRY = 3600000; // 1 hour
+
+async function getClientId(): Promise<string | null> {
+  if (cachedClientId && Date.now() - lastClientIdFetch < CLIENT_ID_EXPIRY) {
+    return cachedClientId;
+  }
+
+  try {
+    console.log('[SoundCloud] Fetching fresh client_id...');
+    const response = await secureFetch('https://soundcloud.com', {
+      headers: {
+        'User-Agent':
+          'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+      },
+    });
+    const html = await response.text();
+    const scriptUrls = html.match(/src="([^"]+\/assets\/[^"]+\.js)"/g) || [];
+
+    for (const scriptTag of scriptUrls.reverse()) {
+      const match = scriptTag.match(/src="([^"]+)"/u);
+      if (!match) continue;
+      const url = match[1];
+      const scriptRes = await secureFetch(url);
+      const scriptBody = await scriptRes.text();
+      const idMatch = scriptBody.match(/client_id:"([a-zA-Z0-9]{32})"/u);
+      if (idMatch) {
+        cachedClientId = idMatch[1];
+        lastClientIdFetch = Date.now();
+        console.log(`[SoundCloud] Found client_id: ${cachedClientId}`);
+        return cachedClientId;
+      }
+    }
+  } catch (error: unknown) {
+    console.error(
+      '[SoundCloud] Failed to fetch client_id:',
+      error instanceof Error ? error.message : String(error)
+    );
+  }
+  return cachedClientId;
+}
+
+export async function search(query: string): Promise<unknown[]> {
+  const clientId = await getClientId();
+  if (!clientId) return [];
+
+  try {
+    const url = `https://api-v2.soundcloud.com/search/tracks?q=${encodeURIComponent(query)}&client_id=${clientId}&limit=5`;
+    const response = await secureFetch(url);
+    const { collection } = (await response.json()) as {
+      collection?: unknown[];
+    };
+    return collection ?? [];
+  } catch (error: unknown) {
+    if (error instanceof Error) {
+      console.error('[SoundCloud] Search error:', error.message);
+    } else {
+      console.error('[SoundCloud] Search error:', error);
+    }
+    return [];
+  }
+}
+
+interface SoundCloudTranscoding {
+  url: string;
+  format: {
+    protocol: string;
+    mime_type: string;
+  };
+}
+
+interface SoundCloudTrack {
+  policy: string;
+  duration: number;
+  full_duration: number;
+  title: string;
+  media?: {
+    transcodings?: SoundCloudTranscoding[];
+  };
+  id: string | number;
+  user?: {
+    username: string;
+    avatar_url?: string;
+  };
+  artwork_url?: string;
+}
+
+export async function getInfo(
+  url: string,
+  _options: ExtractorOptions = {}
+): Promise<VideoInfo> {
+  const clientId = await getClientId();
+  if (!clientId) throw new Error('Could not obtain SoundCloud client_id');
+  console.log(
+    `[Metadata] Engine: Pure-JS | Platform: SoundCloud | URL: ${url}`
+  );
+
+  try {
+    const resolveUrl = `https://api-v2.soundcloud.com/resolve?url=${encodeURIComponent(url)}&client_id=${clientId}`;
+    const response = await secureFetch(resolveUrl);
+    if (!response.ok)
+      throw new Error(`Failed to resolve SoundCloud URL: ${response.status}`);
+    const track = (await response.json()) as SoundCloudTrack;
+
+    const isSnippet =
+      track.policy === 'SNIPPET' ||
+      (track.duration < 60000 && track.full_duration > 60000);
+    if (isSnippet) {
+      console.warn(
+        `[SoundCloud] Rejected snippet: ${track.title} (${(track.duration / 1000).toFixed(1)}s)`
+      );
+      throw new Error('This track is a preview snippet only.');
+    }
+
+    const transcoding =
+      track.media?.transcodings?.find(
+        (transcodingItem) => transcodingItem.format.protocol === 'progressive'
+      ) ||
+      track.media?.transcodings?.find(
+        (transcodingItem) => transcodingItem.format.protocol === 'hls'
+      );
+
+    if (!transcoding)
+      throw new Error('No supported stream found for this track');
+
+    return {
+      type: 'video',
+      id: track.id.toString(),
+      extractorKey: 'soundcloud',
+      isJsInfo: true,
+      title: track.title,
+      author: track.user?.username || 'Unknown',
+      uploader: track.user?.username || 'Unknown',
+      duration: track.duration / 1000,
+      thumbnail: track.artwork_url || track.user?.avatar_url || '',
+      webpageUrl: url,
+      formats: [
+        {
+          formatId: 'audio',
+          url,
+          extension: 'mp3',
+          resolution: 'Audio',
+          acodec: 'mp3',
+          abr: 128,
+          isAudio: true,
+          isVideo: false,
+          isMuxed: false,
+        },
+      ],
+      fromBrain: false,
+      isPartial: false,
+      isIsrcMatch: false,
+      isFullData: false,
+    };
+  } catch (error: unknown) {
+    console.error(
+      '[SoundCloud] getInfo error:',
+      error instanceof Error ? error.message : String(error)
+    );
+    throw error;
+  }
+}
+
+export async function getStream(
+  info: VideoInfo,
+  _options: ExtractorOptions = {}
+): Promise<Readable> {
+  const clientId = await getClientId();
+  if (!clientId) throw new Error('Missing client_id');
+
+  const format = info.formats[0];
+  const streamAuthUrl = `${format.url}?client_id=${clientId}`;
+  const response = await secureFetch(streamAuthUrl);
+  const data = (await response.json()) as { url: string };
+  const directUrl = data.url;
+
+  const streamResponse = await secureFetch(directUrl);
+  if (!streamResponse.body) throw new Error('No stream body');
+  return Readable.fromWeb(
+    streamResponse.body as import('node:stream/web').ReadableStream
+  );
+}

backend/src/services/extractors/spotify.ts

@@ -0,0 +1,147 @@
+import {
+  getInfo as getYtInfo,
+  getStream as getYtStream,
+} from './youtube/index.js';
+import { VideoInfo, ExtractorOptions, Format } from '../../types/index.js';
+import { Readable } from 'node:stream';
+
+type SpotifyData = {
+  targetUrl: string;
+  youtubeUrl?: string;
+  fromBrain?: boolean;
+  formats?: Format[];
+  imageUrl?: string;
+  cover?: string;
+  thumbnail?: string;
+  duration?: number;
+  isrc?: string;
+  title?: string;
+  artist?: string;
+  album?: string;
+  previewUrl?: string;
+  [key: string]: unknown;
+};
+
+interface SpotifyService {
+  resolveSpotifyToYoutube(
+    url: string,
+    ids: string[],
+    onProgress: (status: string, progress: number, extra: unknown) => void
+  ): Promise<SpotifyData>;
+}
+
+async function getSpotifyService(): Promise<SpotifyService> {
+  const spotifyModule =
+    (await import('../spotify/index.js')) as unknown as SpotifyService;
+
+  if (
+    !spotifyModule ||
+    typeof spotifyModule.resolveSpotifyToYoutube !== 'function'
+  ) {
+    console.error('[JS-Spotify] Circular dependency error');
+    throw new Error('Service initialization error.');
+  }
+
+  return spotifyModule as SpotifyService;
+}
+
+function mapToBrainResult(spotifyData: SpotifyData): VideoInfo {
+  const resolvedYoutubeUrl = spotifyData.targetUrl || spotifyData.youtubeUrl;
+
+  return {
+    ...(spotifyData as unknown as VideoInfo),
+    type: 'video',
+    targetUrl: resolvedYoutubeUrl,
+    cover: spotifyData.imageUrl || (spotifyData.cover as string),
+    thumbnail: (spotifyData.imageUrl || spotifyData.thumbnail || '') as string,
+
+    duration: (spotifyData.duration || 0) / 1000,
+    extractorKey: 'spotify',
+    isJsInfo: true,
+    fromBrain: true,
+    isPartial: false,
+    isIsrcMatch: true,
+    isFullData: true,
+  };
+}
+
+function mapToJsResult(
+  url: string,
+  spotifyData: SpotifyData,
+  ytInfo: VideoInfo
+): VideoInfo {
+  return {
+    ...ytInfo,
+    type: 'video',
+    id: ytInfo.id,
+    isrc: spotifyData.isrc || undefined,
+    extractorKey: 'spotify',
+    title: spotifyData.title || ytInfo.title,
+    artist: spotifyData.artist || ytInfo.artist || 'Unknown Artist',
+    uploader: spotifyData.artist || ytInfo.uploader || 'Unknown Uploader',
+    album: spotifyData.album || '',
+    imageUrl: spotifyData.cover || spotifyData.imageUrl || ytInfo.thumbnail,
+    cover: spotifyData.cover || spotifyData.imageUrl || ytInfo.thumbnail,
+    thumbnail: spotifyData.cover || spotifyData.imageUrl || ytInfo.thumbnail,
+    previewUrl: spotifyData.previewUrl || null,
+    webpageUrl: url,
+    targetUrl: spotifyData.targetUrl,
+    isJsInfo: true,
+    fromBrain: false,
+    isPartial: false,
+    isIsrcMatch: false,
+    isFullData: false,
+  };
+}
+
+// spotify js extractor
+export async function getInfo(
+  url: string,
+  options: ExtractorOptions = {}
+): Promise<VideoInfo | null> {
+  try {
+    const spotifyService = await getSpotifyService();
+
+    const spotifyData: SpotifyData = await spotifyService.resolveSpotifyToYoutube(
+      url,
+      [],
+      (status: string, progress: number, extra: unknown) => {
+        if (options.onProgress)
+          options.onProgress(
+            status,
+            progress,
+            typeof extra === 'string' ? extra : undefined
+          );
+      }
+    );
+
+    if (!spotifyData?.targetUrl) {
+      return null;
+    }
+
+    if (spotifyData.fromBrain && (spotifyData.formats?.length ?? 0) > 0) {
+      return mapToBrainResult(spotifyData);
+    }
+
+    const ytInfo = await getYtInfo(spotifyData.targetUrl);
+    if (!ytInfo) return null;
+    return mapToJsResult(url, spotifyData, ytInfo);
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[JS-Spotify] Error extracting ${url}: ${message}`);
+    return null;
+  }
+}
+
+export async function getStream(
+  videoInfo: VideoInfo,
+  options: ExtractorOptions = {}
+): Promise<Readable> {
+  // refresh expired urls
+  if (videoInfo.fromBrain) {
+    const liveYtInfo = await getYtInfo(videoInfo.targetUrl || '');
+    if (!liveYtInfo) throw new Error('Failed to refresh stream URL');
+    return getYtStream(liveYtInfo, options);
+  }
+  return getYtStream(videoInfo, options);
+}

backend/src/services/extractors/threads/constants.ts

@@ -0,0 +1,20 @@
+export const DESKTOP_UA =
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36';
+
+// cdn authorizes media against this origin
+export const STREAM_REFERER = 'https://www.threads.com/';
+
+export const HEADERS = {
+  'User-Agent': DESKTOP_UA,
+  Accept:
+    'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8',
+  'Accept-Language': 'en-US,en;q=0.5',
+  'Sec-Fetch-Mode': 'navigate',
+  'Sec-Fetch-Site': 'none',
+  'Sec-Fetch-Dest': 'document',
+  'Sec-Fetch-User': '?1',
+  'Upgrade-Insecure-Requests': '1',
+};
+
+// post|t shortcode from permalink
+export const ID_REGEX = /\/(?:post|t)\/([A-Za-z0-9_-]+)/u;

backend/src/services/extractors/threads/fetcher.ts

@@ -0,0 +1,62 @@
+import { HEADERS, DESKTOP_UA } from './constants.js';
+import { secureFetch } from '../../../utils/network/security.util.js';
+
+type FetchOptions = {
+  cookie?: string;
+};
+
+type FetchResult = { html: string; targetUrl: string };
+
+// public embed endpoint, often ungated
+function buildEmbedUrl(url: string): string {
+  const clean = url.split('?')[0].replace(/\/+$/u, '');
+  return `${clean}/embed`;
+}
+
+async function fetchPage(
+  target: string,
+  options: FetchOptions
+): Promise<FetchResult | null> {
+  const cookie = typeof options.cookie === 'string' ? options.cookie : null;
+  const response = await secureFetch(target, {
+    headers: {
+      ...HEADERS,
+      ...(cookie && { Cookie: cookie }),
+    },
+    signal: AbortSignal.timeout(10000),
+  });
+  if (!response.ok) return null;
+  return { html: await response.text(), targetUrl: response.url };
+}
+
+export function fetchHtml(
+  url: string,
+  options: FetchOptions
+): Promise<FetchResult | null> {
+  return fetchPage(url, options);
+}
+
+export function fetchEmbed(
+  url: string,
+  options: FetchOptions
+): Promise<FetchResult | null> {
+  return fetchPage(buildEmbedUrl(url), options);
+}
+
+export async function fetchFileSize(url: string): Promise<number | undefined> {
+  try {
+    const headResponse = await secureFetch(url, {
+      method: 'HEAD',
+      headers: { 'User-Agent': DESKTOP_UA },
+      signal: AbortSignal.timeout(5000),
+    });
+    if (headResponse.ok) {
+      const contentLength = headResponse.headers.get('content-length');
+      if (contentLength) return parseInt(contentLength, 10);
+    }
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.debug('[ThreadsExtractor] Size fetch error:', message);
+  }
+  return undefined;
+}

backend/src/services/extractors/threads/index.ts

@@ -0,0 +1,75 @@
+import { getQuantumStream } from '../../../utils/network/proxy.util.js';
+import { VideoInfo, Format, ExtractorOptions } from '../../../types/index.js';
+import { Readable } from 'node:stream';
+import { DESKTOP_UA, STREAM_REFERER } from './constants.js';
+import { fetchHtml, fetchEmbed, fetchFileSize } from './fetcher.js';
+import { parseHtml } from './parser.js';
+import { normalizeVideoInfo } from './normalizer.js';
+
+function extract(html: string, targetUrl: string): VideoInfo | null {
+  return normalizeVideoInfo(targetUrl, parseHtml(html, targetUrl));
+}
+
+export async function getInfo(
+  url: string,
+  options: ExtractorOptions = {}
+): Promise<VideoInfo | null> {
+  try {
+    const primary = await fetchHtml(url, options);
+    let videoInfo = primary ? extract(primary.html, primary.targetUrl) : null;
+
+    // walled/empty page: try public embed
+    if (!videoInfo || videoInfo.formats.length === 0) {
+      const embed = await fetchEmbed(url, options);
+      const alt = embed ? extract(embed.html, embed.targetUrl) : null;
+      if (alt && alt.formats.length > 0) videoInfo = alt;
+    }
+
+    if (!videoInfo || videoInfo.formats.length === 0) return null;
+
+    // fetch size
+    for (let i = 0; i < videoInfo.formats.length; i += 3) {
+      const batch = videoInfo.formats.slice(i, i + 3);
+      await Promise.all(
+        batch.map(async (format: Format) => {
+          if (format.url) {
+            const size = await fetchFileSize(format.url);
+            if (size) format.filesize = size;
+          }
+        })
+      );
+    }
+
+    return videoInfo;
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[JS-Threads] Error extracting ${url}: ${message}`);
+    return null;
+  }
+}
+
+export function getStream(
+  videoInfo: VideoInfo,
+  options: ExtractorOptions = {}
+): Promise<Readable> {
+  const targetFormat =
+    videoInfo.formats.find(
+      (formatItem: Format) =>
+        String(formatItem.formatId) === String(options.formatId)
+    ) || videoInfo.formats[0];
+  if (!targetFormat?.url) throw new Error('No stream URL found');
+
+  return Promise.resolve(
+    getQuantumStream(targetFormat.url, {
+      'User-Agent': DESKTOP_UA,
+      Referer: STREAM_REFERER,
+      Origin: 'https://www.threads.com',
+      Accept: '*/*',
+      'Accept-Language': 'en-US,en;q=0.9',
+      Range: 'bytes=0-',
+      'Sec-Fetch-Dest': 'video',
+      'Sec-Fetch-Mode': 'cors',
+      'Sec-Fetch-Site': 'cross-site',
+    })
+  );
+}

backend/src/services/extractors/threads/json-extractor.ts

@@ -0,0 +1,171 @@
+// json-block walk; regex/og stays as fallback
+import { ThreadsRawFormat, ThreadsParsed } from './types.js';
+
+type Obj = Record<string, unknown>;
+
+// no id here; parser adds it
+type ThreadsJsonResult = Omit<ThreadsParsed, 'id'>;
+
+const str = (value: unknown): string | undefined =>
+  typeof value === 'string' && value ? value : undefined;
+
+const num = (value: unknown): number | undefined =>
+  typeof value === 'number' ? value : undefined;
+
+// walk every object node in parsed json
+function walk(node: unknown, visit: (obj: Obj) => void): void {
+  if (!node || typeof node !== 'object') return;
+  if (Array.isArray(node)) {
+    for (const item of node) walk(item, visit);
+    return;
+  }
+  visit(node as Obj);
+  for (const value of Object.values(node)) walk(value, visit);
+}
+
+// highest-resolution entry from a versions array
+function bestVideo(
+  versions: unknown
+): { url: string; width?: number; height?: number } | null {
+  if (!Array.isArray(versions)) return null;
+  let best: { url: string; width?: number; height?: number } | null = null;
+  for (const entry of versions) {
+    if (!entry || typeof entry !== 'object') continue;
+    const url = str((entry as Obj).url);
+    if (!url) continue;
+    const width = num((entry as Obj).width);
+    if (!best || (width ?? 0) > (best.width ?? 0)) {
+      best = { url, width, height: num((entry as Obj).height) };
+    }
+  }
+  return best;
+}
+
+// highest-resolution image candidate url
+function bestImage(imageVersions: unknown): string | undefined {
+  if (!imageVersions || typeof imageVersions !== 'object') return undefined;
+  const candidates = (imageVersions as Obj).candidates;
+  if (!Array.isArray(candidates)) return undefined;
+  let best: { url: string; width: number } | undefined;
+  for (const candidate of candidates) {
+    if (!candidate || typeof candidate !== 'object') continue;
+    const url = str((candidate as Obj).url);
+    const width = num((candidate as Obj).width) ?? 0;
+    if (url && (!best || width > best.width)) best = { url, width };
+  }
+  return best?.url;
+}
+
+function captionText(value: unknown): string | undefined {
+  if (value && typeof value === 'object') return str((value as Obj).text);
+  return str(value);
+}
+
+// pull uri from {image:{uri}} or {uri} node
+function nestedUri(value: unknown): string | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  const node = value as Obj;
+  const image = node.image as Obj | undefined;
+  return str(image?.uri) ?? str(node.uri);
+}
+
+export function extractFromJson(html: string): ThreadsJsonResult | null {
+  const blocks = html.matchAll(
+    /<script[^>]+type="application\/json"[^>]*>([\s\S]*?)<\/script>/gu
+  );
+
+  const formats: ThreadsRawFormat[] = [];
+  const seen = new Set<string>();
+  const photos: string[] = [];
+  let title = '';
+  let uploader = '';
+  let thumbnail = '';
+
+  const addVideo = (
+    url: string | undefined,
+    id: string,
+    width?: number,
+    height?: number
+  ) => {
+    if (!url || seen.has(url)) return;
+    if (formats.some((format) => format.format_id === id)) return;
+    seen.add(url);
+    formats.push({
+      url,
+      format_id: id,
+      ext: 'mp4',
+      vcodec: 'h264',
+      acodec: 'aac',
+      width,
+      height,
+    });
+  };
+
+  for (const block of blocks) {
+    let data: unknown;
+    try {
+      data = JSON.parse(block[1]);
+    } catch {
+      continue;
+    }
+    walk(data, (obj) => {
+      // ig/threads adaptive media
+      const video = bestVideo(obj.video_versions);
+      if (video) addVideo(video.url, 'hd', video.width, video.height);
+
+      // fb-style direct urls; dims co-located on node
+      const dimW = num(obj.original_width);
+      const dimH = num(obj.original_height);
+      addVideo(
+        str(obj.browser_native_hd_url) ?? str(obj.playable_url_quality_hd),
+        'hd',
+        dimW,
+        dimH
+      );
+      addVideo(
+        str(obj.browser_native_sd_url) ?? str(obj.playable_url),
+        'sd',
+        dimW,
+        dimH
+      );
+
+      if (!title) title = captionText(obj.caption) ?? str(obj.title) ?? '';
+      if (!uploader) {
+        const user = obj.user as Obj | undefined;
+        uploader =
+          str(user?.full_name) ??
+          str(user?.username) ??
+          str(obj.username) ??
+          '';
+      }
+      const image = bestImage(obj.image_versions2);
+      if (image) {
+        if (!thumbnail) thumbnail = image;
+        if (!photos.includes(image)) photos.push(image);
+      }
+      // fb-style poster for video posts
+      if (!thumbnail) {
+        thumbnail =
+          nestedUri(obj.preferred_thumbnail) ??
+          str(obj.thumbnail_url) ??
+          str(obj.cover_photo_url) ??
+          '';
+      }
+    });
+  }
+
+  // image post: no video found, use candidates
+  if (formats.length === 0 && photos.length > 0) {
+    const single = photos.length === 1;
+    photos.forEach((url, index) => {
+      formats.push({
+        url,
+        format_id: single ? 'photo' : `photo_${index}`,
+        ext: 'jpeg',
+      });
+    });
+  }
+
+  if (formats.length === 0) return null;
+  return { formats, title, uploader, thumbnail };
+}

backend/src/services/extractors/threads/normalizer.ts

@@ -0,0 +1,74 @@
+import { VideoInfo, Format } from '../../../types/index.js';
+import { normalizeTitle, normalizeArtist } from '../../social.service.js';
+import { ThreadsParsed } from './types.js';
+
+export function normalizeVideoInfo(
+  url: string,
+  parsedData: ThreadsParsed | null
+): VideoInfo | null {
+  if (!parsedData) return null;
+
+  const formats: Format[] = parsedData.formats.map((formatItem, index) => {
+    const isPhoto = formatItem.format_id?.startsWith('photo') ?? false;
+    const vcodec = formatItem.vcodec ?? (isPhoto ? undefined : 'h264');
+    const acodec = formatItem.acodec ?? (isPhoto ? undefined : 'aac');
+    const { width, height } = formatItem;
+
+    // label when dimensions are unavailable
+    const tier =
+      formatItem.format_id === 'hd'
+        ? 'HD'
+        : formatItem.format_id === 'sd'
+          ? 'SD'
+          : isPhoto
+            ? 'Photo'
+            : undefined;
+
+    const quality = height ? `${height}p` : tier;
+
+    return {
+      formatId: formatItem.format_id || `th_${index}`,
+      url: formatItem.url,
+      extension: formatItem.ext ?? 'mp4',
+      resolution: width && height ? `${width}x${height}` : (tier ?? 'Source'),
+      quality,
+      width,
+      height,
+      vcodec,
+      acodec,
+      isAudio: Boolean(acodec && acodec !== 'none'),
+      isVideo: Boolean(vcodec && vcodec !== 'none'),
+      isMuxed: Boolean(
+        acodec && acodec !== 'none' && vcodec && vcodec !== 'none'
+      ),
+    };
+  });
+
+  if (formats.length === 0) return null;
+
+  const info: VideoInfo = {
+    type: 'video',
+    id: parsedData.id || url,
+    title: parsedData.title || 'Threads Post',
+    uploader: parsedData.uploader || 'Threads User',
+    thumbnail: parsedData.thumbnail || undefined,
+    webpageUrl: url,
+    formats,
+    extractorKey: 'threads',
+    isJsInfo: true,
+    fromBrain: false,
+    isPartial: false,
+    isIsrcMatch: false,
+    isFullData: false,
+  };
+
+  // make caption authoritative over og:title
+  if (parsedData.title) {
+    info.metascraper = { title: parsedData.title };
+  }
+
+  info.title = normalizeTitle(info as unknown as Record<string, unknown>);
+  info.uploader = normalizeArtist(info as unknown as Record<string, unknown>);
+
+  return info;
+}

backend/src/services/extractors/threads/parser.ts

@@ -0,0 +1,68 @@
+import { ID_REGEX } from './constants.js';
+import { decode, decodeHtmlEntities } from '../facebook/utils.js';
+import { extractFromJson } from './json-extractor.js';
+import { ThreadsRawFormat, ThreadsParsed } from './types.js';
+
+function matchContent(html: string, property: string): string | undefined {
+  const pattern = new RegExp(
+    `<meta property="${property}" content="([^"]*)"`,
+    'u'
+  );
+  const match = html.match(pattern);
+  return match ? decodeHtmlEntities(match[1]) : undefined;
+}
+
+function parseOgVideo(html: string): string | undefined {
+  return (
+    matchContent(html, 'og:video:secure_url') ??
+    matchContent(html, 'og:video:url') ??
+    matchContent(html, 'og:video')
+  );
+}
+
+// strip "(@handle) on Threads" noise
+function parseOgAuthor(html: string): string | undefined {
+  const title = matchContent(html, 'og:title');
+  if (!title) return undefined;
+  const handle = title.match(/\(@([A-Za-z0-9_.]+)\)/u);
+  if (handle) return handle[1];
+  return title.replace(/\s+on Threads.*$/iu, '').trim() || undefined;
+}
+
+export function parseHtml(html: string, url: string): ThreadsParsed {
+  const idMatch = url.match(ID_REGEX);
+  const code = idMatch ? idMatch[1] : null;
+  const ogCaption = matchContent(html, 'og:description');
+  const ogImage = matchContent(html, 'og:image');
+  const ogAuthor = parseOgAuthor(html);
+
+  // json-first; og regex fallback
+  const json = extractFromJson(html);
+  if (json) {
+    return {
+      id: code,
+      title: json.title || ogCaption || '',
+      uploader: json.uploader || ogAuthor || '',
+      thumbnail: json.thumbnail || ogImage || '',
+      formats: json.formats,
+    };
+  }
+
+  const formats: ThreadsRawFormat[] = [];
+  const ogVideo = parseOgVideo(html);
+  if (ogVideo)
+    formats.push({ url: decode(ogVideo), format_id: 'hd', ext: 'mp4' });
+
+  // photo only when no video found
+  if (formats.length === 0 && ogImage) {
+    formats.push({ url: ogImage, format_id: 'photo', ext: 'jpeg' });
+  }
+
+  return {
+    id: code,
+    title: ogCaption || '',
+    uploader: ogAuthor || '',
+    thumbnail: ogImage || '',
+    formats,
+  };
+}

backend/src/services/extractors/threads/types.ts

@@ -0,0 +1,21 @@
+// shared contract across parse + normalize
+
+// snake_case mirrors threads/ig wire keys
+export interface ThreadsRawFormat {
+  url: string;
+  format_id?: string;
+  ext?: string;
+  vcodec?: string;
+  acodec?: string;
+  width?: number;
+  height?: number;
+}
+
+// parsed media and page meta
+export interface ThreadsParsed {
+  id: string | null;
+  title: string;
+  uploader: string;
+  thumbnail: string;
+  formats: ThreadsRawFormat[];
+}

backend/src/services/extractors/tiktok.ts

@@ -0,0 +1,239 @@
+import { secureFetch } from '../../utils/network/security.util.js';
+import { VideoInfo, Format, ExtractorOptions } from '../../types/index.js';
+import { Readable } from 'node:stream';
+import { normalizeTitle, normalizeArtist } from '../social.service.js';
+
+const DESKTOP_UA =
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36';
+
+const cookieCache = new Map<string, string>();
+
+interface TikTokPlayAddr {
+  Width?: number;
+  Height?: number;
+  DataSize?: number;
+  UrlList?: string[];
+}
+interface TikTokBitrate {
+  Bitrate?: number;
+  GearName?: string;
+  CodecType?: string;
+  PlayAddr?: TikTokPlayAddr;
+}
+interface TikTokVideo {
+  duration?: number;
+  width?: number;
+  height?: number;
+  cover?: string;
+  originCover?: string;
+  playAddr?: string;
+  codecType?: string;
+  bitrateInfo?: TikTokBitrate[];
+}
+interface TikTokItem {
+  id?: string;
+  desc?: string;
+  author?: { uniqueId?: string; nickname?: string };
+  video?: TikTokVideo;
+  imagePost?: { images?: { imageURL?: { urlList?: string[] } }[] };
+}
+
+// extract embedded rehydration JSON
+function parseUniversalData(html: string): TikTokItem | null {
+  const match = html.match(
+    /<script\b[^>]*\bid="__UNIVERSAL_DATA_FOR_REHYDRATION__"[^>]*>([\s\S]*?)<\/script>/u
+  );
+  if (!match) return null;
+  try {
+    const data = JSON.parse(match[1]) as {
+      __DEFAULT_SCOPE__?: {
+        'webapp.video-detail'?: { itemInfo?: { itemStruct?: TikTokItem } };
+      };
+    };
+    return (
+      data.__DEFAULT_SCOPE__?.['webapp.video-detail']?.itemInfo?.itemStruct ??
+      null
+    );
+  } catch {
+    return null;
+  }
+}
+
+function buildVideoFormats(video: TikTokVideo): Format[] {
+  const mapped = (video.bitrateInfo ?? [])
+    .map((rung): Format | null => {
+      const url = rung.PlayAddr?.UrlList?.[0];
+      if (!url) return null;
+      const width = rung.PlayAddr?.Width ?? video.width;
+      const height = rung.PlayAddr?.Height ?? video.height;
+      const short = width && height ? Math.min(width, height) : undefined;
+      const isHevc = rung.CodecType?.includes('265') ?? false;
+      return {
+        formatId: rung.GearName || `${short ?? 'src'}p`,
+        url,
+        extension: 'mp4',
+        width,
+        height,
+        resolution: width && height ? `${width}x${height}` : undefined,
+        quality: short ? `${short}p${isHevc ? ' (HEVC)' : ''}` : undefined,
+        vcodec: isHevc ? 'hevc' : 'h264',
+        acodec: 'aac',
+        tbr: rung.Bitrate ? Math.round(rung.Bitrate / 1000) : undefined,
+        filesize:
+          typeof rung.PlayAddr?.DataSize === 'number'
+            ? rung.PlayAddr.DataSize
+            : undefined,
+        isMuxed: true,
+        isVideo: true,
+        isAudio: false,
+      };
+    })
+    .filter((format): format is Format => format !== null);
+
+  // dedup by resolution; prefer h264
+  mapped.sort((lhs, rhs) => {
+    const byHeight = (rhs.height ?? 0) - (lhs.height ?? 0);
+    if (byHeight !== 0) return byHeight;
+    if (lhs.vcodec !== rhs.vcodec) return lhs.vcodec === 'h264' ? -1 : 1;
+    return (rhs.tbr ?? 0) - (lhs.tbr ?? 0);
+  });
+  const seen = new Set<number>();
+  const deduped = mapped.filter((format) => {
+    const key = format.height ?? 0;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  // fallback to single muxed url
+  if (deduped.length === 0 && video.playAddr) {
+    deduped.push({
+      formatId: 'source',
+      url: video.playAddr,
+      extension: 'mp4',
+      width: video.width,
+      height: video.height,
+      resolution:
+        video.width && video.height
+          ? `${video.width}x${video.height}`
+          : undefined,
+      vcodec: video.codecType?.includes('265') ? 'hevc' : 'h264',
+      acodec: 'aac',
+      isMuxed: true,
+      isVideo: true,
+      isAudio: false,
+    });
+  }
+  return deduped;
+}
+
+function buildPhotoFormats(item: TikTokItem): Format[] {
+  return (item.imagePost?.images ?? [])
+    .map((image, index): Format | null => {
+      const url = image.imageURL?.urlList?.[0];
+      if (!url) return null;
+      return {
+        formatId: `image_${index}`,
+        url,
+        extension: 'jpeg',
+        isMuxed: false,
+        isVideo: false,
+        isAudio: false,
+      };
+    })
+    .filter((format): format is Format => format !== null);
+}
+
+export async function getInfo(
+  url: string,
+  _options: ExtractorOptions = {}
+): Promise<VideoInfo | null> {
+  try {
+    const response = await secureFetch(url, {
+      headers: {
+        'User-Agent': DESKTOP_UA,
+        'Accept-Language': 'en-US,en;q=0.9',
+      },
+    });
+    if (!response.ok) return null;
+
+    const cookieHeader = (response.headers.getSetCookie?.() ?? [])
+      .map((entry) => entry.split(';')[0])
+      .join('; ');
+
+    // null lets pipeline fall back to yt-dlp
+    const item = parseUniversalData(await response.text());
+    if (!item) return null;
+
+    const isPhoto = Boolean(item.imagePost?.images?.length);
+    const formats = isPhoto
+      ? buildPhotoFormats(item)
+      : item.video
+        ? buildVideoFormats(item.video)
+        : [];
+    if (formats.length === 0) return null;
+
+    const info: VideoInfo = {
+      type: 'video',
+      id: item.id || url,
+      title: item.desc || 'TikTok Video',
+      uploader:
+        item.author?.nickname || item.author?.uniqueId || 'TikTok User',
+      webpageUrl: response.url,
+      thumbnail: item.video?.cover || item.video?.originCover || undefined,
+      duration: item.video?.duration,
+      formats,
+      extractorKey: 'tiktok',
+      isJsInfo: true,
+      fromBrain: false,
+      isPartial: false,
+      isIsrcMatch: false,
+      isFullData: !isPhoto,
+    };
+
+    info.title = normalizeTitle(info as unknown as Record<string, unknown>);
+    info.uploader = normalizeArtist(info as unknown as Record<string, unknown>);
+
+    if (cookieHeader) {
+      if (cookieCache.size >= 100) {
+        const oldest = cookieCache.keys().next().value;
+        if (oldest !== undefined) cookieCache.delete(oldest);
+      }
+      cookieCache.set(info.id, cookieHeader);
+    }
+
+    return info;
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[JS-TikTok] Error extracting ${url}: ${message}`);
+    return null;
+  }
+}
+
+export async function getStream(
+  videoInfo: VideoInfo,
+  options: ExtractorOptions = {}
+): Promise<Readable> {
+  const selected =
+    videoInfo.formats.find(
+      (format) => String(format.formatId) === String(options.formatId)
+    ) || videoInfo.formats[0];
+  if (!selected?.url) throw new Error('No stream URL found');
+
+  // cookies + referer + range authorize cdn
+  const headers: Record<string, string> = {
+    'User-Agent': DESKTOP_UA,
+    Referer: 'https://www.tiktok.com/',
+    Range: 'bytes=0-',
+  };
+  const cookie = cookieCache.get(videoInfo.id);
+  if (cookie) headers.Cookie = cookie;
+
+  const response = await secureFetch(selected.url, { headers });
+  if (!response.ok || !response.body) {
+    throw new Error(`TikTok stream failed: HTTP ${response.status}`);
+  }
+  return Readable.fromWeb(
+    response.body as import('node:stream/web').ReadableStream
+  );
+}