@blagoja/ts-dlp 0.1.0 → 0.1.2

package/README.md

@@ -57,7 +57,7 @@ pip install -U yt-dlp
 
 Official project:
 
-TBD
+https://www.npmjs.com/package/@blagoja/ts-dlp
 
 ---
 
@@ -108,24 +108,19 @@ await ytdlp
 ## v0.1.0 - Foundation
 
 - [x] Detect yt-dlp installation
-- [ ] Execute simple yt-dlp commands
+- [x] 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)`
+- [x] `.download(url)`
+- [x] `.run()`
+- [x] `.output(path)`
 - [ ] `.format(format)`
-- [ ] `.audio()`
+- [x] `.audio()`
 - [ ] `.video()`
-- [ ] `.resolution()`
+- [x] `.resolution()`
 - [ ] `.fps()`
 
 Example:
@@ -136,7 +131,7 @@ await ytdlp.download(url).resolution("720p").run();
 
 ---
 
-## v0.3.0 - Metadata & Information
+## v0.2.0 - Metadata & Information
 
 - [ ] `.info()`
 - [ ] Video metadata parsing
@@ -152,7 +147,7 @@ const info = await ytdlp.info(url);
 
 ---
 
-## v0.4.0 - Advanced Features
+## v0.3.0 - Advanced Features
 
 - [ ] Subtitle support
 - [ ] Thumbnail downloads
@@ -163,7 +158,7 @@ const info = await ytdlp.info(url);
 
 ---
 
-## v0.5.0 - Developer Experience
+## v0.4.0 - Developer Experience
 
 - [ ] Better typed builders
 - [ ] Presets

package/dist/index.cjs

@@ -0,0 +1,170 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  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);
+}
+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"
+    );
+  }
+  throw error;
+}
+
+// src/download.ts
+var DownloadBuilder = class {
+  constructor(url) {
+    this.url = url;
+  }
+  url;
+  args = [];
+  videoFormat;
+  audioFormat;
+  outputDir;
+  filenameTemplate;
+  /**
+   * Set the desired resolution for the video download.
+   * The method will automatically select the best video format that is less than or equal to the specified resolution.
+   * For example, if you specify "720p", it will select the best available video format that is 720p or lower.
+   *
+   * @param res The desired resolution for the video. You can specify common resolutions like "720p", "1080p", etc. The method will automatically select the best video format that is less than or equal to the specified resolution.
+   * @returns The current instance of DownloadBuilder for method chaining.
+   */
+  resolution(res) {
+    const height = res.replace("p", "");
+    this.videoFormat = `bestvideo[height<=${height}]`;
+    return this;
+  }
+  /**
+   * Set the output directory for the downloaded file. You can specify a directory path like "downloads".
+   * If not specified, the file will be saved in the current working directory.
+   *
+   * @example
+   * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+   * .output("downloads")
+   * .run();
+   *
+   * @param dir The output directory where the downloaded file will be saved.
+   * You can specify a directory path like "downloads". If not specified, the file will be saved in the current working directory.
+   * @returns The current instance of DownloadBuilder for method chaining.
+   */
+  output(dir) {
+    this.outputDir = dir;
+    return this;
+  }
+  /**
+   * Set the desired audio codec for the download.
+   * The method will select the best available audio format that matches the specified codec.
+   * 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")
+   * .audio("mp3")
+   * .run();
+   *
+   * @param codec The desired audio codec for the download. You can specify common audio codecs like "mp3", "aac", "opus", etc. If no codec is specified, it will select the best available audio format.
+   * @returns The current instance of DownloadBuilder for method chaining.
+   */
+  audio(codec) {
+    this.audioFormat = codec ? `bestaudio[ext=${codec}]` : "bestaudio";
+    return this;
+  }
+  /**
+   * Set the filename template for the downloaded file.
+   * The callback receives common output fields as named parameters which are
+   * automatically mapped to their values at download time.
+   *
+   * @example // Using a string template
+   * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+   * 	.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")
+   * 	.output("downloads")
+   * 	.filename(({ title, ext }) => `${title}.${ext}`)
+   * 	.run();
+   *
+   * @param template A callback that receives output fields and returns a filename string. If omitted, defaults to the video title with its original extension.
+   * @returns The current instance of DownloadBuilder for method chaining.
+   */
+  filename(template) {
+    if (typeof template === "string") {
+      this.filenameTemplate = template;
+    } else {
+      const fields = new Proxy({}, {
+        get(_, prop) {
+          return `%(${prop})s`;
+        }
+      });
+      this.filenameTemplate = template(fields);
+    }
+    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() {
+    const args = [...this.args];
+    if (this.videoFormat || this.audioFormat) {
+      const video = this.videoFormat ?? "bestvideo";
+      const audio = this.audioFormat ?? "bestaudio";
+      args.push("-f", `${video}+${audio}/best`);
+    }
+    if (this.outputDir || this.filenameTemplate) {
+      const dir = this.outputDir ?? "";
+      const file = this.filenameTemplate ?? "%(title)s.%(ext)s";
+      args.push("-o", dir ? `${dir}/${file}` : file);
+    }
+    await runYtDlp([...args, this.url]);
+  }
+};
+
+// src/index.ts
+function download(url) {
+  return new DownloadBuilder(url);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  download
+});

package/dist/index.d.cts

@@ -0,0 +1,109 @@
+type Resolution = "144p" | "240p" | "360p" | "480p" | "720p" | "1080p" | "1440p" | "2160p" | (string & {});
+type OutputFields = {
+    title: string;
+    ext: string;
+    id: string;
+    uploader: string;
+    uploader_id: string;
+    channel: string;
+    upload_date: string;
+    release_date: string;
+    epoch: string;
+    height: string;
+    width: string;
+    resolution: string;
+    fps: string;
+    vcodec: string;
+    acodec: string;
+    duration_string: string;
+    playlist_title: string;
+    playlist_index: string;
+    autonumber: string;
+};
+type AudioCodec = "opus" | "aac" | "m4a" | "mp3" | "flac" | "wav" | (string & {});
+
+declare class DownloadBuilder {
+    private readonly url;
+    private readonly args;
+    private videoFormat?;
+    private audioFormat?;
+    private outputDir?;
+    private filenameTemplate?;
+    constructor(url: string);
+    /**
+     * Set the desired resolution for the video download.
+     * The method will automatically select the best video format that is less than or equal to the specified resolution.
+     * For example, if you specify "720p", it will select the best available video format that is 720p or lower.
+     *
+     * @param res The desired resolution for the video. You can specify common resolutions like "720p", "1080p", etc. The method will automatically select the best video format that is less than or equal to the specified resolution.
+     * @returns The current instance of DownloadBuilder for method chaining.
+     */
+    resolution(res: Resolution): this;
+    /**
+     * Set the output directory for the downloaded file. You can specify a directory path like "downloads".
+     * If not specified, the file will be saved in the current working directory.
+     *
+     * @example
+     * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+     * .output("downloads")
+     * .run();
+     *
+     * @param dir The output directory where the downloaded file will be saved.
+     * You can specify a directory path like "downloads". If not specified, the file will be saved in the current working directory.
+     * @returns The current instance of DownloadBuilder for method chaining.
+     */
+    output(dir: string): this;
+    /**
+     * Set the desired audio codec for the download.
+     * The method will select the best available audio format that matches the specified codec.
+     * 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")
+     * .audio("mp3")
+     * .run();
+     *
+     * @param codec The desired audio codec for the download. You can specify common audio codecs like "mp3", "aac", "opus", etc. If no codec is specified, it will select the best available audio format.
+     * @returns The current instance of DownloadBuilder for method chaining.
+     */
+    audio(codec?: AudioCodec): this;
+    /**
+     * Set the filename template for the downloaded file.
+     * The callback receives common output fields as named parameters which are
+     * automatically mapped to their values at download time.
+     *
+     * @example // Using a string template
+     * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+     * 	.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")
+     * 	.output("downloads")
+     * 	.filename(({ title, ext }) => `${title}.${ext}`)
+     * 	.run();
+     *
+     * @param template A callback that receives output fields and returns a filename string. If omitted, defaults to the video title with its original extension.
+     * @returns The current instance of DownloadBuilder for method chaining.
+     */
+    filename(template: ((fields: OutputFields) => string) | 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>;
+}
+
+declare function download(url: string): DownloadBuilder;
+
+export { download };

package/dist/index.d.ts

@@ -1,3 +1,109 @@
-import { DownloadBuilder } from "./download.js";
-export declare function download(url: string): DownloadBuilder;
-//# sourceMappingURL=index.d.ts.map
+type Resolution = "144p" | "240p" | "360p" | "480p" | "720p" | "1080p" | "1440p" | "2160p" | (string & {});
+type OutputFields = {
+    title: string;
+    ext: string;
+    id: string;
+    uploader: string;
+    uploader_id: string;
+    channel: string;
+    upload_date: string;
+    release_date: string;
+    epoch: string;
+    height: string;
+    width: string;
+    resolution: string;
+    fps: string;
+    vcodec: string;
+    acodec: string;
+    duration_string: string;
+    playlist_title: string;
+    playlist_index: string;
+    autonumber: string;
+};
+type AudioCodec = "opus" | "aac" | "m4a" | "mp3" | "flac" | "wav" | (string & {});
+
+declare class DownloadBuilder {
+    private readonly url;
+    private readonly args;
+    private videoFormat?;
+    private audioFormat?;
+    private outputDir?;
+    private filenameTemplate?;
+    constructor(url: string);
+    /**
+     * Set the desired resolution for the video download.
+     * The method will automatically select the best video format that is less than or equal to the specified resolution.
+     * For example, if you specify "720p", it will select the best available video format that is 720p or lower.
+     *
+     * @param res The desired resolution for the video. You can specify common resolutions like "720p", "1080p", etc. The method will automatically select the best video format that is less than or equal to the specified resolution.
+     * @returns The current instance of DownloadBuilder for method chaining.
+     */
+    resolution(res: Resolution): this;
+    /**
+     * Set the output directory for the downloaded file. You can specify a directory path like "downloads".
+     * If not specified, the file will be saved in the current working directory.
+     *
+     * @example
+     * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+     * .output("downloads")
+     * .run();
+     *
+     * @param dir The output directory where the downloaded file will be saved.
+     * You can specify a directory path like "downloads". If not specified, the file will be saved in the current working directory.
+     * @returns The current instance of DownloadBuilder for method chaining.
+     */
+    output(dir: string): this;
+    /**
+     * Set the desired audio codec for the download.
+     * The method will select the best available audio format that matches the specified codec.
+     * 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")
+     * .audio("mp3")
+     * .run();
+     *
+     * @param codec The desired audio codec for the download. You can specify common audio codecs like "mp3", "aac", "opus", etc. If no codec is specified, it will select the best available audio format.
+     * @returns The current instance of DownloadBuilder for method chaining.
+     */
+    audio(codec?: AudioCodec): this;
+    /**
+     * Set the filename template for the downloaded file.
+     * The callback receives common output fields as named parameters which are
+     * automatically mapped to their values at download time.
+     *
+     * @example // Using a string template
+     * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+     * 	.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")
+     * 	.output("downloads")
+     * 	.filename(({ title, ext }) => `${title}.${ext}`)
+     * 	.run();
+     *
+     * @param template A callback that receives output fields and returns a filename string. If omitted, defaults to the video title with its original extension.
+     * @returns The current instance of DownloadBuilder for method chaining.
+     */
+    filename(template: ((fields: OutputFields) => string) | 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>;
+}
+
+declare function download(url: string): DownloadBuilder;
+
+export { download };

package/dist/index.js

@@ -1,5 +1,143 @@
-import { DownloadBuilder } from "./download.js";
-export function download(url) {
-    return new DownloadBuilder(url);
+// 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);
 }
-//# sourceMappingURL=index.js.map
+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;
+}
+
+// src/download.ts
+var DownloadBuilder = class {
+  constructor(url) {
+    this.url = url;
+  }
+  url;
+  args = [];
+  videoFormat;
+  audioFormat;
+  outputDir;
+  filenameTemplate;
+  /**
+   * Set the desired resolution for the video download.
+   * The method will automatically select the best video format that is less than or equal to the specified resolution.
+   * For example, if you specify "720p", it will select the best available video format that is 720p or lower.
+   *
+   * @param res The desired resolution for the video. You can specify common resolutions like "720p", "1080p", etc. The method will automatically select the best video format that is less than or equal to the specified resolution.
+   * @returns The current instance of DownloadBuilder for method chaining.
+   */
+  resolution(res) {
+    const height = res.replace("p", "");
+    this.videoFormat = `bestvideo[height<=${height}]`;
+    return this;
+  }
+  /**
+   * Set the output directory for the downloaded file. You can specify a directory path like "downloads".
+   * If not specified, the file will be saved in the current working directory.
+   *
+   * @example
+   * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+   * .output("downloads")
+   * .run();
+   *
+   * @param dir The output directory where the downloaded file will be saved.
+   * You can specify a directory path like "downloads". If not specified, the file will be saved in the current working directory.
+   * @returns The current instance of DownloadBuilder for method chaining.
+   */
+  output(dir) {
+    this.outputDir = dir;
+    return this;
+  }
+  /**
+   * Set the desired audio codec for the download.
+   * The method will select the best available audio format that matches the specified codec.
+   * 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")
+   * .audio("mp3")
+   * .run();
+   *
+   * @param codec The desired audio codec for the download. You can specify common audio codecs like "mp3", "aac", "opus", etc. If no codec is specified, it will select the best available audio format.
+   * @returns The current instance of DownloadBuilder for method chaining.
+   */
+  audio(codec) {
+    this.audioFormat = codec ? `bestaudio[ext=${codec}]` : "bestaudio";
+    return this;
+  }
+  /**
+   * Set the filename template for the downloaded file.
+   * The callback receives common output fields as named parameters which are
+   * automatically mapped to their values at download time.
+   *
+   * @example // Using a string template
+   * download("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+   * 	.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")
+   * 	.output("downloads")
+   * 	.filename(({ title, ext }) => `${title}.${ext}`)
+   * 	.run();
+   *
+   * @param template A callback that receives output fields and returns a filename string. If omitted, defaults to the video title with its original extension.
+   * @returns The current instance of DownloadBuilder for method chaining.
+   */
+  filename(template) {
+    if (typeof template === "string") {
+      this.filenameTemplate = template;
+    } else {
+      const fields = new Proxy({}, {
+        get(_, prop) {
+          return `%(${prop})s`;
+        }
+      });
+      this.filenameTemplate = template(fields);
+    }
+    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() {
+    const args = [...this.args];
+    if (this.videoFormat || this.audioFormat) {
+      const video = this.videoFormat ?? "bestvideo";
+      const audio = this.audioFormat ?? "bestaudio";
+      args.push("-f", `${video}+${audio}/best`);
+    }
+    if (this.outputDir || this.filenameTemplate) {
+      const dir = this.outputDir ?? "";
+      const file = this.filenameTemplate ?? "%(title)s.%(ext)s";
+      args.push("-o", dir ? `${dir}/${file}` : file);
+    }
+    await runYtDlp([...args, this.url]);
+  }
+};
+
+// src/index.ts
+function download(url) {
+  return new DownloadBuilder(url);
+}
+export {
+  download
+};

package/package.json

@@ -1,17 +1,18 @@
 {
 	"name": "@blagoja/ts-dlp",
-	"version": "0.1.0",
+	"version": "0.1.2",
 	"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"
+			"types": "./dist/index.d.ts",
+			"require": "./dist/index.cjs"
 		}
 	},
 	"scripts": {
-		"build": "tsc",
+		"build": "tsup src/index.ts --format esm,cjs --dts",
 		"dev": "tsx src/index.ts",
 		"lint": "eslint src",
 		"prepublishOnly": "npm run build"
@@ -22,6 +23,10 @@
 		"downloader",
 		"wrapper"
 	],
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/blagojablazhevski/ts-dlp.git"
+	},
 	"author": "Blagoja Blazhevski",
 	"files": [
 		"dist"
@@ -29,15 +34,16 @@
 	"engines": {
 		"node": ">=18"
 	},
-	"license": "ISC",
+	"license": "MIT",
 	"type": "module",
 	"devDependencies": {
 		"@types/node": "^25.9.1",
-		"typescript-eslint": "^8.60.0",
 		"eslint": "^10.4.0",
 		"jiti": "^2.7.0",
+		"tsup": "^8.5.1",
 		"tsx": "^4.22.3",
-		"typescript": "^6.0.3"
+		"typescript": "^6.0.3",
+		"typescript-eslint": "^8.60.0"
 	},
 	"dependencies": {
 		"execa": "^9.6.1"