DefaceIT
راهنمای فارسی | Persian Guide
DefaceIT is a cross-platform application for blurring faces and license plates in videos using YOLOv11. The app supports both English and Persian languages and is available for desktop (macOS, Linux, Windows) and Android.
Features
- Easy to use graphical interface
- Fast processing with GPU acceleration support (CUDA, MPS, CPU)
- Accurate detection using YOLOv11-based face and license plate detection
- Audio preservation with automatic audio merging
- Audio pitch shifting with preview functionality
- Cross-platform support (macOS, Linux, Windows, Android)
- Bilingual interface (English and Persian)
- Customizable settings (blur strength, confidence, blur type)
- Native Android app with modern Material Design UI
Requirements
- Python 3.8 or higher
- ffmpeg (for audio preservation)
- macOS:
brew install ffmpeg
- Linux:
sudo apt-get install ffmpeg (Ubuntu/Debian) or sudo yum install ffmpeg (RHEL/CentOS)
- Windows: Download from ffmpeg.org
Installation
macOS / Linux
- Open Terminal
- Navigate to the faceblur_app directory:
cd faceblur_app
- Run the setup script:
chmod +x setup.sh
./setup.sh
- Run the application:
python run.py
The run.py script will automatically:
- Detect your operating system
- Use the virtual environment if available
- Fall back to system Python if needed
- Handle tkinter detection and errors
Windows
- Open Command Prompt or PowerShell
- Navigate to the faceblur_app directory:
cd faceblur_app
- Run the setup script:
setup.bat
- Run the application:
python run.py
The run.py script will automatically:
- Detect your operating system
- Use the virtual environment if available
- Fall back to system Python if needed
- Handle tkinter detection and errors
Docker (Web Interface - Recommended)
The easiest way to run DefaceIT is using Docker with a simple web interface. No need to install Python, dependencies, or deal with GUI complications.
Prerequisites
Quick Start
Clone the repository:
git clone https://github.com/pourmand1376/DefaceIT.git
cd DefaceIT
Start the application:
docker-compose up
Open your browser and go to:
http://localhost:8080
Upload your video, adjust settings, and process!
The web interface provides:
- Drag-and-drop video upload
- All processing settings (blur strength, confidence, device, etc.)
- Real-time progress tracking
- Direct download of processed videos
Using GPU (NVIDIA)
To enable GPU acceleration for faster processing:
Install NVIDIA Container Toolkit
Uncomment the GPU section in docker-compose.yml:
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: all
capabilities: [gpu]
Restart the application:
docker-compose down
docker-compose up
Stopping the Application
docker-compose down
Usage
- Launch the application using the instructions above
- Click "Browse..." next to "Input Video" to select your video file
- Optionally set the output location (auto-generated if not set)
- Adjust settings:
- Blur Strength: Higher values = more blur (21-101)
- Confidence: Lower values = more detections (0.05-0.5)
- Blur Type: Gaussian or Pixelate
- Detect: Choose faces and/or license plates
- Device: Auto-detect, CPU, or GPU
- Audio Pitch Shift: Adjust pitch in semitones (-12 to +12)
- Click "Preview Audio" to test the pitch shift (optional)
- Click "Start Processing"
- Wait for processing to complete
- Your blurred video will be saved with audio preserved
Android App
DefaceIT is also available as a native Android application with a modern Material Design interface.
Download
Download the latest release APK from the Releases page or build it yourself.
Requirements
- Android 7.0 (API level 24) or higher
- Camera permission (optional, for future camera features)
- Storage permission (for reading and saving videos)
Installation
- Download the
DefaceIT-release.apk from the releases page
- Enable "Install from Unknown Sources" in your Android settings
- Open the downloaded APK file
- Follow the installation prompts
Features
- Modern Material Design 3 UI built with Jetpack Compose
- Face detection using Google ML Kit
- Real-time video processing
- Audio pitch shifting support
- Bilingual interface (English and Persian)
- Same powerful blurring capabilities as the desktop version
Building from Source
To build the Android app from source:
- Open the project in Android Studio
- Sync Gradle dependencies
- Build the release APK:
cd DefaceIT
./gradlew assembleRelease
- The APK will be located at
DefaceIT/app/build/outputs/apk/release/
Building Standalone Executable
Using PyInstaller
pip install pyinstaller
pyinstaller --onefile --windowed --name DefaceIT defaceit_gui.py
The executable will be in the dist folder.
Troubleshooting
Tkinter Not Found Error
If you see: ModuleNotFoundError: No module named '_tkinter'
macOS Solutions:
Linux Solutions:
# Ubuntu/Debian
sudo apt-get install python3-tk
# RHEL/CentOS/Fedora
sudo yum install python3-tk
# or
sudo dnf install python3-tk
Windows Solutions:
Tkinter should be included with Python. If not:
- Reinstall Python from python.org
- Make sure "tcl/tk and IDLE" is checked during installation
Virtual Environment Issues
If tkinter doesn't work in your venv:
Option 1: Use system Python directly
python3 defaceit_gui.py
Option 2: Install dependencies globally (not recommended)
pip3 install -r requirements.txt
python3 defaceit_gui.py
Other Common Issues
- No audio in output: Make sure ffmpeg is installed and in your PATH
- Slow processing: Try using GPU acceleration or lower video resolution
- Missing faces: Lower the confidence threshold (try 0.1)
- Too much blur: Reduce blur strength
- App runs but is slow: Make sure GPU acceleration is enabled (select "Auto" or "GPU" in device settings)
- Faces not being detected: Lower the confidence threshold, increase blur strength for better coverage, make sure "Detect Faces" is checked
- librosa not installed: Run
pip install librosa soundfile for audio pitch shifting features
Notes
- First run will download YOLOv11n model (~5.4MB)
- Processing speed depends on your hardware (GPU recommended)
- Audio preservation requires ffmpeg to be installed
- Large videos may take some time to process
Credits
Developer: Shin
Support the Developer
Note: Translation and Readme was generated by Cursor AI
DefaceIT (فارسی)
DefaceIT یک برنامه چند پلتفرمی برای تار کردن چهرهها و پلاکها در ویدیوها با استفاده از YOLOv11 است. این برنامه از زبانهای انگلیسی و فارسی پشتیبانی میکند و برای دسکتاپ (macOS, Linux, Windows) و اندروید در دسترس است.
ویژگیها
- رابط گرافیکی ساده
- پردازش سریع با پشتیبانی از شتاب GPU (CUDA, MPS, CPU)
- تشخیص دقیق با استفاده از YOLOv11
- حفظ صدا با ادغام خودکار صدا
- تغییر زیر و بم صدا با قابلیت پیشنمایش
- پشتیبانی از چند پلتفرم (macOS, Linux, Windows, Android)
- رابط دو زبانه (انگلیسی و فارسی)
- تنظیمات قابل تنظیم
- برنامه اندروید بومی با رابط کاربری Material Design مدرن
نیازمندیها
- Python 3.8 یا بالاتر
- ffmpeg (برای حفظ صدا)
- macOS:
brew install ffmpeg
- Linux:
sudo apt-get install ffmpeg (Ubuntu/Debian) یا sudo yum install ffmpeg (RHEL/CentOS)
- Windows: از ffmpeg.org دانلود کنید
نصب
macOS / Linux
- Terminal را باز کنید
- به پوشه faceblur_app بروید:
cd faceblur_app
- اسکریپت نصب را اجرا کنید:
chmod +x setup.sh
./setup.sh
- برنامه را اجرا کنید:
python run.py
اسکریپت run.py به صورت خودکار:
- سیستم عامل شما را تشخیص میدهد
- در صورت وجود از محیط مجازی استفاده میکند
- در صورت نیاز به Python سیستم بازمیگردد
- تشخیص tkinter و خطاها را مدیریت میکند
Windows
- Command Prompt یا PowerShell را باز کنید
- به پوشه faceblur_app بروید:
cd faceblur_app
- اسکریپت نصب را اجرا کنید:
setup.bat
- برنامه را اجرا کنید:
python run.py
اسکریپت run.py به صورت خودکار:
- سیستم عامل شما را تشخیص میدهد
- در صورت وجود از محیط مجازی استفاده میکند
- در صورت نیاز به Python سیستم بازمیگردد
- تشخیص tkinter و خطاها را مدیریت میکند
Docker (رابط وب - توصیه میشود)
سادهترین راه برای اجرای DefaceIT استفاده از Docker با یک رابط وب ساده است. نیازی به نصب Python، وابستگیها یا مشکلات رابط گرافیکی نیست.
پیشنیازها
شروع سریع
مخزن را کلون کنید:
git clone https://github.com/pourmand1376/DefaceIT.git
cd DefaceIT
برنامه را اجرا کنید:
docker-compose up
مرورگر خود را باز کنید و به آدرس زیر بروید:
http://localhost:8080
ویدیوی خود را آپلود کنید، تنظیمات را تنظیم کنید و پردازش کنید!
رابط وب شامل موارد زیر است:
- آپلود ویدیو با کشیدن و رها کردن
- تمام تنظیمات پردازش (قدرت تار کردن، اعتماد، دستگاه و غیره)
- پیگیری پیشرفت در زمان واقعی
- دانلود مستقیم ویدیوهای پردازش شده
استفاده از GPU (NVIDIA)
برای فعالسازی شتاب GPU برای پردازش سریعتر:
NVIDIA Container Toolkit را نصب کنید
بخش GPU را در docker-compose.yml از حالت توضیح خارج کنید:
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: all
capabilities: [gpu]
برنامه را مجدداً راهاندازی کنید:
docker-compose down
docker-compose up
متوقف کردن برنامه
docker-compose down
استفاده
- برنامه را با دستورالعملهای بالا اجرا کنید
- روی "مرور..." کنار "ویدیوی ورودی" کلیک کنید تا فایل ویدیوی خود را انتخاب کنید
- به صورت اختیاری مکان خروجی را تنظیم کنید (در صورت عدم تنظیم، به صورت خودکار تولید میشود)
- تنظیمات را تنظیم کنید:
- قدرت تار کردن: مقادیر بالاتر = تار بیشتر (21-101)
- اعتماد: مقادیر پایینتر = تشخیص بیشتر (0.05-0.5)
- نوع تار کردن: گاوسی یا پیکسلی
- تشخیص: چهرهها و/یا پلاکها را انتخاب کنید
- دستگاه: خودکار، CPU، یا GPU
- تغییر زیر و بم صدا: زیر و بم را در نیمپرده تنظیم کنید (-12 تا +12)
- روی "پیشنمایش صدا" کلیک کنید تا تغییر زیر و بم را تست کنید (اختیاری)
- روی "شروع پردازش" کلیک کنید
- منتظر بمانید تا پردازش کامل شود
- ویدیوی تار شده شما با صدا حفظ شده ذخیره میشود
برنامه اندروید
DefaceIT همچنین به عنوان یک برنامه اندروید بومی با رابط کاربری Material Design مدرن در دسترس است.
دانلود
آخرین نسخه APK را از صفحه Releases دانلود کنید یا خودتان آن را بسازید.
نیازمندیها
- اندروید 7.0 (سطح API 24) یا بالاتر
- مجوز دوربین (اختیاری، برای ویژگیهای آینده دوربین)
- مجوز ذخیرهسازی (برای خواندن و ذخیره ویدیوها)
نصب
- فایل
DefaceIT-release.apk را از صفحه releases دانلود کنید
- "نصب از منابع ناشناخته" را در تنظیمات اندروید خود فعال کنید
- فایل APK دانلود شده را باز کنید
- دستورالعملهای نصب را دنبال کنید
ویژگیها
- رابط کاربری Material Design 3 مدرن ساخته شده با Jetpack Compose
- تشخیص چهره با استفاده از Google ML Kit
- پردازش ویدیو در زمان واقعی
- پشتیبانی از تغییر زیر و بم صدا
- رابط دو زبانه (انگلیسی و فارسی)
- همان قابلیتهای قدرتمند تار کردن نسخه دسکتاپ
ساخت از منبع
برای ساخت برنامه اندروید از منبع:
- پروژه را در Android Studio باز کنید
- وابستگیهای Gradle را همگامسازی کنید
- APK نسخه release را بسازید:
cd DefaceIT
./gradlew assembleRelease
- فایل APK در مسیر
DefaceIT/app/build/outputs/apk/release/ قرار خواهد گرفت
ساخت فایل اجرایی مستقل
استفاده از PyInstaller
pip install pyinstaller
pyinstaller --onefile --windowed --name DefaceIT defaceit_gui.py
فایل اجرایی در پوشه dist خواهد بود.
عیبیابی
خطای Tkinter پیدا نشد
اگر این خطا را میبینید: ModuleNotFoundError: No module named '_tkinter'
راهحلهای macOS:
راهحلهای Linux:
# Ubuntu/Debian
sudo apt-get install python3-tk
# RHEL/CentOS/Fedora
sudo yum install python3-tk
# یا
sudo dnf install python3-tk
راهحلهای Windows:
Tkinter باید با Python همراه باشد. اگر نیست:
- Python را از python.org دوباره نصب کنید
- مطمئن شوید "tcl/tk and IDLE" در طول نصب انتخاب شده است
مشکلات محیط مجازی
اگر tkinter در venv شما کار نمیکند:
گزینه 1: استفاده مستقیم از Python سیستم
python3 defaceit_gui.py
گزینه 2: نصب وابستگیها به صورت سراسری (توصیه نمیشود)
pip3 install -r requirements.txt
python3 defaceit_gui.py
مشکلات رایج دیگر
- بدون صدا در خروجی: مطمئن شوید ffmpeg نصب شده و در PATH است
- پردازش کند: از شتاب GPU استفاده کنید یا وضوح ویدیو را کاهش دهید
- چهرههای از دست رفته: آستانه اعتماد را کاهش دهید (0.1 را امتحان کنید)
- تار بیش از حد: قدرت تار کردن را کاهش دهید
- برنامه کند اجرا میشود: مطمئن شوید شتاب GPU فعال است (در تنظیمات دستگاه "Auto" یا "GPU" را انتخاب کنید)
- چهرهها تشخیص داده نمیشوند: آستانه اعتماد را کاهش دهید، قدرت تار کردن را برای پوشش بهتر افزایش دهید، مطمئن شوید "تشخیص چهرهها" انتخاب شده است
- librosa نصب نشده: برای ویژگیهای تغییر زیر و بم صدا
pip install librosa soundfile را اجرا کنید
یادداشتها
- اولین اجرا مدل YOLOv11n را دانلود میکند (~5.4MB)
- سرعت پردازش به سختافزار شما بستگی دارد (GPU توصیه میشود)
- حفظ صدا نیاز به نصب ffmpeg دارد
- ویدیوهای بزرگ ممکن است زمان زیادی ببرد
Credits
توسعهدهنده: Shin
حمایت از توسعهدهنده
یادداشت: ترجمه و راهنما توسط Cursor AI تولید شده است