YouTube Playlist Tracker

A lightweight tool to monitor YouTube playlists, track video titles, and identify which videos have been removed, set to private, or are otherwise no longer available.

Features

• Dual Providers: Choose between the robust InnerTube (web-based) scraper or the official Google OAuth API.
• Watch Later Support: Track your "Watch Later" list (requires cookies).
• Bulk Scanning: Read a list of playlists from a text file and scan them in sequence.
• Change Detection: Automatically identifies videos that disappeared since the last scan.
• Reporting: Export detailed HTML reports or list unavailable videos in your terminal.
• Local History: Maintains a permanent SQLite database of all videos tracked.

Authentication & Providers

The tracker supports two distinct ways to access YouTube data. Choose the one that fits your needs:

Support Matrix

| Feature | InnerTube (Default) | Official Google API (OAuth2) | | :--- | :---: | :---: | | Public Playlists | ✅ | ✅ | | Unlisted Playlists | ✅ | ✅ | | Your Private Playlists | ❌ No | ✅ | | "Watch Later" (WL) | ✅ (Requires Cookies) | ❌ No | | Setup Complexity | Low (Export Cookies) | High (GCP Project) |

1. InnerTube Provider (Default)

This provider mimics a web browser using the internal YouTube API (via youtubei.js).

• Capabilities: Can access everything a browser can, including Public, Unlisted, Private playlists, and the Watch Later list.
• Watch Later: This is the only provider that supports the WL ID.
• Setup: Export your YouTube cookies in Netscape format (using an extension like "Get cookies.txt LOCALLY") and save them as cookies.txt in the project root.

2. Official Google API (OAuth2)

This provider uses the official YouTube Data API v3.

• Capabilities: Stable access to Public, Unlisted, and Private playlists that you own.
• Watch Later: NOT SUPPORTED. Google officially blocked third-party API access to the Watch Later list in 2016.
• Setup:
  1. Create a project in the Google Cloud Console.
  2. Enable the "YouTube Data API v3" and create OAuth 2.0 Client IDs.
  3. Copy .env.example to .env and populate your credentials.
• Usage: Explicitly enabled by passing the --use-oauth flag.

Configuration

The tracker uses a hierarchical configuration system. It looks for files in the following order:

1. Current Working Directory: Local files (e.g., ./cookies.txt).
2. Global Config Directory: ~/.yt-playlist-tracker/ on Linux/macOS.

Persistent Global Settings

You can store your API credentials globally so they work in any folder. Create a config.json in ~/.yt-playlist-tracker/:

{
  "YOUTUBE_CLIENT_ID": "your-client-id",
  "YOUTUBE_CLIENT_SECRET": "your-client-secret"
}

Supported Files

• playlist.db: The SQLite database (defaults to the global directory if not found locally).
• cookies.txt: YouTube cookies for "Watch Later" support.
• .yt-auth.json: Stored OAuth tokens (generated after the first login).

Installation

Global Installation (Recommended)

Install directly from NPM to use the tool anywhere:

npm install -g yt-playlist-tracker

Once installed, you can use the yt-tracker command.

Local Setup

1. Clone this repository.
2. Install dependencies:

   npm install

3. Copy .env.example to .env and populate your credentials.

Usage

Using the CLI (Global)

If installed globally, use yt-tracker:

# Track a single playlist
yt-tracker --playlist <URL/ID>

# Track multiple playlists from a file
yt-tracker --file playlists.txt --delay 5

# List all unavailable videos recorded in database
yt-tracker --list-unavailable

# Export results to HTML
yt-tracker --export-html report.html

Development usage

If you are running from the source:

npm start -- --playlist <URL/ID>

The tracker is executed via npm start. All arguments must be passed after --.

Command Line Arguments

| Argument | Description | | :--- | :--- | | --playlist <URL/ID> | Scan a single playlist by its URL or ID. | | --file <path> | Scan multiple playlists listed in a text file. | | --cookies <path> | Path to a Netscape cookies file (defaults to cookies.txt). | | --use-oauth | Force the use of the official Google API (requires .env setup). | | --list-unavailable | List all videos currently marked as unavailable in the database. | | --export-html [file]| Generate a styled HTML report of unavailable videos. | | --delay <seconds> | Delay between scans when using a bulk file (prevents rate limiting). |

Examples

Track a single public playlist:

npm start -- --playlist PLQM2lBFqkjfAwtb71rjQ7LglG46S1KvLI

Bulk scan from a file with a 5-second delay:

npm start -- --file playlists.txt --delay 5

Scan a private playlist using official OAuth:

npm start -- --playlist PL... --use-oauth

Generate an HTML report:

npm start -- --export-html report.html

Bulk File Format (playlists.txt)

List playlist URLs or IDs, one per line. Lines starting with # are ignored:

# My Playlists
https://www.youtube.com/playlist?list=PL...
WL # Watch Later
PLQM2lBFqkjfBDo8eoK6Ep8xlt1WSnaKI8