ts-dlp

A lightweight, fluent TypeScript wrapper for yt-dlp made for humans.

ts-dlp makes using yt-dlp feel natural in Node.js and TypeScript projects through a chainable, strongly-typed API.

yt-dlp is extremely powerful, but constructing CLI arguments manually from Node.js can become difficult to maintain and hard to type safely.

ts-dlp provides a fluent TypeScript API that keeps you close to native yt-dlp functionality while improving developer experience.

• Fluent builder-style API
• Fully typed with TypeScript
• Uses your local yt-dlp installation
• Promise-based
• Easy process handling
• Cross-platform

Early development / proof of concept

npm install ts-dlp

ts-dlp requires a local yt-dlp installation available in your system PATH.

Windows

winget install yt-dlp.yt-dlp

macOS

brew install yt-dlp

Linux

pip install -U yt-dlp

Official yt-dlp project: https://github.com/yt-dlp/yt-dlp

Instead of writing:

yt-dlp -f "bestvideo[height<=1080]+bestaudio" -o "downloads/%(title)s.%(ext)s" URL

You write:

import {download} from "ts-dlp";

await download(url).resolution("1080p").output("downloads").run();

import {download} from "ts-dlp";

await download(url)
	.resolution("1080p")
	.fps(60)
	.format("mp4")
	.audio("aac")
	.output("./downloads")
	.filename(({title, ext}) => `${title}.${ext}`)
	.run();

ts-dlp aims to stay thin and predictable.

The project does not attempt to hide yt-dlp or replace its ecosystem. Instead, it focuses on:

• Better TypeScript ergonomics
• Safer command construction
• Cleaner process handling
• Fluent APIs

ts-dlp will not try to model every yt-dlp flag as a typed method. Instead, future versions will expose escape hatches for advanced usage:

// Planned
await download(url)
	.customFormat("bestvideo[height<=1080][vcodec^=avc]+bestaudio[ext=m4a]")
	.args(["--no-playlist", "--write-subs"])
	.run();

• Make yt-dlp easier to use from Node.js
• Avoid manually constructing CLI arguments
• Provide autocomplete and type safety
• Keep the wrapper lightweight
• Stay close to native yt-dlp functionality

• Detect yt-dlp installation
• Execute yt-dlp commands
• .download(url) / .run()
• .output(path)
• .format(ext)
• .audio(codec?)
• .resolution(res)
• .fps(fps)
• .filename(template)
• Error handling
• Capture stdout/stderr
• Unit test setup

• .info(url) - fetch video metadata
• JSON output support
• Playlist support
• Progress events

• Subtitle support
• Thumbnail downloads
• Playlist filtering
• Cookies support
• Proxy support
• .customFormat(selector) escape hatch
• .args(flags[]) escape hatch

• Presets
• Config file support
• Improved documentation
• CI/CD pipeline
• Automated tests

At least for now, ts-dlp will NOT:

• Bundle yt-dlp binaries
• Replace yt-dlp functionality
• Abstract every yt-dlp flag into typed methods
• Become a GUI application

The goal is to remain a lightweight developer wrapper.

Contributions, suggestions, and issue reports are welcome.

If you have ideas for the API design or developer experience, feel free to open an issue.

This project follows Conventional Commits and maintains a CHANGELOG.

ts-dlp is a developer wrapper around yt-dlp. Users are responsible for complying with the terms of service and applicable laws of the media sources they access.

MIT