social-media-gif-downloader 1.0.5
A GUI to download videos/GIFs from social media.
Requires Python: >=3.8

# Social Media GIF Downloader

A user-friendly GUI application for downloading videos and GIFs from Twitter/X, Pinterest, and Instagram posts and converting them to GIF format. Built with Python, this tool leverages yt-dlp for media downloading and moviepy for high-quality GIF conversion, ensuring optimal frame rates and seamless performance.

## Features

- **Multi-Platform Support**: Download from Twitter/X, Pinterest, and Instagram (videos only from Instagram)
- **Simple GUI Interface**: Intuitive CustomTkinter-based interface for easy URL input and file saving.
- **User Configuration Persistence**: Automatically saves and restores user settings including:
  - Default save location
  - Preferred output format (GIF or MP4)
  - FPS settings for GIF conversion (1-60 FPS)
- **Automatic FPS Detection**: Analyzes the source video to detect and apply the appropriate frame rate for GIF conversion.
- **High-Quality Conversion**: Uses moviepy and FFmpeg to convert videos to GIFs with preserved quality.
- **GIF Preservation**: Downloads Pinterest GIFs directly without re-encoding when possible.
- **Cross-Platform Compatibility**: Runs on all platforms including Windows, macOS, and Linux with bundled dependencies.
- **Error Handling and Logging**: Comprehensive logging for troubleshooting, especially in bundled executable mode.
- **Background Processing**: Non-blocking downloads and conversions using threading for a responsive UI.
- **Custom Save Locations**: Allows users to choose output filenames and directories via a save dialog.

## Installation

### Option 1: Download Pre-built Executables (Recommended for End Users)

Download the latest release for your platform from the [Releases](https://github.com/ax2bboud/social-media-gif-downloader/releases) page:

- **Windows**: Download `SocialMediaGIFDownloader-Windows-x64.zip`, extract, and run the `.exe` file
- **macOS**: Download `.dmg` or `.zip`, open/extract, and drag to Applications folder
- **Linux**: Download `.AppImage`, make it executable (`chmod +x SocialMediaGIFDownloader-Linux-x86_64.AppImage`), and run

No Python or FFmpeg installation required - all dependencies are bundled!

### Option 2: Install from PyPI

1.  **Install Python**: Ensure you have Python 3.8 or higher installed. You can download it from [python.org](https://www.python.org/).
2.  **Install FFmpeg**: This is required for video processing.
    -   **Windows**: Download from [ffmpeg.org](https://ffmpeg.org/download.html) and add the `bin` directory to your system's PATH.
    -   **macOS**: `brew install ffmpeg`
    -   **Linux**: `sudo apt-get install ffmpeg` (or use your distribution's package manager).
3.  **Install the Application**:
    ```bash
    pip install social-media-gif-downloader
    ```
4.  **Run the Application**:
    ```bash
    social-media-gif-downloader
    ```

## Usage

1. Launch the application.
2. Configure your preferences (optional):
   - Click "Set Default Save Location" to choose a default folder for downloads
   - Select preferred output format from the dropdown (GIF or MP4)
   - Adjust FPS slider for GIF conversion quality (1-60 FPS)
3. Paste a social media post URL into the input field:
   - Twitter/X: `https://x.com/user/status/123456789`
   - Pinterest: `https://www.pinterest.com/pin/123456789/`
   - Instagram: `https://www.instagram.com/p/{post_id}/` or `https://www.instagram.com/reel/{reel_id}/`
4. Click "Download as GIF" or "Download as Video".
5. Choose a save location and filename (defaults to your configured location).
6. The application will download the media and convert it if necessary.
7. Monitor progress via the status messages in the interface.

**Note**: The tool automatically detects the platform from the URL. Pinterest GIFs are downloaded directly when available, while videos from all platforms are converted to GIF format. Instagram support is limited to videos only (posts and reels). Your preferences are automatically saved to `~/.social_media_gif_downloader.json` and will be restored the next time you launch the application.


## Entry Point

This package installs a command-line entry point. After installation, you can run the application from your terminal by simply typing:

```bash
social-media-gif-downloader
```

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## Attributions

This project relies on several open-source dependencies. For detailed information about licenses, copyrights, and attribution requirements for all dependencies used in this project, please refer to the [ATTRIBUTIONS.md](ATTRIBUTIONS.md) file.

## Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a feature branch: `git checkout -b feature/your-feature-name`.
3. Make your changes and commit: `git commit -m 'Add some feature'`.
4. Push to the branch: `git push origin feature/your-feature-name`.
5. Open a Pull Request.

For bug reports or feature requests, please use the issues page.

---

**Disclaimer**: This tool is for personal use only. Respect the terms of service and copyright laws of Twitter/X, Pinterest, and Instagram when downloading content.