@blagoja/ts-dlp 0.1.0

package/README.md

@@ -0,0 +1,201 @@
+# ts-dlp
+
+A lightweight, fluent TypeScript wrapper for yt-dlp made for humans.
+
+`ts-dlp` aims to make downloading media with yt-dlp feel natural in Node.js and TypeScript projects through a chainable, strongly-typed API.
+
+---
+
+## Features
+
+- Fluent builder-style API
+- Fully typed with TypeScript
+- Uses your local yt-dlp installation
+- Promise-based API
+- Easy process handling
+- Cross-platform support
+
+---
+
+## Current Status
+
+> Early development / proof of concept
+
+Current functionality:
+
+- Detects whether `yt-dlp` is installed and available in PATH
+
+---
+
+# Installation
+
+```bash
+npm install ts-dlp
+```
+
+You must also have yt-dlp installed on your system.
+
+## Install yt-dlp
+
+### Windows
+
+```bash
+winget install yt-dlp.yt-dlp
+```
+
+### macOS
+
+```bash
+brew install yt-dlp
+```
+
+### Linux
+
+```bash
+pip install -U yt-dlp
+```
+
+Official project:
+
+TBD
+
+---
+
+# Vision
+
+Instead of writing:
+
+```bash
+yt-dlp -f "bestvideo[height<=1080]+bestaudio" URL
+```
+
+You write:
+
+```ts
+await ytdlp.download(url).resolution("1080p").audio("best").merge().run();
+```
+
+---
+
+# Example API (Planned)
+
+```ts
+import {ytdlp} from "ts-dlp";
+
+await ytdlp
+	.download("https://youtube.com/watch?v=...")
+	.resolution("1080p")
+	.fps(60)
+	.format("mp4")
+	.output("./downloads")
+	.run();
+```
+
+---
+
+# Goals
+
+- 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
+
+---
+
+# Roadmap
+
+## v0.1.0 - Foundation
+
+- [x] Detect yt-dlp installation
+- [ ] Execute simple yt-dlp commands
+- [ ] Basic command runner
+- [ ] Error handling
+- [ ] Capture stdout/stderr
+- [ ] TypeScript support
+- [ ] Unit test setup
+
+---
+
+## v0.2.0 - Download API
+
+- [ ] `.download(url)`
+- [ ] `.run()`
+- [ ] `.output(path)`
+- [ ] `.format(format)`
+- [ ] `.audio()`
+- [ ] `.video()`
+- [ ] `.resolution()`
+- [ ] `.fps()`
+
+Example:
+
+```ts
+await ytdlp.download(url).resolution("720p").run();
+```
+
+---
+
+## v0.3.0 - Metadata & Information
+
+- [ ] `.info()`
+- [ ] Video metadata parsing
+- [ ] JSON output support
+- [ ] Playlist support
+- [ ] Progress events
+
+Example:
+
+```ts
+const info = await ytdlp.info(url);
+```
+
+---
+
+## v0.4.0 - Advanced Features
+
+- [ ] Subtitle support
+- [ ] Thumbnail downloads
+- [ ] Playlist filtering
+- [ ] Cookies support
+- [ ] Proxy support
+- [ ] Custom yt-dlp arguments
+
+---
+
+## v0.5.0 - Developer Experience
+
+- [ ] Better typed builders
+- [ ] Presets
+- [ ] Config files
+- [ ] Improved documentation
+- [ ] More examples
+- [ ] CI/CD pipeline
+- [ ] Automated tests
+
+---
+
+# Non-Goals
+
+At least for now, `ts-dlp` will NOT:
+
+- Bundle yt-dlp binaries
+- Replace yt-dlp functionality
+- Abstract every yt-dlp flag
+- Become a GUI application
+
+The goal is to remain a lightweight developer wrapper.
+
+---
+
+# Contributing
+
+Contributions, suggestions, and issue reports are welcome.
+
+If you have an idea for the API design or developer experience, feel free to open an issue.
+
+---
+
+# License
+
+MIT

package/dist/download.d.ts

