youtube-cli/docs/TUI.md

YouTube TUI Documentation

A modern, terminal-based user interface for browsing and downloading YouTube videos using Textual and yt-dlp.

Features

• Modern Terminal Interface - Built with Textual for a rich, interactive experience
• Search Videos - Search YouTube with keyword queries and view results in a table
• Download Videos - Download videos directly with progress indication
• Playlist Support - Download entire YouTube playlists
• Pagination - Navigate through search results with keyboard shortcuts
• Category Selection - Choose download locations from configured categories
• Network Share Integration - Automatically copy downloads to network shares
• Download Archive - Track already downloaded videos
• Short Video Detection - Automatically detect and mark short videos
• Keyboard Navigation - Full keyboard control with intuitive shortcuts
• Responsive Design - Works in any terminal size with adaptive layout

Requirements

• Python 3.7+
• Textual (TUI framework)
• yt-dlp
• rich

Installation

From Source

git clone https://github.com/yourusername/youtube-cli.git
cd youtube-cli
pip install -e .[tui,dev]

With pip

pip install youtube-cli[tui]

Using pip with all extras

pip install youtube-cli[all]

This will install:

• Core dependencies (yt-dlp, rich, requests)
• TUI dependencies (textual)
• Development tools (pytest, black, ruff, mypy)

Docker Installation

docker build -t youtube-tui -f docker/Dockerfile.tui .
docker run -it --rm -v ~/Downloads:/root/Downloads youtube-tui

Usage

Basic Usage

youtube-tui

Running with Arguments

youtube-tui "python tutorial"

This will open the TUI and immediately search for "python tutorial".

Keyboard Shortcuts

Global Shortcuts

Key	Action	Description
Ctrl+C	Quit	Exit the application
Ctrl+Q	Quit	Exit the application
F1	Help	Open help screen
Esc	Back	Go back to previous screen
Ctrl+R	Refresh	Refresh current screen

Search Screen

Key	Action	Description
Enter	Search	Execute search with current input
Ctrl+F	Search	Open search from anywhere
Escape	Cancel	Go back to previous screen

Results Screen

Key	Action	Description
Enter	Download	Download selected video
n	Next Page	Go to next page of results
p	Previous Page	Go to previous page of results
q	Quit	Go back to search screen
Escape	Quit	Go back to search screen
Ctrl+R	Refresh	Refresh current results
Ctrl+F	Search	Open search from anywhere

Download Screen

Key	Action	Description
Escape	Cancel	Cancel current download
Ctrl+R	Refresh	Refresh screen

Navigation

Moving Between Screens

1. From Search to Results: Enter a search term and press Enter
2. From Results to Download: Select a video and press Enter
3. From Download to Results: Wait for download to complete or press Escape to cancel
4. From Any Screen to Search: Press Escape or use the navigation menu

Page Navigation

• Next Page: Press n or click the "Next" button
• Previous Page: Press p or click the "Previous" button
• Page Indicator: Shows current page and total pages

Configuration

The TUI reads configuration from the same config file as the CLI:

Location: ~/.config/youtube_cli/config.json

Example Configuration:

{
  "download_dir": "~/Downloads/youtube",
  "default_locations": [
    "~/Downloads/youtube",
    "~/Movies/youtube",
    "/tmp/youtube"
  ],
  "max_videos_per_page": 15,
  "yt_dlp_args": {
    "format": "bestvideo[height=1080]+bestaudio/bestvideo[height<=1080]+bestaudio",
    "write_thumbnail": true,
    "extractor_args": "youtube:player-client=default,-tv_simply"
  },
  "network_share_path": "/Volumes/MediaServer/Youtube/",
  "default_network_subfolder": "General"
}

Configuration Options

Option	Description	Default
download_dir	Default download directory	~/Downloads/youtube
default_locations	List of category folders	["~/Downloads/youtube"]
max_videos_per_page	Number of videos per page	15
yt_dlp_args	Custom yt-dlp arguments	{"format": "bestvideo[height=1080]+bestaudio"}
network_share_path	Network share path	/Volumes/MediaServer/Youtube/
default_network_subfolder	Default network subfolder	General

Screens

Search Screen

The search screen is the main entry point. Enter a search term and press Enter to search YouTube.

Features:

• Search input field with placeholder text
• Search and Cancel buttons
• Status bar showing current screen and mode

