Imported from slhad/ytmanager (AGENTS.md). Install upstream with npx skills add slhad/ytmanager. Copyright stays with the author.

AGENTS.md - YouTube Manager (ytmanager)

Project Overview

ytmanager is a TypeScript-based command-line tool for managing YouTube live streams and videos via the YouTube Data API v3. It provides functionality to configure stream metadata, manage playlists, upload YouTube Shorts ("verticals"), set thumbnails, and update video descriptions with timestamps.

Technology Stack

Repository Structure

ytmanager/
├── src/                    # TypeScript source files
│   ├── index.ts            # Main entry point, YouTube API logic
│   ├── cmd.ts              # CLI command definitions using @rushstack/ts-command-line
│   └── persistence.ts      # Stream/vertical history and library management
├── lib/                    # Compiled JavaScript output (generated by tsc)
├── tests/                  # Jest unit tests
│   └── persistence.test.ts # Tests for date/time extraction functions
├── dist/                   # Bundled executable (Windows .exe)
├── scripts/                # Helper scripts (currently empty)
├── .vscode/                # VSCode configuration (launch, settings, tasks)
├── config.json             # OAuth tokens and configuration (gitignored)
├── creds.json              # Google API credentials (gitignored)
├── streamLib.json          # Stream library history (gitignored)
├── videos.json             # Video data cache (gitignored)
├── package.json            # npm configuration and dependencies
├── tsconfig.json           # TypeScript compiler configuration
├── jest.config.js          # Jest test configuration
├── .eslintrc               # ESLint configuration
└── README.md               # Project documentation

Key Source Files

src/index.ts (Main Entry Point)

• Purpose: Main application logic and YouTube API interactions
• Key Functions:
  • getLiveBroadcast() - Fetch current live stream info
  • getVideo() - Fetch video metadata by ID
  • updateVideo() - Update video metadata (title, description, tags, category, language)
  • setTitleStream() - Update live broadcast title
  • setCurrentStream() - Apply multiple settings to current stream
  • setCurrentThumbnail() - Upload video thumbnail with optional auto-compression
  • uploadVerticalsToYoutube() - Upload shorts/verticals to YouTube
  • getPlaylists() / getPlaylistsId() - Manage playlists
  • addVideoInPlaylist() - Add video to playlist
  • askForAuth() - OAuth2 authentication flow using Express server
• OAuth Flow: Uses Google OAuth2Client with Express callback handler

src/cmd.ts (CLI Commands)

• Purpose: Define all CLI commands and parameters using @rushstack/ts-command-line
• Exports: commandLineParser object containing:
  • cmd - Main command line parser
  • flags - Global flags (verbose, pretty, history)
  • actions - All available command actions

src/persistence.ts (Data Persistence)

• Purpose: Manage stream history and vertical metadata
• Key Types:
  • Vertical - YouTube Shorts metadata
  • Stream - Stream metadata with associated verticals
  • StreamLib - Root library structure
• Key Class: StreamLibrary - Load/save stream library, manage verticals
• Key Functions:
  • conversionVideoToStreamInfo() - Convert YouTube API response to Stream type
  • extractAndCompareDateTime() - Parse filename timestamps for vertical synchronization
  • convertStreamToVerticalInfo() - Create vertical metadata from stream

Available CLI Commands

Global Flags

REST API Server

The serve command starts a local REST API server that exposes all CLI functionality via HTTP endpoints.

Starting the Server

# Start with default settings (localhost:3001)
ytmanager serve

# Custom port and host
ytmanager serve --port 8080 --host 0.0.0.0

API Endpoints

Example API Calls

# Get stream info
curl http://localhost:3001/api/stream/info

# Set stream title
curl -X PUT http://localhost:3001/api/stream/title \
  -H "Content-Type: application/json" \
  -d '{"title": "My Stream Title"}'

# Set current stream with multiple options
curl -X PUT http://localhost:3001/api/stream/current \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Stream Title",
    "playlist": ["Gaming", "Live"],
    "tags": ["gaming", "live"],
    "category": "Gaming"
  }'

# Get playlists
curl "http://localhost:3001/api/playlists?name=Gaming"

# Update settings
curl -X PUT http://localhost:3001/api/settings \
  -H "Content-Type: application/json" \
  -d '{"verticalVisibility": "public"}'

Development Commands

# Install dependencies
npm ci

# Build TypeScript to JavaScript
npm run build

# Run tests
npm test

# Run the CLI
npm start
# or directly: node lib/src/index.js <command>

# Generate CLI documentation
npm run doc

# Bundle into Windows executable
npm run bundle

Configuration Files

creds.json (Required)

Google API credentials with OAuth2 client configuration:

{
  "installed": {
    "client_id": "<your-client-id>",
    "client_secret": "<your-client-secret>",
    "redirect_uris": ["http://localhost:3000/callback"]
  }
}

config.json (Auto-generated)

Stores OAuth tokens after authentication:

{
  "code": "<auth-code>",
  "tokens": {
    "access_token": "...",
    "refresh_token": "...",
    "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
    "token_type": "Bearer",
    "expiry_date": 1234567890
  }
}

streamLib.json (Auto-generated)

Stream history and vertical library with settings:

{
  "verticalsOptions": {
    "path": "/path/to/verticals",
    "addLinkToVideo": true,
    "offsetLinkToVideoInSeconds": 0,
    "visibility": "public"
  },
  "pageDock": "",
  "thumbPath": "",
  "watchUrl": "https://www.youtube.com/watch?v=",
  "timestampsPath": "",
  "streams": {}
}

Code Conventions

• No semicolons - ESLint enforces no semicolons at end of statements
• Double quotes - ESLint enforces double quotes for strings
• Strict TypeScript - strict: true in tsconfig.json
• ES2022 target - Uses modern JavaScript features
• CommonJS modules - Output format is CommonJS

Testing

Tests use Jest with ts-jest for TypeScript support. Test files are located in tests/:

• persistence.test.ts - Tests datetime extraction and comparison for vertical file naming

Run tests with:

npm test

OAuth2 Authentication Flow

1. First run triggers OAuth flow via Express server
2. User visits authorization URL in browser
3. Google redirects to callback URL with auth code
4. App exchanges code for tokens and saves to config.json
5. Subsequent runs use stored refresh token

Important Notes for AI Agents

1. Sensitive Files: creds.json, config.json, streamLib.json, and videos.json contain sensitive data and are gitignored. Never commit these files.

2. API Scope: Uses youtube.force-ssl scope for full YouTube Data API access.

3. Thumbnail Limits: YouTube thumbnail size limit is 2MB. The tool supports auto-recompression using imagemin-pngquant.

4. Vertical/Shorts: "Verticals" refer to YouTube Shorts. The tool tracks them in streamLib.json and can batch upload them.

5. Environment Variables: Many CLI parameters support environment variable overrides (see parameter definitions in cmd.ts).

6. Build Output: Compiled JavaScript goes to lib/ directory, matching the binary entry point in package.json.

7. Executable: The bundle script creates a standalone Windows executable using pkg.