social-video-downloader 0.1.0
Download publicly available videos from Instagram, TikTok, and Facebook
License: MIT
Requires Python: >=3.8
Keywords: instagram, tiktok, facebook, video, downloader, public

# social-video-downloader

A production-ready Python package for downloading publicly available videos from Instagram, TikTok, and Facebook.

## Features

- **Multi-platform support**: Instagram (posts, reels, TV), TikTok, and Facebook
- **Public content only**: Respects platform access controls and Terms of Service
- **Robust error handling**: Clear, actionable error messages
- **Streaming downloads**: Efficient memory usage with chunked downloads
- **Retry logic**: Automatic retry with exponential backoff for network resilience
- **CLI + Python API**: Use from command line or integrate into your code
- **Production-ready**: Fully tested, no placeholders, ready for PyPI

## Legal Notice

**IMPORTANT**: This tool only downloads publicly available content. Users are responsible for:

- Complying with the Terms of Service of each platform
- Respecting copyright and intellectual property rights
- Following applicable laws in their jurisdiction
- Obtaining proper authorization before downloading copyrighted content

Misuse of this tool may violate platform Terms of Service or local laws. The authors assume no liability for misuse.

## Installation

### From PyPI

```bash
pip install social-video-downloader
```

### From source

```bash
git clone https://github.com/yourusername/social-video-downloader.git
cd social-video-downloader
pip install -e .
```

## Quick Start

### Command Line

Download a video using the `svd` command:

```bash
# Download from Instagram
svd https://www.instagram.com/p/ABC123/

# Download from TikTok
svd https://www.tiktok.com/@user/video/123456789

# Download from Facebook
svd https://www.facebook.com/watch/?v=123456789

# Specify output directory
svd https://www.instagram.com/reel/ABC123/ -o ~/videos
```

### Python API

```python
from social_video_downloader import download

# Download a video
output_path = download('https://www.instagram.com/p/ABC123/')
print(f"Video saved to: {output_path}")

# Specify output directory
output_path = download(
    'https://www.tiktok.com/@user/video/123456789',
    output_dir='./downloads'
)
```

## Supported Platforms

### Instagram
- Public posts (photos and videos)
- Public reels
- Public TV videos

**URL formats**:
- `https://www.instagram.com/p/POST_ID/`
- `https://www.instagram.com/reel/REEL_ID/`
- `https://www.instagram.com/tv/TV_ID/`

### TikTok
- Public videos

**URL formats**:
- `https://www.tiktok.com/@username/video/VIDEO_ID`
- `https://www.tiktok.com/video/VIDEO_ID`
- `https://vm.tiktok.com/SHORT_CODE`
- `https://vt.tiktok.com/SHORT_CODE`

### Facebook
- Public videos

**URL formats**:
- `https://www.facebook.com/watch/?v=VIDEO_ID`
- `https://www.facebook.com/username/videos/VIDEO_ID`
- `https://fb.watch/SHORT_CODE/`

## Error Handling

The package provides specific exceptions for different error scenarios:

```python
from social_video_downloader import download
from social_video_downloader.exceptions import (
    InvalidURLError,
    PlatformNotSupportedError,
    AccessDeniedError,
    ExtractionFailedError,
    DownloadFailedError,
)

try:
    output_path = download('https://www.instagram.com/p/ABC123/')
except InvalidURLError:
    print("Invalid URL format")
except PlatformNotSupportedError:
    print("Platform not supported")
except AccessDeniedError:
    print("Video is private or access denied")
except ExtractionFailedError:
    print("Failed to extract video URL")
except DownloadFailedError:
    print("Failed to download video")
```

## CLI Usage

```bash
svd --help
```

Output:
```
usage: svd [-h] [-o OUTPUT_DIR] [-v] url

Download publicly available videos from Instagram, TikTok, and Facebook.

positional arguments:
  url                   URL of the public video to download

optional arguments:
  -h, --help            show this help message and exit
  -o OUTPUT_DIR, --output OUTPUT_DIR
                        Output directory for the downloaded video (default: current directory)
  -v, --version         show program's version number and exit

Examples:
  svd https://www.instagram.com/p/ABC123/
  svd https://www.tiktok.com/@user/video/123456789
  svd https://www.facebook.com/watch/?v=123456789
  svd https://www.instagram.com/reel/ABC123/ -o ~/videos
```

## Architecture

```
src/social_video_downloader/
├── __init__.py          # Main API: download()
├── detector.py          # URL detection and normalization
├── core.py              # Download logic, retries, filesystem operations
├── instagram.py         # Instagram extraction logic
├── tiktok.py            # TikTok extraction logic
├── facebook.py          # Facebook extraction logic
├── exceptions.py        # Custom exception types
└── cli.py               # Command-line interface
```

### Module Responsibilities

- **detector.py**: Identifies platform from URL, normalizes URLs
- **core.py**: HTTP requests with retry logic, streaming downloads, filename generation
- **instagram.py**: Extracts direct video URLs from Instagram public content
- **tiktok.py**: Extracts direct video URLs from TikTok public content
- **facebook.py**: Extracts direct video URLs from Facebook public content
- **exceptions.py**: Custom exception hierarchy for error handling
- **cli.py**: Command-line interface with argparse

## Requirements

- Python >= 3.8
- requests >= 2.28.0

## Development

### Install development dependencies

```bash
pip install -e ".[dev]"
```

### Run tests

```bash
pytest
```

### Run linting

```bash
black src/
flake8 src/
mypy src/
```

## Technical Details

### URL Extraction Strategy

The package uses a multi-layered approach to extract video URLs:

1. **Public API endpoints**: Attempts to fetch JSON data from public endpoints
2. **HTML parsing**: Extracts URLs from HTML meta tags and script content
3. **Fallback patterns**: Uses regex patterns to find video URLs in page content

### Retry Logic

- **Max retries**: 3 attempts
- **Backoff strategy**: Exponential backoff (2^attempt seconds)
- **Timeout**: 15 seconds per request

### Streaming Downloads

- **Chunk size**: 8KB chunks
- **Memory efficient**: Files are not loaded into memory
- **Progress tracking**: Compatible with progress libraries

## Limitations

- Only downloads **publicly available** content
- Requires internet connection
- May be affected by platform rate limiting
- Some platforms may block or restrict access over time

## Contributing

Contributions are welcome! Please ensure:

- Code follows PEP 8 style guidelines
- All functions have docstrings
- No placeholder code or TODO comments
- Code is tested and working

## License

MIT License - See LICENSE file for details

## Disclaimer

This tool is provided as-is for educational and personal use. Users are solely responsible for ensuring their use complies with applicable laws and platform Terms of Service. The authors and contributors assume no liability for misuse or damages resulting from use of this tool.

## Support

For issues, questions, or contributions, please visit:
- **Issues**: https://github.com/yourusername/social-video-downloader/issues
- **Discussions**: https://github.com/yourusername/social-video-downloader/discussions

## Changelog

### Version 1.0.0 (Initial Release)
- Instagram support (posts, reels, TV)
- TikTok support
- Facebook support
- CLI interface
- Python API
- Comprehensive error handling
- Retry logic with exponential backoff