התיעוד של subthis

1. התקנה

subthis צריך שני דברים על המחשב: uv (שמתקין את subthis ואת פייתון עצמו) ו‑ffmpeg (שקורא את האודיו מקובצי וידאו). שניהם פקודה אחת לכל מערכת.

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
winget install --id Gyan.FFmpeg -e
uv tool install subthis

אחרי התקנת uv פתחו חלון PowerShell חדש כדי שהפקודה תזוהה.

macOS (Terminal)

curl -LsSf https://astral.sh/uv/install.sh | sh
brew install ffmpeg
uv tool install subthis

‏אם אין Homebrew, התקינו אותו קודם מ‑brew.sh.

Linux

curl -LsSf https://astral.sh/uv/install.sh | sh
sudo apt install ffmpeg   # או dnf / pacman לפי ההפצה
uv tool install subthis

2. הפעלה ראשונה

subthis setup

ההפעלה הראשונה היא אשף חד-פעמי שמדבר אנגלית פשוטה. כאן מופיע כל מסך שלו בדיוק כפי שתראו אותו בטרמינל, ומתחתיו הסבר בעברית: מה המטרה, מה כל שורה אומרת, ומה לעשות. ברוב המחשבים כל זה לוקח כשתי דקות ודורש שתי לחיצות Enter והדבקה אחת.

מסך 1: ברוכים הבאים

╭───────────────────────────────╮
│ Welcome to subthis  ·  v1.8.4 │
╰───────────────────────────────╯

subthis turns a video into subtitles. This one-time setup takes about
two minutes. Nothing on your computer is changed except subthis's own
settings folder: ~/.config/subthis

המטרה: להגיד לכם מה עומד לקרות. subthis הופך וידאו לכתוביות, ההפעלה הראשונה חד-פעמית ולוקחת כשתי דקות, ושום דבר במחשב לא משתנה חוץ מתיקיית ההגדרות של subthis עצמו (הנתיב שמופיע בשורה האחרונה). אין כאן מה לעשות, רק לקרוא.

מסך 2: בדיקת ffmpeg

  ✓ ffmpeg is installed (subthis uses it to read the sound from your videos)

המטרה: לוודא ש‑ffmpeg, התוכנה שקוראת את הסאונד מתוך הווידאו, מותקנת. סימן ✓ ירוק אומר שהכול בסדר וממשיכים. אם במקום זה מופיע:

  ! A helper program called ffmpeg is missing. It reads the sound from videos.
    To install it: sudo apt install ffmpeg
    Then run 'subthis setup' again.

מסך 3: למה צריך מפתח OpenAI

subthis sends your video's audio to OpenAI (the company behind ChatGPT)
to turn the speech into text. For that you need your own OpenAI key:
a long code starting with sk- that acts like a password. It is saved
only on this computer.

המטרה: להסביר את המנגנון. הסאונד נשלח ל‑OpenAI (החברה שמאחורי ChatGPT) כדי להפוך דיבור לטקסט, ובשביל זה צריך מפתח API אישי: קוד ארוך שמתחיל ב‑sk- ומתפקד כמו סיסמה. המפתח נשמר רק במחשב שלכם. אם כבר יש מפתח שמור מהפעם הקודמת, יופיע במקום ההוראות הבאות: A key is already saved. Press Enter at the prompt below to keep it. כלומר Enter ריק שומר על המפתח הקיים.

מסך 4: פתיחת דף המפתחות

