A Node.js library offers an easy and uncomplicated method for downloading YouTube audio
| Lint |  |
| Unit Testing |  |
| Integration Testing |  |
| Code Coverage |  |
Wiki Homepage: [here]
API Documentation: [here]
YTMP3-JS is a Node.js library designed for effortlessly downloading audio from YouTube videos, whether it's a single URL or multiple URLs, utilizing the @distube/ytdl-core module. The library also optionally converts these audio files into MP3 format.
This module offers both simple APIs and a command-line interface, allowing you to download audio from a single YouTube URL provided as an input argument or from multiple YouTube URLs listed in a file with ease.
All downloaded audio files are saved in the current directory (unless being overridden with -o CLI option), which is relative to the project's root directory. If the FFmpeg library is installed on your system, these files are optionally converted to MP3 format (use the -C option to enable the audio conversion behavior).
[!WARNING]
This project usesfluent-ffmpegto convert audio files to the desired codec, specifically MP3. Therefore, it requires theffmpeglibrary and its binaries to be installed on your system, along with any necessary encoding libraries such aslibmp3lamefor MP3 conversion.However, don't worry if your system does not have
ffmpeginstalled. The download process will not fail; instead, the audio conversion will be skipped, and the downloaded audio files will remain in AAC (Advanced Audio Coding) format with a.m4aextension.
npm i -g ytmp3-js
If you've downloaded package from the release asset, you may use local installation like this:
npm i -g /path/to/ytmp3-js.<VERSION>.tgz
ytmp3 [options] [[URL ...] | [-f <FILE>]]
For command-line options with detailed information, please refer to Command-Line Options wiki's page.
ytmp3 https://youtu.be/abcdef123 -o /home/Music -C --format flac --codec flac --frequency 48000
In above example, the code is trying to download audio from a single URL and convert it to FLAC codec with frequency set to 48000 Hz (equal to 48 KHz) and save the processed audio file to /home/Music directory.
If you'd supplied only the -C (or --convertAudio) option, then a downloaded audio file will be automatically converted to MP3 format (which is the default behavior).
But only if you've installed FFmpeg.
singleDownloadasync function singleDownload(
inputUrl: string | URL,
downloadOptions?: DownloadOptions | Object
): Promise<string>
Downloads audio from a single YouTube URL and saves it to the output directory (change the output directory with -o or --outDir option).
| Name | Type | Description |
|---|---|---|
inputUrl | string | URL | The URL of the YouTube video to download audio from. |
downloadOptions | DownloadOptions | Object | Options to configure the download process. If not specified, it will automatically uses default options. |
A promise that resolves a string representating the output file when the download completes.
Type: Promise<string>
batchDownloadasync function batchDownload(
inputFile: string,
downloadOptions?: DownloadOptions | Object
): Promise<string[]>
Downloads audio from a file containing YouTube URLs and saves them to the output directory (change the output directory with -o or --outDir option).
| Name | Type | Description |
|---|---|---|
inputFile | string | The path to the file containing YouTube URLs. |
downloadOptions | DownloadOptions | Object | Options to configure the download process. If not specified, it will automatically uses default options. |
A promise that resolves to an array of strings representing the successfully downloaded files.
Type: Promise<string[]>
getVideosInfoasync function getVideosInfo(
...urls: string | URL
): Promise<import('@distube/ytdl-core').videoInfo[]>
Retrieves information for multiple YouTube videos sequentially.
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.
| Name | Type | Description |
|---|---|---|
...urls | string | URL | The YouTube video URLs to fetch information for. Each URL can be either a string or a URL object. |
A promise that resolves to an array of video information objects.
Type: Promise<import('@distube/ytdl-core').videoInfo[]>
checkFfmpegasync function checkFfmpeg(verbose?: boolean = false): Promise<boolean>
Checks whether the ffmpeg binary is installed on system or not.
First, it checks if the FFMPEG_PATH environment variable is set. If it is set, it returns true. Otherwise, if not set, it checks if the ffmpeg binary is installed on system by directly executing it.
| Name | Type | Description |
|---|---|---|
verbose | boolean | undefined | Whether to log verbose messages or not. Defaults to false. |
A promise that resolves to a boolean value, true if the ffmpeg binary installed on system; otherwise, false.
Type: boolean
convertAudioasync function convertAudio(
inFile: string,
options?: ConvertAudioOptions = defaultOptions
): Promise<void>
Converts an audio file to a specified format using the given options.
Before performing audio conversion, it first checks the ffmpeg binary by searching on the FFMPEG_PATH environment variable, if set. Otherwise, it force check by calling the ffmpeg command itself on child process.
If the ffmpeg is not installed on the system, this function will aborts immediately and rejects with an error.
| Name | Type | Description |
|---|---|---|
inFile | string | The input file path of the audio file to be converted. |
options | ConvertAudioOptions | undefined | Options object for configuring the conversion process. If not provided, it will uses default options and convert audios to MP3 format. |
extractVideoIdfunction extractVideoId(url: string | URL): string
Extracts the YouTube video ID from given YouTube URL.
The YouTube video ID have exactly 11 characters with allowed symbols are A-Z, a-z, 0-9, _, and -.
Allowed YouTube domains to extract:
www.youtube.comm.youtube.comyoutube.comyoutu.bemusic.youtube.com| Name | Type | Description |
|---|---|---|
url | string | URL | The URL to evaluate. |
A string with 11 characters representing the video ID.
Type: string
validateUrlfunction validateUrl(url: string | URL, withId?: boolean = true): boolean
Validates the given YouTube URL and optionally validates its video ID.
| Name | Type | Description |
|---|---|---|
url | string | URL | The URL to validate. |
withId | boolean | Whether to also validate the video ID within the URL. If false, the function will only validate the URL's domain name. Defaults to true. |
Returns true if the given URL is a valid YouTube URL; otherwise false.
Type: boolean
validateIdfunction validateId(id: string): boolean
| Name | Type | Description |
|---|---|---|
id | string | The video ID to validate. |
Returns true if the given ID correctly represents the YouTube video ID; otherwise false.
Type: boolean
Refer to Wiki's Homepage for information on how to use APIs.
This project utilizes the following libraries and APIs:
ytdl-core - Yet another YouTube downloading module. Written with only Javascript and a node-friendly streaming interface.@distube/ytdl-core - DisTube fork of ytdl-core. This fork is dedicated to fixing bugs and adding features that are not merged into the original repo as soon as possible.fluent-ffmpeg] - A library that fluents ffmpeg command-line usage, easy to use Node.js module.Special thanks to the authors and contributors of these libraries for their valuable work.
Any contributions to this project are welcome :D
This project is licensed under MIT License. For more details, see LICENSE file.
FAQs
A Node.js library offers an easy and uncomplicated method for downloading YouTube audio
The npm package ytmp3-js receives a total of 27 weekly downloads. As such, ytmp3-js popularity was classified as not popular.
We found that ytmp3-js demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ECMAScript 2025 introduces Iterator Helpers, Set methods, JSON modules, and more in its latest spec update approved by Ecma in June 2025.
Security News
A new Node.js homepage button linking to paid support for EOL versions has sparked a heated discussion among contributors and the wider community.
Research
North Korean threat actors linked to the Contagious Interview campaign return with 35 new malicious npm packages using a stealthy multi-stage malware loader.