youtube-tui/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

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

### With pip

```bash
pip install youtube-cli[tui]
```

### Using pip with all extras

```bash
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

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

## Usage

### Basic Usage

```bash
youtube-tui
```

### Running with Arguments

```bash
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**:

```json
{
  "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**:
```bash
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:

```bash
# Start the API server
python app.py

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

## Development

### Running Tests

```bash
# 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

```bash
# 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](https://textual.textualize.io/) - A TUI framework for Python
- Uses [yt-dlp](https://github.com/yt-dlp/yt-dlp) for YouTube video handling
- Inspired by [Rich](https://github.com/Textualize/rich) for terminal formatting