Results Screen

Displays search results in a table format with:

• Video Title: Click to select for download
• Author/Channel: Shows the video creator
• Duration: Video length (MM:SS format)
• Type: Video, Short, or Playlist indicator

Table Features:

• Keyboard navigation (arrow keys)
• Selection highlighting
• Auto-truncation of long text
• Short video detection with "(short)" prefix

Download Screen

Shows download progress with:

• Video Title: Current video being downloaded
• Progress Bar: Visual progress indicator
• Status Message: Current download state
• Cancel Button: Cancel ongoing download

States:

• Preparing: Initial setup
• Downloading: Active download in progress
• Complete: Download finished successfully
• Failed: Download encountered an error

Help Screen

Displays help information with:

• Keyboard shortcuts reference
• Configuration options
• Troubleshooting tips
• Version information

Status Bar

The status bar appears at the bottom of each screen and shows:

• Current screen name
• Application version
• yt-dlp version
• Status message
• Current time
• Active theme

Theming

The TUI supports theming through Textual's CSS system. You can customize colors and styles by creating a custom CSS file.

Default Theme

The default theme uses a modern dark color scheme with:

• Dark background colors
• Bright text for readability
• Primary color accents
• Muted colors for secondary elements

Custom Themes

Create a custom theme by editing the TUI's CSS file or using Textual's theme system.

Troubleshooting

Application Won't Start

Issue: ModuleNotFoundError: No module named 'textual'

Solution:

pip install textual

Search Returns No Results

Issue: Search completes but no videos are found

Possible Causes:

1. Network connectivity issues
2. YouTube API restrictions
3. Invalid search term

Solutions:

1. Check internet connection
2. Try a different search term
3. Check yt-dlp installation: yt-dlp --version

Download Fails

Issue: Download starts but fails partway through

Possible Causes:

1. Network interruption
2. Video unavailable
3. Storage space issues

Solutions:

1. Check network connection
2. Verify video URL works in browser
3. Check available disk space

Keyboard Shortcuts Not Working

Issue: Keyboard shortcuts don't respond

Solutions:

1. Ensure terminal supports keyboard events
2. Check for terminal-specific key bindings
3. Try different terminal application

Screen Displays Incorrectly

Issue: Text appears garbled or misaligned

Solutions:

1. Resize terminal window
2. Check terminal encoding (UTF-8 recommended)
3. Update Textual: pip install --upgrade textual

Configuration Changes Not Applied

Issue: Changes to config file don't take effect

Solutions:

1. Restart the application
2. Check config file permissions
3. Verify JSON syntax is valid

Advanced Usage

Download Multiple Videos

1. Search for videos
2. Select multiple videos by navigating and using the download function
3. The TUI will queue downloads sequentially

Download Playlists

1. Search for a playlist URL
2. Select the playlist from results
3. The TUI will download all videos in the playlist

Custom Download Locations

1. Press Ctrl+F to open search from anywhere
2. Search for a video
3. When downloading, select a custom category
4. The video will be saved to that category's folder

API Integration

The TUI can also be used with the REST API:

# Start the API server
python app.py

# Use the API
curl "http://localhost:4096/search?q=python&page=1"

Development

Running Tests

# Run all tests
python test_tui.py

# Run with coverage
pytest --cov=youtube_tui tests/

# Run specific test file
pytest tests/unit/test_models.py

Building the TUI

# Install development dependencies
pip install -e .[dev]

# Run linter
ruff check .

# Format code
black .

# Type checking
mypy .

Directory Structure

youtube_tui/
├── app.py              # Main application class
├── __main__.py         # Entry point
├── models/             # Data models
│   ├── __init__.py
│   └── video.py
├── services/           # Service layer
│   ├── __init__.py
│   └── youtube.py
├── screens/            # Textual screens
│   ├── __init__.py
│   ├── search.py
│   ├── results.py
│   ├── download.py
│   └── help.py
└── widgets/            # Custom widgets
    ├── __init__.py
    ├── status_bar.py
    └── command_palette.py

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (python test_tui.py)
5. Commit your changes (git commit -m 'Add some amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

License

MIT License

Acknowledgments

• Built with Textual - A TUI framework for Python
• Uses yt-dlp for YouTube video handling
• Inspired by Rich for terminal formatting