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