Global

Members

(package, constant) STYLE_FMTS

A list contains all supported style formats for styling text.

It extends the builtin color formats from `util.inspect.colors``property.

Since:
  • 2.0.0
Source:

Type Definitions

AllThumbnailsObject

An object containing arrays of author and video thumbnail objects. Typically returned by the getThumbnails function.

Type:
  • Object
Properties:
Name Type Description
author Array.<ThumbnailObject>

An array of author thumbnail objects or an empty array if not available.
video Array.<ThumbnailObject>

An array of video thumbnail objects or an empty array if not available.
Since:
  • 2.0.0
Source:

AudioConverterOptions

Options for configuring the audio conversion.

Type:
  • Object
Properties:
Name Type Attributes Default Description
inputOptions Array.<string> <optional>
 []

The input options for the conversion.
outputOptions Array.<string> <optional>
 []

The output options for the conversion.
format string <optional>
 'mp3'

The desired output format (e.g., 'mp3').
bitrate string | number <optional>
 128

The audio bitrate (e.g., '128k'), it may be a number or a string with an optional k suffix.
frequency number <optional>
 44100

The audio sampling frequency in Hz.
codec string <optional>
 'libmp3lame'

The audio codec to use (e.g., 'libmp3lame').
channels number <optional>
 2

The number of audio channels (2 for stereo).
deleteOld boolean <optional>
 false

Whether to delete the original file after conversion.
quiet boolean <optional>
 false

Whether to suppress the conversion progress and error message or not.
Since:
  • 1.0.0
Source:
See:

AuthorInfo

Represents the extracted and normalized author information.

Type:
  • object
Properties:
Name Type Attributes Description
name string

The normalized author name.
id string

The author's unique ID.
userUrl string

The author's user profile URL.
channelUrl string

The author's channel URL.
externalChannelUrl string <optional>

The external URL linking to the author's channel.
username string <optional>

The author's YouTube username.
thumbnails Array.<ThumbnailObject> <optional>

An array of thumbnail objects representing the author's profile images.
verified boolean

Whether the author is a verified YouTube user.
subscriberCount number <optional>

The number of subscribers the author has.
Since:
  • 2.0.0
Source:

BatchDownloadOptions

An object to configure the batch download process, including the getting of video information, and audio conversion. This interface extends to DownloadOptions and ytdl.downloadOptions.

The batch download is known to have different processor which makes it have a custom default download handler, see defaultBatchHandler.

Type:
Properties:
Name Type Attributes Default Description
encoding string <optional>
 'utf-8'

The encoding to use for reading the batch file contents.
includeID boolean <optional>

Whether to include and parse any string representing a YouTube video ID when processing batch file.
Since:
  • 2.0.0
Source:

BatchDownloadResult

The download result object returned by the batchDownload function.

Type:
  • Object
Properties:
Name Type Description
results Record.<string, DownloadResult>

A mapping of video IDs to their download results.
results[videoId].errors Array.<Error>

All errors that occurred during the download process for each video ID, or null if there are no errors.
Since:
  • 2.0.0
Source:
See:

DLHandlerData

This interface represents a handler data object that shared to download handler function during download process.

Type:
  • Object
Properties:
Name Type Attributes Description
videoInfo ytdl.videoInfo

The information about the video.
videoFormat ytdl.videoFormat

The format information of the video.
outStream fs.WriteStream

The output stream for the video.
range object <optional>

The range information of the video.

Properties
Name Type Description
start number

The start byte of the range.
end number

The end byte of the range.
title string | null

The title of the video.
authorName string

The name of the author.
videoUrl string

The URL of the video.
videoId string

The ID of the video.
channelId string

The ID of the channel.
duration string

The duration of the video.
viewers number | null

The view count of the video.
subscribers number | null

The subscriber count of the author's channel.
Since:
  • 2.0.0
Source:

DownloadOptions

An object to configure the download process, including the getting of video information, and audio conversion. It extends the ytdl.downloadOptions interface from the @distube/ytdl-core module, this way you can pass any option of the ytdl.downloadOptions object.

Type:
  • ytdl.downloadOptions
Properties:
Name Type Attributes Default Description
cwd string <optional>
 '.'

The current working directory. If not specified, defaults to the current directory. Used to resolve relative paths for outDir.
outDir string <optional>
 '.'

The output directory where downloaded files will be saved. If not specified, defaults to the current directory.
outFile string <optional>

The output file name for the downloaded audio. If not specified, defaults to the sanitized title of the video.
convertAudio boolean <optional>
 false

Whether to enable audio conversion behavior. Defaults to false.
converterOptions AudioConverterOptions <optional>

The options for audio conversion (requires convertAudio). If not specified, defaults to AudioConverterOptions.
quiet boolean | 'all' <optional>
 true

Whether to suppress all log messages. If set to 'all', the audio conversion process will also run silently, default is true.
handler function <optional>

An asynchronous function to handle and customize the download process. If not specified, defaults to defaultHandler.
format ytdl.videoFormat <optional>

The audio format to download. If not specified, defaults to the best audio format.
useCache boolean <optional>
 true

Whether to enable caching video information during the download process. Defaults to true.
Since:
  • 1.0.0
Source:

DownloadResult

The download result object returned by the download function.

Type:
  • Object
Properties:
Name Type Description
path string

The full path to the downloaded audio file.
outputFile string

Alias for path. Refers to the downloaded audio file.
url string

The URL of the video.
cache object
Properties
Name Type Description
useCache boolean

Whether the cache is used or not.
id string | null

The unique ID of the cache, or null if no cache is used.
path string | null

The full path to the cache file, or null if no cache is used.
metadata object

The metadata information of the video.

Properties
Name Type Description
title string

The title of the video.
description string | null

The description of the video.
publishDate string | null

The publish date of the video.
authorUrl string

The URL of the video's author.
authorName string

The name of the video's author.
videoId string

The ID of the video.
channelId string

The ID of the channel that uploaded the video.
duration number

The duration of the video in seconds.
viewers number | null

The view count of the video.
subscribers number | null

The subscriber count of the author's channel.
keywords Array.<string>

The keywords of the video.
thumbnails object

The thumbnails information of the video.

Properties
Name Type Description
author Array.<ThumbnailObject>

The thumbnails of the video's author.
video Array.<ThumbnailObject>

The thumbnails of the video.
conversionResult ConversionResult | null

The audio conversion result object.
Since:
  • 2.0.0
Source:

ExtractedVideoInfoCacheObject

Type:
  • Object
Properties:
Name Type Description
id string

The ID of the video.
title string

The title of the video or '<unknown>' if not available.
authorName string

The name of the author of the video or '<unknown>' if not available.
videoUrl string

The URL of the video.
authorUrl string

The URL of the author of the video (refers to author profile).
videoInfo ytdl.videoInfo

The extracted and unsealed video information object.
Since:
  • 2.0.0
Source:

ParsedYTFormatObject

Type:
Properties:
Name Type Attributes Description
mimeType MIMEType

MIMEType instance representing the media type.
initRange Object <nullable>

Byte range for the initialization segment.

Properties
Name Type Description
start number

Parsed integer value of start byte of the initialization range.
end number

Parsed integer value of end byte of the initialization range.
indexRange Object <nullable>

Byte range for the index segment.

Properties
Name Type Description
start number

Parsed integer value of start byte of the index range.
end number

Parsed integer value of end byte of the index range.
lastModified module:utils/info-utils~DateFormatter <nullable>

A DateFormatter instance created from the lastModified timestamp, or null.
contentLength number <nullable>

Parsed integer value of the content length.
approxDurationMs number <nullable>

Parsed integer value of the approximate duration in milliseconds.
audioSampleRate number <nullable>

Parsed integer value of the audio sample rate.
Since:
  • 2.0.0
Source:

ThumbnailObject

Type:
  • Object
Properties:
Name Type Description
url string

The URL of the thumbnail image.
width number

The width of the thumbnail image in pixels.
height number

The height of the thumbnail image in pixels.
Since:
  • 2.0.0
Source:

VideoInfoCacheObject

Type:
  • Object
Properties:
Name Type Description
id string

The ID of the video.
title string

The title of the video or '<unknown>' if not available.
authorName string

The name of the author of the video or '<unknown>' if not available.
videoUrl string

The URL of the video.
authorUrl string

The URL of the author of the video (refers to author profile).
videoInfo Object

The sealed video information object.

Properties
Name Type Description
type 'zlib/bin'

The type of the video information.
data string

The compressed and binary encoded video information data.
Since:
  • 2.0.0
Source:

YTFormatObject

Type:
  • Object
Properties:
Name Type Attributes Description
mimeType string

The MIME type of the format, e.g., 'audio/mp4; codecs="mp4a.40.2"'.
qualityLabel string <nullable>

The video quality label (e.g., '720p'), or null for audio-only formats.
bitrate number <nullable>

The average bitrate in bits per second (bps).
audioBitrate number <nullable>

The audio bitrate in kilo bits per second (kbps), or null for video-only formats.
itag number

The format's unique identifier.
url string

The direct URL for downloading the format.
initRange Object <nullable>

Byte range for the initialization segment.

Properties
Name Type Description
start string

Start byte of the initialization range.
end string

End byte of the initialization range.
indexRange Object <nullable>

Byte range for the index segment.

Properties
Name Type Description
start string

Start byte of the index range.
end string

End byte of the index range.
lastModified string <nullable>

The timestamp of the last modification in microseconds since the UNIX epoch.
contentLength string <nullable>

The total length of the content in bytes, or null if unknown.
quality string <nullable>

The quality string, e.g., 'tiny'.
projectionType string <nullable>

The type of video projection, e.g., 'RECTANGULAR', or null.
averageBitrate number <nullable>

The average bitrate in bits per second (bps), or null if unknown.
highReplication boolean <nullable>

Indicates if the format uses high replication for streaming.
audioQuality string <nullable>

The audio quality label, e.g., 'AUDIO_QUALITY_MEDIUM', or null for video-only formats.
approxDurationMs string

The approximate duration of the format in milliseconds as a string.
audioSampleRate string <nullable>

The audio sample rate in Hertz as a string (e.g., '44100'), or null.
audioChannels number <nullable>

The number of audio channels, or null if unknown.
loudnessDb number <nullable>

The loudness level in decibels, or null if unavailable.
hasVideo boolean

Indicates whether the format includes a video track.
hasAudio boolean

Indicates whether the format includes an audio track.
container string

The container format, e.g., 'mp4'.
codecs string

The combined codecs for audio and video or only one of them, e.g., 'mp4a.40.2'.
videoCodec string <nullable>

The video codec, or null for audio-only formats.
audioCodec string <nullable>

The audio codec, or null for video-only formats.
isLive boolean

Indicates if the format is part of a live stream.
isHLS boolean

Indicates if the format is in HLS (HTTP Live Streaming) format.
isDashMPD boolean

Indicates if the format is in DASH (Dynamic Adaptive Streaming over HTTP) format.
Since:
  • 2.0.0
Source:

YTMP3Config

A typedef representating the configuration object containing options to configure the both download and audio conversion process.

Type:
  • Object
Properties:
Name Type Attributes Description
downloadOptions DownloadOptions

Options related to the download process.
audioConverterOptions ConvertAudioOptions <optional>

Options related to the audio conversion process, if not defined in downloadOptions. This field will be ignored if the downloadOptions.converterOptions property are defined and not contains a nullable value.
Since:
  • 1.0.0
Source: