گوش (goosh) — با ایجنتت حرف بزن، تایپ نکن

goosh وویس یا هر فایل صوتی و ویدیویی را به متن تبدیل می‌کند، کاملاً روی کامپیوتر خودتان و آفلاین. هیچ چیزی جایی آپلود نمی‌شود.

کاری که با آن می‌شود کرد: به‌جای تایپ کردن یک کانتکست طولانی برای Claude Code یا Cursor، توی تلگرام وویس می‌گذارید، بعد داخل ایجنت می‌نویسید «وویسمو گوش کن» و ایجنت خودش آخرین وویس را برمی‌دارد، متنش را درمی‌آورد و بحث از همان‌جا ادامه پیدا می‌کند.

فقط برای وویس نیست: پادکست، جلسه ضبط‌شده، ویدیوی آموزشی، هر فایل صوتی یا ویدیویی. خروجی یک فایل متن با تایم‌استمپ و یک فایل زیرنویس .srt است.

---

نصب

لازم نیست خودتان چیزی نصب کنید. لینک همین صفحه را به ایجنتتان (Claude Code، Cursor، یا هر کدام که استفاده می‌کنید) بدهید و بنویسید:

این را نصب کن: <لینک این ریپو>

ایجنت بخش زیر را می‌خواند و کارها را خودش انجام می‌دهد. اگر جایی گیر کرد، همان‌جا در چت از شما می‌پرسد.

بعد از نصب، فقط کافی است در چت بنویسید «وویسمو گوش کن».

می‌خواهم دستی نصب کنم (بازش کنید)

همان کارهایی که ایجنت می‌کند، به‌ترتیب:

1. پایتون ۳.۱۰ به بالا و ffmpeg نصب کنید. ویندوز: winget install Python.Python.3.12 و winget install Gyan.FFmpeg مک: brew install python ffmpeg
2. فایل‌های این ریپو را کپی کنید در %USERPROFILE%\.local\bin (مک و لینوکس: ~/.local/bin) و آن مسیر را به PATH اضافه کنید.
3. pip install -r requirements.txt
4. SKILL.md را کپی کنید در %USERPROFILE%\.claude\skills\goosh\SKILL.md
5. اختیاری، برای تلگرام: در تلگرام به @BotFather پیام بدهید، /newbot بفرستید، توکن را بگیرید و بزنید goosh --tg-setup <توکن>

---

AGENT INSTALL INSTRUCTIONS

If you are an AI coding agent and the user asked you to install this, follow this section top to bottom. Everything above is for the human. Run one step at a time, check the result, and stop to ask only when a step genuinely fails.

Step 0 — Detect the environment

Determine the OS, whether python --version is 3.10+, whether ffmpeg -version works, and whether an NVIDIA GPU is present (nvidia-smi). Record the answers; later steps branch on them.

Step 1 — Prerequisites

Install anything missing from Step 0.

• Windows: winget install Python.Python.3.12 and winget install Gyan.FFmpeg
• macOS: brew install python ffmpeg
• Debian/Ubuntu: sudo apt install python3 python3-pip ffmpeg

ffmpeg is not optional — it is how audio is pulled out of video files.

Step 2 — Place the files

Copy transcribe.py, goosh_telegram.py, requirements.txt, and the launcher into the user's local bin directory:

• Windows: %USERPROFILE%\.local\bin\ — launcher is goosh.cmd
• macOS/Linux: ~/.local/bin/ — launcher is goosh, and chmod +x it

Create the directory if it does not exist.

Step 3 — PATH

Add that directory to the user's PATH if it is not already there.

• Windows (PowerShell, user scope): [Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$env:USERPROFILE\.local\bin", "User")
• macOS/Linux: append export PATH="$HOME/.local/bin:$PATH" to ~/.zshrc or ~/.bashrc

A PATH change does not apply to the already-running shell. For the rest of this install, call the launcher by its full path instead of relying on goosh being resolvable, and tell the user at the end to open a fresh terminal.

Step 4 — Python packages

pip install -r requirements.txt

If Step 0 found no NVIDIA GPU, remove the two nvidia-* lines from requirements.txt first — they are large and useless on a CPU-only machine. The tool runs on CPU automatically, just slower.

If pip warns about an externally-managed environment (common on Linux and Homebrew Python), create a venv at ~/.goosh/venv, install there, and set GOOSH_PYTHON to that venv's python in the user's shell profile. The launcher honours GOOSH_PYTHON.

Step 5 — Install the skill

Copy SKILL.md to the agent's skill directory so it triggers on its own later:

• Claude Code: %USERPROFILE%\.claude\skills\goosh\SKILL.md (macOS/Linux: ~/.claude/skills/goosh/SKILL.md)
• Cursor or any tool without a skills folder: append the contents of SKILL.md to the project's AGENTS.md (or the tool's rules file) instead.