@@ -0,0 +1,43 @@
+export declare class DownloadBuilder {
+    private readonly url;
+    private readonly args;
+    constructor(url: string);
+    /**
+     * Set the desired resolution for the video to be downloaded.
+     * This will instruct yt-dlp to download the best video and audio streams that are less than or equal to the specified height.
+     * For example, if you specify "720p", yt-dlp will download the best video and audio streams that are 720 pixels in height or less.
+     * If you want to download the best available quality regardless of resolution, you can omit this option or set it to a very high value like "9999p".
+     *
+     * @example
+     * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+     *   .resolution("720p")
+     *   .output("downloads/%(title)s.%(ext)s")
+     *
+     * @param res The desired resolution for the video. For example: "720p", "1080p", etc. This will tell yt-dlp to download the best video and audio streams that are less than or equal to the specified height. If you want to download the best available quality, you can omit this option or set it to a very high value like "9999p".
+     * @returns The current instance of DownloadBuilder for method chaining.
+     */
+    resolution(res: string): this;
+    /**
+     * Set the output directory and filename template for the downloaded file.
+     *
+     * @param template The output template for the downloaded file. You can use placeholders like %(title)s, %(ext)s, etc. For example: "downloads/%(title)s.%(ext)s"
+     * @returns The current instance of DownloadBuilder for method chaining.
+     */
+    output(template: string): this;
+    /**
+     * Execute the download with the specified options.
+     * This will run yt-dlp with the accumulated arguments and the provided URL.
+     * The output will be displayed in the console.
+     *
+     * @throws Will throw an error if yt-dlp is not installed or not in PATH, or if any other error occurs during the execution of yt-dlp.
+     *
+     * @example
+     * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+     *  .resolution("720p")
+     *  .output("downloads/%(title)s.%(ext)s")
+     *  .run();
+     *
+     */
+    run(): Promise<void>;
+}
+//# sourceMappingURL=download.d.ts.map

package/dist/download.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../src/download.ts"],"names":[],"mappings":"AAEA,qBAAa,eAAe;IAGf,OAAO,CAAC,QAAQ,CAAC,GAAG;IAFhC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;gBAER,GAAG,EAAE,MAAM;IAExC;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAS7B;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAK9B;;;;;;;;;;;;;OAaG;IACG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CAG1B"}

package/dist/download.js

@@ -0,0 +1,55 @@
+import { runYtDlp } from "./internal/runner.js";
+export class DownloadBuilder {
+    url;
+    args = [];
+    constructor(url) {
+        this.url = url;
+    }
+    /**
+     * Set the desired resolution for the video to be downloaded.
+     * This will instruct yt-dlp to download the best video and audio streams that are less than or equal to the specified height.
+     * For example, if you specify "720p", yt-dlp will download the best video and audio streams that are 720 pixels in height or less.
+     * If you want to download the best available quality regardless of resolution, you can omit this option or set it to a very high value like "9999p".
+     *
+     * @example
+     * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+     *   .resolution("720p")
+     *   .output("downloads/%(title)s.%(ext)s")
+     *
+     * @param res The desired resolution for the video. For example: "720p", "1080p", etc. This will tell yt-dlp to download the best video and audio streams that are less than or equal to the specified height. If you want to download the best available quality, you can omit this option or set it to a very high value like "9999p".
+     * @returns The current instance of DownloadBuilder for method chaining.
+     */
+    resolution(res) {
+        const height = res.replace("p", "");
+        this.args.push("-f", `bestvideo[height<=${height}]+bestaudio/best[height<=${height}]`);
+        return this;
+    }
+    /**
+     * Set the output directory and filename template for the downloaded file.
+     *
+     * @param template The output template for the downloaded file. You can use placeholders like %(title)s, %(ext)s, etc. For example: "downloads/%(title)s.%(ext)s"
+     * @returns The current instance of DownloadBuilder for method chaining.
+     */
+    output(template) {
+        this.args.push("-o", template);
+        return this;
+    }
+    /**
+     * Execute the download with the specified options.
+     * This will run yt-dlp with the accumulated arguments and the provided URL.
+     * The output will be displayed in the console.
+     *
+     * @throws Will throw an error if yt-dlp is not installed or not in PATH, or if any other error occurs during the execution of yt-dlp.
+     *
+     * @example
+     * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+     *  .resolution("720p")
+     *  .output("downloads/%(title)s.%(ext)s")
+     *  .run();
+     *
+     */
+    async run() {
+        await runYtDlp([...this.args, this.url]);
+    }
+}
+//# sourceMappingURL=download.js.map