Here's what happens next:
  1. OpenAI's key page opens in your browser. No account yet? The site
     will have you sign up first (same login as ChatGPT, and it's quick).
  2. On the key page, click 'Create new secret key', give it any name,
     click 'Create secret key', then 'Copy'. It is shown only this once.
  3. Come back here and paste it.

Press Enter to open the key page in your browser... 

המטרה: להשיג מפתח. שלוש השורות הממוספרות מתארות מה יקרה, והשורה האחרונה מחכה ללחיצת Enter שתפתח את דף המפתחות של OpenAI בדפדפן. אם הדפדפן לא נפתח לבד, זו הכתובת: platform.openai.com/api-keys

מסך 5: הדבקת המפתח ובדיקתו

Paste your OpenAI key here and press Enter: sk-••••••••••••
  Checking your key with OpenAI...
  ✓ The key works and your account has credit.

המטרה: לוודא שהמפתח עובד לפני ששומרים אותו. הדביקו את המפתח (Ctrl+V, או קליק ימני והדבקה; בטרמינלים מסוימים Ctrl+Shift+V) ולחצו Enter. subthis שולח ל‑OpenAI בקשה זעירה, שעולה שבריר סנט, כי רק בקשה אמיתית חושפת חשבון בלי קרדיט. שני ✓ ירוקים אומרים שהמפתח תקין ושיש קרדיט. יש שלוש תוצאות אחרות אפשריות:

  ✗ OpenAI does not accept this key. It may be mistyped, expired,
    or revoked. Copy a fresh one from:
    https://platform.openai.com/api-keys
Paste your OpenAI key here and press Enter: 

  ✗ The key itself works, but the account behind it has no credit yet.
    The transcription service is prepaid, like a phone card. In the
    billing page that opens next:
      1. Click 'Add payment method' and enter your card details.
      2. Click 'Add to credit balance' and choose 5 dollars (the
         minimum; it covers roughly five hours of video).
      3. If it offers auto-reload, you can switch that off.
    Press Enter to open the billing page... 
    Press Enter once your balance shows the credit, and it will be checked again... 

  ! Could not reach OpenAI to test the key (network is unreachable).
    Saving it anyway. subthis will say so clearly if it turns out not to work.

מסך 6: שמירה וקובץ מונחים

  ✓ Key saved to ~/.config/subthis/.env
  ✓ Created a terms file at ~/.config/subthis/terms.txt
    (optional: list names and jargon there and subthis will spell them right)

המטרה: לדווח מה נשמר. השורה הראשונה מציינת איפה נשמר המפתח. השורה השנייה מציינת שנוצר קובץ מונחים ריק, שאליו אפשר להוסיף בעתיד שמות ומונחים מקצועיים כדי ש‑subthis יאיית אותם נכון (ראו לימוד מונחים). זה אופציונלי; אין מה לעשות עכשיו. אם הקובץ כבר היה קיים, תופיע במקום זה השורה Keeping your existing terms file.

  ! The 'subthis' command is not reachable from new terminals yet. To fix:
    installed with uv:   run  uv tool update-shell
    installed with pipx: run  pipx ensurepath
    then open a new terminal window.

מסך 7: סיום

╭─────────────────╮
│ You're all set! │
╰─────────────────╯

To make subtitles, type subthis, a space, and then your video file:
    subthis ~/Videos/lecture.mp4
Tip: type "subthis " and drag the video from your files into this
window, then press Enter. The subtitles are saved as an .srt file
next to the video.

המטרה: להגיד שסיימתם ולהראות איך משתמשים. מקלידים subthis, רווח, ואז נתיב הווידאו. הטיפ: אחרי הרווח אפשר פשוט לגרור את קובץ הווידאו מסייר הקבצים לתוך חלון הטרמינל, והנתיב יודבק לבד. Enter מתחיל את העבודה, וקובץ ה‑.srt נשמר ליד הווידאו. ההמשך ביצירת כתוביות.

משתנה סביבה OPENAI_API_KEY, אם מוגדר, גובר על המפתח השמור; האשף יזהיר על כך במסך הראשון. להחלפת מפתח בעתיד: subthis config key.

3. יצירת כתוביות

זה כל השימוש הבסיסי: מקלידים subthis, רווח, ואת קובץ הווידאו, ולוחצים Enter.

subthis lecture.mp4

הדרך הקלה להגיע לנתיב הנכון: הקלידו subthis  (עם רווח) וגררו את קובץ הווידאו מסייר הקבצים לתוך חלון הטרמינל. הנתיב המלא יודבק לבד. ואז Enter. ככה זה נראה:

$ subthis lecture.mp4
Transcribing your video...
  still working on your video (1m00s so far)...

  ✓ Done! 214 subtitles were created.
  Your subtitle file is here:
    /home/dana/Videos/lecture.srt

שורה אחר שורה: Transcribing your video... אומר שהסאונד נשלח ל‑OpenAI ומתומלל. בזמן ההמתנה מופיעה מדי פעם שורת still working עם הזמן שעבר, רק כדי שתדעו שהכול חי; זה לוקח בערך דקה לכל עשר דקות דיבור. בסיום: כמה כתוביות נוצרו, ומתחת הנתיב המלא של קובץ ה‑.srt. הוא נשמר ליד הווידאו, באותו שם.

סרטון ארוך נחתך אוטומטית לחלקים, כל חלק מתומלל בנפרד, והתוצאה מתאחדת לקובץ אחד. בטרמינל תראו את זה כך:

$ subthis lecture.mp4
Long video: 3 parts of up to 20 minutes each. Each part takes roughly a minute per 10 minutes of speech.
Transcribing part 1 of 3...
Transcribing part 2 of 3...
Transcribing part 3 of 3...

  ✓ Done! 1,180 subtitles were created.
  Your subtitle file is here:
    /home/dana/Videos/lecture.srt

אם כבר קיים קובץ כתוביות באותו שם, subthis לא דורס אותו בשקט אלא עוצר:

$ subthis lecture.mp4
subthis: Output already exists: /home/dana/Videos/lecture.srt. Use --force to replace it.

עכשיו אפשר לגרור את קובץ ה‑.srt לעורך הווידאו (Premiere Pro, DaVinci Resolve, Final Cut Pro, CapCut וכל עורך אחר שמייבא SRT) או לנגן וידאו. איך הכתוביות מיוצרות? כל קטע נשלח ל‑OpenAI פעמיים: פעם אחת לניסוח המדויק ביותר ופעם אחת לתזמון של כל מילה, ו‑subthis מיישר בין השניים. אין צורך להבין את זה כדי להשתמש.

4. לימוד מונחים

מונחים הם שמות וביטויים ש‑subthis צריך לאיית נכון ולהשאיר באנגלית בתוך דיבור עברי: שמות חברות, מוצרים, אנשים, ז'רגון מקצועי. התחביר זהה בכל מקום: רווחים מפרידים בין מונחים, וגרש בודד מקבץ מונח של כמה מילים.

מונחים להרצה אחת

subthis clip.mp4 --term "Omarchy 'Wispr Flow'"

המונחים חלים רק על ההרצה הזו. אפשר לחזור על --term כמה פעמים באותה פקודה.

מונחים קבועים לכל הסרטונים

$ subthis config terms "Omarchy 'Wispr Flow'"
  ✓ Added 2 term(s) to ~/.config/subthis/terms.txt:
    Omarchy
    Wispr Flow
  These now apply to every video you transcribe.

המונחים נוספים לקובץ המונחים הקבוע (הנתיב מופיע בשורה הראשונה) וחלים על כל סרטון מעכשיו. בלי ארגומנט, subthis config terms פותח עורך אינטראקטיבי שמציג את המונחים השמורים, עם מדריך מקשים בתחתית המסך: חצים לתנועה, רווח לבחירה, m לסימון או ביטול של הכול, r להסרת המסומנים אחרי אישור, a להוספה, q לשמירה ויציאה. בסיום מודפס Saved N term(s) to ….

מונחים לתיקייה

שימו קובץ בשם subthis-terms.txt ליד הסרטונים, והוא ייקלט אוטומטית לכל סרטון באותה תיקייה. מונח בכל שורה. תיקון איות נעשה עם כינויים: שם נכון, סימן שווה, ואז הצורות השגויות מופרדות בקו אנכי.

MyCompany
DaVinci Resolve = דה וינצ'י ריזולב | Davinci Resolve

כשקובץ כזה נמצא, subthis אומר זאת בתחילת ההרצה:

$ subthis clip.mp4
Using the terms from /home/dana/Videos/subthis-terms.txt
Transcribing your video...

5. אפשרויות והגדרות

יש שני סוגים. אפשרויות בשורת הפקודה משפיעות על הרצה אחת בלבד: מוסיפים אותן אחרי שם הקובץ. הגדרות קבועות נשמרות פעם אחת עם subthis config וחלות על כל הסרטונים הבאים.

אפשרויות להרצה אחת

-o, --output

לאן לשמור את קובץ הכתוביות. בלי זה הקובץ נשמר ליד הווידאו באותו שם. תיקייה שלא קיימת נוצרת.

$ subthis talk.mp4 -o subs/talk.srt
Transcribing your video...

  ✓ Done! 96 subtitles were created.
  Your subtitle file is here:
    /home/dana/Videos/subs/talk.srt

--max-words 1|2|3

כמה מילים לכל היותר בכתובית אחת. ברירת המחדל 3 (או מה שקבעתם ב‑config captions words). ערך 2 נותן כתוביות קצרות וקצביות יותר, שמתאימות לסרטונים אנכיים; 1 מציג מילה-מילה. הפלט בטרמינל זהה להרצה רגילה.

subthis clip.mp4 --max-words 2

--language

אילו שפות צפויות בדיבור, בקוד של שתי אותיות (he עברית, en אנגלית, ru רוסית, ar ערבית וכן הלאה). ברירת המחדל היא עברית ואנגלית יחד, ולכן ברוב המקרים אין צורך בדגל הזה. חוזרים עליו לכל שפה נוספת.

subthis clip.mp4 --language he --language ru

--force

להחליף קובץ כתוביות קיים. בלי הדגל subthis עוצר עם ההודעה Output already exists (ראו יצירת כתוביות).

subthis lecture.mp4 --force

--term

מונחים להרצה הזו בלבד. מוסבר בלימוד מונחים.

--terms-file

להשתמש בקובץ מונחים אחר במקום הקובץ הקבוע. שימושי כשיש רשימת מונחים נפרדת ללקוח או לפרויקט.

subthis clip.mp4 --terms-file ~/clients/acme-terms.txt

--version, help, docs

subthis --version מדפיס את הגרסה. subthis help (או subthis לבד) מדפיס עזרה מלאה באנגלית. subthis docs פותח את התיעוד הזה בדפדפן.

הגדרות קבועות

הרצת subthis config בלי המשך מציגה את ארבע תת-הפקודות:

$ subthis config
subthis: Usage:
  subthis config key     change your saved OpenAI key
  subthis config terms   review, add, and remove your saved terms
  subthis config terms "term 'multi word term'"   add terms directly
  subthis config open on|off   open the folder when subtitles are done
  subthis config captions      view and tune caption timing and style

subthis config key

החלפת מפתח OpenAI השמור, למשל אחרי שהמפתח הישן בוטל. הפקודה פותחת את דף המפתחות בדפדפן, מחכה להדבקה, ובודקת את המפתח החדש בדיוק כמו בהפעלה הראשונה (תקינות וקרדיט) לפני השמירה. מטעמי בטיחות המפתח לא מתקבל כארגומנט בשורת הפקודה, רק בהדבקה בשורה שמחכה.

$ subthis config key
Let's replace your saved OpenAI key. Copy the new one from:
    https://platform.openai.com/api-keys
Paste your OpenAI key here and press Enter: sk-••••••••••••
  Checking your key with OpenAI...
  ✓ The key works and your account has credit.
  ✓ New key saved to ~/.config/subthis/.env

subthis config terms

עריכת המונחים הקבועים. מוסבר בלימוד מונחים.

subthis config open on|off

האם לפתוח בסיום את סייר הקבצים עם קובץ הכתוביות מסומן, בנוסף להדפסת הנתיב. כבוי כברירת מחדל. בלי on או off הפקודה רק מציגה את המצב הנוכחי:

$ subthis config open
Opening the folder when done is currently: off
Turn it on or off with: subthis config open on   (or off)

$ subthis config open on
  ✓ subthis will now open the folder with your file when it finishes.

מעכשיו כל הרצה מסתיימת בשורה נוספת, וסייר הקבצים נפתח:

  ✓ Done! 214 subtitles were created.
  Your subtitle file is here:
    /home/dana/Videos/lecture.srt
  Opening its folder...

subthis config captions

כאן קובעים איך הכתוביות נראות ומתוזמנות. ברירות המחדל עוקבות אחרי תקני תעשיית הכתוביות (למשל הנחיות Netflix), ולרוב אין צורך לגעת בהן. בלי ארגומנטים מוצגת הרשימה המלאה: שם ההגדרה, הערך הנוכחי, אם הוא ברירת מחדל או שונה, והסבר קצר.

$ subthis config captions
Caption settings (change one with: subthis config captions <name> <value>):

  words        3        (default)  words per caption line, 1 to 3
  pause        0.5      (default)  a silence this long (seconds) starts a new line
  hang         0.5      (default)  how long a line stays after its last word (seconds)
  min          0.83     (default)  minimum time a line stays on screen (seconds)
  gap          0        (default)  empty space kept between one line and the next (seconds)
  punctuation  remove   (default)  'remove' cleans captions, 'keep' leaves punctuation in
  silence      hold     (default)  'hold' keeps a line up until the next one starts (captions connect), 'cut' ends it after the hang time

  reset        put everything back to the defaults

מה כל הגדרה אומרת:

משנים הגדרה אחת עם שם וערך. השינוי נשמר וחל על כל הסרטונים מעכשיו:

$ subthis config captions words 2
  ✓ Saved: words = 2. This applies to every video from now on.

שם בלי ערך מציג את ההגדרה הזו בלבד:

$ subthis config captions words
words is 2  (words per caption line, 1 to 3)
Change it with: subthis config captions words <value>

ערך לא תקין נדחה עם הסבר. הזמנים חייבים להיות מספר שניות בין 0 ל‑10:

$ subthis config captions pause fast
subthis: pause must be a number of seconds, like 0.5

וכדי לחזור לברירות המחדל בכל ההגדרות בבת אחת:

$ subthis config captions reset
  ✓ Caption settings are back to the defaults.

כל ההגדרות הקבועות נשמרות בתיקיית ההגדרות של subthis (~/.config/subthis בלינוקס ומק, %APPDATA%\subthis בווינדוס). מחיקת התיקייה מחזירה הכול למצב התחלתי, כולל המפתח.

6. עדכונים

בתחילת הרצה אינטראקטיבית subthis בודק את PyPI (תקציב של שלוש שניות, שקט כשאין רשת). אם יש גרסה חדשה הוא שואל פעם אחת. ענו כן — והוא מתעדכן ומריץ מחדש בדיוק את הפקודה שלכם; ענו לא — והוא מדפיס את פקודת העדכון להמשך. בווינדוס תוכנה לא יכולה להחליף את עצמה בזמן שהיא רצה, ולכן subthis מדפיס שם את הפקודה להרצה בחלון חדש:

uv tool upgrade subthis

7. פתרון תקלות

‏"subthis: command not found" אחרי התקנה

הריצו uv tool update-shell (או pipx ensurepath) ופתחו טרמינל חדש.

‏"OpenAI no longer accepts your saved key"

המפתח בוטל או נמחק. הריצו subthis config key והדביקו מפתח חדש מ‑platform.openai.com/api-keys.

‏"Your OpenAI account is out of credit"

הוסיפו קרדיט בדף החיוב (מינימום 5 דולר) והריצו שוב.

‏"Required command not found: ffmpeg"

התקינו ffmpeg לפי המערכת שלכם (ראו התקנה). subthis setup מדפיס את הפקודה המדויקת למערכת שלכם.

‏"The video may have no audio track"

לקובץ אין סאונד לתמלל. בדקו שהוא מתנגן עם שמע בנגן מדיה.

8. מדריך פקודות

קודי יציאה: 0 הצלחה, 1 שגיאה מטופלת (הודעה ב‑stderr עם התחילית subthis:), 130 ביטול עם Ctrl+C.

9. לסוכני AI

אם אתם סוכן AI שמפעיל מחשב עבור משתמש: subthis בטוח להרצה לא-אינטראקטיבית. קלט מנותב (pipe) מכבה את כל השאלות, הצבעים ופתיחת הדפדפן; בדיקת העדכון מדולגת כשאין TTY, ואפשר לכבות אותה מפורשות עם SUBTHIS_SKIP_UPDATE=1. הסיכום הקריא-מכונה נמצא ב‑llms.txt והתיעוד המלא כ‑markdown ב‑docs.md.

# minimal agent flow
uv tool install subthis
OPENAI_API_KEY=sk-... subthis input.mp4 -o output.srt --force
# stdout ends with the absolute path of the written file