Skip to content

README.md

Latest commit

 

History

History
158 lines (121 loc) · 4.7 KB

README.md

File metadata and controls

158 lines (121 loc) · 4.7 KB

ytviewer

YouTube TUI that pulls subscriptions from YouTube API and plays videos in MPV

ytviewer demo

Overview

ytviewer is a terminal-based YouTube subscription viewer built in Go using the Bubble Tea framework. It allows you to:

  • View the latest videos from your subscribed channels
  • Play videos directly in MPV with optimized settings
  • Navigate your subscriptions with a simple keyboard interface
  • Manage your subscriptions directly through the TUI
  • Filter videos by title or channel name
  • Track watched videos with persistent history
  • Copy video URLs to clipboard

Installation

Prerequisites

  • Go 1.16 or higher
  • MPV media player
  • yt-dlp (for video downloads)
  • YouTube API key

Building from source

# Clone the repository
git clone https://github.com/fabean/ytviewer.git
cd ytviewer

# Build the application
go build -o ytviewer cmd/ytviewer/main.go

# Optional: Install system-wide
go install ./cmd/ytviewer

Configuration

ytviewer requires a configuration file at ~/.config/ytviewer/config.json with the following structure:

{
  "api_key": "YOUR_YOUTUBE_API_KEY",
  "subscriptions": [
    "CHANNEL_ID_1",
    "CHANNEL_ID_2"
  ],
  "max_videos": 10,
  "mpv_options": {
    "max_resolution": "1080",
    "hardware_accel": true,
    "cache_size": "150M",
    "mark_as_watched": true
  },
  "cache_duration": 30
}
  • api_key: Your YouTube API key
  • subscriptions: List of YouTube channel IDs
  • max_videos: Maximum number of videos to fetch per channel
  • mpv_options: Options for the MPV player
    • max_resolution: Maximum video resolution
    • hardware_accel: Enable hardware acceleration
    • cache_size: MPV cache size
    • mark_as_watched: Mark videos as watched after playing
  • cache_duration: How long to cache videos (in minutes)

Getting a YouTube API Key

  1. Go to the Google Cloud Console
  2. Create a new project or select an existing one
  3. Navigate to "APIs & Services" > "Library"
  4. Search for and enable "YouTube Data API v3"
  5. Go to "APIs & Services" > "Credentials"
  6. Click "Create Credentials" > "API Key"
  7. Copy the generated API key to your config file

Finding YouTube Channel IDs

To find a channel ID:

  1. Go to the YouTube channel page
  2. View the page source (right-click > "View Page Source")
  3. Search for "channelId"
  4. The ID will look like "UCuAXFkgsw1L7xaCfnd5JJOw"

Alternatively, use a service like Comment Picker to find channel IDs.

Usage

# Run the application
ytviewer

Keyboard Controls

Main View

  • /: Filter videos (by title or channel name)
  • ↑/↓: Navigate through videos
  • Enter: Play selected video in MPV
  • c: Copy current video URL to clipboard
  • D: Download current video using yt-dlp
  • s: Open subscription management screen
  • r: Reload videos (uses cache if valid)
  • f: Force reload videos (clears cache)
  • q: Quit the application

Subscription Management

  • ↑/↓: Navigate through subscriptions
  • a: Add new subscription by entering a channel ID
  • d: Remove selected subscription
  • b: Return to main video list
  • q: Quit the application

Managing Subscriptions

Press s from the main screen to access the subscription management interface. From there, you can:

  • View all your current subscriptions
  • Add new subscriptions by entering a channel ID
  • Remove existing subscriptions
  • Return to the main video list

Changes to subscriptions are automatically saved to your config file.

Video Reloading and Caching

To minimize API usage and improve performance, ytviewer implements caching:

  • r: Reload videos from cache (if available and not expired)
  • f: Force reload by clearing all caches and fetching fresh data from YouTube API

The cache duration is configurable in your config file using the cache_duration setting (in minutes). The default is 30 minutes.

Features

  • Fetches latest videos from your subscribed channels
  • Displays video titles, channel names, and publish dates
  • Plays videos in MPV with optimized settings
  • Simple, keyboard-driven interface
  • Manage subscriptions directly through the TUI
  • Filter videos by title or channel name
  • Caching to reduce API usage
  • Persistent watch history tracking
  • Copy video URLs to clipboard
  • Download videos using yt-dlp in best quality

Notes

  • The YouTube Data API has quotas (10,000 units per day for free tier)
  • Different API operations consume different amounts of quota
  • The application requires a valid YouTube API key and at least one channel ID in the config file to work
  • Using the cache functionality can help stay within API limits