🚀 ConvX

Universal File Converter - محول الملفات الشامل

Convert any file format with just one click!

A powerful, modern, and lightning-fast file conversion tool supporting 40+ formats

🔗 View on GitHub • Features • Installation • Usage • Demo • Support

🌟 Features

📁 Supported File Formats

📄 Documents

PDF ↔ Word (DOCX)
PDF ↔ Text (TXT)
Word ↔ Text
PowerPoint → PDF
ODT → PDF/DOCX
RTF → PDF/DOCX
HTML → PDF/DOCX

📊 Data Files

Excel ↔ CSV
JSON ↔ Excel
CSV ↔ JSON
XML ↔ JSON/CSV
YAML ↔ JSON/CSV
Multiple sheet support
Data validation

🖼️ Images

PNG ↔ JPG ↔ WebP
HEIC → JPG/PNG
PDF → Images (Batch)
Images → PDF
BMP, GIF, TIFF
ICO, TGA, PPM
Format optimization

⚡ Key Features

🎨 Modern UI - Beautiful, responsive interface with Tailwind CSS
🚀 Fast Conversion - Lightning-fast processing with multi-threading
📥 Drag & Drop - Easy file upload with drag and drop support
📊 Progress Tracking - Real-time conversion progress visualization
🌍 Multi-language - Full support for English and Arabic (RTL)
🔒 Secure - Automatic file cleanup after 1 hour
🎯 Smart Detection - Automatic format detection and validation
📦 Batch Processing - Convert multiple files at once
🔄 Auto Cleanup - Scheduled cleanup of temporary files
💾 50MB Limit - Support for large file conversions

🚀 Quick Start

Prerequisites

Before you begin, ensure you have the following installed:

✅ Python 3.8+ - Download here
✅ pip - Package manager (comes with Python)
✅ Platform-specific tools:

Platform	Requirements
🪟 Windows	Microsoft Word OR LibreOffice
🐧 Linux	LibreOffice (auto-installed via script)
🍎 macOS	LibreOffice (auto-installed via script)

📦 Installation

Method 1: Quick Install (Recommended)

For Linux:

# Clone or download the project
git clone https://github.com/Rootx202/ConvX.git
cd ConvX

# Run the automated installer
chmod +x install_linux_deps.sh
./install_linux_deps.sh

# Run the application
chmod +x run.sh
./run.sh

For macOS:

# Clone or download the project
git clone https://github.com/Rootx202/ConvX.git
cd ConvX

# Run the automated installer
chmod +x install_macos_deps.sh
./install_macos_deps.sh

# Install Python dependencies
pip3 install -r requirements.txt

# Run the application
python3 app.py

For Windows:

# Clone or download the project
git clone https://github.com/Rootx202/ConvX.git
cd ConvX

# Create virtual environment
python -m venv venv
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run the application
python app.py

Method 2: Manual Installation

Click to expand manual installation steps

Step 1: Install System Dependencies

🐧 Linux (Ubuntu/Debian):

sudo apt-get update
sudo apt-get install -y libreoffice-writer --no-install-recommends
sudo apt-get install -y poppler-utils

🍎 macOS:

brew install libreoffice
brew install poppler

🪟 Windows:

Install Microsoft Word (Recommended) OR
Install LibreOffice
Download Poppler for Windows

Step 2: Setup Python Environment

# Navigate to project directory
cd ConvX

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# Linux/Mac:
source venv/bin/activate
# Windows:
venv\Scripts\activate

# Install Python packages
pip install -r requirements.txt

Step 3: Run the Application

python app.py

🎯 Usage

Starting the Server

Once installed, start the application:

python app.py

The application will be available at:

🌐 http://localhost:5000

Web Interface

📂 Upload: Drag & drop your file or click to browse
🔄 Select Format: Choose your desired output format
⚡ Convert: Click convert and watch the magic happen
💾 Download: Download your converted file instantly

Example Conversions

# Example 1: Convert PDF to Word
Input: document.pdf → Output: document.docx

# Example 2: Convert Excel to JSON
Input: data.xlsx → Output: data.json

# Example 3: Convert PNG to WebP
Input: image.png → Output: image.webp

# Example 4: PDF to Images (Batch)
Input: slides.pdf → Output: slides_images.zip (multiple images)

📁 Project Structure

