@blagoja/ts-dlp 0.1.3 → 0.1.4

package/README.md

@@ -1,8 +1,22 @@
+<div align="center">
+
+[![ts-dlp](https://i.imgur.com/UX6vDEk_d.webp?maxwidth=760&fidelity=grand)](#readme)
+
+</div>
+
 # ts-dlp
 
-A lightweight, fluent TypeScript wrapper for yt-dlp made for humans.
+A lightweight, fluent TypeScript wrapper for [yt-dlp](https://github.com/yt-dlp/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.
+
+---
+
+## Why ts-dlp?
+
+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` aims to make downloading media with yt-dlp feel natural in Node.js and TypeScript projects through a chainable, strongly-typed API.
+`ts-dlp` provides a fluent TypeScript API that keeps you close to native yt-dlp functionality while improving developer experience.
 
 ---
 
@@ -11,9 +25,9 @@ A lightweight, fluent TypeScript wrapper for yt-dlp made for humans.
 - Fluent builder-style API
 - Fully typed with TypeScript
 - Uses your local yt-dlp installation
-- Promise-based API
+- Promise-based
 - Easy process handling
-- Cross-platform support
+- Cross-platform
 
 ---
 
@@ -21,79 +35,111 @@ A lightweight, fluent TypeScript wrapper for yt-dlp made for humans.
 
 > Early development / proof of concept
 
-Current functionality:
-
-- Detects whether `yt-dlp` is installed and available in PATH
-
 ---
 
-# Installation
+## Installation
 
 ```bash
 npm install ts-dlp
 ```
 
-You must also have yt-dlp installed on your system.
+`ts-dlp` requires a local yt-dlp installation available in your system PATH.
 
-## Install yt-dlp
+### Install yt-dlp
 
-### Windows
+**Windows**
 
 ```bash
 winget install yt-dlp.yt-dlp
 ```
 
-### macOS
+**macOS**
 
 ```bash
 brew install yt-dlp
 ```
 
-### Linux
+**Linux**
 
 ```bash
 pip install -U yt-dlp
 ```
 
-Official project:
-
-https://www.npmjs.com/package/@blagoja/ts-dlp
+Official yt-dlp project: [https://github.com/yt-dlp/yt-dlp](https://github.com/yt-dlp/yt-dlp)
 
 ---
 
-# Vision
+## Quick Start
 
 Instead of writing:
 
 ```bash
-yt-dlp -f "bestvideo[height<=1080]+bestaudio" URL
+yt-dlp -f "bestvideo[height<=1080]+bestaudio" -o "downloads/%(title)s.%(ext)s" URL
 ```
 
 You write:
 
 ```ts
-await ytdlp.download(url).resolution("1080p").audio("best").merge().run();
+import {download} from "ts-dlp";
+
+await download(url).resolution("1080p").output("downloads").run();
 ```
 
 ---
 
-# Example API (Planned)
+## API
 
 ```ts
-import {ytdlp} from "ts-dlp";
+import {download} from "ts-dlp";
 
-await ytdlp
-	.download("https://youtube.com/watch?v=...")
+await download(url)
 	.resolution("1080p")
 	.fps(60)
 	.format("mp4")
+	.audio("aac")
 	.output("./downloads")
+	.filename(({title, ext}) => `${title}.${ext}`)
+	.run();
+```
+
+### Methods
+
+| Method                | Description                                        |
+| --------------------- | -------------------------------------------------- |
+| `.resolution(res)`    | Max video resolution (e.g. `"1080p"`, `"720p"`)    |
+| `.format(ext)`        | Preferred video container (e.g. `"mp4"`, `"webm"`) |
+| `.fps(fps)`           | Max frame rate (e.g. `60`)                         |
+| `.audio(codec?)`      | Audio codec preference (e.g. `"aac"`, `"mp3"`)     |
+| `.output(dir)`        | Output directory                                   |
+| `.filename(template)` | Filename template string or callback               |
+| `.run()`              | Execute the download                               |
+
+---
+
+## Philosophy
+
+`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:
+
+```ts
+// Planned
+await download(url)
+	.customFormat("bestvideo[height<=1080][vcodec^=avc]+bestaudio[ext=m4a]")
+	.args(["--no-playlist", "--write-subs"])
 	.run();
 ```
 
 ---
 
-# Goals
+## Goals
 
 - Make yt-dlp easier to use from Node.js
 - Avoid manually constructing CLI arguments
@@ -103,94 +149,79 @@ await ytdlp
 
 ---
 
-# Roadmap
+## Roadmap
 
-## v0.1.0 - Foundation
+### v0.1.0 - Foundation
 
 - [x] Detect yt-dlp installation
-- [x] Execute simple yt-dlp commands
-- [ ] Basic command runner
-- [ ] Error handling
-- [ ] Capture stdout/stderr
-- [ ] TypeScript support
-- [ ] Unit test setup
-- [x] `.download(url)`
-- [x] `.run()`
+- [x] Execute yt-dlp commands
+- [x] `.download(url)` / `.run()`
 - [x] `.output(path)`
-- [x] `.format(format)`
-- [x] `.audio()`
-- [ ] `.video()`
-- [x] `.resolution()`
-- [x] `.fps()`
-
-Example:
-
-```ts
-await ytdlp.download(url).resolution("720p").run();
-```
-
----
-
-## v0.2.0 - Metadata & Information
-
-- [ ] `.info()`
-- [ ] Video metadata parsing
+- [x] `.format(ext)`
+- [x] `.audio(codec?)`
+- [x] `.resolution(res)`
+- [x] `.fps(fps)`
+- [x] `.filename(template)`
+- [x] Error handling
+- [x] Capture stdout/stderr
+- [x] Unit test setup
+
+### v0.2.0 - Metadata & Information
+
+- [ ] `.info(url)` - fetch video metadata
 - [ ] JSON output support
 - [ ] Playlist support
 - [ ] Progress events
 
-Example:
-
-```ts
-const info = await ytdlp.info(url);
-```
-
----
-
-## v0.3.0 - Advanced Features
+### v0.3.0 - Advanced Features
 
 - [ ] Subtitle support
 - [ ] Thumbnail downloads
 - [ ] Playlist filtering
 - [ ] Cookies support
 - [ ] Proxy support
-- [ ] Custom yt-dlp arguments
-
----
+- [ ] `.customFormat(selector)` escape hatch
+- [ ] `.args(flags[])` escape hatch
 
-## v0.4.0 - Developer Experience
+### v0.4.0 - Developer Experience
 
-- [ ] Better typed builders
 - [ ] Presets
-- [ ] Config files
+- [ ] Config file support
 - [ ] Improved documentation
-- [ ] More examples
 - [ ] CI/CD pipeline
 - [ ] Automated tests
 
 ---
 
-# Non-Goals
+## Non-Goals
 
 At least for now, `ts-dlp` will NOT:
 
 - Bundle yt-dlp binaries
 - Replace yt-dlp functionality
-- Abstract every yt-dlp flag
+- Abstract every yt-dlp flag into typed methods
 - Become a GUI application
 
 The goal is to remain a lightweight developer wrapper.
 
 ---
 
-# Contributing
+## 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.
+If you have ideas for the API design or developer experience, feel free to open an issue.
+
+This project follows [Conventional Commits](https://www.conventionalcommits.org/) and maintains a [CHANGELOG](./CHANGELOG.md).
+
+---
+
+## Disclaimer
+
+`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.
 
 ---
 
-# License
+## License
 
 MIT

package/dist/index.cjs

@@ -20,21 +20,56 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  YtDlpError: () => YtDlpError,
+  YtDlpNotFoundError: () => YtDlpNotFoundError,
   download: () => download
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/internal/runner.ts
 var import_execa = require("execa");
-async function runYtDlp(args) {
-  await (0, import_execa.execa)("yt-dlp", ["--js-runtimes", "node", ...args], {
-    stdio: "inherit"
-  }).catch(handleEnoent);
+
+// src/errors.ts
+var YtDlpNotFoundError = class extends Error {
+  constructor() {
+    super(
+      "yt-dlp is not installed or not in PATH. Refer to https://github.com/yt-dlp/yt-dlp#installation"
+    );
+    this.name = "YtDlpNotFoundError";
+  }
+};
+var YtDlpError = class extends Error {
+  constructor(message, exitCode, stderr) {
+    super(message);
+    this.exitCode = exitCode;
+    this.stderr = stderr;
+    this.name = "YtDlpError";
+  }
+  exitCode;
+  stderr;
+};
+
+// src/internal/runner.ts
+async function runYtDlp(args, pipe = false) {
+  const result = await (0, import_execa.execa)(
+    "yt-dlp",
+    ["--js-runtimes", "node", ...args],
+    { stdio: pipe ? "pipe" : "inherit" }
+  ).catch(handleError);
+  return {
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? ""
+  };
 }
-function handleEnoent(error) {
-  if (error instanceof import_execa.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"
+function handleError(error) {
+  if (error instanceof import_execa.ExecaError) {
+    if (error.code === "ENOENT") {
+      throw new YtDlpNotFoundError();
+    }
+    throw new YtDlpError(
+      `yt-dlp exited with code ${error.exitCode}`,
+      error.exitCode ?? 1,
+      error.stderr ?? ""
     );
   }
   throw error;
@@ -44,6 +79,11 @@ function handleEnoent(error) {
 var DownloadBuilder = class {
   constructor(url) {
     this.url = url;
+    try {
+      new URL(url);
+    } catch {
+      throw new TypeError(`Invalid URL: ${url}`);
+    }
   }
   url;
   args = [];
@@ -54,6 +94,12 @@ var DownloadBuilder = class {
   videoExt;
   videoFps;
   videoHeight;
+  /**
+   * A private method to build the command-line arguments for yt-dlp based on the options set by the user.
+   * This method constructs the appropriate format filters and output template arguments according to the options set by the user.
+   *
+   * @returns The command-line arguments to be passed to yt-dlp based on the specified options.
+   */
   buildArgs() {
     const args = [...this.args];
     if (this.videoHeight || this.videoFps || this.videoExt || this.audioFormat) {
@@ -88,7 +134,7 @@ var DownloadBuilder = class {
    * If not specified, the file will be saved in the current working directory.
    *
    * @example
-   * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+   * download("https://www.example.com/video")
    * .output("downloads")
    * .run();
    *
@@ -106,7 +152,7 @@ var DownloadBuilder = class {
    * If no codec is specified, it will select the best available audio format regardless of codec.
    *
    * @example // Specifying an audio codec
-   * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+   * download("https://www.example.com/video")
    * .audio("mp3")
    * .run();
    *
@@ -123,7 +169,7 @@ var DownloadBuilder = class {
    * If not specified, it will select the best available video format regardless of extension.
    *
    * @example
-   * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+   * download("https://www.example.com/video")
    * .format("mp4")
    * .run();
    *
@@ -134,7 +180,20 @@ var DownloadBuilder = class {
     this.videoExt = ext;
     return this;
   }
+  /**
+   * Set the desired frames per second (FPS) for the video download. You can specify a positive integer value for FPS, such as 30, 60, etc.
+   * The method will select the best available video format that has an FPS less than or equal to the specified value.
+   *
+   * @param fps The desired frames per second (FPS) for the video download.
+   * You can specify a positive integer value for FPS, such as 30, 60, etc.
+   * @returns  The current instance of DownloadBuilder for method chaining.
+   */
   fps(fps) {
+    if (!Number.isInteger(fps) || fps <= 0) {
+      throw new RangeError(
+        `Invalid FPS value: ${fps}. FPS must be a positive integer.`
+      );
+    }
     this.videoFps = fps;
     return this;
   }
@@ -144,12 +203,12 @@ var DownloadBuilder = class {
    * automatically mapped to their values at download time.
    *
    * @example // Using a string template
-   * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+   * download("https://www.example.com/video")
    * 	.output("downloads")
    * 	.filename("%(title)s.%(ext)s")
    *
    * @example // Using a callback to specify a custom filename template
-   * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+   * download("https://www.example.com/video")
    * 	.output("downloads")
    * 	.filename(({ title, ext }) => `${title}.${ext}`)
    * 	.run();
@@ -178,7 +237,7 @@ var DownloadBuilder = class {
    * @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")
+   * download("https://www.example.com/video")
    *  .resolution("720p")
    *  .output("downloads/%(title)s.%(ext)s")
    *  .run();
@@ -188,6 +247,10 @@ var DownloadBuilder = class {
     const args = this.buildArgs();
     await runYtDlp([...args, this.url]);
   }
+  async capture() {
+    const args = this.buildArgs();
+    return runYtDlp([...args, this.url], true);
+  }
 };
 
 // src/index.ts
@@ -196,5 +259,7 @@ function download(url) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  YtDlpError,
+  YtDlpNotFoundError,
   download
 });

package/dist/index.d.cts

@@ -1,3 +1,8 @@
+interface RunResult {
+    stdout: string;
+    stderr: string;
+}
+
 type LiteralUnion<T extends string> = T | (string & {});
 type Resolution = LiteralUnion<"144p" | "240p" | "360p" | "480p" | "720p" | "1080p" | "1440p" | "2160p">;
 type AudioCodec = LiteralUnion<"opus" | "aac" | "m4a" | "mp3" | "flac" | "wav">;
@@ -35,6 +40,12 @@ declare class DownloadBuilder {
     private videoFps?;
     private videoHeight?;
     constructor(url: string);
+    /**
+     * A private method to build the command-line arguments for yt-dlp based on the options set by the user.
+     * This method constructs the appropriate format filters and output template arguments according to the options set by the user.
+     *
+     * @returns The command-line arguments to be passed to yt-dlp based on the specified options.
+     */
     private buildArgs;
     /**
      * Set the desired resolution for the video download.
@@ -50,7 +61,7 @@ declare class DownloadBuilder {
      * If not specified, the file will be saved in the current working directory.
      *
      * @example
-     * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+     * download("https://www.example.com/video")
      * .output("downloads")
      * .run();
      *
@@ -65,7 +76,7 @@ declare class DownloadBuilder {
      * If no codec is specified, it will select the best available audio format regardless of codec.
      *
      * @example // Specifying an audio codec
-     * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+     * download("https://www.example.com/video")
      * .audio("mp3")
      * .run();
      *
@@ -79,7 +90,7 @@ declare class DownloadBuilder {
      * If not specified, it will select the best available video format regardless of extension.
      *
      * @example
-     * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+     * download("https://www.example.com/video")
      * .format("mp4")
      * .run();
      *
@@ -87,6 +98,14 @@ declare class DownloadBuilder {
      * @returns The current instance of DownloadBuilder for method chaining.
      */
     format(ext: VideoExt): this;
+    /**
+     * Set the desired frames per second (FPS) for the video download. You can specify a positive integer value for FPS, such as 30, 60, etc.
+     * The method will select the best available video format that has an FPS less than or equal to the specified value.
+     *
+     * @param fps The desired frames per second (FPS) for the video download.
+     * You can specify a positive integer value for FPS, such as 30, 60, etc.
+     * @returns  The current instance of DownloadBuilder for method chaining.
+     */
     fps(fps: number): this;
     /**
      * Set the filename template for the downloaded file.
@@ -94,12 +113,12 @@ declare class DownloadBuilder {
      * automatically mapped to their values at download time.
      *
      * @example // Using a string template
-     * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+     * download("https://www.example.com/video")
      * 	.output("downloads")
      * 	.filename("%(title)s.%(ext)s")
      *
      * @example // Using a callback to specify a custom filename template
-     * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+     * download("https://www.example.com/video")
      * 	.output("downloads")
      * 	.filename(({ title, ext }) => `${title}.${ext}`)
      * 	.run();
@@ -116,15 +135,25 @@ declare class DownloadBuilder {
      * @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")
+     * download("https://www.example.com/video")
      *  .resolution("720p")
      *  .output("downloads/%(title)s.%(ext)s")
      *  .run();
      *
      */
     run(): Promise<void>;
+    capture(): Promise<RunResult>;
+}
+
+declare class YtDlpNotFoundError extends Error {
+    constructor();
+}
+declare class YtDlpError extends Error {
+    readonly exitCode: number;
+    readonly stderr: string;
+    constructor(message: string, exitCode: number, stderr: string);
 }
 
 declare function download(url: string): DownloadBuilder;
 
-export { download };
+export { type AudioCodec, type OutputFields, type Resolution, type RunResult, type VideoExt, YtDlpError, YtDlpNotFoundError, download };

package/dist/index.d.ts

@@ -1,3 +1,8 @@
+interface RunResult {
+    stdout: string;
+    stderr: string;
+}
+
 type LiteralUnion<T extends string> = T | (string & {});
 type Resolution = LiteralUnion<"144p" | "240p" | "360p" | "480p" | "720p" | "1080p" | "1440p" | "2160p">;
 type AudioCodec = LiteralUnion<"opus" | "aac" | "m4a" | "mp3" | "flac" | "wav">;
@@ -35,6 +40,12 @@ declare class DownloadBuilder {
     private videoFps?;
     private videoHeight?;
     constructor(url: string);
+    /**
+     * A private method to build the command-line arguments for yt-dlp based on the options set by the user.
+     * This method constructs the appropriate format filters and output template arguments according to the options set by the user.
+     *
+     * @returns The command-line arguments to be passed to yt-dlp based on the specified options.
+     */
     private buildArgs;
     /**
      * Set the desired resolution for the video download.
@@ -50,7 +61,7 @@ declare class DownloadBuilder {
      * If not specified, the file will be saved in the current working directory.
      *
      * @example
-     * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+     * download("https://www.example.com/video")
      * .output("downloads")
      * .run();
      *
@@ -65,7 +76,7 @@ declare class DownloadBuilder {
      * If no codec is specified, it will select the best available audio format regardless of codec.
      *
      * @example // Specifying an audio codec
-     * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+     * download("https://www.example.com/video")
      * .audio("mp3")
      * .run();
      *
@@ -79,7 +90,7 @@ declare class DownloadBuilder {
      * If not specified, it will select the best available video format regardless of extension.
      *
      * @example
-     * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+     * download("https://www.example.com/video")
      * .format("mp4")
      * .run();
      *
@@ -87,6 +98,14 @@ declare class DownloadBuilder {
      * @returns The current instance of DownloadBuilder for method chaining.
      */
     format(ext: VideoExt): this;
+    /**
+     * Set the desired frames per second (FPS) for the video download. You can specify a positive integer value for FPS, such as 30, 60, etc.
+     * The method will select the best available video format that has an FPS less than or equal to the specified value.
+     *
+     * @param fps The desired frames per second (FPS) for the video download.
+     * You can specify a positive integer value for FPS, such as 30, 60, etc.
+     * @returns  The current instance of DownloadBuilder for method chaining.
+     */
     fps(fps: number): this;
     /**
      * Set the filename template for the downloaded file.
@@ -94,12 +113,12 @@ declare class DownloadBuilder {
      * automatically mapped to their values at download time.
      *
      * @example // Using a string template
-     * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+     * download("https://www.example.com/video")
      * 	.output("downloads")
      * 	.filename("%(title)s.%(ext)s")
      *
      * @example // Using a callback to specify a custom filename template
-     * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+     * download("https://www.example.com/video")
      * 	.output("downloads")
      * 	.filename(({ title, ext }) => `${title}.${ext}`)
      * 	.run();
@@ -116,15 +135,25 @@ declare class DownloadBuilder {
      * @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")
+     * download("https://www.example.com/video")
      *  .resolution("720p")
      *  .output("downloads/%(title)s.%(ext)s")
      *  .run();
      *
      */
     run(): Promise<void>;
+    capture(): Promise<RunResult>;
+}
+
+declare class YtDlpNotFoundError extends Error {
+    constructor();
+}
+declare class YtDlpError extends Error {
+    readonly exitCode: number;
+    readonly stderr: string;
+    constructor(message: string, exitCode: number, stderr: string);
 }
 
 declare function download(url: string): DownloadBuilder;
 
-export { download };
+export { type AudioCodec, type OutputFields, type Resolution, type RunResult, type VideoExt, YtDlpError, YtDlpNotFoundError, download };

package/dist/index.js

@@ -1,14 +1,47 @@
 // src/internal/runner.ts
 import { execa, ExecaError } from "execa";
-async function runYtDlp(args) {
-  await execa("yt-dlp", ["--js-runtimes", "node", ...args], {
-    stdio: "inherit"
-  }).catch(handleEnoent);
+
+// src/errors.ts
+var YtDlpNotFoundError = class extends Error {
+  constructor() {
+    super(
+      "yt-dlp is not installed or not in PATH. Refer to https://github.com/yt-dlp/yt-dlp#installation"
+    );
+    this.name = "YtDlpNotFoundError";
+  }
+};
+var YtDlpError = class extends Error {
+  constructor(message, exitCode, stderr) {
+    super(message);
+    this.exitCode = exitCode;
+    this.stderr = stderr;
+    this.name = "YtDlpError";
+  }
+  exitCode;
+  stderr;
+};
+
+// src/internal/runner.ts
+async function runYtDlp(args, pipe = false) {
+  const result = await execa(
+    "yt-dlp",
+    ["--js-runtimes", "node", ...args],
+    { stdio: pipe ? "pipe" : "inherit" }
+  ).catch(handleError);
+  return {
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? ""
+  };
 }
-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"
+function handleError(error) {
+  if (error instanceof ExecaError) {
+    if (error.code === "ENOENT") {
+      throw new YtDlpNotFoundError();
+    }
+    throw new YtDlpError(
+      `yt-dlp exited with code ${error.exitCode}`,
+      error.exitCode ?? 1,
+      error.stderr ?? ""
     );
   }
   throw error;
@@ -18,6 +51,11 @@ function handleEnoent(error) {
 var DownloadBuilder = class {
   constructor(url) {
     this.url = url;
+    try {
+      new URL(url);
+    } catch {
+      throw new TypeError(`Invalid URL: ${url}`);
+    }
   }
   url;
   args = [];
@@ -28,6 +66,12 @@ var DownloadBuilder = class {
   videoExt;
   videoFps;
   videoHeight;
+  /**
+   * A private method to build the command-line arguments for yt-dlp based on the options set by the user.
+   * This method constructs the appropriate format filters and output template arguments according to the options set by the user.
+   *
+   * @returns The command-line arguments to be passed to yt-dlp based on the specified options.
+   */
   buildArgs() {
     const args = [...this.args];
     if (this.videoHeight || this.videoFps || this.videoExt || this.audioFormat) {
@@ -62,7 +106,7 @@ var DownloadBuilder = class {
    * If not specified, the file will be saved in the current working directory.
    *
    * @example
-   * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+   * download("https://www.example.com/video")
    * .output("downloads")
    * .run();
    *
@@ -80,7 +124,7 @@ var DownloadBuilder = class {
    * If no codec is specified, it will select the best available audio format regardless of codec.
    *
    * @example // Specifying an audio codec
-   * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+   * download("https://www.example.com/video")
    * .audio("mp3")
    * .run();
    *
@@ -97,7 +141,7 @@ var DownloadBuilder = class {
    * If not specified, it will select the best available video format regardless of extension.
    *
    * @example
-   * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+   * download("https://www.example.com/video")
    * .format("mp4")
    * .run();
    *
@@ -108,7 +152,20 @@ var DownloadBuilder = class {
     this.videoExt = ext;
     return this;
   }
+  /**
+   * Set the desired frames per second (FPS) for the video download. You can specify a positive integer value for FPS, such as 30, 60, etc.
+   * The method will select the best available video format that has an FPS less than or equal to the specified value.
+   *
+   * @param fps The desired frames per second (FPS) for the video download.
+   * You can specify a positive integer value for FPS, such as 30, 60, etc.
+   * @returns  The current instance of DownloadBuilder for method chaining.
+   */
   fps(fps) {
+    if (!Number.isInteger(fps) || fps <= 0) {
+      throw new RangeError(
+        `Invalid FPS value: ${fps}. FPS must be a positive integer.`
+      );
+    }
     this.videoFps = fps;
     return this;
   }
@@ -118,12 +175,12 @@ var DownloadBuilder = class {
    * automatically mapped to their values at download time.
    *
    * @example // Using a string template
-   * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+   * download("https://www.example.com/video")
    * 	.output("downloads")
    * 	.filename("%(title)s.%(ext)s")
    *
    * @example // Using a callback to specify a custom filename template
-   * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+   * download("https://www.example.com/video")
    * 	.output("downloads")
    * 	.filename(({ title, ext }) => `${title}.${ext}`)
    * 	.run();
@@ -152,7 +209,7 @@ var DownloadBuilder = class {
    * @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")
+   * download("https://www.example.com/video")
    *  .resolution("720p")
    *  .output("downloads/%(title)s.%(ext)s")
    *  .run();
@@ -162,6 +219,10 @@ var DownloadBuilder = class {
     const args = this.buildArgs();
     await runYtDlp([...args, this.url]);
   }
+  async capture() {
+    const args = this.buildArgs();
+    return runYtDlp([...args, this.url], true);
+  }
 };
 
 // src/index.ts
@@ -169,5 +230,7 @@ function download(url) {
   return new DownloadBuilder(url);
 }
 export {
+  YtDlpError,
+  YtDlpNotFoundError,
   download
 };

package/package.json

@@ -1,51 +1,53 @@
-{
-	"name": "@blagoja/ts-dlp",
-	"version": "0.1.3",
-	"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",
-			"require": "./dist/index.cjs"
-		}
-	},
-	"scripts": {
-		"build": "tsup src/index.ts --format esm,cjs --dts",
-		"dev": "tsx src/index.ts",
-		"lint": "eslint src",
-		"prepublishOnly": "npm run build"
-	},
-	"keywords": [
-		"yt-dlp",
-		"youtube-dl",
-		"downloader",
-		"wrapper"
-	],
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/blagojablazhevski/ts-dlp.git"
-	},
-	"author": "Blagoja Blazhevski",
-	"files": [
-		"dist"
-	],
-	"engines": {
-		"node": ">=18"
-	},
-	"license": "MIT",
-	"type": "module",
-	"devDependencies": {
-		"@types/node": "^25.9.1",
-		"eslint": "^10.4.0",
-		"jiti": "^2.7.0",
-		"tsup": "^8.5.1",
-		"tsx": "^4.22.3",
-		"typescript": "^6.0.3",
-		"typescript-eslint": "^8.60.0"
-	},
-	"dependencies": {
-		"execa": "^9.6.1"
-	}
-}
+{
+	"name": "@blagoja/ts-dlp",
+	"version": "0.1.4",
+	"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",
+			"require": "./dist/index.cjs"
+		}
+	},
+	"scripts": {
+		"build": "tsup src/index.ts --format esm,cjs --dts",
+		"dev": "tsx src/index.ts",
+		"lint": "eslint src",
+		"prepublishOnly": "npm run build",
+		"test": "vitest run"
+	},
+	"keywords": [
+		"yt-dlp",
+		"youtube-dl",
+		"downloader",
+		"wrapper"
+	],
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/blagojablazhevski/ts-dlp.git"
+	},
+	"author": "Blagoja Blazhevski",
+	"files": [
+		"dist"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"license": "MIT",
+	"type": "module",
+	"devDependencies": {
+		"@types/node": "^25.9.1",
+		"eslint": "^10.4.0",
+		"jiti": "^2.7.0",
+		"tsup": "^8.5.1",
+		"tsx": "^4.22.3",
+		"typescript": "^6.0.3",
+		"typescript-eslint": "^8.60.0",
+		"vitest": "^4.1.7"
+	},
+	"dependencies": {
+		"execa": "^9.6.1"
+	}
+}

package/dist/download.d.ts

@@ -1,43 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,55 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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.map

@@ -1 +0,0 @@
-{"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

@@ -1,3 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,13 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

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

package/dist/types.d.ts.map

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

package/dist/types.js

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

package/dist/types.js.map

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

package/dist/version.d.ts

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

package/dist/version.d.ts.map

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

package/dist/version.js

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

package/dist/version.js.map

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