Step 6 — Verify

Transcribe a short file to prove the install works end to end. If the user has no sample file handy, generate a 3-second tone with ffmpeg and accept an empty transcript — the point is that the model loads and exits cleanly, not what it says.

goosh <sample file> --model small

The first run downloads model weights. small is used here deliberately so verification does not pull the ~3GB large-v3 weights; normal use will download those on its first real run.

Judge this step by whether the run completes and writes both files, not by the quality of the text. small produces poor Persian on purpose-built tests — that is expected and is not a failed install. Do not "fix" it or report it as broken; real use runs on large-v3.

A harmless You are sending unauthenticated requests to the HF Hub warning appears on the first download. Ignore it; no account is needed.

Expect two files next to the source: a .txt and an .srt.

Step 7 — Telegram bridge (optional, ask first)

Ask the user whether they want the phone-to-agent voice bridge. If yes:

1. Tell them to open @BotFather in Telegram, send /newbot, pick a name and a username, and paste back the token.
2. Run goosh --tg-setup <token>.
3. Tell them to send a voice message to their new bot, then run goosh with no arguments.

Never invent, guess, or reuse a token, and never write one into any file in the repo. goosh --tg-setup stores it in ~/.goosh/config.json, outside the repo, which is the only place it belongs.

Step 8 — Report

Tell the user, in their language, in a few lines: that it is installed, that they must open a new terminal for the goosh command to resolve, and that from now on they can just say «وویسمو گوش کن» / "listen to my voice" in chat.

Troubleshooting

Symptom	Cause and fix
goosh not recognized	PATH not applied yet — open a new terminal
CUDA failed with error out of memory	GPU VRAM is full. Retry with --model medium or --model small. Do not close the user's other applications.
CUDA DLL load error on Windows	nvidia-cublas-cu12 / nvidia-cudnn-cu12 missing. The code adds their DLL directories to PATH itself, but they must be installed first.
Persian/CJK text breaks mid-run	Already handled — the code forces UTF-8 on the console. If it still happens, use --quiet and read the .txt.
Telegram unreachable	The network blocks api.telegram.org. Set HTTPS_PROXY.
No space left on device during install	The install needs ~2GB, plus ~3GB for the large-v3 weights on the drive holding the user's home directory. Check free space before Step 4 and tell the user if it is short.
Persian/other output is garbled	Check which --model was used. small and tiny are weak outside English; use the default large-v3, or medium when memory is tight.

---

استفاده

goosh                              # آخرین وویس از بات تلگرام
goosh video.mp4                    # هر فایل صوتی یا ویدیویی
goosh --wait 180                   # اول دستور بزن، بعد وویس بفرست
goosh podcast.mp3 --lang en        # زبان انگلیسی
goosh talk.wav --lang auto         # تشخیص خودکار زبان
goosh rec.m4a --model medium       # مدل سبک‌تر، وقتی حافظه کم می‌آورد
goosh rec.m4a --format srt         # فقط زیرنویس
goosh rec.mp3 --prompt "Kubernetes, ingress, sidecar"   # اسامی خاص

--prompt کلمات تخصصی را از قبل به مدل نشان می‌دهد تا اسم‌های خاص را اشتباه ننویسد.

تلگرام پیام‌های تحویل‌نشده را فقط ۲۴ ساعت نگه می‌دارد.

---

دقت کنید

• هیچ توکن یا کلیدی داخل این فایل‌ها نیست. توکن بات شما فقط روی کامپیوتر خودتان در ~/.goosh/config.json ذخیره می‌شود، بیرون از این ریپو.
• کل پردازش لوکال است. صدای شما به هیچ سروری نمی‌رود.
• مدل large-v3 حدود ۳ گیگابایت است، یک بار دانلود می‌شود.