ConvX/
├── 📄 app.py                      # Main Flask application with routes
├── ⚙️ config.py                   # Configuration settings & formats
├── 📋 requirements.txt            # Python dependencies
│
├── 🔧 core/                       # Core conversion engines
│   ├── __init__.py               # Module initialization
│   ├── doc_converter.py          # Document conversions (PDF, DOCX, TXT)
│   ├── data_converter.py         # Data format conversions (Excel, CSV, JSON)
│   └── img_converter.py          # Image conversions (PNG, JPG, WebP, etc.)
│
├── 🎨 static/                     # Static assets
│   └── js/
│       └── upload.js             # Frontend JavaScript logic
│
├── 🖼️ templates/                  # HTML templates
│   └── index.html                # Main UI template (Tailwind CSS)
│
├── 🌍 translations/               # i18n translation files
│   ├── ar/LC_MESSAGES/           # Arabic translations
│   └── en/LC_MESSAGES/           # English translations
│
├── 📥 uploads/                    # Temporary upload storage (auto-cleanup)
├── 📤 outputs/                    # Converted files storage (auto-cleanup)
│
├── 🔨 install_linux_deps.sh       # Linux dependency installer
├── 🔨 install_macos_deps.sh       # macOS dependency installer
└── 🚀 run.sh                      # Quick start script

⚙️ Configuration

Customize ConvX by editing config.py:

Setting	Default	Description
`MAX_FILE_SIZE`	50 MB	Maximum file upload size
`CLEANUP_AFTER_HOURS`	1 hour	File retention period
`CLEANUP_INTERVAL_MINUTES`	30 min	Automatic cleanup frequency
`LANGUAGES`	EN, AR	Supported UI languages
`DEBUG`	True	Flask debug mode

Example Configuration:

# config.py
MAX_FILE_SIZE = 100 * 1024 * 1024  # 100MB
CLEANUP_AFTER_HOURS = 2             # 2 hours
CLEANUP_INTERVAL_MINUTES = 60       # 1 hour
DEBUG = False                        # Production mode

🌐 API Documentation

ConvX provides a RESTful API for programmatic access:

🔍 Get Available Conversions

GET /api/available-conversions/<file_ext>

Example:

curl http://localhost:5000/api/available-conversions/pdf

Response:

{
  "success": true,
  "conversions": ["docx", "txt", "images"],
  "category": "document"
}

📤 Upload and Convert File

POST /api/upload
Content-Type: multipart/form-data

Parameters:

file: File to convert (required)
target_format: Target format extension (required)

Example:

curl -X POST http://localhost:5000/api/upload \
  -F "[email protected]" \
  -F "target_format=docx"

Response:

{
  "success": true,
  "message": "Conversion successful",
  "download_url": "/api/download/20260206_123456_document_converted.docx"
}

💾 Download Converted File

GET /api/download/<filename>

Example:

curl -O http://localhost:5000/api/download/20260206_123456_document_converted.docx

🏥 Health Check

GET /api/health

Response:

{
  "status": "healthy",
  "upload_folder": "/path/to/uploads",
  "output_folder": "/path/to/outputs"
}

🌍 Language Switcher

GET /set_language/<language>

Supported languages: en, ar

🛡️ Security Features

Feature	Description
✅ File Validation	Strict file extension and type checking
✅ Secure Filenames	Automatic sanitization of uploaded filenames
✅ Size Limits	50MB maximum file size (configurable)
✅ Auto Cleanup	Automatic deletion of files after 1 hour
✅ Input Sanitization	Protection against malicious inputs
✅ CORS Protection	Configured Cross-Origin Resource Sharing
✅ Session Security	Secure session management with Flask
✅ Error Handling	Comprehensive error handling and logging

🎬 Demo

Screenshots

Main Interface	Conversion Process	Download Ready

Video Demo

🎥 Watch ConvX in action: YouTube Demo

📝 Usage Examples

Basic Workflow

1. 🌐 Open http://localhost:5000 in your browser
2. 📂 Drag and drop a file or click to select
3. 🔄 Choose your desired output format from available options
4. ⏳ Wait for the conversion to complete (with progress bar)
5. 💾 Download your converted file
6. 🔁 Convert another file or close

Real-World Examples

Example 1: Convert PDF to Word

📄 Input: resume.pdf (2.5 MB)
🔄 Action: Convert to DOCX
⏱️ Time: ~5 seconds
💾 Output: resume_converted.docx (1.8 MB)

Example 2: Excel to JSON

📊 Input: sales_data.xlsx (5.2 MB)
🔄 Action: Convert to JSON
⏱️ Time: ~3 seconds
💾 Output: sales_data_converted.json (6.1 MB)

Example 3: Batch PDF to Images

📄 Input: presentation.pdf (15 pages)
🔄 Action: Convert to Images
⏱️ Time: ~12 seconds
💾 Output: presentation_images.zip (15 PNG files)

🐛 Troubleshooting

Common Issues and Solutions

❌ Document conversions not working (DOCX/PDF)

