Module: ytmp3

Core library for YTMP3 project.

This module contains the core functionality for YTMP3 project. It utilizes the @distube/ytdl-core (to download YouTube videos) and fluent-ffmpeg (to convert audio formats) libraries.

This module provides APIs to easily download YouTube videos (also supports YouTube Music) and convert them to MP3 format. The output MP3 files are stored in the specified output directory named download relatively to the project's root directory.

You can download a single YouTube video or a bunch of YouTube videos from a file as audio files and convert them to MP3 format. If you want to download a single YouTube video, please use the singleDownload function. Or if you want to download a bunch of YouTube videos, first you need to store all YouTube URLs in a file and then use the batchDownload function to download them by passing the path of the file.

Version:
  • 2.0.0
Since:
  • 1.0.0
Author:
  • Ryuu Mitsuki <https://github.com/mitsuki31>
License:
  • MIT
Source:
Examples

Download a single YouTube video 

const ytmp3 = require('ytmp3-js');
ytmp3.singleDownload('https://www.youtube.com/watch?v=<VIDEO_ID>')
  .then(outputFile => console.log('Download complete:', outputFile))
  .catch(err => console.error('Download failed:', err));

Download a batch of YouTube videos 

const ytmp3 = require('ytmp3-js');
ytmp3.batchDownload('./urls.txt')
  .then(outputFiles => {
    for (const outFile of outputFiles) {
      console.log('Download complete:', outFile);
    }
  })
  .catch(err => console.error('Download failed:', err));

Requires

Members

(inner, constant) version

The library version retrieved directly from package.json.

Source:

(inner, constant) version_info

The library version information in a frozen object.

Properties:
Name Type Description
major number

The major version number.
minor number

The minor version number.
patch number

The patch version number.
build string

The build information of current version (i.e., stable).
Since:
  • 1.1.0
Source:

Methods

(async, inner) batchDownload(file, optionsopt) → {Promise.<Record.<string, BatchDownloadResult>>}

Downloads audio from a file containing YouTube URLs and saves them to the output directory.

This function is similar to download but accepts a file containing a list of YouTube URLs as input. If the given file is empty or does not exist, an error will be thrown.

As of version 1.0.0, this function has been enhanced and made more robust, aiming at the download process. Previously, it only downloaded the first 15 URLs from the given file. Now, it downloads all of them sequentially. The function can now handle an unlimited number of URLs, downloading them one by one (also known as, sequential download) instead of all at once. Additionally, the download progress bar has been reworked to display more precise and colorful information in the terminal, providing users with better insights into the download process, and also more better and improved errors handling.

As of version 2.0.0, the batch file now supports comments, allowing users to include notes or instructions in the file. These comments will be ignored during the pre-download process. Supported comments are:

  • # This is a comment
  • // This is also a comment Not only that, the function now capable to parse any string representing the YouTube video ID, this behavior can be enabled by set the options.includeID to true. Furthermore, the function has improved to make user more easy to integrate their download handler and the returned result now provide detail information for each downloaded audio, they are includes but not least, the downloaded audio path, metadata information per audio, audio conversion result (if enabled), and all errors that occurred during download process.
Parameters:
Name Type Attributes Description
file string | Buffer.<ArrayBufferLike>

The path to the file containing YouTube URLs.
options BatchDownloadOptions <optional>

Options to configure the batch download process. If not specified, it will automatically uses default options, see defaults.DownloadOptions. There is one option exclusively for this function, it is called includeID, if set to true the batch file processor will treats and parses any string representing the video ID.
Since:
  • 1.0.0
Source:
Throws:

If the file does not exist or no URLs found within file, or if there is an error occurred during download process.

Type
Error
Returns:

Fulfills with an object with video IDs as keys and the download result objects as values.

Type
Promise.<Record.<string, BatchDownloadResult>>

(async, package, inner) defaultBatchHandler(stream, data, options) → {Promise.<void>}

Handles the batch download process, including progress updates, error handling, and completion notification.

Parameters:
Name Type Description
stream Readable

The readable stream to download from.
data object

Metadata of the video content.

Properties
Name Type Attributes Description
title string

The title of the video.
outStream fs.WriteStream <optional>

