youtube-playlist-api

TypeScript helpers for the YouTube Data API v3: OAuth2 (desktop-style loopback), playlist items, video metadata, resumable-style uploads via googleapis, and batch helpers for uploading many video files from a folder.

Runtime: Node.js (uses fs, http, and file streams for uploads).

Features

• OAuth2 with local redirect server; refresh token persisted to a JSON file
• List playlist items (full list or async generator stream)
• Upload videos, update title/description/category, change privacy / "made for kids"
• Safely rename a video when you know the previous title (throws on mismatch)
• Add videos to a playlist, optionally skipping duplicates when you pass existing items
• Batch utilities: scan list-name.txt / list-title.txt pairs and upload + publish + playlist in one flow
• Get your channel's uploads playlist ID

Prerequisites

1. A Google Cloud project with the YouTube Data API v3 enabled.
2. An OAuth 2.0 Client ID (type Desktop app or compatible with http://localhost:<PORT> redirect).
3. Scopes used by this library: youtube and youtube.force-ssl (see src/oauth.ts).

Configuration

Copy .env.example to .env and fill in:

| Variable | Description | | ---------------------------- | ---------------------------------------------------------------------- | | GOOGLE_OAUTH_CLIENT_ID | OAuth client ID | | GOOGLE_OAUTH_CLIENT_SECRET | OAuth client secret | | SERVER_PORT | Optional. Local port for the OAuth redirect (default 8080) | | GOOGLE_OAUTH_TOKEN_FILE | Optional. Path to store tokens (default res/google-oauth-token.json) |

On first API use, the library prints an authorization URL. Open it, sign in, and the code exchanges the code and saves the token file automatically.

Installation

npm install youtube-playlist-api

You can also use pnpm, yarn, or slnpm.

Usage examples

All functions are imported directly from the package root (no sub-path needed):

import {
  getPlaylistItems,
  uploadVideo,
  publishVideo,
  addToPlaylist,
  batchUploadAndPublish,
} from 'youtube-playlist-api'

List every item in a playlist:

import { getPlaylistItems } from 'youtube-playlist-api'

let items = await getPlaylistItems({ playlist_id: 'PLxxxx...' })

Upload, then add to a playlist (pass 'skip' for playlist_items if you do not need duplicate detection):

import { uploadVideo, addToPlaylist } from 'youtube-playlist-api'

let uploaded = await uploadVideo({
  file: '/path/to/video.mp4',
  title: 'My title',
  description: 'Recorded on 2025-01-15 10:30 at Campus, Room 808',
  privacyStatus: 'unlisted',
  selfDeclaredMadeForKids: false, // false allows viewers to bookmark the video
})

await addToPlaylist({
  video_id: uploaded.id,
  playlist_id: 'PLxxxx...',
  playlist_items: 'skip',
})

Publish an existing video (e.g., manually uploaded via web UI):

import { publishVideo } from 'youtube-playlist-api'

await publishVideo({
  video_id: 'xxxxxxxx',
  privacyStatus: 'unlisted',
  selfDeclaredMadeForKids: false, // false allows viewers to bookmark the video
})

Batch folder layout (batch)

scanUploadItems reads parallel lists from a folder:

• list-name.txt — one basename per line
• list-title.txt — matching lines of titles

Files are resolved as <name><ext> (default ext is .mp4, can be customized).

Then use batchUploadAndPublish (see src/batch.ts) with your playlist id, privacy, and optional progress callback.

Main exports (API surface)

api.ts:

• Playlist: getPlaylistItems, streamPlaylistItems, addToPlaylist
• Videos: getVideoInfo, updateVideoInfo, renameVideo, uploadVideo, publishVideo
• Channel: getMyUploadPlaylistId
• Types: VideoInfo, PlaylistItem, Thumbnail, UploadVideoResponse

batch.ts:

• Batch upload: scanUploadItems, batchUploadAndPublish
• Batch publish: batchPublish, scanRenameItems, batchRename
• Types: UploadVideoItem, PublishItem, RenameItem

License

This project is licensed with BSD-2-Clause

This is free, libre, and open-source software. It comes down to four essential freedoms [ref]:

• The freedom to run the program as you wish, for any purpose
• The freedom to study how the program works, and change it so it does your computing as you wish
• The freedom to redistribute copies so you can help others
• The freedom to distribute copies of your modified versions to others