YTMP3-JS

ESLint
Unit Test
IRL Test

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 (default behavior, can be overriden 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 uses fluent-ffmpeg to convert audio files to the desired codec, specifically MP3. Therefore, it requires the ffmpeg library and its binaries to be installed on your system, along with any necessary encoding libraries such as libmp3lame for MP3 conversion.

However, don't worry if your system does not have ffmpeg installed. 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 .m4a extension.

Features

Download a YouTube single audio or multiple audios and save them to your device with ease and uncomplicated command-line usage.
Support batch download using a file containing a list of YouTube URLs (per line).
Provide a simple and minimal Node.js library for programmatic use.
Easy and automatic conversion of downloaded audio files to specific encoding and format as per your preferences (requires FFmpeg).

Disadvantages

Unable to continue downloading bytes from the last downloaded bytes.
Doesn't support downloading a YouTube playlist.
The lack of APIs makes it difficult to integrate them into complex website or bot projects.

Getting Started

Installation

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

Command Usage

ytmp3 [options] [[URL ...] | [-f <FILE>]]

Example Usage

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.

Options

Download Options

Option Name	Accepts	Description
`--cwd`	`string`	Sets the current working directory to specified directory, used to resolve the `outDir` path. Defaults to the current directory.
`-f` \| `--file` \| `--batch`	`string`	Specifies the path to a file containing a list of YouTube URLs for batch downloading.
`-c` \| `--config`	`string`	Specifies the path to a configuration file containing the `downloadOptions` object to configure both the download options and audio converter options.
`-o` \| `--outDir` \| `--out-dir`	`string`	Specifies the output directory for downloaded files. Defaults to the current directory.
`-C` \| `--convertAudio` \| `--convert-audio`	-	Enables audio conversion behavior (requires FFmpeg).
`-q` \| `--quiet`	-	Suppresses all output messages. Use it twice (`-qq`) to also suppresses the audio conversion progress.

Note

When using the -c or --config option to specify a configuration file, any changes made to specific options on the command line will override the corresponding options in the configuration file. This means that the modified options in the configuration file will be overridden with the values set from the command line.

Audio Converter Options

Option Name	Accepts	Description
`--input-options` \| `--inputOptions` \| `--addInputOptions` \| `--add-input-options` \| `--inOpt`	`string`	Specifies custom FFmpeg input options for audio conversion.
`--output-options` \| `--outputOptions` \| `--addOptions` \| `--add-options` \| `--addOutputOptions` \| `--add-output-options` \| `--outOpt`	`string`	Specifies custom FFmpeg output options for audio conversion.
`--format`	`string`	Converts the audio to the specified format, also used for output file extension.
`--codec` \| `--encoding`	`string`	Specifies the codec for the converted audio.
`--bitrate`	`int` \| `string`	Sets the bitrate for the converted audio in kbps.
`--freq` \| `--frequency`	`int`	Sets the audio sampling frequency for the converted audio in Hertz (Hz).
`--channels`	`int`	Specifies the audio channels for the converted audio.
`--deleteOld` \| `--delete-old` \| `--overwrite`	-	Deletes the old audio file after the audio conversion is done.

Note

All audio converter options above requires the audio conversion behavior to be enabled first -- enable it using -C or --convertAudio option -- otherwise, the specified values from these options will be ignored.

To customize FFmpeg with specific input and output options, use the --input-options and --output-options flags. The options should be enclosed in either single or double quotes, with each option separated by a space. For example:

ytmp3 <YT_URL> -C --output-options '-b:a 320k -ar 28000'

When using any of those input or output options, they will take precedence over other audio conversion options (e.g., --bitrate, --frequency, etc.).

However, you can still specify the output format or file extension using the --format flag in combination with these options. For instance:

ytmp3 <URL> -o ~/Downloads -C --format opus --output-options "-acodec libopus -ar 28000"

Miscellaneous Options

Option Name	Description
`-h` \| `-?` \| `--help`	Displays the help message and exit.
`-V` \| `--version`	Displays the module version and exit. Use it twice (`-VV`) to also display all dependencies' version (not including `devDependencies`).
`--copyright`	Displays the copyright information and exit.
`--print-config`	Displays the configuration options that being used and exit. Very useful for debugging.

APIs

`singleDownload`

async function singleDownload(inputUrl: string | URL): Promise<string>

API Details

Downloads audio from a single YouTube URL and saves it to the output directory (change the output directory with -o or --outDir option).

Parameters

Name	Type	Description
`inputUrl`	`string \| URL`	The URL of the YouTube video to download audio from.

Returns

A promise that resolves a string representating the output file when the download completes.
Type: Promise<string>

`batchDownload`

async function batchDownload(inputFile: string): Promise<string[]>

API Details

Downloads audio from a file containing YouTube URLs and saves them to the output directory (change the output directory with -o or --outDir option).

Parameters

Name	Type	Description
`inputFile`	`string`	The path to the file containing YouTube URLs.

Returns

A promise that resolves to an array of strings representing the successfully downloaded files.
Type: Promise<string[]>

`getVideosInfo`

async function getVideosInfo(
  ...urls: string | URL
): Promise<import('@distube/ytdl-core').videoInfo[]>

API Details

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.

Parameters

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.

Returns

A promise that resolves to an array of video information objects.
Type: Promise<import('@distube/ytdl-core').videoInfo[]>

`checkFfmpeg`

async function checkFfmpeg(verbose?: boolean = false): Promise<boolean>

API Details

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.

Parameters

Name	Type	Description
`verbose`	`boolean \| undefined`	Whether to log verbose messages or not. Defaults to `false`.

Returns

A promise that resolves to a boolean value, true if the ffmpeg binary installed on system; otherwise, false.
Type: boolean

`convertAudio`

async function convertAudio(
  inFile: string,
  options?: ConvertAudioOptions = defaultOptions
): Promise<void>

API Details

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.

Parameters

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.

`extractVideoId`

function extractVideoId(url: string | URL): string

API Details

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.com
m.youtube.com
youtube.com
youtu.be
music.youtube.com

Parameters

Name	Type	Description
`url`	`string \| URL`	The URL to evaluate.

Returns

A string with 11 characters representing the video ID.
Type: string

`validateUrl`

function validateUrl(url: string | URL, withId?: boolean = true): boolean

API Details

Validates the given YouTube URL and optionally validates its video ID.

Parameters

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

Returns true if the given URL is a valid YouTube URL; otherwise false.
Type: boolean

`validateId`

function validateId(id: string): boolean

API Details

Parameters

Name	Type	Description
`id`	`string`	The video ID to validate.

Returns

Returns true if the given ID correctly represents the YouTube video ID; otherwise false.
Type: boolean

API Usage

Download audio from a single YouTube URL:

const ytmp3 = require('ytmp3-js');
const url = 'https://youtu.be/abcdefg'

ytmp3.singleDownload(url)
  .then(outFile => console.log(outFile))
  .catch(err => console.error(err));

Download audios from a bunch of YouTube URLs within a file:

const ytmp3 = require('ytmp3-js');
const batchFile = 'path/to/myurls.txt';

ytmp3.batchDownload(batchFile)
  .then(outFiles => console.log(outFiles))
  .catch(err => console.error(err));

Download multiple URLs from an array:

const ytmp3 = require('ytmp3-js');
const urls = [
  'https://music.youtube.com/watch?v=abcdefg'
  'https://youtube.com/watch?v=abcd1234'
  // ... and more
];

(async () => {
  // Iterate over the array of URL using for-loop
  // Use this iteration to ensure the download processes
  // runs sequentially instead of parallel
  for (const url of urls) {
    const outFile = await singleDownload(url);
    console.log('Downloaded:', outFile);
  }
})();

Acknowledgements

This project utilizes the following libraries and APIs:

(Outdated) 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.

Contribution

Any contributions to this project are welcome :D

License

This project is licensed under MIT License. For more details, see LICENSE file.

Name		Name	Last commit message	Last commit date
Latest commit History 289 Commits
.github		.github
bin		bin
config/example		config/example
lib		lib
test		test
.gitignore		.gitignore
.mocharc.js		.mocharc.js
.nycrc.json		.nycrc.json
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
eslint.config.test.js		eslint.config.test.js
index.js		index.js
jsdoc.config.js		jsdoc.config.js
package-lock.json		package-lock.json
package.json		package.json

License

mitsuki31/ytmp3-js

Folders and files

Latest commit

History

Repository files navigation

YTMP3-JS

Features

Disadvantages

Getting Started

Installation

Command Usage

Example Usage

Options

Download Options

Audio Converter Options

Miscellaneous Options

APIs

singleDownload

Parameters

Returns

batchDownload

Parameters

Returns

getVideosInfo

Parameters

Returns

checkFfmpeg

Parameters

Returns

convertAudio

Parameters

extractVideoId

Parameters

Returns

validateUrl

Parameters

Returns

validateId

Parameters

Returns

API Usage

Acknowledgements

Contribution

License

About

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases 6

Contributors 2

Languages

`singleDownload`

`batchDownload`

`getVideosInfo`

`checkFfmpeg`

`convertAudio`

`extractVideoId`

`validateUrl`

`validateId`