npm - @blagoja/ts-dlp - Versions diffs - 0.1.1 → 0.1.2 - Mend

@blagoja/ts-dlp 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -47,36 +47,87 @@ var DownloadBuilder = class {
   }
   url;
   args = [];
+  videoFormat;
+  audioFormat;
+  outputDir;
+  filenameTemplate;
   /**
-   * 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".
+   * 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")
-   *   .resolution("720p")
-   *   .output("downloads/%(title)s.%(ext)s")
+   * .output("downloads")
+   * .run();
    *
-   * @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".
+   * @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.
    */
-  resolution(res) {
-    const height = res.replace("p", "");
-    this.args.push(
-      "-f",
-      `bestvideo[height<=${height}]+bestaudio/best[height<=${height}]`
-    );
+  output(dir) {
+    this.outputDir = dir;
     return this;
   }
   /**
-   * Set the output directory and filename template for the downloaded file.
+   * 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 The output template for the downloaded file. You can use placeholders like %(title)s, %(ext)s, etc. For example: "downloads/%(title)s.%(ext)s"
+   * @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.
    */
-  output(template) {
-    this.args.push("-o", template);
+  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;
   }
   /**
@@ -94,7 +145,18 @@ var DownloadBuilder = class {
    *
    */
   async run() {
-    await runYtDlp([...this.args, this.url]);
+    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]);
   }
 };

package/dist/index.d.cts CHANGED Viewed

@@ -1,29 +1,92 @@
+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 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".
+     * 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")
-     *   .resolution("720p")
-     *   .output("downloads/%(title)s.%(ext)s")
+     * .output("downloads")
+     * .run();
      *
-     * @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".
+     * @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.
      */
-    resolution(res: string): this;
+    output(dir: string): this;
     /**
-     * Set the output directory and filename template for the downloaded file.
+     * 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 The output template for the downloaded file. You can use placeholders like %(title)s, %(ext)s, etc. For example: "downloads/%(title)s.%(ext)s"
+     * @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.
      */
-    output(template: string): this;
+    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.

package/dist/index.d.ts CHANGED Viewed

@@ -1,29 +1,92 @@
+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 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".
+     * 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")
-     *   .resolution("720p")
-     *   .output("downloads/%(title)s.%(ext)s")
+     * .output("downloads")
+     * .run();
      *
-     * @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".
+     * @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.
      */
-    resolution(res: string): this;
+    output(dir: string): this;
     /**
-     * Set the output directory and filename template for the downloaded file.
+     * 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 The output template for the downloaded file. You can use placeholders like %(title)s, %(ext)s, etc. For example: "downloads/%(title)s.%(ext)s"
+     * @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.
      */
-    output(template: string): this;
+    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.

package/dist/index.js CHANGED Viewed

@@ -21,36 +21,87 @@ var DownloadBuilder = class {
   }
   url;
   args = [];
+  videoFormat;
+  audioFormat;
+  outputDir;
+  filenameTemplate;
   /**
-   * 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".
+   * 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")
-   *   .resolution("720p")
-   *   .output("downloads/%(title)s.%(ext)s")
+   * .output("downloads")
+   * .run();
    *
-   * @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".
+   * @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.
    */
-  resolution(res) {
-    const height = res.replace("p", "");
-    this.args.push(
-      "-f",
-      `bestvideo[height<=${height}]+bestaudio/best[height<=${height}]`
-    );
+  output(dir) {
+    this.outputDir = dir;
     return this;
   }
   /**
-   * Set the output directory and filename template for the downloaded file.
+   * 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 The output template for the downloaded file. You can use placeholders like %(title)s, %(ext)s, etc. For example: "downloads/%(title)s.%(ext)s"
+   * @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.
    */
-  output(template) {
-    this.args.push("-o", template);
+  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;
   }
   /**
@@ -68,7 +119,18 @@ var DownloadBuilder = class {
    *
    */
   async run() {
-    await runYtDlp([...this.args, this.url]);
+    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]);
   }
 };

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
 	"name": "@blagoja/ts-dlp",
-	"version": "0.1.1",
+	"version": "0.1.2",
 	"description": "A human readable TypeScript wrapper for yt-dlp",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -23,6 +23,10 @@
 		"downloader",
 		"wrapper"
 	],
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/blagojablazhevski/ts-dlp.git"
+	},
 	"author": "Blagoja Blazhevski",
 	"files": [
 		"dist"
@@ -30,7 +34,7 @@
 	"engines": {
 		"node": ">=18"
 	},
-	"license": "ISC",
+	"license": "MIT",
 	"type": "module",
 	"devDependencies": {
 		"@types/node": "^25.9.1",