package/dist/download.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.js","sourceRoot":"","sources":["../src/download.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,QAAQ,EAAC,MAAM,sBAAsB,CAAC;AAE9C,MAAM,OAAO,eAAe;IAGE;IAFZ,IAAI,GAAa,EAAE,CAAC;IAErC,YAA6B,GAAW;QAAX,QAAG,GAAH,GAAG,CAAQ;IAAG,CAAC;IAE5C;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,GAAW;QACrB,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,CAAC,IAAI,CACb,IAAI,EACJ,qBAAqB,MAAM,4BAA4B,MAAM,GAAG,CAChE,CAAC;QACF,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,QAAgB;QACtB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC/B,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,GAAG;QACR,MAAM,QAAQ,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1C,CAAC;CACD"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { DownloadBuilder } from "./download.js";
+export declare function download(url: string): DownloadBuilder;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,eAAe,EAAC,MAAM,eAAe,CAAC;AAE9C,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAErD"}

package/dist/index.js

@@ -0,0 +1,5 @@
+import { DownloadBuilder } from "./download.js";
+export function download(url) {
+    return new DownloadBuilder(url);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,eAAe,EAAC,MAAM,eAAe,CAAC;AAE9C,MAAM,UAAU,QAAQ,CAAC,GAAW;IACnC,OAAO,IAAI,eAAe,CAAC,GAAG,CAAC,CAAC;AACjC,CAAC"}

package/dist/internal/runner.d.ts

@@ -0,0 +1,3 @@
+export declare function runYtDlp(args: string[]): Promise<void>;
+export declare function handleEnoent(error: unknown): never;
+//# sourceMappingURL=runner.d.ts.map

package/dist/internal/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/internal/runner.ts"],"names":[],"mappings":"AAEA,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAI5D;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAOlD"}

package/dist/internal/runner.js

@@ -0,0 +1,13 @@
+import { execa, ExecaError } from "execa";
+export async function runYtDlp(args) {
+    await execa("yt-dlp", ["--js-runtimes", "node", ...args], {
+        stdio: "inherit",
+    }).catch(handleEnoent);
+}
+export function handleEnoent(error) {
+    if (error instanceof ExecaError && error.code === "ENOENT") {
+        throw new Error("yt-dlp is not installed or not in PATH. Please refer to https://github.com/yt-dlp/yt-dlp#installation");
+    }
+    throw error;
+}
+//# sourceMappingURL=runner.js.map

package/dist/internal/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/internal/runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,KAAK,EAAE,UAAU,EAAC,MAAM,OAAO,CAAC;AAExC,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAc;IAC5C,MAAM,KAAK,CAAC,QAAQ,EAAE,CAAC,eAAe,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE;QACzD,KAAK,EAAE,SAAS;KAChB,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAc;IAC1C,IAAI,KAAK,YAAY,UAAU,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC5D,MAAM,IAAI,KAAK,CACd,uGAAuG,CACvG,CAAC;IACH,CAAC;IACD,MAAM,KAAK,CAAC;AACb,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC"}

package/dist/version.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC"}

package/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "@blagoja/ts-dlp",
+	"version": "0.1.0",
+	"description": "A human readable TypeScript wrapper for yt-dlp",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"scripts": {
+		"build": "tsc",
+		"dev": "tsx src/index.ts",
+		"lint": "eslint src",
+		"prepublishOnly": "npm run build"
+	},
+	"keywords": [
+		"yt-dlp",
+		"youtube-dl",
+		"downloader",
+		"wrapper"
+	],
+	"author": "Blagoja Blazhevski",
+	"files": [
+		"dist"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"license": "ISC",
+	"type": "module",
+	"devDependencies": {
+		"@types/node": "^25.9.1",
+		"typescript-eslint": "^8.60.0",
+		"eslint": "^10.4.0",
+		"jiti": "^2.7.0",
+		"tsx": "^4.22.3",
+		"typescript": "^6.0.3"
+	},
+	"dependencies": {
+		"execa": "^9.6.1"
+	}
+}