🚀 Big News: Socket Acquires Coana to Bring Reachability Analysis to Every Appsec Team.Learn more
Socket
DemoInstallSign in
Socket

ytmp3-js

Package Overview
Dependencies
Maintainers
0
Versions
6
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

ytmp3-js

A Node.js library offers an easy and uncomplicated method for downloading YouTube audio

1.1.2
latest
Source
npm
Version published
Weekly downloads
10
Maintainers
0
Weekly downloads
 
Created
Source

YTMP3-JS

Buy Me a Coffee at ko-fi.com
LintESLint
Unit TestingUnit Test
Integration TestingIRL Test
Code CoverageCode coverage in codecov.io

NPM License Min. Node NPM Unpacked Size

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 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>]]

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.

singleDownload

async function singleDownload(
  inputUrl: string | URL,
  downloadOptions?: DownloadOptions | Object
): Promise<string>

[See the implementation]

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

NameTypeDescription
inputUrlstring | URLThe URL of the YouTube video to download audio from.
downloadOptionsDownloadOptions | ObjectOptions 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[]>

[See the implementation]

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

NameTypeDescription
inputFilestringThe path to the file containing YouTube URLs.
downloadOptionsDownloadOptions | ObjectOptions 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[]>

[See the implementation]

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

NameTypeDescription
...urlsstring | URLThe 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>

[See the implementation]

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

NameTypeDescription
verboseboolean | undefinedWhether 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>

[See the implementation]

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

NameTypeDescription
inFilestringThe input file path of the audio file to be converted.
optionsConvertAudioOptions | undefinedOptions 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

[See the implementation]

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

NameTypeDescription
urlstring | URLThe 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

[See the implementation]

API Details

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

Parameters

NameTypeDescription
urlstring | URLThe URL to validate.
withIdbooleanWhether 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

[See the implementation]

API Details

Parameters

NameTypeDescription
idstringThe 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 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.

Keywords

javascript

FAQs

Package last updated on 05 Nov 2024

Did you know?

Socket

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.

Install

Related posts