From eea1ae53182c7d60915b2bba42f277c674e46740 Mon Sep 17 00:00:00 2001 From: Jarian Cottingham Date: Wed, 4 Feb 2026 02:53:12 +0000 Subject: [PATCH] Update README with comprehensive project functionalities and documentation --- README.md | 209 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 200 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index a38683f..86ab871 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,20 @@ # YouTube CLI -A command-line interface for browsing and downloading YouTube videos. +A command-line interface for browsing and downloading YouTube videos with advanced features including API support and network sharing capabilities. ## Features -- Search YouTube videos with keyword queries -- Display up to 15 videos at a time with title, author, duration, and type (short/video) -- Download videos using yt-dlp with progress indication -- Configure download locations -- Handle short videos (videos with /shorts/ in URL) with special "(short)" prefix +- **Search YouTube videos** with keyword queries +- **Display up to 15 videos at a time** with title, author, duration, and type (short/video/playlist) +- **Download videos** using yt-dlp with progress indication +- **Configure download locations** with default locations and network share support +- **Handle short videos** (videos with /shorts/ in URL) with special "(short)" prefix +- **REST API support** with OpenAPI specification +- **MCP (Model Context Protocol) compliance** for enhanced integration +- **Playlist support** for downloading entire YouTube playlists +- **Network share copying** - automatically copy downloads to network shares +- **Download archive tracking** - track already downloaded videos +- **Update checking** - automatically check for yt-dlp updates ## Requirements @@ -16,6 +22,7 @@ A command-line interface for browsing and downloading YouTube videos. - yt-dlp - rich - requests +- Flask (for API functionality) ## Installation @@ -53,6 +60,18 @@ youtube-cli --download "https://www.youtube.com/watch?v=xyz123" youtube-cli --help ``` +### Check for yt-dlp Updates + +```bash +youtube-cli --check-update +``` + +### Update yt-dlp + +```bash +youtube-cli --update +``` + ## Configuration The application will create a default configuration file at `~/.config/youtube_cli/config.json` if one doesn't exist. You can customize: @@ -70,7 +89,9 @@ The application will create a default configuration file at `~/.config/youtube_c "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" } ``` @@ -81,11 +102,52 @@ The application will create a default configuration file at `~/.config/youtube_c - Title (short videos marked with "(short)") - Author - Duration - - Type indicator + - Type indicator (Video, Short, Playlist) 3. Choose an option: - `n` for next page of results - `q` to quit - Enter a number to select and download a video + - Enter multiple numbers or ranges (e.g., `1,2,3` or `1-3`) to download multiple videos + - `s` to search for a new term + +## API Endpoints + +The YouTube CLI also provides a REST API with the following endpoints: + +### Search Videos +``` +GET /search?q=QUERY&page=PAGE +``` + +### Download Video +``` +POST /download +Content-Type: application/json + +{ + "url": "https://www.youtube.com/watch?v=xyz123" +} +``` + +### Health Check +``` +GET /health +``` + +### Version Information +``` +GET /version +``` + +### Capabilities +``` +GET /capabilities +``` + +### OpenAPI Specification +``` +GET /openapi.json +``` ## Features @@ -95,6 +157,11 @@ The application will create a default configuration file at `~/.config/youtube_c - **Short Detection**: Automatically detects and marks short videos - **Configuration**: Customizable download locations - **Cross-platform**: Works on macOS and Linux +- **Playlist Support**: Download entire YouTube playlists +- **Network Share Integration**: Copy downloads to network shares automatically +- **Download Archive**: Track already downloaded videos +- **Update Checking**: Automatically check for yt-dlp updates +- **MCP Compliance**: Compatible with Model Context Protocol for enhanced integration ## Dependencies @@ -104,6 +171,27 @@ This tool depends on `yt-dlp` which must be installed separately: pip install yt-dlp ``` +## API Development + +The application includes a Flask-based REST API for programmatic access: + +```bash +# Run the API server +python app.py +``` + +The API will be available at `http://localhost:4096` + +## Docker Support + +The application can be run in Docker: + +```bash +docker-compose up +``` + +This will start the API server on port 4096. + ## Contributing 1. Fork it @@ -114,4 +202,107 @@ pip install yt-dlp ## License -MIT License \ No newline at end of file +MIT License + +## MCP Integration + +This project supports Model Context Protocol (MCP) integration, allowing it to work with AI agents and tools that require MCP-compliant interfaces. The API endpoints provide capabilities that can be used by MCP servers to interact with YouTube content. + +## Network Share Support + +The application supports copying downloaded videos to network shares. Configure the `network_share_path` in your configuration file to enable this feature. + +## Download Archive + +The application maintains an archive of downloaded videos to prevent duplicate downloads. This archive is stored in `~/.config/youtube_cli/downloaded_videos.json`. + +## Advanced Usage + +### Download Multiple Videos +``` +youtube-cli "python tutorial" +# When prompted, enter: 1,2,3 +``` + +### Download Video Range +``` +youtube-cli "python tutorial" +# When prompted, enter: 1-5 +``` + +### Custom Download Locations +``` +youtube-cli --download "https://www.youtube.com/watch?v=xyz123" +# When prompted, enter a network folder name to copy to network share +``` + +### Update Management +``` +youtube-cli --check-update +youtube-cli --update +``` + +## Troubleshooting + +### JavaScript Challenges +If you encounter JavaScript challenge solving errors: +```bash +yt-dlp --remote-components ejs:github +``` + +### Permission Issues +Ensure proper permissions for download directories: +```bash +mkdir -p ~/Downloads/youtube +chmod 755 ~/Downloads/youtube +``` + +### API Issues +If the API server fails to start: +```bash +pip install -r requirements-api.txt +``` + +## Technical Details + +### Core Components +- **youtube_cli/main.py**: Main application logic with search, download, and archive functionality +- **youtube_cli/__main__.py**: Entry point for command-line interface +- **app.py**: REST API implementation with Flask +- **Dockerfile**: Containerization support +- **docker-compose.yml**: Docker orchestration + +### Architecture +The application follows a modular architecture with: +- Command-line interface for direct usage +- REST API for programmatic access +- Configuration management +- Download tracking and archive functionality +- Network share integration +- Update checking capabilities + +### Data Flow +1. User input via CLI or API +2. Search or download request processing +3. yt-dlp integration for video operations +4. Configuration and archive management +5. Network share copying (if configured) +6. Result delivery to user + +## Version History + +### v0.1.0 +- Initial release with core search and download functionality +- Basic configuration support +- API endpoint implementation +- Network share support +- Update checking capabilities + +## Future Enhancements + +- Enhanced playlist management +- Improved error handling and recovery +- More sophisticated download filtering +- Advanced configuration options +- Better integration with AI tools and agents +- Enhanced logging and monitoring \ No newline at end of file