The output stream to write to.
options object

Options for the download process.

Properties
Name Type Attributes Default Description
quiet boolean <optional>
 false

If true, suppresses log output.
verbose boolean <optional>
 false

If true, enables verbose logging.
outDir string <optional>
 '.'

The output directory for the downloaded file.
outFile string <optional>

The name of the output file.
range Object <optional>

The range of bytes to download.
Since:
  • 2.0.0
Source:
Throws:

If an error occurs during the download process.

Type
Error
Returns:
Type
Promise.<void>

(async, package, inner) defaultHandler(stream, data, options) → {Promise.<void>}

Handles the download process, including progress updates, error handling, and completion notification.

Parameters:
Name Type Description
stream Readable

The readable stream to download from.
data object

Metadata of the video content.

Properties
Name Type Attributes Description
title string

The title of the video.
outStream fs.WriteStream <optional>

The output stream to write to.
options object

Options for the download process.

Properties
Name Type Attributes Default Description
quiet boolean <optional>
 false

If true, suppresses log output.
verbose boolean <optional>
 false

If true, enables verbose logging.
outDir string <optional>
 '.'

The output directory for the downloaded file.
outFile string <optional>

The name of the output file.
range Object <optional>

The range of bytes to download.
Since:
  • 2.0.0
Source:
Throws:

If an error occurs during the download process.

Type
Error
Returns:
Type
Promise.<void>

(async, inner) download(url, optionsopt) → {Promise.<DownloadResult>}

Downloads audio from a YouTube video using the provided video URL or video ID.

This function performs the entire process of downloading YouTube audio, including:

  • Validating and resolving the input (URL or video ID).
  • Fetching video metadata and selecting the best available audio format.
  • Managing file naming, sanitization, and output directory resolution.
  • Handling download interruptions and ensuring safe termination.
  • Writing the downloaded data to a file with proper error handling.
  • Optionally converting the downloaded audio format.

The function retrieves video metadata from YouTube, checks for available audio formats, and downloads the content in AAC (Advanced Audio Coding) format by default. The file is saved in the current directory unless options.outDir is specified.

Customizing the Download Process

If you want to change the behavior of the download process, you can provide a custom options.handler function to handle the download stream and log messages. The handler function accepts 3 arguments: a ReadableStream instance, the video metadata object, and the options object. The handler function can be a synchronous or asynchronous function that returns a promise, both of them are handled properly by this function. But it is recommended to use an asynchronous function, as it might cause to blocking of the main thread if the handler function is synchronous.

Caching Behavior

By default, video metadata is cached in YTMP3’s cache directory to optimize subsequent downloads. This behavior can be disabled by setting options.useCache to false, which forces the function to always fetch fresh metadata from the YouTube server. Disabling this option also prevents the function from creating or updating any cached data for the given video.

Cache Expiration

Cached video metadata expires after 2 hours (7200 seconds or 7.2×10⁵ milliseconds). Once expired, the function attempts to verify cache validity by sending a HEAD request to YouTube. If the response status is 200 OK, the cached data is used instead of fetching new metadata. Otherwise, fresh data is retrieved and the cache is updated.

Parameters:
Name Type Attributes Description
url string | URL

A YouTube video URL or video ID to download its audio content.
options DownloadOptions <optional>

Options to configure the video information retrieval and download process.
Since:
  • 2.0.0
Source:
Throws:

  • If the provided video ID is invalid.

    Type
    IDValidationError

  • If options are not a valid object.

    Type
    InvalidTypeError

  • If an error occurs during fetching, downloading, or writing the file.

    Type
    Error
Returns:

Fulfills with an object containing download metadata and file paths.

Type
Promise.<DownloadResult>

(async, generator, package, inner) downloadAudio(…urls) → {Promise.<object>}

Downloads audio from multiple YouTube videos sequentially.

Parameters:
Name Type Attributes Description
urls string | URL <repeatable>

The URLs to download audio from. Each URL can be a string or a URL object.
Since:
  • 1.0.0, 2.0.0
Deprecated:
  • Yes
Source:
Yields:
A promise that resolves to an object containing video information, video data, and a download stream.
Type
Promise.<object>

