ytdlp-typescript

A TypeScript rewrite of the yt-dlp engine, scoped to four platforms:

• YouTube (innertube API: visionos / ios / tv / android_vr / web client fallback chain, sig + nsig challenge solving via node:vm, HLS/DASH manifests, subtitles, PO-token passthrough)
• TikTok (universal-data scrape, WAF challenge solver, short-link redirects)
• Facebook (ScheduledServerJS relay data, tahoe fallback, DASH manifests embedded in page JSON)
• Pinterest (resource API, master/media HLS playlists)

Zero runtime dependencies. Node 20+. ffmpeg required only for format merging (bv*+ba).

Install

npm install ytdlp-typescript
# or
bun add ytdlp-typescript

Usage

import { extract, download } from 'ytdlp-typescript'

const info = await extract('https://www.youtube.com/watch?v=dQw4w9WgXcQ')
console.log(info.title, info.formats.length)

const files = await download('https://www.tiktok.com/@user/video/123456', {
  format: 'bv*+ba/b',
  outtmpl: '%(title)s [%(id)s].%(ext)s',
  onProgress: (p) => console.log(p.status, p.downloaded_bytes),
})

Options

| Option | Default | Description | | --- | --- | --- | | format | bv*+ba/b | yt-dlp-style selector (b, w, bv*, ba, filters like [height<=720], direct itags like 137+140) | | outtmpl | %(title)s [%(id)s].%(ext)s | Output filename template | | paths | – | { home, temp } output directories | | cookiesFile | – | Netscape cookies.txt (auth / private content) | | cookieJar | – | Programmatic CookieJar | | httpHeaders | – | Extra headers | | userAgent | Chrome UA | Override | | retries / fragmentRetries | 10 | Network retry counts | | rateLimit | – | Bytes/sec throttle | | concurrentFragments | 1 | Parallel HLS/DASH fragment downloads | | poToken | – | { gvs?, player?, subs? } YouTube proof-of-origin tokens | | playerClient | – | Restrict YouTube innertube clients | | ffmpegPath | ffmpeg | Binary path for merging | | noMerge | false | Disable ffmpeg merge attempts |

Documentation

| Doc | Contents | | --- | --- | | docs/API.md | extract / download, all options, progress events, errors, types | | docs/format-selection.md | Format spec grammar, operators, merge rules, ranking | | docs/architecture.md | Engine layers, download flow, challenge solving | | docs/platforms.md | Per-platform extraction internals & gotchas | | AGENTS.md | Guidance for AI coding agents working in this repo |

Architecture

Mirrors the upstream Python layout:

src/
  core/ytdlp.ts            orchestrator: extract → select → download
  core/format-selector.ts  yt-dlp format-spec grammar subset
  core/outtmpl.ts          %(field)s templating
  networking/http.ts       fetch-based request layer (redirects, retries, cookies)
  networking/cookies.ts    RFC6265 cookie jar + Netscape import/export
  extractor/base.ts        InfoExtractor base (m3u8/MPD parsing, search helpers)
  extractor/{pinterest,facebook,tiktok,youtube}
  extractor/youtube/sig.ts player-JS challenge solver (node:vm sandbox)
  downloader/              http (range-resume), fragment engine,
                           native HLS (+AES-128), DASH segments, ffmpeg merge

Key design decision: upstream no longer interprets YouTube's obfuscated JS internally — it delegates to external JS runtimes. Running inside Node, this port executes the player JS natively in a vm sandbox instead of porting jsinterp.py.

Development

bun run test                  # unit tests (31)
bun run src/scripts/smoke.ts <url>          # live extraction report
bun run src/scripts/smoke.ts <url> --dl     # live download

Known limitations (v1)

• Single videos only — playlists/channels not implemented
• Facebook reels and TikTok bot-walled content may require cookiesFile
• VK videos requiring an account (private/friends-only) need cookiesFile; VK login itself is not implemented
• Live streams not supported
• No browser-impersonation equivalent (curl_cffi); bot walls are mitigated via UA strategies per platform

Contributing

See CONTRIBUTING.md. Bug reports and feature requests go through GitHub Issues — check SECURITY.md before reporting anything security-sensitive.

Legal

This project does not host or distribute any copyrighted media; it is a technical client for platforms' publicly served streams. You are responsible for complying with each platform's Terms of Service and applicable copyright law in your jurisdiction. The project is not affiliated with YouTube, TikTok, Facebook/Meta, or Pinterest.