aion-image-downloader/README.md

CLI tool to download images and videos from URLs with advanced features

# Aion - CLI Tool for Image and Video Downloads

A powerful command-line interface tool to download images and videos from URLs with advanced features like resizing, format conversion, batch processing, and YouTube video downloads.

## Features

- **Image Downloads**: Download images from any HTTP/HTTPS URL
- **YouTube Video Downloads**: Download videos from YouTube with quality and format options
- **Image Processing**: Resize, convert formats, and adjust quality
- **Batch Processing**: Download multiple images from URLs or files
- **Smart Filename Generation**: Automatic filename cleaning and generation
- **Progress Tracking**: Real-time download progress for videos
- **Multiple Output Formats**: Support for various image and video formats
- **Directory Management**: Automatic folder creation and organization

## Installation

```bash
# Clone the repository
git clone <repository-url>
cd aion-image-downloader

# Install dependencies
npm install

# Link globally (optional)
npm link
```

## Usage

### Basic Image Download

```bash
# Download a single image
aion get <image_url>

# Download with custom filename
aion get <image_url> --name my_image.jpg

# Download to specific directory
aion get <image_url> --path ./downloads
```

### YouTube Video Download

```bash
# Quick download with default settings
aion -y <youtube_url>

# Using the full command
aion youtube <youtube_url>

# Download with specific quality and format
aion youtube <youtube_url> --quality 720p --format mp4

# Custom output filename and directory
aion youtube <youtube_url> --output my_video --directory ./videos
```

### Image Processing

```bash
# Download and resize
aion get <image_url> --resize 800x600

# Download and convert format
aion get <image_url> --format png

# Download with quality adjustment
aion get <image_url> --quality 80

# Combine multiple options
aion get <image_url> --resize 400x300 --format webp --quality 90
```

### Batch Operations

```bash
# Download multiple images from comma-separated URLs
aion batch "url1,url2,url3"

# Download from a file containing URLs
aion batch urls.txt --file

# Batch download with processing options
aion batch urls.txt --file --resize 800x600 --format jpg
```

### Image Conversion

```bash
# Convert existing image file
aion convert image.jpg --resize 500x500

# Convert format
aion convert image.jpg --format png

# Adjust quality
aion convert image.jpg --quality 85
```

### Utility Commands

```bash
# Get image information without downloading
aion info <image_url>

# List supported websites
aion sites

# Create sample URLs file
aion create-urls

# Clean downloaded images from directory
aion clean ./downloads
```

## Command Reference

### `get` Command
- `--name <filename>`: Custom filename
- `--path <directory>`: Output directory (default: current directory)
- `--timeout <ms>`: Request timeout in milliseconds
- `--info`: Show image information before download
- `--resize <width>x<height>`: Resize image
- `--format <format>`: Convert to specific format (jpg, png, webp, etc.)
- `--quality <1-100>`: JPEG quality setting

### `youtube` Command
- `-q, --quality <quality>`: Video quality (highest, lowest, 720p, 480p, etc.)
- `-f, --format <format>`: Video format (mp4, webm, etc.)
- `-o, --output <filename>`: Output filename (without extension)
- `-d, --directory <dir>`: Output directory (default: ./video)

### `batch` Command
- `--file`: Treat input as a file path instead of comma-separated URLs
- `--resize <width>x<height>`: Apply to all images
- `--format <format>`: Convert all images to format
- `--quality <1-100>`: Set quality for all images

### `convert` Command
- `--resize <width>x<height>`: Resize image
- `--format <format>`: Convert to format
- `--quality <1-100>`: Adjust JPEG quality

### `clean` Command
- `-e, --extensions <exts>`: File extensions to remove (comma-separated)
- `-d, --dry-run`: Show what would be deleted without actually deleting

## Examples

### Download and Process Images

```bash
# Download a landscape photo and resize for mobile
aion get https://images.unsplash.com/photo-1506905925346-21bda4d32df4 \
  --resize 375x667 --format jpg --quality 85

# Batch download and convert to webp
aion batch sample-urls.txt --file --format webp --resize 800x600
```

### YouTube Downloads

```bash
# Download in highest quality
aion -y https://www.youtube.com/watch?v=dQw4w9WgXcQ

# Download specific quality to custom folder
aion youtube https://www.youtube.com/watch?v=dQw4w9WgXcQ \
  --quality 480p --directory ./my_videos --output tutorial
```

### File Management

```bash
# Convert existing images
aion convert photo.jpg --resize 1920x1080 --format png

# Clean up downloaded files
aion clean ./downloads --extensions jpg,png --dry-run
```

## Supported Formats

### Image Formats
- **Input**: JPG, JPEG, PNG, GIF, WebP, BMP, TIFF
- **Output**: JPG, JPEG, PNG, WebP, AVIF

### Video Formats
- **YouTube**: MP4, WebM (depending on available formats)

## File Structure

```
aion-image-downloader/
├── bin/
│   └── aion.js          # Main CLI executable
├── package.json          # Package configuration
├── README.md            # This file
└── QUICK_START.md       # Quick start guide
```

## Error Handling

The tool includes comprehensive error handling for:
- Invalid URLs
- Network timeouts
- File system errors
- Invalid image formats
- YouTube URL validation
- Download failures

## Troubleshooting

### Common Issues

1. **Permission Denied**: Ensure you have write permissions to the target directory
2. **Invalid URL**: Check that the URL is properly formatted and accessible
3. **YouTube Download Fails**: Some videos may have restrictions; try different quality settings
4. **Memory Issues**: Large images may require more memory; use resize option for very large files

### Getting Help

```bash
# Show all commands
aion --help

# Show help for specific command
aion get --help
aion youtube --help
```

## Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

## License

This project is licensed under the MIT License.

## Changelog

### Version 1.0.0
- Initial release with image download functionality
- Image processing and conversion features
- Batch download capabilities
- YouTube video download support
- Comprehensive CLI interface