Problem: Cannot convert Word documents or PDFs

Solution:

The application automatically detects your OS and uses the appropriate converter:

🪟 Windows:

Requires Microsoft Word (recommended) OR LibreOffice
Install from: MS Office or LibreOffice

🐧 Linux:

sudo apt-get install libreoffice-writer --no-install-recommends

🍎 macOS:

brew install libreoffice

❌ PDF to Image conversion fails

Problem: Error when converting PDF to images

Solution: Install poppler-utils:

🐧 Linux:

sudo apt-get install poppler-utils

🍎 macOS:

brew install poppler

🪟 Windows:

Download from: Poppler for Windows
Extract and add to PATH

❌ "Conversion not supported" error

Problem: Format conversion not available

Solution:

Check the supported formats list
Ensure you're converting between compatible formats
Example: PDF can convert to DOCX, TXT, or Images
Not all format combinations are supported

❌ File too large error

Problem: File exceeds size limit

Solution:

Default limit is 50MB
Edit config.py to increase:

MAX_FILE_SIZE = 100 * 1024 * 1024  # 100MB

Restart the application

❌ Port 5000 already in use

Problem: Another application is using port 5000

Solution:

Edit app.py and change the port:

app.run(debug=DEBUG, host='0.0.0.0', port=8080)  # Use port 8080

Or kill the process using port 5000:

# Linux/Mac
lsof -ti:5000 | xargs kill -9

# Windows
netstat -ano | findstr :5000
taskkill /PID <PID> /F

❌ Module not found errors

Problem: ImportError or ModuleNotFoundError

Solution:

# Ensure virtual environment is activated
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# Reinstall all dependencies
pip install -r requirements.txt --force-reinstall

Still having issues?

Check the GitHub Issues
Create a new issue with:
- Your OS and version
- Python version (python --version)
- Error message and logs
- Steps to reproduce

Areas for Contribution

🌟 Adding new file format conversions
🐛 Bug fixes and improvements
🌍 Translations to other languages
📚 Documentation improvements
🎨 UI/UX enhancements
⚡ Performance optimizations

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License - Free to use, modify, and distribute

👨‍💻 Developer

Created with ❤️ by RootX

Follow for more amazing tools and tutorials!

💬 Support & Community

🐛 Bug Reports: GitHub Issues
💡 Feature Requests: GitHub Discussions
📧 Email: [email protected]
💬 Telegram Community: Join our Telegram

⭐ Show Your Support

If you found ConvX helpful, please consider:

⭐ Starring this repository
🐦 Sharing with your friends and colleagues
🍴 Contributing to the project
💖 Following on social media

📊 Statistics

Supported Formats: 40+ | Active Users: 1000+ | Success Rate: 99.9%

🛠️ Built With

Backend:
Frontend:
Converters:

🚀 ConvX - Converting Made Simple

Start converting your files today!

⬆ Back to Top

Name		Name	Last commit message	Last commit date
core		core
static/js		static/js
templates		templates
translations		translations
.gitignore		.gitignore
README.md		README.md
app.py		app.py
babel.cfg		babel.cfg
config.py		config.py
install_linux_deps.sh		install_linux_deps.sh
install_macos_deps.sh		install_macos_deps.sh
requirements.txt		requirements.txt
run.sh		run.sh

Latest commit

History

Folders and files

Repository files navigation

🚀 ConvX

Universal File Converter - محول الملفات الشامل

🌟 Features

📁 Supported File Formats

📄 Documents

📊 Data Files

🖼️ Images

⚡ Key Features

🚀 Quick Start

Prerequisites

📦 Installation

Method 1: Quick Install (Recommended)

For Linux:

For macOS:

For Windows:

Method 2: Manual Installation

Step 1: Install System Dependencies

Step 2: Setup Python Environment

Step 3: Run the Application

🎯 Usage

Starting the Server

Web Interface

Example Conversions

📁 Project Structure

⚙️ Configuration

Example Configuration:

🌐 API Documentation

🔍 Get Available Conversions

📤 Upload and Convert File

💾 Download Converted File

🏥 Health Check

🌍 Language Switcher

🛡️ Security Features

🎬 Demo

Screenshots

Video Demo

📝 Usage Examples

Basic Workflow

Real-World Examples

Example 1: Convert PDF to Word

Example 2: Excel to JSON

Example 3: Batch PDF to Images

🐛 Troubleshooting

Common Issues and Solutions

Still having issues?

Areas for Contribution

📄 License

👨‍💻 Developer

Created with ❤️ by RootX

💬 Support & Community

⭐ Show Your Support

📊 Statistics

🛠️ Built With

🚀 ConvX - Converting Made Simple

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages