Home

Welcome to YTMP3-JS' Wiki! 🔭

What is YTMP3-JS?

YTMP3-JS is a Node.js module that provides a simple API to download and convert YouTube videos into MP3 format. It is designed for Linux environments, with special support for Termux on Android, but also works on Windows.

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.

Features

• YouTube to MP3 Conversion: Easily convert YouTube videos to MP3 format.
• Cross-platform: Works on Linux, Windows, macOS, and also Termux (Android).
• Efficient and Fast: Optimized for asynchronous operations.
• Customizable: Supports various configuration options (including global configuration) to fine-tune the download and conversion process.
• FFmpeg Integration: Utilizes FFmpeg for high-quality audio processing.
• Batch Downloads: Support batch download from specified batch file containing a list of YouTube URLs (per line).
• Simple & Flexible: Provides a simple and non-complex Node.js library for programmatic use and flexible command-line interface.

Installation

npm install -g ytmp3-js

Getting Started

YTMP3-JS offers flexible ways to download YouTube videos into audio files and typically will saved them as AAC (Advanced Audio Coding) unless being converted to specified format. Below are examples showing how to use the command-line interface (CLI) and JavaScript APIs for single and batch downloads.

Using Command Line

With the command-line tool, you can download a single YouTube video directly by running:

ytmp3 https://www.youtube.com/watch?v=example -o /home/downloads

Or if you want to download multiple YouTube videos, you can supply more URLs to command line arguments.

ytmp3 <URL1> <URL2> <URL3> -o /home/downloads

These commands will download the YouTube video to AAC format, saving it in the specified output directory.

Note

If there's no arguments specified when using the ytmp3 command, the system will attempt to search the downloads.txt batch file at current directory and start batch downloads with that file. Otherwise, if unable to find the downloads.txt file, an error occurred and the program immediately exits.

For more information about command line options, please refer to Command Line Options page.

---

Using JavaScript APIs (Programmatic)

You can also programmatically download and convert YouTube videos with YTMP3-JS in a Node.js environment.

Single Video Download

To download a single YouTube video:

const ytmp3 = require('ytmp3-js');
// For ESM: import ytmp3 from 'ytmp3-js';

ytmp3.singleDownload('https://www.youtube.com/watch?v=example', { outDir: '/home/downloads' })
  .then((outFile) => console.log('Download complete:', outFile))
  .catch((error) => console.error('An error occurred:', error));

This will download the audio of the specified YouTube video, default convert it to AAC format, and save it in the provided directory.

Batch Download

YTMP3-JS also supports batch downloads, allowing you to process multiple videos at once by reading a file that contains a list of YouTube URLs (one URL per line).

Example of downloads.txt

https://www.youtube.com/watch?v=VIDEO_ID1
https://music.youtube.com/watch?v=VIDEO_ID2
https://youtu.be/VIDEO_ID3

To download multiple videos:

const ytmp3 = require('ytmp3-js');
// For ESM: import ytmp3 from 'ytmp3-js';

const batchFile = 'path/to/downloads.txt';
ytmp3.batchDownload(batchFile, { outDir: '/home/downloads' })
  .then((outFiles) => console.log('Downloads complete:', outFiles))  // Returns a list of output files
  .catch((error) => console.error('An error occurred:', error));

This command processes each URL in the file, downloads, and converts them to AAC format (default), and saving them in the specified output directory.

Note

This function does not download all of them in parallel, which can produce race conditions and connection issues on low bandwidth connections; instead, it retrieves the video information and then downloads it sequentially.

For more information about APIs documentation and usage, please refer to this homepage.

Example API Usages

Download an audio from a single YouTube URL:

const ytmp3 = require('ytmp3-js');
// ESM: import ytmp3 from '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 list of YouTube URLs within a file:

const ytmp3 = require('ytmp3-js');
// ESM: import ytmp3 from 'ytmp3-js';

const batchFile = 'path/to/myurls.txt';

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

---

Download audios from multiple URLs from an array:

CJS

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 ytmp3.singleDownload(url);
    console.log('Downloaded:', outFile);
  }
})();

ESM

import ytmp3 from 'ytmp3-js';

const urls = [
  'https://music.youtube.com/watch?v=abcdefg'
  'https://youtube.com/watch?v=abcd1234'
  // ... and more
];

// 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 ytmp3.singleDownload(url);
  console.log('Downloaded:', outFile);
}

---

Further Reading

• Command-Line Options
• Configuration Setup