https://github.com/qodesmith/dl-yt-playlist
An app to download all videos in a YouTube playlist, including metadata.
https://github.com/qodesmith/dl-yt-playlist
Last synced: 2 months ago
JSON representation
An app to download all videos in a YouTube playlist, including metadata.
- Host: GitHub
- URL: https://github.com/qodesmith/dl-yt-playlist
- Owner: qodesmith
- Created: 2023-09-17T11:10:52.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2026-01-16T12:39:50.000Z (5 months ago)
- Last Synced: 2026-02-21T17:30:29.367Z (4 months ago)
- Language: TypeScript
- Homepage:
- Size: 288 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Download YouTube Playlist
Download all videos from a YouTube playlist. You can optionally download the audio and thumbnail images as well.
## Prerequisites
You'll need a few things to use this project:
- This project uses [Bun](https://bun.sh/)! Get that installed or feel free to edit the source code to use Node instead (it'll only be a few adjustments).
- You'll need a [YouTube Data API](https://developers.google.com/youtube/v3) key. Set that to the `API_KEY` env variable.
- The [yt-dlp](https://github.com/yt-dlp/yt-dlp) command line tool needs to be present on your system. You can easily install it with a tool like [Brew](https://formulae.brew.sh/formula/yt-dlp).
## Usage
The type signature looks like this:
```typescript
downloadYoutubePlaylist({
/** YouTube playlist id. */
playlistId: string
/**
* YouTube API key. This will be used to fetch all metadata for videos in the
* playlist.
*/
youTubeApiKey: string
/**
* The absolute path to where the data should be stored. Sub-folders will be
* created as needed. The folder structure will be:
*
* - `/metadata.json` - an array of objects (`Video[]`)
* - `/audio` - contains the audio files
* - `/video` - contains the video files
* - `/thumbnails` - contains the jpg thumbnail files
*/
directory: string
/**
* `'none'` - No files will be downloaded, including thumbnails. Only the
* `metadata.json` file will be written.
*
* `'audio'` - Download only audio files as determined by the `audioFormat`
* option. Defaults to `'mp3'`.
*
* `'video'` - Download only video files as determined by the `videoFormat`
* option. Defaults to `'mp4'`
*
* `'both'` - Download audio and video files as determined by their
* corresponding format options.
*/
downloadType: DownloadType
/**
* Optional - default value `'mp3'`
*
* A valid ffmpeg audio [format](https://github.com/yt-dlp/yt-dlp?tab=readme-ov-file#format-selection) string.
*/
audioFormat?: string
/**
* Optional - default value `'mp4'`
*
* A valid ffmpeg video [format](https://github.com/yt-dlp/yt-dlp?tab=readme-ov-file#format-selection) string.
*/
videoFormat?: string
/**
* Optional - default value `false`
*
* A boolean indicating wether to download a `.jpg` thumbnail for each video.
* The highest resolution available will be downloaded. Only thumbnails for
* new videos will be downloaded.
*/
downloadThumbnails?: boolean
/**
* Optional - default value `Infinity`
*
* The maximum duration in seconds a playlist item can be to be downloaded.
*/
maxDurationSeconds?: number
/**
* Optional - default value `undefined`
*
* A _positive_ number (max of 50) indicating how many items in the playlist
* to retrieve, starting with the most recent. Negative and invalid numbers
* will be ignored. All items will be retrieved if no value is provided.
*
* I.e. `mostRecentItemsCount: 20` will only retrieve data for the most recent
* 20 videos in the playlist. This option is useful when running in a cron job
* to avoid fetching and parsing the entire list when you may already have a
* substantial portion processed and downloaded already.
*/
mostRecentItemsCount?: number
/**
* Optional - default value `false`
*
* Boolean indicating wether to silence all internal console.log's.
*/
silent?: boolean
/**
* Optional - deafaults to the system time zone.
*
* String indicating what timezone to use for the logger.
*/
timeZone?: string
/**
* Options - default value `4`
*
* The number of concurrent fetch calls made to the YouTube
* [VideosList API](https://developers.google.com/youtube/v3/docs/videos/list).
*/
maxConcurrentFetchCalls?: number
/**
* Options - default value `10`
*
* The number of concurrent downloads to process. We use
* [Bun's shell](https://bun.sh/docs/runtime/shell) to asychronously execute
* the [yt-dlp](https://github.com/yt-dlp/yt-dlp) command.
*/
maxConcurrentYtdlpCalls?: number
/**
* Optiona - default value `false`
*
* Boolean indicated whether to save the response data directly from the
* YouTube API. This can be helpful for debugging. If set to `true`, two files
* will be saved:
*
* - youtubePlaylistResponses.json
* - youtubeVideoResponses.json
*/
saveRawResponses?: boolean
}): Promise
```
## Folder Structure
Downloads will be organized into the following folder structure:
```
directory-you-provided
/
/video
[].mp4
...
/audio
[].mp3
...
/thumbnails
.jpg
...
metadata.json
youtubePlaylistResponses.json (only if `saveRawResponses` is true)
youtubeVideoResponses.json (only if `saveRawResponses` is true)
```
/video
This folder will contain all the video files (file extension is dependent upon `audioFormat` option).
/audio
This folder will contain all the audio files (file extension is dependent upon `videoFormat` option).
/thumbnails
This folder will contain all the jpg thumbnail files
metadata.json
This file will contain an array of metadata on each video. See shape below
youtubePlaylistResponses.json
This file will contain an array of raw responses from YouTube's PlaylistItems: list api.
youtubeVideoResponses.json
This file will contain an array of raw responses from YouTube's Videos: list api.
## Metadata Shape
Each video will have metadata stored in the `metadata.json` file with the following shape:
```typescript
{
id: string
title: string
description: string
channelId: string
channelName: string
dateCreated: string
dateAddedToPlaylist: string
thumbnailUrl: string | null
durationInSeconds: number
url: string
channelUrl: string | null
audioFileExtension: string | null
videoFileExtension: string | null
/**
* This value will be changed to `true` when future API calls are made and the
* video is found to be unavailable. This will allow us to retain previously
* fetch metadata.
*/
isUnavailable: boolean
}
```