Cross-platform OCR, PDF text extractor and speech-to-text tool in Python (CLI + Kivy GUI, Persian supported).
📖 آموزش قدم‌به‌قدم استفاده (موبایل + ویندوز + لینوکس + مک) · 🌐 نسخه وب بدون نصب (مخصوص کاربران عادی)
ابزار چندسکویی پایتون برای استخراج متن از عکس و PDF و تبدیل گفتار به نوشتار؛ با رابط خط فرمان و رابط گرافیکی Kivy و پشتیبانی از زبان فارسی.
📘 OCR‑STT Tool
ابزار چندسکویی برای استخراج متن از تصویر، PDF و تبدیل گفتار به نوشتار
یک ابزار پایتونی چندسکویی (Cross‑Platform) که قابلیت‌های زیر را در یک پروژه واحد ارائه می‌دهد:
- استخراج متن از تصویر (OCR)
- استخراج متن از PDF
- تبدیل گفتار به نوشتار (Speech‑to‑Text)
- رابط CLI برای استفادهٔ سریع
- رابط GUI با Kivy برای اجرا روی Windows / macOS / Linux / Android / iOS
این پروژه کاملاً اوپن‌سورس است و برای توسعه‌دهندگان، پژوهشگران، دانشجویان و کاربران عمومی طراحی شده است.
⭐ لطفاً از پروژه حمایت کنید اگر این ابزار برای شما مفید بود، لطفاً با زدن دکمهٔ Star ⭐ از پروژه حمایت کنید. این کار باعث می‌شود پروژه دیده شود و توسعهٔ آن ادامه پیدا کند.
📢 کانال رسمی تلگرام برای دریافت آخرین آپدیت‌ها، نسخه‌های جدید، آموزش‌ها و ابزارهای مرتبط: کانال رسمی: @a_c_official
✨ ویژگی‌ها
- پشتیبانی از تصویر، PDF، فایل صوتی
- پشتیبانی از زبان‌های مختلف (fa‑IR، en‑US و …)
- اجرای مستقیم روی:
- Windows
- macOS
- Linux
- Android (با Buildozer، با محدودیت OCR — بخش موبایل را ببینید)
- iOS (با Xcode + Kivy-iOS، با محدودیت OCR)
- طراحی ماژولار و قابل توسعه
- مدیریت خطای مناسب (پیام واضح به‌جای Traceback خام)
📖 آموزش قدم‌به‌قدم
اگر تازه شروع کرده‌ای، صفحه آموزش تعاملی را باز کن — بخش موبایل (اندروید/آیفون) و دسکتاپ (ویندوز/لینوکس/مک) کاملاً تفکیک شده‌اند:
📖 ورود به صفحه آموزش · مشاهده فایل آموزش در ریپو
🌐 نسخه وب بدون نصب (برای کاربران عادی)
اگر حوصله خط فرمان و نصب نداری: فایل docs/web-ocr.html را دانلود کن و در مرورگر گوشی یا کامپیوتر باز کن.
عکس یا PDF را انتخاب می‌کنی و متن فارسی/انگلیسی را در کادر پایین تحویل می‌گیری — بدون نصب هیچ‌چیز، پردازش داخل خود دستگاه:
🌐 اجرای نسخه وب · دانلود فایل نسخه وب از ریپو
دفعه اول به اینترنت نیاز است تا موتور و داده زبان دانلود شود؛ فایل تو هیچ‌جا آپلود نمی‌شود. در هر اجرا حداکثر ۱۰ صفحه خوانده می‌شود — بازه صفحه (مثلاً ۱ تا ۱۰، ۱۱ تا ۲۰) را خودت بگذار.
📁 ساختار پروژه
ocr-stt-tool/
├─ app/
│ ├─ core/
│ │ ├─ __init__.py
│ │ ├─ models.py
│ │ ├─ image_ocr.py
│ │ ├─ pdf_ocr.py
│ │ ├─ speech_to_text.py
│ │ ├─ whisper_stt.py
│ │ └─ fa_normalize.py
│ ├─ __init__.py
│ ├─ __main__.py
│ ├─ cli.py
│ └─ gui_kivy.py
├─ examples/
│ ├─ sample.png
│ ├─ sample.pdf
│ └─ sample.wav
├─ tests/
│ ├─ test_smoke.py
│ └─ test_golden.py
├─ docs/
│ ├─ tutorial.html
│ └─ web-ocr.html
├─ requirements.txt
├─ requirements-gui.txt
├─ requirements-optional.txt
├─ pyproject.toml
├─ buildozer.spec
├─ Dockerfile
├─ CHANGELOG.md
├─ README.md
└─ LICENSE
🔧 نصب و راه‌اندازی
نسخه پایتون مهم است: همه قابلیت‌ها (OCR، گفتار گوگل، whisper) فقط روی پایتون 3.10 تا 3.12 کار می‌کنند. روی 3.13+ نصب انجام می‌شود ولی فقط استخراج متن PDF کار می‌کند. ویندوز: از python.org نسخه 3.12 را نصب کن و با
py -3.12اجرا کن (می‌تواند کنار نسخه فعلی باشد).
کدام فایل نیازمندی برای چیست؟
| File | EN | FA |
|---|---|---|
requirements.txt |
CLI + core: image OCR, PDF text extraction, Google STT — no GUI, no heavy ML | هسته و CLI: OCR عکس، استخراج متن PDF، گفتار گوگل — بدون GUI و بدون مدل سنگین |
requirements-gui.txt |
Desktop GUI only (Kivy) — CLI works without it | فقط رابط گرافیکی دسکتاپ (Kivy) — CLI بدون آن کار می‌کند |
requirements-optional.txt |
Optional extras — mic input, MP3 convert, scanned-PDF OCR, offline Whisper STT, Persian normalize; install only what you need | موارد اختیاری — ورودی میکروفون، تبدیل MP3، OCR اسکن-PDF، STT آفلاین Whisper، نرمالایز فارسی؛ فقط همان را نصب کن که لازم داری |
- نصب وابستگی‌ها (CLI و هسته — بدون GUI)
pip install -r requirements.txt
# ویندوز با چند نسخه پایتون: py -3.12 -m pip install -r requirements.txtGUI دسکتاپ (Kivy):
pip install -r requirements-gui.txtموارد اختیاری (میکروفون، تبدیل MP3، OCR اسکن-PDF، STT آفلاین، نرمالایز فارسی):
pip install -r requirements-optional.txt
# یا انتخابی (از روی سورس): pip install ".[offline,fa]"- نصب Tesseract OCR
- Windows:
باینری UB-Mannheim را نصب کنید:
https://github.com/UB-Mannheim/tesseract/wiki
و گزینهٔ زبان فارسی (
fas) را موقع نصب فعال کنید. سپسtesseractباید در PATH باشد. - macOS:
brew install tesseract tesseract-lang- Linux:
sudo apt install tesseract-ocr tesseract-ocr-fas tesseract-ocr-eng poppler-utilsبررسی:
tesseract --version
tesseract --list-langsاجرای CLI
python -m app.cli image examples/sample.png --ocr-lang eng
python -m app.cli pdf examples/sample.pdf
python -m app.cli pdf scan.pdf --ocr-fallback --ocr-lang fas+eng
python -m app.cli audio examples/sample.wav --lang fa-IR
python -m app.cli audio speech.wav --lang en-US -o out.txtآفلاین (بدون اینترنت، نیازمند pip install faster-whisper):
python -m app.cli audio speech.wav --engine whisper --whisper-model small --lang fa-IRفرمت خروجی و نرمالایز فارسی:
python -m app.cli pdf examples/sample.pdf --format json -o res.json
python -m app.cli audio speech.wav --engine whisper --format srt -o subs.srt
python -m app.cli audio speech.wav --normalize-fa -o clean.txt--format srt فقط برای صوت است؛ خروجی json شامل موتور، زبان، تعداد صفحات، هشدارها و زمان اجراست.
--normalize-fa از hazm (اگر نصب باشد) وگرنه جایگزین داخلی استفاده می‌کند.
چیدمان اصلی متن (سطرها و فاصله‌ها) به‌صورت پیش‌فرض حفظ می‌شود؛ با --no-layout به حالت قدیمی برمی‌گردی.
اجرای GUI
python -m app.gui_kivyدر GUI زبان STT و OCR و موتور (google/whisper) از منوی کشویی انتخاب می‌شود، گزینهٔ Normalize FA نرمال‌سازی فارسی را فعال می‌کند، کار سنگین در Thread پس‌زمینه اجرا می‌شود (UI فریز نمی‌شود) و خطاها داخل خود برنامه نمایش داده می‌شوند.
🐳 اجرا با Docker (بدون نصب Tesseract و poppler روی سیستم)
docker build -t ocrstt:1.2.0 .
docker run --rm -v "$PWD/examples:/data" ocrstt:1.2.0 pdf /data/sample.pdf
docker run --rm -v "$PWD:/work" ocrstt:1.2.0 audio /work/speech.wav --lang fa-IR --format jsonایمیج شامل tesseract-ocr-fas، poppler-utils و ffmpeg است (پایتون 3.12-slim).
📱 وضعیت موبایل (Android / iOS) — آزمایشی
هدف اصلی پروژه دسکتاپ و سرور است. بیلد موبایل نگه داشته شده ولی آزمایشی محسوب می‌شود:
محدودیت مهم:
pytesseractفقط Wrapper است و به باینریtesseractنیاز دارد.python-for-androidوkivy-iosبه‌صورت پیش‌فرضtesseractندارند، پس OCR عکس روی موبایل بدون Recipe اختصاصی و باندلfas.traineddataکار نمی‌کند. استخراج متن PDF (text-layer) واقع‌بینانه‌ترین قابلیت روی موبایل است.
🟩 Android (Buildozer، روی لینوکس)
pip install buildozer
sudo apt install openjdk-17-jdk unzip autoconf libtool pkg-config zlib1g-dev \
libncurses-dev cmake libffi-dev libssl-dev
buildozer -v android debugفایل buildozer.spec در ریپو موجود است. خروجی: bin/*.apk.
دسترسی اینترنت/حافظه در spec فعال شده (INTERNET, READ_EXTERNAL_STORAGE).
🟦 iOS (Kivy-iOS + Xcode، روی macOS)
pip install kivy-ios
toolchain build python3 kivy pillow
toolchain create ocrstt .
open ocrstt-ios/ocrstt.xcodeprojسپس در Xcode بیلد و اجرا روی دستگاه یا شبیه‌ساز.
🖥️ راهنمای بیلد برای دسکتاپ
Windows / macOS / Linux
pip install pyinstaller
pyinstaller --name ocrstt --paths . --onefile -m app.cliخروجی در پوشهٔ dist/ قرار می‌گیرد.
توجه: باینری tesseract جداگانه روی سیستم مقصد لازم است (داخل exe باندل نمی‌شود).
- برای STT آنلاین نیاز به اینترنت دارید (Google Speech API). صوت شما به سرور گوگل ارسال می‌شود — برای فایل حساس رضایت بگیرید. جایگزین آفلاین:
requirements-optional.txt(Vosk / faster-whisper). - برای OCR فارسی باید دیتای زبان فارسی Tesseract نصب شود (
fas) و--ocr-lang fasیاfas+engبدهید. - PDF اسکن‌شده لایهٔ متنی ندارد؛ خروجی خالی یعنی اسکن است — با
--ocr-fallback(نیازمند poppler + tesseract) دوباره تلاش کنید. - فرمت صوتی پشتیبانی‌شده: WAV/AIFF/FLAC. برای MP3/OGG/M4A اول با
ffmpegبه WAV تبدیل کنید. - توجه نسخه پایتون: همه قابلیت‌ها فقط روی 3.10 تا 3.12 تست شده‌اند. روی 3.13+ کتابخانه
SpeechRecognition(حذفaifc) وfaster-whisper(نبود ویلav) کار نمی‌کنند و ابزار برای حالت صوتی خطای واضح می‌دهد؛ استخراج متن PDF همچنان کار می‌کند. - روی موبایل، عملکرد OCR وابسته به قدرت CPU دستگاه است.
- محدودیت حجم پیش‌فرض برای جلوگیری از OOM: عکس ۳۰MB، PDF و صوت ۱۰۰MB.
🛠️ Troubleshooting | عیب‌یابی
EN:
tesseract: command not found— install Tesseract (see install section) and make suretesseractis in PATH; check withtesseract --version. For Persian OCR also install thefaslanguage data and pass--ocr-lang fasorfas+eng.- Wrong Python version — all features (OCR, Google STT, Whisper) are only tested on Python 3.10–3.12. On 3.13+ install succeeds but only PDF text extraction works; audio mode shows a clear error.
- Whisper model did not download — first
--engine whisperrun needs internet and disk space (~1–3 GB depending on--whisper-model); retry with a smaller model (e.g.--whisper-model small) on a stable connection.
FA:
- خطای
tesseract پیدا نشد— تسرکت را از بخش نصب، نصب کن و مطمئن شو دستورtesseractدر PATH است؛ باtesseract --versionتست کن. برای OCR فارسی دیتای زبانfasرا هم نصب کن و--ocr-lang fasیاfas+engبده. - نسخه اشتباه پایتون — همه قابلیت‌ها (OCR، گفتار گوگل، Whisper) فقط روی پایتون 3.10 تا 3.12 تست شده‌اند. روی 3.13+ نصب انجام می‌شود ولی فقط استخراج متن PDF کار می‌کند و حالت صوتی خطای واضح می‌دهد.
- دانلود نشدن مدل Whisper — اولین اجرای
--engine whisperبه اینترنت و فضای دیسک نیاز دارد (بسته به--whisper-modelحدود ۱ تا ۳ گیگ)؛ با اتصال پایدار و مدل کوچک‌تر (مثلاً--whisper-model small) دوباره تلاش کن.
📄 لایسنس این پروژه تحت لایسنس MIT منتشر شده است. برای مشاهدهٔ متن کامل، فایل LICENSE را ببینید.
- EN: Issues and Pull Requests are welcome. Please see
CONTRIBUTING.md. - FA: برای گزارش مشکل یا پیشنهاد قابلیت جدید، لطفا ایشو یا پول‌ریکوئست ثبت کنید.
MIT — see LICENSE.