(async, package, inner) downloadHandler(readablenon-null, data, verbose)

Parameters:
Name Type Description
readable Readable

The readable stream to process.
data Object

The data object containing video information, video data, and an output stream.

Properties
Name Type Description
videoData VideoData

The processed video data.
outStream fs.WriteStream

The output stream to write to.
errLogFile string

The error log file for logging errors during download.
progressBar ProgressBar

The progress bar object.
verbose boolean

Whether to display progress bar and error message to the terminal or not.
Since:
  • 1.0.0, 2.0.0
Deprecated:
  • Yes
Source:

(async, inner) getInfo(url, optionsopt) → {Promise.<(ytdl.videoInfo|Array.<ytdl.videoInfo>|Record.<string, ytdl.videoInfo>)>}

Retrieves the YouTube video information from the given YouTube URL(s) or ID(s).

If the given URL is an array either of strings or URL objects, the function will returns an array fullfilled with the video information from each URLs (except options.asObject is set to true). The function will automatically filter out any nullable values (null, undefined or an empty string) from the array, if provided.

For more flexibility, this function also accepts video ID to url parameter. In this case, the function will returns the video information for the given video ID.

This function will able to create and retrieve a cache of video information for faster access by enabling the options.useCache option. The cache file will be created in the YTMP3's cache directory, see VINFO_CACHE_PATH. If the cache not found or options.useCache is set to false, the function will ignore the cache and fetch the video information from the server, and if the options.useCache is set to true, the function will store the cache for later retrieval the video information.

Parameters:
Name Type Attributes Description
url string | URL | Array.<(string|URL)>

The YouTube video URL(s) or ID(s) to retrieve its information.
options ytdl.getInfoOptions <optional>

Options to use when fetching the video information. This options object is extend to the ytdl.getInfoOptions object.

Properties
Name Type Attributes Default Description
asObject boolean <optional>

If set to true, the returned value will be an object with video ID as keys and video information object as values. Otherwise, the returned value will be an array of video information objects. This option will be ignored if the url is not an array.
useCache boolean <optional>

If set to true, the function will use the cache to retrieve the video information. Otherwise, the function will ignore the cache and fetch the video information from the server. This also will make the function to create a new cache file in the YTMP3's cache directory.
verbose boolean <optional>
 false

Whether to print the process retrieval to standard output. Defaults to false.
Since:
  • 2.0.0
Source:
Throws:

  • If there is an invalid YouTube video ID.

    Type
    IDValidationError

  • If there is an invalid YouTube video URL.

    Type
    URLValidationError

  • If there is an error occurred while fetching video information from server or cache.

    Type
    Error
Returns:

A promise fulfills with a video information. If the url is an array, returned value will be an array of video information(s), or if the options.asObject is set to true, the returned value will be an object with video ID as keys and video information object as values.

Type
Promise.<(ytdl.videoInfo|Array.<ytdl.videoInfo>|Record.<string, ytdl.videoInfo>)>

(async, inner) getVideosInfo(…urls) → {Promise.<Array.<ytdl.videoInfo>>}

Retrieves information for multiple YouTube videos sequentially.

Deprecated: Please use getInfo instead for better video information retrieval with caching capability.

This function accepts multiple YouTube URLs and retrieves information for each video sequentially. It processes each URL one by one, ensuring that the next URL is processed only after the previous one is complete.

Parameters:
Name Type Attributes Description
urls string | URL <repeatable>

The YouTube video URLs to fetch information for. Each URL can be either a string or a URL object.
Since:
  • 0.2.0, 2.0.0
Deprecated:
  • Yes
Source:
See:
Throws:

If any of the provided URLs are invalid, validated using validateURL function from ytdl-core module.

Type
Error
Returns:

A promise that resolves to an array of video information objects.

Type
Promise.<Array.<ytdl.videoInfo>>
Example
const videoUrls = [
  'https://www.youtube.com/watch?v=abcd1234',
  'https://www.youtube.com/watch?v=wxyz5678'
];

getVideosInfo(...videoUrls).then(videoInfos => {
  console.log(videoInfos);
}).catch(error => {
  console.error('Error fetching video info:', error);
});

(inner) resolveDlOptions(options) → {DownloadOptions}

