Configuration Setup

This page explains how to configure YTMP3-JS for efficient downloads and audio conversion. You can set up configuration options globally or at a user level to suit different environments and use cases. Configuration files can be written in CommonJS (CJS), ECMAScript Module (ESM), or JSON format, offering flexibility in how you structure your settings.

Configuration Fields

Name	Type	Description
downloadOptions	Object	Options for downloading videos and audio conversion.
└─ cwd	string	Sets the current working directory to resolve paths. Optional.
└─ outDir	string	Specifies the output directory for downloaded files. Optional.
└─ convertAudio	boolean	Enables audio conversion behavior. Optional.
└─ converterOptions	Object | false	Options for customizing audio conversion. Optional.
└─ inputOptions	Array<string>	Custom FFmpeg options for input files. Optional.
└─ outputOptions	Array<string>	Custom FFmpeg options for output files. Optional.
└─ format	string	Specifies the output format (e.g., 'mp3', 'ogg'). Optional.
└─ codec	string	Specifies the encoding for output audio conversion. Use command ffmpeg -encoders to see list of supported encoding. Optional.
└─ bitrate	number | string	Sets the output bitrate in kbps (e.g., 192, 192k). Optional.
└─ frequency	number	Specifies the output audio sampling frequency in Hertz (Hz). Optional.
└─ channels	number	Specifies the output audio channels (1 = mono, 2 = stereo). Optional.
└─ deleteOld	boolean	Deletes the old audio file after conversion. Optional.
└─ quiet	boolean	Suppresses all output messages. Optional.
audioConverterOptions	Object	Separate options for audio conversion.
└─ inputOptions	Array<string>	Custom FFmpeg options for input files. Optional.
└─ outputOptions	Array<string>	Custom FFmpeg options for output files. Optional.
└─ format	string	Specifies the output format (e.g., 'mp3', 'ogg'). Optional.
└─ codec	string	Specifies the encoding for output audio conversion. Optional.
└─ bitrate	number | string	Sets the output bitrate in kbps (e.g., 192, 192k). Optional.
└─ frequency	number	Specifies the output audio sampling frequency in Hertz (Hz). Optional.
└─ channels	number	Specifies the output audio channels (1 = mono, 2 = stereo). Optional.
└─ deleteOld	boolean	Deletes the old audio file after conversion. Optional.

Global Configuration Setup

The Global Configuration Setup allows you to define settings that apply across all YTMP3-JS executions on your system. This method is ideal for setting default paths, enabling specific behaviors like audio conversion, and controlling the general environment for the module.

Supported Global Configuration Formats

YTMP3-JS supports configuration files in the following formats, listed in order of priority:

1. ytmp3-js.config.mjs (ESM format – highest priority)
2. ytmp3-js.config.cjs (CommonJS format)
3. ytmp3-js.config.js (JavaScript module format, treated as ESM module by default – lowest priority for JS files)
4. ytmp3-js.json (JSON format – lowest overall priority)

The system will look for these configuration files in the YTMP3-JS' home directory. The first file that exists and not empty among these will be loaded and applied.

Important

The home directory of YTMP3-JS is typically located relative to the user's home directory, specifically in a directory named ".ytmp3-js". This equates to "$HOME/.ytmp3-js" on POSIX systems and "%USERPROFILE%\.ytmp3-js" on Windows.

How to Set Up Global Configuration

Simply create a YTMP3-JS' configuration file in YTMP3-JS' home directory either using CommonJS, EcmaScript Module, or JSON format, back to your preferences.

Here's some examples for each configuration format:

ESM Example (ytmp3-js.config.mjs)

export default {
  downloadOptions: {
    cwd: '/path/to/working/directory',
    outDir: '/path/to/output/directory',
    convertAudio: true,
    quiet: true
  },
  audioConverterOptions: {
    format: 'mp3',
    bitrate: 192,
    channels: 2
  }
};

CommonJS Example (ytmp3-js.config.cjs)

'use strict';
module.exports = {
  cwd: '/path/to/working/directory',
  outDir: '/path/to/output/directory',
  convertAudio: true,
  quiet: true,
  audioConverterOptions: {
    format: 'mp3',
    bitrate: 192,
    channels: 2
  }
};

JSON Example (ytmp3-js.json)

{
  "cwd": "/path/to/working/directory",
  "outDir": "/path/to/output/directory",
  "convertAudio": true,
  "quiet": true,
  "audioConverterOptions": {
    "format": "mp3",
    "bitrate": 192,
    "channels": 2
  }
}

Using Global Configuration

Once the global configuration file is set up, YTMP3-JS will automatically load and apply it unless overridden by user-specific settings or command-line options.

Note

If you're unsure and want to check whether the configuration was correctly configured or not, use --print-config to print the configuration that being used by the execution of ytmp3.

ytmp3 --print-config

User Configuration Setup

The User Configuration Setup allows you to customize settings for individual users or specific projects. Configuration files for user-level setups can also be written in CJS, ESM, or JSON formats, giving flexibility based on the project's or user's preference.

How to Set Up User Configuration

Create a <ANY_NAME>.{config.js|config.mjs|config.cjs|json} file in your preferred directory. In the user configuration file, you can override global settings. See all known configuration fields.

Using User Configuration

To use user-specific configurations, pass the -c or --config option when running the command:

ytmp3 https://www.youtube.com/watch?v=EXAMPLE -c <CONFIG_PATH>

Please change the <CONFIG_PATH> with your actual configuration file path.

This will load the configuration from the file and apply the specified options.

Important Notes

• Any command-line options will override both global and user configurations. This means if you provide an option via the command line, it will take precedence over the configurations.
• You can combine both global and user configurations to create a flexible setup that meets various needs, depending on the environment or task at hand.
• To disable and stopping the system from parsing both global configuration and user-specified configuration file, simply add --no-config to the command. For more details, refer to Command-Line Options page.

---

Related Pages

• Command-Line Options