ytmp3-js
v1.1.2
Published
A Node.js library offers an easy and uncomplicated method for downloading YouTube audio
Downloads
76
Maintainers
Readme
YTMP3-JS
| | | |:--|:--| | 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-ffmpeg
to convert audio files to the desired codec, specifically MP3. Therefore, it requires theffmpeg
library and its binaries to be installed on your system, along with any necessary encoding libraries such aslibmp3lame
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>]]
Command Line Options
For command-line options with detailed information, please refer to Command-Line Options wiki's page.
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.
Featured APIs
singleDownload
async 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).
Parameters
| 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. |
Returns
A promise that resolves a string representating the output file when the download completes.
Type: Promise<string>
batchDownload
async 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).
Parameters
| 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. |
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[]>
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>
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>
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
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
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
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
Refer to Wiki's Homepage for information on how to use APIs.
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 ofytdl-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 fluentsffmpeg
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.