Resolves and validates download options.

This function ensures the provided download options are correctly typed and assigns default values where necessary.

Parameters:
Name Type Description
options Object

The options object.

Properties
Name Type Attributes Description
downloadOptions DownloadOptions | Object | undefined <nullable>

The download options to resolve and validate.
Since:
  • 1.0.0, 2.0.0
Deprecated:
  • Yes
Source:
Throws:

If the given argument is non-null, but also not an object type. And if any of the options have incorrect type.

Type
TypeError
Returns:

The resolved download options. This object can be passed safely to singleDownload or singleDownload function.

Type
DownloadOptions

(inner) sanitizeFilename(filename) → {string}

Sanitizes a filename by replacing invalid characters with underscores.

The following characters are considered invalid in filenames and will be replaced: /\:*?"|<>

Parameters:
Name Type Description
filename string

The original filename to be sanitized.
Source:
Returns:
  • The sanitized filename with invalid characters replaced by underscores.
Type
string

(async, inner) singleDownload(inputUrlnon-null, downloadOptionsopt) → {Promise.<string>}

Downloads audio from a single YouTube URL and saves it to the output directory.

Deprecated: Please use download instead. The processes handling are more better than this function.

Parameters:
Name Type Attributes Description
inputUrl string | URL

The URL of the YouTube video to download audio from.
downloadOptions DownloadOptions <optional>

Options to configure the download process. If not specified, it will automatically uses default options.
Since:
  • 1.0.0, 2.0.0
Deprecated:
  • Since v2.0.0, deprecated due to inefficiency processes handling and will be removed in a future version. Please use `download` for better and improved processes handling and more efficient.
Source:
See:
Throws:

  • If there is an error occurs during download process.

    Type
    Error

  • If the input URL is not a string nor an instance of URL.

    Type
    TypeError
Returns:

A promise that resolves a string representating the output file when the download completes or rejects if an error occurs.

Type
Promise.<string>
Example
singleDownload('https://www.youtube.com/watch?v=<VIDEO_ID>')
  .then(outFile => console.log(outFile))
  .catch(err => console.error('Download failed:', err));

(package, inner) validateYTURL(url, verboseopt)

Validates a YouTube URL.

This function validates a YouTube URL and throws an error if it is not valid.

Parameters:
Name Type Attributes Default Description
url string | URL

The URL to validate.
verbose boolean <optional>
 false

Whether to log verbose messages or not.
Since:
  • 1.0.0
Deprecated:
  • Yes
Source:
Throws:

  • If the URL is not a string nor an instance of URL.

    Type
    TypeError

  • If the input URL is not valid.

    Type
    Error

(async, package, inner) writeErrorLog(logfile, videoData, erroropt) → {Promise.<boolean>}

Writes error details and associated video information to a log file.

This function creates or appends to a log file in the LOGDIR directory, logging the error message along with relevant video data. If the log file is empty after writing, it will be deleted, and the function returns false. Otherwise, it returns true to indicate successful logging.

The error message is written to the log file in the following format:

[ERROR] <error message>
  Title: <video title>
  Author: <video author>
  Channel ID: <video channel ID>
  Viewers: <video viewers>
  URL: <video URL>
---------------------------------------------

Immediately return false if the given log file name is invalid. The error log will be in the LOGDIR directory.

Parameters:
Name Type Attributes Description
logfile string

The name of the log file where the error details should be written.
videoData VideoData | Object

An object containing information about the video associated with the error.
error Error <optional>

The error object, optional. If not provided, an error message will be 'Unknown error'.
Since:
  • 1.0.0
Deprecated:
  • Yes
Source:
Returns:

A promise that resolves to true if the log was written successfully, otherwise false.

Type
Promise.<boolean>

(async, inner) ytmp3(input, optionsopt)

Downloads a YouTube audio and optionally convert into specific audio format with one function.

Use the ytmp3.batchDownload function if you want to batch download some YouTube audios from a specific file.

Parameters:
Name Type Attributes Description
input string | URL

The YouTube URL or video ID to download.
options DownloadOptions <optional>

An optional options object to configure the retrieval video information, download, and audio conversion process.
Since:
  • 2.0.0
Source:
See: