Add AGENTS.md and install.sh script
This commit is contained in:
parent
a2e8042f27
commit
ff2660e083
297
AGENTS.md
Normal file
297
AGENTS.md
Normal file
@ -0,0 +1,297 @@
|
|||||||
|
# YouTube CLI Agent Guidelines
|
||||||
|
|
||||||
|
## Project Overview
|
||||||
|
|
||||||
|
This is a Python command-line interface (CLI) application for browsing and downloading YouTube videos using yt-dlp. The application provides both CLI and REST API interfaces, with support for search, pagination, playlist downloads, and network share integration.
|
||||||
|
|
||||||
|
## System Requirements
|
||||||
|
|
||||||
|
### Prerequisites (Install via system package manager)
|
||||||
|
|
||||||
|
**macOS (using Homebrew):**
|
||||||
|
```bash
|
||||||
|
# Install Python 3 (includes pip)
|
||||||
|
brew install python
|
||||||
|
|
||||||
|
# Install git
|
||||||
|
brew install git
|
||||||
|
```
|
||||||
|
|
||||||
|
**Ubuntu/Debian (using apt):**
|
||||||
|
```bash
|
||||||
|
# Install Python 3 and pip
|
||||||
|
sudo apt update
|
||||||
|
sudo apt install python3 python3-pip git
|
||||||
|
|
||||||
|
# Optional: Install yt-dlp system-wide
|
||||||
|
sudo apt install yt-dlp
|
||||||
|
```
|
||||||
|
|
||||||
|
**Fedora/RHEL (using dnf/yum):**
|
||||||
|
```bash
|
||||||
|
# Install Python 3 and pip
|
||||||
|
sudo dnf install python3 python3-pip git
|
||||||
|
# or on older systems:
|
||||||
|
sudo yum install python3 python3-pip git
|
||||||
|
|
||||||
|
# Optional: Install yt-dlp system-wide
|
||||||
|
sudo dnf install yt-dlp
|
||||||
|
```
|
||||||
|
|
||||||
|
### Python Dependencies (Install system-wide or in virtual environment)
|
||||||
|
|
||||||
|
**Option 1: System-wide installation (no virtual environment needed)**
|
||||||
|
```bash
|
||||||
|
# Install Python packages system-wide
|
||||||
|
pip3 install --user yt-dlp rich requests flask==2.3.3
|
||||||
|
```
|
||||||
|
|
||||||
|
**Option 2: Virtual environment (recommended for development)**
|
||||||
|
```bash
|
||||||
|
python3 -m venv venv
|
||||||
|
source venv/bin/activate
|
||||||
|
pip install -e .
|
||||||
|
# For API development:
|
||||||
|
pip install -r requirements-api.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
**Option 3: Docker (isolation guaranteed)**
|
||||||
|
```bash
|
||||||
|
docker-compose up --build
|
||||||
|
```
|
||||||
|
|
||||||
|
### Installing yt-dlp
|
||||||
|
|
||||||
|
**Using pip (recommended):**
|
||||||
|
```bash
|
||||||
|
pip3 install --user yt-dlp
|
||||||
|
```
|
||||||
|
|
||||||
|
**Using Homebrew (macOS):**
|
||||||
|
```bash
|
||||||
|
brew install yt-dlp
|
||||||
|
```
|
||||||
|
|
||||||
|
**Using apt (Ubuntu/Debian):**
|
||||||
|
```bash
|
||||||
|
sudo apt install yt-dlp
|
||||||
|
```
|
||||||
|
|
||||||
|
**Note:** The application requires yt-dlp version 2023.12.0 or later for full functionality.
|
||||||
|
|
||||||
|
## Build & Deployment
|
||||||
|
|
||||||
|
### Installation from Source (After installing prerequisites)
|
||||||
|
```bash
|
||||||
|
git clone <repository>
|
||||||
|
cd youtube-cli
|
||||||
|
pip3 install --user -e .
|
||||||
|
```
|
||||||
|
|
||||||
|
### Running the CLI Application
|
||||||
|
```bash
|
||||||
|
# Direct execution
|
||||||
|
youtube-cli "search query"
|
||||||
|
|
||||||
|
# Using module syntax
|
||||||
|
python -m youtube_cli "search query"
|
||||||
|
|
||||||
|
# Using run script
|
||||||
|
./run.sh "search query"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Running the API Server
|
||||||
|
```bash
|
||||||
|
python app.py
|
||||||
|
```
|
||||||
|
The API server runs on port 4096 by default.
|
||||||
|
|
||||||
|
### Docker Deployment
|
||||||
|
```bash
|
||||||
|
docker-compose up --build
|
||||||
|
```
|
||||||
|
|
||||||
|
## Dependencies
|
||||||
|
|
||||||
|
**Core dependencies (requirements.txt):**
|
||||||
|
- yt-dlp - YouTube video downloading
|
||||||
|
- rich - Terminal formatting and UI
|
||||||
|
- requests - HTTP requests for API calls
|
||||||
|
|
||||||
|
**API dependencies (requirements-api.txt):**
|
||||||
|
- Flask==2.3.3 - REST API framework
|
||||||
|
- All core dependencies
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
### Running Tests
|
||||||
|
```bash
|
||||||
|
# Run the API test script
|
||||||
|
python test_api.py
|
||||||
|
|
||||||
|
# Run all tests with pytest (if configured)
|
||||||
|
pytest
|
||||||
|
```
|
||||||
|
|
||||||
|
### Running a Single Test
|
||||||
|
```bash
|
||||||
|
# Execute specific test file
|
||||||
|
python test_api.py
|
||||||
|
|
||||||
|
# For pytest-based tests
|
||||||
|
pytest test_api.py::test_function_name
|
||||||
|
```
|
||||||
|
|
||||||
|
## Code Style Guidelines
|
||||||
|
|
||||||
|
### Python Conventions
|
||||||
|
- **Python version:** 3.6+
|
||||||
|
- **Style:** PEP 8 compliant
|
||||||
|
- **Line length:** 80 characters (strict)
|
||||||
|
- **Imports:** Grouped as: standard library, third-party, local
|
||||||
|
- **Type hints:** Optional but recommended for public APIs
|
||||||
|
|
||||||
|
### Import Organization
|
||||||
|
```python
|
||||||
|
# 1. Standard library imports (alphabetical)
|
||||||
|
import argparse
|
||||||
|
import json
|
||||||
|
import os
|
||||||
|
import subprocess
|
||||||
|
|
||||||
|
# 2. Third-party imports (alphabetical)
|
||||||
|
from rich.console import Console
|
||||||
|
from rich.table import Table
|
||||||
|
|
||||||
|
# 3. Local imports
|
||||||
|
from youtube_cli.main import YouTubeCLI
|
||||||
|
```
|
||||||
|
|
||||||
|
### Naming Conventions
|
||||||
|
- **Classes:** PascalCase (e.g., `YouTubeCLI`, `VideoHandler`)
|
||||||
|
- **Functions/Variables:** snake_case (e.g., `search_videos`, `download_dir`)
|
||||||
|
- **Constants:** UPPERCASE (e.g., `MAX_VIDEOS_PER_PAGE`)
|
||||||
|
- **Private members:** Leading underscore (e.g., `_private_method`)
|
||||||
|
|
||||||
|
### Error Handling
|
||||||
|
- Use try/except blocks for predictable error conditions
|
||||||
|
- Provide user-friendly error messages using Rich color tags
|
||||||
|
- Log detailed errors internally while showing simplified messages to users
|
||||||
|
- Use `console.print()` with colored output for all user-facing messages:
|
||||||
|
- `[red]` for errors
|
||||||
|
- `[green]` for success
|
||||||
|
- `[yellow]` for warnings
|
||||||
|
- `[blue]` for info
|
||||||
|
|
||||||
|
### String Formatting
|
||||||
|
- Use f-strings for dynamic content
|
||||||
|
- Use Rich's inline markup for terminal colors: `[blue]text[/blue]`
|
||||||
|
- Escape special characters in user input to prevent injection
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
### Core Components
|
||||||
|
|
||||||
|
**youtube_cli/main.py**
|
||||||
|
- Contains `YouTubeCLI` class with all main functionality
|
||||||
|
- Handles search, download, and archive operations
|
||||||
|
- Manages configuration and user interaction
|
||||||
|
|
||||||
|
**youtube_cli/__main__.py**
|
||||||
|
- Entry point for CLI execution
|
||||||
|
- Calls `main()` from main.py
|
||||||
|
|
||||||
|
**youtube_cli/__init__.py**
|
||||||
|
- Package initialization
|
||||||
|
- Version information
|
||||||
|
|
||||||
|
**app.py**
|
||||||
|
- Flask-based REST API
|
||||||
|
- Provides JSON endpoints for search and download
|
||||||
|
- Implements MCP (Model Context Protocol) compliance
|
||||||
|
|
||||||
|
### Data Flow
|
||||||
|
1. User input (CLI or API)
|
||||||
|
2. Request processing in `YouTubeCLI` methods
|
||||||
|
3. yt-dlp integration for YouTube operations
|
||||||
|
4. Configuration and archive management
|
||||||
|
5. Result delivery to user
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
**Configuration file location:** `~/.config/youtube_cli/config.json`
|
||||||
|
|
||||||
|
**Key configuration options:**
|
||||||
|
- `download_dir`: Default download directory
|
||||||
|
- `default_locations`: List of category folders for downloads
|
||||||
|
- `max_videos_per_page`: Number of videos to display per page (default: 15)
|
||||||
|
- `yt_dlp_args`: Custom yt-dlp arguments (format, thumbnail, extractor args)
|
||||||
|
- `network_share_path`: Network share path for copying downloads
|
||||||
|
- `default_network_subfolder`: Default subfolder on network share
|
||||||
|
|
||||||
|
### Archive System
|
||||||
|
- Stores downloaded videos in `~/.config/youtube_cli/downloaded_videos.json`
|
||||||
|
- Tracks videos by YouTube video ID
|
||||||
|
- Prevents duplicate downloads
|
||||||
|
- Supports pre-filling from existing downloads
|
||||||
|
|
||||||
|
## API Endpoints
|
||||||
|
|
||||||
|
| Endpoint | Method | Description |
|
||||||
|
|----------|--------|-------------|
|
||||||
|
| `/search` | GET | Search YouTube videos (requires `q` parameter) |
|
||||||
|
| `/download` | POST | Download video by URL (requires `url` field) |
|
||||||
|
| `/health` | GET | Health check endpoint |
|
||||||
|
| `/version` | GET | API version info |
|
||||||
|
| `/capabilities` | GET | MCP capabilities |
|
||||||
|
| `/openapi.json` | GET | OpenAPI specification |
|
||||||
|
|
||||||
|
**API Port:** 4096
|
||||||
|
|
||||||
|
## Special Features
|
||||||
|
|
||||||
|
### Short Video Detection
|
||||||
|
Videos with `/shorts/` in the URL are automatically detected and marked with "(short)" prefix in display.
|
||||||
|
|
||||||
|
### Pagination
|
||||||
|
Search results display 15 videos per page. Users can navigate with 'n' for next page or 's' for new search.
|
||||||
|
|
||||||
|
### Category Selection
|
||||||
|
Downloads require category selection from configured locations. Users can select from predefined categories or create custom folder names.
|
||||||
|
|
||||||
|
### Network Share Integration
|
||||||
|
After download, videos can be automatically copied to configured network shares.
|
||||||
|
|
||||||
|
### yt-dlp Integration
|
||||||
|
- Uses yt-dlp for all YouTube operations
|
||||||
|
- Supports custom format selection (default: 1080p)
|
||||||
|
- Handles JavaScript challenges with remote components
|
||||||
|
- Automatically checks for updates
|
||||||
|
|
||||||
|
## Git Conventions
|
||||||
|
|
||||||
|
- **Branch naming:** feature/branch-name or fix/branch-name
|
||||||
|
- **Commit messages:** Use present tense, imperative mood
|
||||||
|
- **Pull requests:** Include description of changes and testing steps
|
||||||
|
|
||||||
|
## Development Notes
|
||||||
|
|
||||||
|
### Adding New Features
|
||||||
|
1. Follow existing code structure and patterns
|
||||||
|
2. Use Rich for all terminal output
|
||||||
|
3. Implement proper error handling with user-friendly messages
|
||||||
|
4. Update documentation and README as needed
|
||||||
|
5. Test both CLI and API interfaces
|
||||||
|
|
||||||
|
### Common Patterns
|
||||||
|
- Use `Path` objects for file operations
|
||||||
|
- Always validate user input
|
||||||
|
- Provide clear feedback during long operations
|
||||||
|
- Handle timeouts for external commands (yt-dlp, API calls)
|
||||||
|
- Use subprocess with proper timeout values (60s for search, 600s for download, 1200s for playlists)
|
||||||
|
|
||||||
|
### Known Constraints
|
||||||
|
- Search results limited to 15 videos per page
|
||||||
|
- Download timeout: 10 minutes (600 seconds)
|
||||||
|
- Playlist download timeout: 20 minutes (1200 seconds)
|
||||||
|
- Network share path must exist and be writable
|
||||||
18
install.sh
Executable file
18
install.sh
Executable file
@ -0,0 +1,18 @@
|
|||||||
|
#!/bin/bash
|
||||||
|
set -e
|
||||||
|
|
||||||
|
echo "Installing YouTube CLI system-wide..."
|
||||||
|
|
||||||
|
cd "$(dirname "$0")"
|
||||||
|
|
||||||
|
# Install the package system-wide
|
||||||
|
pip3 install --user --break-system-packages -e .
|
||||||
|
|
||||||
|
# Add Python user bin to PATH if not already present
|
||||||
|
if ! grep -q "Library/Python" ~/.zshrc 2>/dev/null; then
|
||||||
|
echo 'export PATH="$HOME/Library/Python/3.14/bin:$PATH"' >> ~/.zshrc
|
||||||
|
echo "Added Python user bin to ~/.zshrc"
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo "YouTube CLI installed successfully!"
|
||||||
|
echo "Run 'source ~/.zshrc' or restart your terminal to use youtube-cli"
|
||||||
Loading…
x
Reference in New Issue
Block a user