Skip to content
User guide

KotobaSync User Guide

The whole flow, from the setup before you start to transcription, editing, Japanese translation, review, saving and exporting, and what to check when something goes wrong. The installation steps are on the download page.

App interface: Japanese. Japanese labels are shown in parentheses, for example Settings (設定).

Getting started

Getting started

KotobaSync is an app that transcribes subtitles from a video, lets you correct the text and times while the video plays, adds a Japanese translation and saves the result as SRT. You work through it by pressing the buttons at the top of the window from left to right.

Just press the 3 buttons at the top in order, starting from 1.

Your guide, Tsumugi
  1. 1 Open Video (1 動画を開く): choose the video to make subtitles for. You can also open a video by dropping the file from Finder onto the video area at the top left.
  2. 2 Make Japanese Subtitles (2 日本語字幕を作る): one press runs everything in a row: if there are no subtitles, it transcribes the audio, creates the work notes and the spellings of names and terms (the glossary), translates everything into Japanese, and checks the name spellings and line lengths against rules. If there are subtitles inside the video or in the same folder (including folders such as “Subs” or “English” below it, down to 3 levels), it uses them as the source text. From the arrow on the right you can choose “Name spellings and how to translate (work notes)… (人名の表記と訳し方(作品メモ)…)”, “Only turn the dialogue into text (don't translate) (せりふを文字にするだけ(訳さない))”, “Try translating just 5 lines (from the current position) (試しに5行だけ訳してみる(今の位置から))”, “Choose the source text (the subtitles to translate from) again… (原文(訳すもとの字幕)を選び直す…)” and “Read the subtitles shown in the picture… (replaces the current subtitles) (画面に映っている字幕を読み取る…(今の字幕と置き換え))”. If you stop partway, the button changes to “2 Continue (N left) (2 続きを作る(残りN件))”.
  3. 3 Check and Save (3 確認して保存): if there are lines worth looking at before saving, the button shows “3 Check and Save (N lines to check) (3 確認して保存(要確認 N行))”, and pressing it lists those lines. If there are none, it saves the Japanese subtitles. From the arrow on the right you can choose lines by type, “See the lines to check against the picture (映像で確認する行を見る)”, “Have AI reread and make suggestions (AIに読み直させて提案を作る)”, “Check in detail (細かく確かめる)”, “Save Japanese Subtitles… (日本語字幕を保存…)”, “Watch Through (通して観る)” and “Export Video with Subtitles… (字幕入りの動画を書き出す…)”.

Just below the buttons, a “Next step (次にすること)” card appears. The large text is the next task, and the button on the right takes you to it. The second line and the “or (または)” button are the way to go if you skip that task (for example, “If you are in a hurry, you can save without fixing them. The 3 lines without a translation will appear in English in the subtitles (急ぐなら、直さずに保存しても構いません。訳のない 3 行は英語のまま字幕に出ます)” and “Save as Is… (このまま保存…)”). While there is still work to finish before saving, the card is labeled “Before saving (保存前に)”; once you can save, “Ready to save (保存できます)”; and after saving, “Saved (保存済み)”. If you are unsure which button to press at the current stage, look here.

To start from existing subtitles, use “Load Subtitles (字幕を読み込む)” to load a source SRT, a translation SRT or a diff translation SRT. You can also work with SRT files alone, without opening a video.

The first time you launch the app, the Terms of Use screen appears first. Read it, check “I have read and agree to the Terms of Use above (上記の利用規約を読み、内容に同意します)” and press “Agree and Start (同意して始める)” to start using the app (if you do not agree, the app quits. When the terms are revised, you will be asked to agree again at the next launch). You can read the Terms of Use at any time from “Terms of Use… (利用規約…)” in the app menu and on this site. Next, the “About This App (このアプリについて)” screen appears once. Close it with “Close (閉じる)”. After that, the “Welcome to KotobaSync (ことばシンクへようこそ)” screen opens.

Setup

Setup: model, translation engine, ffmpeg

The “Welcome to KotobaSync (ことばシンクへようこそ)” screen lists 3 things to prepare before you start, each with “✓” or “Needs setup (要準備)” and a button to fix it. From the second time on, the same list appears on the screen shown before you open a video.

① Transcription model

Download the Whisper model used for transcription once, at the start. You can download it with “Download (取得する)” on the welcome screen, or from “Transcription (文字起こし)” in Settings (設定) → the Advanced (詳細) tab. Once downloaded, transcription needs no internet connection.

ModelSizeBest for
large-v3-turboAbout 1.6 GBStandard. Supports many languages
smallAbout 466 MBWhen the large model is too heavy
baseAbout 142 MBWhen you want a light trial
tinyAbout 75 MBChecking that it works
English, speaker-change candidates (英語・話者切替候補) (small.en-tdrz)About 466 MBFor English audio, when you want to mark subtitles where the speaker may have changed

② Translation engine

Japanese translation uses a translation engine that you set up separately. It is not included in KotobaSync, so prepare one of the following first. For transcription, editing and saving only, you can use the app without a translation engine.

EngineWhere it translatesWhat to prepare
OllamaOn this MacInstall Ollama and download a model
LM StudioOn this MacDownload a model and turn the server on
CodexOpenAI's cloudInstall the Codex CLI and sign in with your ChatGPT account

Choosing an engine

AI on this Mac (LM Studio, Ollama)Codex (OpenAI's cloud)
CostFreeUses your ChatGPT usage allowance
Subtitle textDoes not leave the MacSent to OpenAI (video and audio are not sent)
AccuracyDepends on the model and the translation unit (the method that reads the surrounding lines is still being evaluated)Good compared with the old one-line-at-a-time method. Varies by work
How it translates8, 16 or 40 lines at a time, reading the surrounding dialogue (the older one-line-at-a-time method can also be chosen)40 lines at a time, reading the flow and translating them together

A rule of thumb: if you want the subtitle text handled only on your Mac, use the AI on this Mac. If you want to use a cloud AI with your ChatGPT usage allowance, use Codex. In an earlier version, when the AI on this Mac translated an English-subtitled film (160 lines) one line at a time, it made more serious mistranslations than Codex (18–20 lines versus 3–4 lines). A new comparison using the method that reads the surrounding dialogue (from 1.2.35) has not been done yet.

Using Ollama

  1. Install Ollama for Mac from ollama.com.
  2. In Terminal, run the following to download the model used for translation (the example is Qwen3 8B).
ollama pull qwen3:8b

If Ollama is installed, KotobaSync starts Ollama when it is needed.

To translate only on your Mac, choose Ollama or LM Studio.

Your guide, Tsumugi

Using LM Studio

  1. Download a model in LM Studio.
  2. Turn on “Start server” on the “Developer” screen of LM Studio.
  3. If you have turned on authentication in LM Studio, enter the API token in KotobaSync's settings and press “Save Token to Keychain (トークンをキーチェーンに保存)”. The token is stored in the macOS Keychain.

With LM Studio, KotobaSync never starts the server automatically. Turn the server on before translating.

Using Codex

  1. Install the Codex CLI (or the Codex desktop app) following OpenAI's instructions.
  2. In Terminal, run the following and sign in with your ChatGPT account.
codex login
If you choose Codex, the subtitle text is sent to OpenAI

When you choose Codex, the subtitle text and the translation instructions are sent to OpenAI, and your ChatGPT / Codex usage allowance is used. Video and audio files are not sent (only when you turn on image assistance are still images taken from the video also sent). The first time something is sent, a confirmation of what will be sent appears once. Your consent is saved, and you can withdraw it in Settings at any time. Ollama and LM Studio translate only on this Mac.

Choosing and checking the translation engine

On a new Mac, the translation engine is chosen automatically at first. If Codex answers, Codex is chosen; if not, a server on the Mac (Ollama, LM Studio) and a model that fits that Mac are chosen. For the model, it picks the largest installed one up to 32B that fits in 40% of the memory (Gemma 4 is preferred among models of the same size), and marks it “★ Recommended (★ おすすめ)” in the list. To change or check it, go to “Translation Engine (翻訳エンジン)” in Settings (設定) → the Basic (基本) tab and proceed in this order.

  1. Select Translation Engine (翻訳エンジンを選択): choose from Ollama, LM Studio and Codex.
  2. Check Connection and Readiness (接続と準備状態を確認): if it cannot connect, press “Refresh Connection and Model List (接続・モデル一覧を更新)”.
  3. Select a Candidate from the Engine (エンジンから取得した候補を選択): choose from the models the engine has.
  4. Test Translation with a Made-up Sentence (架空短文で翻訳を確認): check with a short sentence such as “Hello.” that it can actually translate.

With Ollama and LM Studio, opening “Details (when translating on this Mac) (詳細(このMacで訳すとき))” below the candidates lets you also choose the following 2 settings.

  • Local Translation Unit (ローカル翻訳の単位): choose 8 lines (standard), 16 lines, 40 lines or the older 1 line. With several lines, it translates while reading the surrounding dialogue together with the work notes, glossary and character materials. More lines is not necessarily more accurate, and it also uses more memory. If it is heavy, or the content of neighboring lines gets mixed in, reduce the number of lines. Lines with strange responses are split into smaller pieces and translated again.
  • Check meaning and subtitle alignment after generating (生成後に意味と字幕の対応を確認する) (on by default): after translating, the same model checks for misread meanings and for content mixed in from neighboring lines (how translation works). It takes longer. You can turn it off when you are in a hurry.

Neither of them rewrites lines that are already translated or lines you corrected by hand. The model and connection are remembered for each engine. If translation fails, the app does not switch automatically to another engine or model.

③ ffmpeg (optional)

ffmpeg is used to open videos such as MKV and WebM, and to export videos with the subtitles added as a subtitle track. If you only use videos such as MP4, you do not need it. If you use Homebrew, run the following in Terminal to install it.

brew install ffmpeg

KotobaSync looks for ffmpeg in /opt/homebrew/bin and /usr/local/bin. If it is somewhere else, choose it in “ffmpeg Location (ffmpegの場所)” in Settings (設定) → the Advanced (詳細) tab.

When everything is ready, refresh the display with “Check Again (もう一度確かめる)” on the welcome screen and press “Start (始める)”.

Transcription

Transcription

When you open a video and press “2 Make Japanese Subtitles (2 日本語字幕を作る)”, if there are no subtitles, it first creates source-text subtitles from the audio. To create only the source-text subtitles, choose “Only turn the dialogue into text (don't translate) (せりふを文字にするだけ(訳さない))” from the arrow on the right. Transcription runs on your Mac and the audio is not sent anywhere.

  • Language: the default is automatic detection. You can also fix it to Japanese, English and so on in “Audio Language (音声の言語)” in Settings (設定) → the Advanced (詳細) tab.
  • Long videos: processed in 5-minute pieces. Progress is shown by the number of pieces, and you can stop with “Cancel Processing (処理を中止)”. When you stop, the subtitles shown so far remain.
  • Matching display times to the voice: at the end of transcription, the app finds the sections where people are speaking and moves the times when each subtitle appears and disappears closer to the voice. It still keeps enough time to read the subtitle (4 characters per second for Japanese, 15 characters per second for English and other languages, at least 1 second). The times of subtitles where no voice is found are not changed.
  • Scenes without subtitles: when there is no subtitle at the current position and the next subtitle is 8 seconds or more away, a message such as “No subtitle at this position · Next subtitle 23:48 (この位置に字幕はありません・次の字幕 23:48)” appears below the video. “Next Subtitle (次の字幕へ)” takes you to that position.

Transcription times are estimates. Correct proper nouns and hard-to-hear parts while playing the video to check them. The speed and accuracy of transcribing an entire 2-hour film have not been checked yet.

Reading subtitles burned into the picture

For videos with subtitles drawn into the picture, choose “Read the subtitles shown in the picture… (replaces the current subtitles) (画面に映っている字幕を読み取る…(今の字幕と置き換え))” from the arrow next to “2 Make Japanese Subtitles (2 日本語字幕を作る)” to read the text on screen and turn it into subtitles. Before reading, it tries reading a few places to tell whether the subtitles are written in English, Korean, Japanese, Chinese or another language, and reads them in that language (even in a Korean drama with English subtitles burned in, it reads them as English). The current subtitles are replaced. Reading errors may remain, so play the video to check.

  • When you choose it, a yellow frame appears over the video. Drag inside the frame to move it, and use the handles on the corners and sides to resize it. Fit the frame to where the original subtitles appear and press “Read This Area (この範囲で読み取る)” to read only the text inside the frame. Text outside the frame, such as signs and captions, is not picked up. Moving through the video with ← / → and fitting the frame in a scene that shows a subtitle makes it more reliable.
  • If you check “Look at the video and adjust the frame automatically (for this video) (動画を見て枠を自動で直す(この動画で))”, before reading the app checks the subtitle position in scenes throughout the video, widens the frame if subtitles stick out of it, and shrinks it if it is too large. How it was adjusted is shown at the top of the screen.
  • The app remembers the frame, and the same frame appears from the start for the next video. After it has been adjusted automatically once, the checkbox starts unchecked, so from the second episode of a drama you can read right away.

When reading is finished, the app checks every line and marks lines that may have been misread with “Reading needs check (読み取り要確認)” (low text-recognition confidence, broken duplicates of the lines before or after, only numbers or symbols, a few characters of another language mixed in, doubtful English spelling and so on). Marked lines are read again over several frames and corrected only when the result is clearly better.

The app also tells apart text inside the frame that is not subtitles (signs, car number plates, logos, titles that appear gradually, end credits and so on). It learns the text size, horizontal position and color of that video's subtitles, and treats text that differs from them, or text that moves while shown, as not subtitles. Lines that clearly differ are removed automatically, and the number of removed lines is shown at the top of the screen (right afterwards you can bring them back with “Restore Removed Lines (消した行を戻す)”). Lines it is unsure about are not removed but listed under “Reading needs check (読み取り要確認)” with the reason. Lines where only the text near the subtitles was removed are also marked, so you can check that it did not remove too much.

  • Press “Reading needs check (読み取り要確認)” at the top of the list to show only the marked lines in the source-text view. Play with R and compare with the subtitle on screen; if it matches, press ⌘↩ (checked), and if the text before the automatic correction was right, press ⇧⌘⌫ (revert). Delete on-screen text that is not dialogue with ⌫, and if the same subtitle is split over several lines, merge them with G.
  • Press “Fix with AI (AIで直す)” to send the remaining lines, together with the lines before and after them, to the translation engine and have only the reading errors corrected (it does not translate. Answers that turn into translations or rewordings are not used). Corrected lines keep their mark, so you can compare them with the text before correction.
  • Lines that the AI judged to be on-screen text that is not dialogue (signs, logos, titles and so on) can be removed together with “Remove Non-Dialogue Lines (台詞でない行を消す)”. Right afterwards you can bring them back with “Restore Removed Lines (消した行を戻す)”.

Using Apple Speech

You can also choose Apple Speech (macOS speech recognition) in “Recognition Method (認識方式)” in Settings (設定) → the Advanced (詳細) tab. macOS “Speech Recognition” permission is needed first. It is used only for languages that can be recognized on the Mac alone, and the app never switches to a method that sends audio to Apple's servers. If it is not available for your Mac or language, use Whisper.

Matching the times of loaded subtitles to the voice

For loaded SRT files and translated subtitles too, you can make the same adjustment with “More (その他)” → “Match Subtitle Display Times to Speech (字幕の表示時刻を発話に合わせる)”. The text and translation do not change. You can undo it with the timing “Undo (戻す)”.

Adding dialogue without subtitles from the audio

Loaded subtitles sometimes leave out part of the dialogue. For example, in English subtitles for Korean dramas, scenes where characters speak English have no subtitles, so that dialogue is not translated. Choose “More (その他)” → “Add Dialogue Without Subtitles by Transcription (字幕のない会話を文字起こしで足す)” to find places in sections without subtitles where someone speaks for 2 seconds or more, transcribe only those sections and add lines.

  • Sections not added: sections heard as dialogue in the video's language (Korean for a Korean drama) are not added, because they are often background voices or songs that the subtitles left out on purpose. Music and silent sections are not added either.
  • Checking added lines: added lines are marked and go into “Lines added from audio (音声から足した行)” under “Optional checks (任意の確認)” at the top of the list. Because they are transcribed by ear, they may include mishearings or lines where music was taken for words. Listen with R, and if it is right, press “Mark as Checked (確認済みにする)” (⌘↩). Delete lines that are not dialogue with “Delete Selected Lines (選択行を削除)”.
  • Translating: added lines are translated with “2 Make Japanese Subtitles (2 日本語字幕を作る)” like the other lines. Right after adding, you can undo with “Undo Added Dialogue (足した会話を取り消す)”.

Transcription runs on your Mac and the audio is not sent anywhere. If you do not have the transcription model yet, first press “Download (取得)” under transcription in Settings (設定). This cannot be used for subtitles transcribed from the audio (there is no dialogue to add).

Playback & editing

Playback and editing

Select a subtitle in the list on the right and correct the text and times in the editing area at the bottom left. When the video plays, the current subtitle is shown in a light color in the list with “Playing (再生中)”, and the list follows automatically.

  • Clicking a subtitle card in the list stops the video and goes back to the start of that subtitle.
  • Enter start and end times in the form 00:01:23.456 and confirm with Return.
  • When you start typing text or times, the video stops automatically. Even if you play the video while typing, the subtitle you are editing does not switch to the next one.
  • When the Japanese translation is shown, the source text appears in a light color above the translation in each line of the list and in the editing area. You can compare them without switching the display.

Keyboard shortcuts

The playback keys are the same as on YouTube. Clicking the video also plays and pauses it. The keyboard button next to the play button shows this list on screen.

KeyAction
Space / KPlay / pause
J / LBack / forward 10 seconds
← / →Back / forward 5 seconds
, / .Back / forward 1 frame (pauses)
Shift + , / Shift + .Slower / faster playback (0.25× to 2×)
0–9Go to 0–90% of the video
Home / EndGo to the beginning / end
↑ / ↓Volume up / down
MMute / unmute
N / PNext / previous subtitle (stops and goes to the start of the subtitle)
Shift + N / Shift + PMove the subtitle being edited to the next / previous one without moving the video
RPlay only the selected subtitle, from a little before it to its end, then stop
I / OSet the start / end of the selected subtitle to the current playback position (changing the start also moves the end, keeping the display time)
ReturnType the text of the selected subtitle
HHide / show the selected subtitle in Japanese on screen (when the Japanese view is shown)
GAbsorb the next subtitle: keeps the text of the selected subtitle and shows it until the end of the next subtitle, and the next subtitle disappears (press repeatedly to merge any number of lines. Undo with ⌘Z)
⌫Delete the selected subtitle and select the next one (press repeatedly to delete in order. Undo with ⌘Z)
Esc (while typing)Finish typing and return the keys to the video
⌘SSave SRT
⇧⌘FStart / end viewing mode

While you are typing text or times, the keys are used for typing. Leave the input field with Esc or by clicking the video, and you can use the keys (Esc during Japanese conversion cancels the conversion). They work even with Japanese input left on.

An example of correcting one line at a time with the keyboard only: N (next subtitle) → Space (listen) → Return (type) → correct → Esc → N.

Watching through in viewing mode

When the subtitles are finished, “Watch (鑑賞する)” at the top of the window (also “Watch Through (通して観る)” in the arrow next to “3 Check and Save (3 確認して保存)”, View (表示) → “Viewing Mode (鑑賞モード)” in the menu bar, or ⇧⌘F) shows the video filling the window, so you can check it all the way through as a viewer would. Playback starts from the current position (from the beginning if you had watched to the end).

  • Subtitles appear with the same size ratio and line breaks as in the exported video.
  • If a subtitle looks wrong, press Return (or “Fix #number (#番号 を直す)” in the bar at the bottom). You return to the editing screen, stopped with that subtitle selected, and can type the text right away. Even if you press it just after the subtitle disappeared, the previous subtitle becomes the one to fix. After fixing it, “Watch (鑑賞する)” again lets you continue watching from that position.
  • Esc or “End Viewing (鑑賞を終える)” returns you to the editing screen at the current position.
  • The playback keys (Space, ← / → and so on) are the same as on the editing screen. The keys that change subtitle times (I / O) and R cannot be used while viewing.
  • If you do not move the mouse during playback, the bar at the bottom and the mouse pointer disappear. They come back when you move the mouse.

Unsaved changes and autosave

  • Subtitles not yet saved to SRT are saved automatically 3 seconds after a change. Even if the app quits suddenly, reopening the same video (or SRT) shows “Your previous work remains (前回の作業が残っています)”. “Restore (復元する)” brings back those subtitles.
  • When there are unsaved changes, before you open another video, close the window, quit the app and so on, the app asks “Save… / Cancel / Continue Without Saving (保存…/キャンセル/保存せずに続ける)”.
  • While unsaved, the window's close button shows a mark indicating changes.
Timing

Adjusting times

When all the subtitles are earlier or later than the voice, you can adjust the times together.

  1. Stop the video at the position where the speech starts.
  2. Select the subtitle you want to align. To select without moving the video, press Shift + N / Shift + P, or click a subtitle in the list while holding the Option key.
  3. Choose “This Line Only (この一行だけ)” or “Selected Subtitle and After (選択字幕以降)” and press “Match Current Playback Position (現在の再生位置に合わせる)”.
  • Display times and the gaps between subtitles are kept. Lines before the selected subtitle do not change.
  • It does not adjust if a time would become negative or a subtitle would newly overlap the one before or after.
  • “Undo (戻す)” cancels the last time adjustment (up to 20 times). Only what the time adjustment moved is undone; text corrections and times you entered by hand afterwards remain.

To adjust line by line, the quick way is to set the start and end to the current playback position with I / O.

Translation

Translating into Japanese

“2 Make Japanese Subtitles (2 日本語字幕を作る)” creates the work notes and the glossary automatically and goes straight on to translate everything. It does not stop to confirm character settings or the style. When it is finished, “Japanese subtitles are ready (日本語字幕ができました)” appears, and you can go on to save or to export a video with subtitles. Set up a translation engine first.

How translation proceeds

  1. Press “2 Make Japanese Subtitles (2 日本語字幕を作る)”. If there are no subtitles for the whole video yet, it starts by transcribing the whole video.
  2. It creates the work notes and the glossary from the whole source text (if they already exist, it uses them).
  3. It goes straight on to translate everything. For character information, with “Automatic (no setup needed) (自動(設定不要))” in character settings, it uses only information that has grounds.
  4. After translating, it checks name spellings, politeness, English letters left in the translation and so on against rules (a few seconds).

To check the style first, choose “Try translating just 5 lines (from the current position) (試しに5行だけ訳してみる(今の位置から))” from the arrow to the right of the button. It translates about 5 lines of dialogue from the current position (this trial translation does not change the translation on screen). Look at the “Points to check (確認する点)” (① meaning ② honorifics and casualness ③ length), and if it does not fit, change the style or the notes on manner of speech with “Change How to Translate (訳し方を変える)”.

Works whose character setting is “Use only confirmed settings (確認した設定だけ使う)” (including works where you turned the character feature on in an earlier version) follow the same flow as before. When work notes are created for the first time, or when there are names or terms to check, the “Work Settings (作品設定)” screen opens; check it and press “Translate with These Settings (この内容で翻訳)”. Then check the style with about 5 lines, and translate everything with “Start Translating in This Style (この文体で翻訳を始める)”.

During translation, the list moves automatically to the line being translated, and the video also moves to that scene (staying paused). Moving the video can be turned off in “Translation Progress (翻訳の進め方)” in the Advanced (詳細) tab of Settings. When you translate with Ollama or LM Studio, an AI reread follows at the end of translation (when you translate with Codex, it is not done by default. You can switch this with “AI Reread After Translation (翻訳後のAIの読み直し)” in Settings).

Style and notes on manner of speech

Choose these on the screen opened with “Name spellings and how to translate (work notes)… (人名の表記と訳し方(作品メモ)…)” from the arrow next to “2 Make Japanese Subtitles (2 日本語字幕を作る)”, or with “Change How to Translate (訳し方を変える)” on the style check screen. You can decide them here even for works with no information on the web (such as videos you shot yourself).

  • Style: choose from 4: “Natural conversation (自然な会話)”, “Polite conversation (丁寧な会話)”, “Action / wild (アクション・ワイルド)” and “Literary / calm conversation (文学的・落ち着いた会話)”.
  • You can also add notes such as how a character talks.

The chosen style and notes on manner of speech are remembered for each video. When you open another video, the settings switch to that video's (the defaults for a video opened for the first time), so the settings of the previous work are never carried over to the next one.

When you open a video, the work from the previous video (the glossary and work notes display, filters and search, the state of a translation in progress, undo for batch operations, playback speed, export results and remaining notices) returns to its initial state. The glossary, work notes and partially saved translations remain on the Mac and are used when you reopen the same video.

How translation works

  • By default, Ollama and LM Studio translate 8 lines at a time, together with the surrounding dialogue and the work notes, glossary and character materials (16 lines, 40 lines or the older 1 line can also be chosen in “Local Translation Unit (ローカル翻訳の単位)” in Settings). Codex translates 40 lines at a time. The app asks the engine to stay close to a readable length (4 characters per second, up to 32 characters per subtitle), but allows longer text when the meaning cannot be kept otherwise.
  • The returned translation is checked for whether it is in Japanese, whether it contains explanations or numbers not in the source text, whether the digits of amounts have changed, and whether English or other languages are mixed in. Translations that cannot be used as subtitles are sent back with the reason to be translated again.
  • Each numbered translation contains only the dialogue of that subtitle. Translations that bring a neighboring line forward or fill a short line with the next line's dialogue are not used.
  • With Ollama and LM Studio, when “Check meaning and subtitle alignment after generating (生成後に意味と字幕の対応を確認する)” is on, the same model makes another draft from the source text without seeing the original translation. If the draft differs, both are translated back into English and compared with the source text, then compared again with the order swapped. The draft replaces the original translation only when both comparisons confirm an error in the original (a mixed-up subject or negation, the direction of a comparison, the digits of an amount, content mixed in from a neighboring line and so on) and that the draft is correct. Lines where the draft does not fit either are translated again individually. Not every error can be found.
  • The source text, subtitle numbers and times are kept as they are, and the Japanese translation is held separately. You can switch between the source text and Japanese to play, edit and save.
  • Loaded translations and translations you corrected by hand are not overwritten. Only lines without a translation are translated.

Translation quality depends on the model you use. It may misread who is who or the flow of the whole work, so play the video to check the translation and correct it if needed.

Stopping and resuming

Translated lines are saved one line at a time as you go. If you stop the translation or it stops partway, the button changes to “2 Continue (N left) (2 続きを作る(残りN件))”, and pressing it continues from where it stopped. When you stop the translation yourself, no error is shown. To check the style at another position, choose “Try translating just 5 lines (from the current position) (試しに5行だけ訳してみる(今の位置から))” from the arrow to the right of the button.

During translation, you can still select lines in the list, scroll and play the video. Edit text and times after the translation has finished.

Lines with translation errors

  • Lines whose translation could not be accepted are shown with a red warning and a pale pink background. The numbers of “Translation errors (翻訳エラー)”, “Hearing needs check (聞き取り要確認)” and “Untranslated (未翻訳)” lines appear above the list. Pressing a number lists only those lines and shows what to do. Press it again or “Show All (すべて表示)” to go back.
  • If error lines remain after translating to the end, those lines alone are translated again automatically using the subtitles before and after them. Lines translated again are marked “Line fixed by AI (AIが直した行)”.
  • For lines where a usable translation still did not come out, the translation with the fewest problems is put in provisionally and marked “Uncertain translation (自信のない訳)” with the reason. “Revert (元に戻す)” returns it to the error state.
  • Error lines show a button such as “Translate Again as Russian (ロシア語として訳し直す)”. Pressing it translates only that line again.
  • Pressing “Accept as Is (このまま採用)” uses the source text as the translation and clears the error. Typing a translation yourself also clears it.
  • For lines that need no translation (songs, lines where you do not want an uncertain translation shown, and so on), select the line in the Japanese view and press “Don't Show This Line on Screen (この行を画面に出さない)” above the editing area, or press the H key. Nothing is shown for that line in Japanese, and the list shows “Not shown on screen (画面に出さない)”. It is written to SRT as an empty subtitle and is not shown in exported videos either. It does not change when translating again or reviewing. Press “Show on Screen (画面に出す)” or the H key again, or type a translation, to undo it.

If the app cannot connect to the translation engine, or a response does not come back within 300 seconds, the translation stops. Translated lines remain.

Glossary & notes

Glossary and work notes

Before translating everything, the app creates a “glossary (用語集)” that keeps the spellings of names and the like consistent, and “work notes (作品メモ)” that sum up the feel of the work. You can see and correct both by choosing “Name spellings and how to translate (work notes)… (人名の表記と訳し方(作品メモ)…)” from the arrow next to “2 Make Japanese Subtitles (2 日本語字幕を作る)”.

Glossary

  • It collects names of people, places and companies, key words of the work and so on from the source text, and fixes one way of writing each throughout the work (example: Acme → アクメ).
  • About 870 words whose spelling is established in Japan (place names, famous people and characters, and so on) are decided from a built-in table and shown as “Established (定訳)”.
  • Words where the translation engine's answers varied, and the like, become “Words to check (確認が必要な語)”. If there are such words before the first translation, the glossary screen opens. Correct the spelling or choose a candidate and press “Translate with These Settings (この内容で翻訳)” to go on to the style check (a translation of about 5 lines).
  • You can correct spellings and how characters talk in “Terms & Characters (用語・人物)”. Corrected spellings do not change even with “Rebuild (作り直す)”. After a correction, the number of translated lines that use a different spelling is shown. Choosing “Have AI reread and make suggestions (AIに読み直させて提案を作る)” from the arrow next to “3 Check and Save (3 確認して保存)” brings those lines in line with the glossary spelling.

Work notes

  • The app reads the whole source text and sums up the plot, period and setting, mood, style policy, expressions to avoid, and how the main characters talk.
  • The first time they are created, the “Work Settings (作品設定)” screen opens once before the style check. After checking it, press “Translate with These Settings (この内容で翻訳)” to go on to the style check.
  • Every item can be corrected. Corrected items are shown as “Entered by hand (手入力)” and do not change even with “Rebuild Work Notes (作品メモを作り直す)”.

The glossary and work notes are saved on the Mac for each source text. The same ones are used even if you change the translation engine or the style.

Looking up the work (Wikipedia, TMDb)

When you open a video, the app asks “Look up this video's work on Wikipedia? (この動画の作品を Wikipedia で調べますか)”. The characters of the work found are used as a reference for name spellings and translation. Only the search words and the year are sent; subtitles, audio and video are not.

  • Look Up (調べる): the search screen opens. The title, year and type (film or drama) read from the file name are already filled in; correct them if they are wrong and press “Search (検索)”. The candidates show a description of the work and the main roles and cast, and if there are subtitles, characters whose names appear in the subtitles get a ✓. The more ✓ marks, the more likely it is this video's work. If it is not found, you can search again with the English title, without the year, with the type set to “Any type (種類を問わない)” and so on.
  • Don't Look Up (調べない): work information is not used for this work (for a drama, the same season).
  • Later (あとで): don't answer now; the app looks it up automatically as before when the source text is decided.

The work you chose (including “Don't Look Up (調べない)”) is remembered for each title, year and season. Opening other episodes of the same drama does not ask again. To choose again later, press “Search for the Work Again… (作品を探し直す…)” (“Search for the Work… (作品を探す…)” for works you did not look up) on the “Name spellings and how to translate (work notes)… (人名の表記と訳し方(作品メモ)…)” screen.

Searching TMDb too (optional)

New or small works that are not on Wikipedia can sometimes be found on TMDb (The Movie Database, a film and TV database that users add to). To use it, you need an API key for your own TMDb account (free for personal, non-commercial use).

  1. Choose “TMDb” in “Search In (探す先)” on the search screen (you can also start from “Enable TMDb (TMDb を使えるようにする)” in “Work Information on the Web (Web の作品情報)” in Settings (設定) → the Basic (基本) tab).
  2. Create a free TMDb account from the instructions shown, and get an API key with “Open TMDb API Settings (TMDb の API 設定を開く)”.
  3. Paste the API key (32 letters and digits) and press “Verify and Save (確かめて保存)”. Right after you apply, it may take a little while before it can be used.

Once the key is saved, automatic lookups also search TMDb when nothing is found on Wikipedia. The key is stored only in this Mac's Keychain, and only the search words, the work's number and this key are sent to TMDb. Subtitles, audio, video and file locations are not sent. You can re-enter or delete the key in “Work Information on the Web (Web の作品情報)”. Plot summaries of TMDb works are shown as TMDb's English descriptions.

Character settings and extra analysis (optional)

In “Character Settings (人物設定)” on the work notes screen, you can choose how character information is used in translation.

  • Automatic (no setup needed) (自動(設定不要)): the default for new works. You can translate without entering any characters. A manner of speech grounded in the subtitles is used only for lines where it is certain who is speaking, and lines where this is unknown are translated without assuming. Settings you corrected by hand take priority.
  • Use only confirmed settings (確認した設定だけ使う): only manners of speech that you checked and adopted yourself are used. This is the same flow as before, where you check the work settings and the style before translating.
  • Don't use (使わない): character materials are not used in translation.

Works where you turned the character feature on or off in an earlier version become “Use only confirmed settings (確認した設定だけ使う)” and “Don't use (使わない)” respectively. Changing the setting does not rewrite lines that are already translated.

“Experimental: Extra Analysis (試験中:追加の解析)” (collapsed) on the same screen has the following 2 options. They are not needed for normal translation, and their effect has not been confirmed yet. Both are off by default. If they cannot be used or fail, the extra analysis is skipped and translation continues.

  • Sort speech by voice on the Mac (Mac内で声ごとに発言を整理する): analyzes the audio on the Mac, splits it into sections by voice, and uses that as a clue to who is speaking. First press “Prepare Model… (モデルを準備…)” to download the speaker analysis model from Hugging Face (it connects only when you press it. Audio and video are not sent). It uses extra time, memory and storage, and its speed on Macs with little memory has not been checked yet. It is not used for videos longer than 3 hours.
  • Assist with images from the video using Codex (sent to OpenAI) (Codexで映像の画像を補助解析する(OpenAIへ送信)): available only when Codex is chosen as the translation engine and the model can handle images. Up to 12 sections at a time, with 3 still frames each (640 pixels or less on the long side), are sent to OpenAI together with the subtitle text as a reference for the scene. When you turn it on, a confirmation about sending images appears. Video and audio files are not sent. When it is on, the app looks at the picture again only at the breaks where it was unsure who is who.

Role names and gender are never decided from the voice or images alone. Analysis results are saved on this Mac.

Review

Reviewing the translation

After translating, have the AI reread the translation in the context of the lines around it. For lines that would be better corrected, it offers a corrected translation as a “suggestion (提案)”. The translation does not change automatically. You decide whether to adopt each one.

Suggestions don't go into the translation until you adopt them. Let's look at them one at a time.

Your guide, Tsumugi

Reviewing the translation

If “AI Reread After Translation (翻訳後のAIの読み直し)” in the Advanced (詳細) tab of Settings is set to the default “Only when translated with the AI on this Mac (recommended) (このMacのAIで訳したときだけ(おすすめ))”, the reread follows the full translation only when you translated with Ollama or LM Studio. Codex translates 40 lines at a time reading the flow, so there is little to correct, and reread suggestions were often worse than the original translation, so by default no reread is done. You can reread at any time with “Have AI reread and make suggestions (AIに読み直させて提案を作る)” from the arrow next to “3 Check and Save (3 確認して保存)”.

  • It looks for translations whose meaning differs from the source text (mixed-up negation, questions, subjects, numbers and so on), names and terms written differently in different places, and translations too long to read.
  • It looks words up in the macOS dictionary (Wisdom English-Japanese Dictionary) on the Mac to check that no word in the source text has been left out of the translation.
  • For English words with very different meanings, such as stock (inventory / shares) and bank (financial bank / riverbank), it tells which meaning fits the scene from the surrounding source-text words. For lines such as one translated as “shares (株)” when the talk is about a shop's inventory, it makes a “word meaning (語の意味)” suggestion. This check does not use AI and also runs in a few seconds after translation.
  • For lines where English (romanized letters) remained in the translation, only that part is turned into Japanese after translating (for example “ゴン・EUNテ” → “ゴン・ウンテ”). English commonly used in Japanese, such as CEO, SNS and OK, is left as it is. Corrected lines get an “Automatically fixed line (自動で直した行)” mark and the reason.
  • A corrected translation is translated back into English to check that the meaning has not changed before it becomes a suggestion.
  • Lines you corrected by hand, marked lines and lines with pending suggestions are not changed.
  • Reviewed sections are saved as it goes. Even if you stop, next time it continues from the sections not yet reviewed.

Using a different AI only for the review

If you normally translate with the AI on your Mac but want to leave only the review to a cloud AI (Codex), choose it in “Check in detail (細かく確かめる)” → “AI for Review (見直しに使うAI)” from the arrow next to “3 Check and Save (3 確認して保存)”.

  • Rereading, rewriting the tone, translating error lines again, and rebuilding the work notes and glossary are done with the chosen AI. Translation stays with the AI in Settings.
  • Quitting the app or choosing “As in Settings (設定どおり)” returns to the AI in Settings.
  • You can choose only engines that you have chosen once in Settings and set a model for. For Codex, you need to have confirmed sending the subtitle text in Settings.
  • When you review with a different AI, sections reviewed before are reread again too.

Checking suggestions

When the review is finished, the number of suggestions is shown by type. “Start Checking (確認を始める)” (or “Check Suggestions (提案を確認する)”) moves to the first suggestion. Lines with a suggestion get a “●” mark, and the list and editing area show the “Current translation (今の訳)” and the “Suggestion (提案)” one above the other (removed characters in red strikethrough, added characters in color). The “13/8字” to the right of the suggestion is the character count if adopted. The reason is also shown for the selected line. The video preview on the left also shows the suggested text of the selected line, looking the same as when adopted (with a “Suggestion preview (not adopted) (提案のプレビュー(未採用))” label at the top left. During normal playback it stays with the current translation). When you move to the next line with the keys, the list scrolls along, with the line you just left at the top and the selected line below it.

ActionKeyResult
Adopt / confirm and go to next⌘↩Adopts a suggestion; for import misalignments, lines fixed by AI and uncertain translations, marks them “Checked (確認済み)”; then moves to the next unhandled line of the same type. For types where you type a translation (such as translation errors), it moves on with the translation you typed. An adopted suggestion can be returned to the current translation with “Revert (元に戻す)” in the editing area
Reject / revert and go to next⇧⌘⌫Rejects a suggestion (the same suggestion will not appear in the next review); for lines fixed by AI and uncertain translations, returns them to before the fix; then moves on
Next / previous unhandled⌘] / ⌘[Moves to a line not yet done of the filtered type (or, if none, the type in “Next step (次にすること)”). After the last one, it goes back to the first
Play this line onlyRPlays the selected line from a little before it to its end, then stops
Check playback⇧⌘RWhen “Import misalignment (取り込みのずれ)” or “Lines fixed by AI (AIが直した行)” is filtered, plays only the unhandled lines in a row from the selected line. When you stop, you can mark all the lines played to the end as checked at once

With the “N suggestions (提案 N 件)” menu above the list, you can filter by type or adopt or reject them all at once (a confirmation appears for both). Right afterwards you can undo with “Undo Adopt All (すべて採用を取り消す)” or “Undo Reject All (すべて却下を取り消す)”.

The counts above the list are arranged in two rows, in the order of the work: “Before saving (保存前に)” (lines that, if left, would put English or mistranslations in the subtitles) and “Optional checks (任意の確認)” (lines you can save without looking at all of them: import misalignments, lines added from audio, suggestions, lines fixed by AI). The small mark on each line has the same shape and color as its count. The “?” to the right of the counts, or “How to Read the List Counts and Marks (一覧の件数と印の見方)” in the Help menu, shows the full explanation. Hovering the pointer over a mark shows the details. Pressing a count lists only those lines and shows what to do and how many are done. With ⌘↩ (confirm and go to next) and ⌘] (next unhandled) in “Check (確認)” in the menu bar, you can deal with them line by line using the keys. For import misalignments and lines fixed by AI, “Check playback (チェック再生)” plays only the unhandled lines in a row, and you can mark the lines you watched as checked all at once.

Every action can also be chosen from “Check (確認)” in the menu bar. When you filter by a count, the actions you can do at once for that type appear below the explanation.

  • Mark All as Checked (まとめて確認済みにする): for import misalignments, only the lines where 2 Japanese subtitles were combined into 1 line and the character count is within the guideline (after confirmation, all of them is also possible). For lines fixed by AI, all of them (a confirmation appears). Uncertain translations and import lines that only partly overlap are not included by default.
  • Merge with Untranslated Neighbor (訳なしの隣の行とまとめる): merges into 1 line the pairs where 1 Japanese subtitle spans 2 English lines and one of them has no translation (the English is joined with a line break, and the display time covers both lines). You can also merge one pair at a time from the editing area.
  • Right after either one, you can undo it all with “Undo … (…を取り消す)”. “Replace All (すべて置換)” does not remove the import misalignment or line fixed by AI marks (because it does not count as looking at each line).

“Next step (次にすること)” looks at the counts in the order of the work to show the next task, and “See … (◯◯を見る)” lists those lines. When the work before saving is finished, “Save Translation SRT… (訳文SRTを保存…)” becomes the main button, and the optional checks move to the “or (または)” side. When you import subtitles and there are lines without translation and import misalignments, it guides you to check the import misalignments before translating (so that dialogue already contained in the Japanese of a neighboring line is not translated again).

Checking first-person pronouns

Because the AI translates from the text of the English subtitles alone, it may use a first-person pronoun that does not suit the speaker, such as “僕” (a male “I”) for a woman's line. “Check in detail (細かく確かめる)” → “Check First-Person Pronouns Line by Line (一人称を1行ずつ確かめる)” from the arrow next to “3 Check and Save (3 確認して保存)” lists only lines whose translation contains a first-person pronoun (僕, 俺, 私, あたし and so on) and shows the pronoun in color. Listen with R, and correct with ⌘1 私, ⌘2 あたし, ⌘3 僕, ⌘4 俺 (the buttons in the editing area do the same) to move to the next line. If it is right, ⌘↩ moves on as is. For lines with 2 people's dialogue in 1 line, you can choose for each word. Corrected lines are treated the same as lines corrected by hand and do not change in later translations. The checked marks are kept in the companion file.

Using work notes and the glossary across drama episodes

When the name of the video or subtitle file has an episode mark (S01E02, 1x02, 第2話, Episode 2 and so on), all episodes of that work share one set of work notes and one glossary. The spellings of names and terms and how characters talk decided in episode 1 are also used in episode 2, and only words appearing for the first time in episode 2 are newly decided. When you correct a spelling, it is used for other episodes too, from the next time you open them and translate or review. The name of the shared work and a “Share with other episodes (ほかの回と共有する)” checkbox appear at the top of the work settings screen. Unchecking it gives that episode its own work notes and glossary.

  • Read All Episodes' Videos to Build… (全話の動画を読んで作る…): select the videos or subtitle files (SRT) of this work together, and the app reads the source text of each episode and combines the glossary (deciding only newly appearing words, in order) and work notes into one. If you stop partway, the finished episodes remain. For episodes without subtitles, first create the source text with “Only turn the dialogue into text (don't translate) (せりふを文字にするだけ(訳さない))” from the arrow next to “2 Make Japanese Subtitles (2 日本語字幕を作る)”, then add them.
  • Read This Episode and Add (この回を読んで足す) (instead of “Rebuild Work Notes (作品メモを作り直す)” in the work notes): reads this episode's source text and adds new characters and this episode's plot to the work notes. The period and setting, style policy, expressions to avoid, and the characters from other episodes stay as they are.
  • “Rebuild (作り直す)” in the glossary decides the spellings again from this episode's source text. Spellings corrected by hand and established spellings stay as they are, whichever episode they came from.

Checking the tone

Because the AI translates without hearing voices or seeing scenes, it may use a tone that does not suit the relationship between characters, such as a subordinate speaking casually to a boss. “Check in detail (細かく確かめる)” → “Check Tone Line by Line (口調を1行ずつ確かめる)” from the arrow next to “3 Check and Save (3 確認して保存)” lists only dialogue lines, adds a tone label decided from the sentence endings (です・ます (polite) / タメ口 (casual) / 混在 (mixed)), and shows the endings in color. Listen with R, and if it does not fit, ⌘5 (です・ます, polite) or ⌘6 (タメ口, casual) makes a draft with only the sentence endings rewritten. The translation does not change yet. Compare the current translation and the draft, and adopt with ⌘↩ or reject with ⇧⌘⌫. If it is right, ⌘↩ moves on as is.

  • Sentence endings with fixed patterns, such as “です→だ”, “〜ています→〜てる” and “〜ください→〜て”, are rewritten on the spot. Others are rewritten by AI, and drafts where words other than the ending, particles, tense, questions or conjecture changed are discarded. For lines where no draft could be made, the reason is shown, so correct them directly in the editing area.
  • To make a whole scene consistent, use ⌥⌘5 / ⌥⌘6. This makes drafts for all lines with a different tone from the current line to the end of the scene (a song, a gap of 5 seconds or more, or up to 20 lines). Reject drafts for other characters' lines one at a time.
  • Songs, on-screen text, lines with only a name, and lines whose tone cannot be decided from the ending get no label. Correct lines with 2 people's dialogue in 1 line directly in the editing area.
  • Adopted lines are treated the same as lines corrected by hand and do not change in later translations. The checked marks are kept in the companion file.

Readability guidelines

For Japanese subtitles, the readability guideline is 4 characters per second, 16 characters per line, up to 2 lines (up to 32 characters per subtitle). While the Japanese translation is shown, each line shows “14/11字” (characters in the translation / characters readable in the display time). Within the guideline it is gray, longer than the guideline orange, and too long to fit in one subtitle red. Lines longer than the guideline also show something like “Too many characters: 18 / guideline 8 (2.0 s) (字数超過:18字/目安8字(2.0秒))”.

Lines whose character count is far over the guideline, and lines with too many characters or lines per subtitle or per line, can be listed alone with “Check in detail (細かく確かめる)” → “See Lines Too Long to Read (長すぎて読み切れない行を見る)” from the arrow next to “3 Check and Save (3 確認して保存)”.

In translation, long translations that do not fit on one line (a one-line translation over 16 characters) are split into 2 lines at a natural position such as a comma or a break in the sentence. When a line translated by Codex is much longer than its display time allows, Codex is asked to translate it again more briefly.

None of these are errors, and they do not affect saving or exporting. Rewriting that cuts meaning to fit the character count is not done automatically. Use them as clues for deciding whether to correct.

Saving

Saving as SRT

Save with “3 Check and Save (3 確認して保存)” (when there are no lines to look at before saving), “Save Japanese Subtitles… (日本語字幕を保存…)” in the arrow to its right, or ⌘S. When the source text is shown, the source text is saved; when the Japanese translation is shown, the Japanese translation is saved (the source text for lines without a translation). If there are lines without a translation when you save the Japanese translation, a screen appears to confirm that those lines will appear in English (the source text) in the subtitles.

  • Save location: the default is the same folder as the video. You can also choose a fixed folder in “Subtitle Save Location (字幕の保存先)” in Settings (設定) → the Basic (基本) tab.
  • File name: it suggests 動画名.generated.en.srt / 動画名.generated.ja.srt (動画名 = the video name), which do not clash with the original SRT. If the same name exists, a number is added.
  • Text encoding: files are always saved as UTF-8. Loading supports UTF-8, UTF-16, Shift_JIS, EUC-JP and Windows-1252.

When only the transcription is finished, “Save Source SRT… (原文SRTを保存…)” appears; when the Japanese subtitles are ready, “Japanese subtitles are ready (日本語字幕ができました)” appears and points you to saving and “Export Video… (動画を書き出す…)”. If you choose “Later (あとで)”, you can keep working without saving.

Industry-format subtitles (punctuation)

KotobaSync's translations use “。” and “、”. In Japanese subtitles for cinemas and streaming, it is common not to use “。” and to show “、” as a space. When you save while the Japanese translation is shown, choosing “Also Save Industry-Format Subtitles (業界書式の字幕も保存する)” on the save screen also saves subtitles written this way as 〜.delivery.ja.srt. The working SRT (with punctuation) is always saved too, so you can keep working as is. To have it on from the start, choose it in “Punctuation for Delivered Japanese Subtitles (納品する日本語字幕の句読点)” in Settings.

Companion files

When there are translation errors, items on hold, suggestions, hand-corrected marks and so on, 〜.srt.translation-review.json (and 〜.srt.speaker-review.json if there are speaker-change candidates) is saved next to the SRT. Loading the translation SRT again brings back the marks and suggestions. When you copy the SRT somewhere else, copy the companion files with it.

Loading existing subtitles

  • Source SRT: loaded as the source-text subtitles.
  • Translation SRT: after loading a source SRT, loads a translation SRT with the same number of entries and times as its pair.
  • Diff translation SRT: puts translations only into lines whose times match exactly. Lines corrected by hand are skipped, and their number is shown.
Export

Exporting a video with subtitles

“Export Video (動画を書き出す)” at the top of the window combines the current video and subtitles into one M4V file. It uses the subtitles you are editing as they are, including unsaved ones. When there are lines without a translation, the export screen shows how many there are and how they are handled (when burned in, they appear in the picture in English (the source text); in a subtitle track, no Japanese subtitle is shown during them).

MethodWhat it doesTime and requirements
Burn in subtitles (字幕を焼き込む)Draws the subtitles into the picture with the same look as the on-screen preview (text size, background opacity, whether the background stays shown, position, shadow). You can choose “Japanese (source text for lines without a translation) (日本語(訳がない行は原文))”, “Source text (原文)” or “Japanese + source text (2 rows) (日本語+原文(2段))”. It looks the same everywhere, but the subtitles cannot be turned offAbout 5–10 minutes for a 2-hour film. No ffmpeg needed
Add as subtitle tracks (字幕トラックとして入れる)Keeps the video and audio as they are and adds 2 subtitle tracks, Japanese and the source text. They can be switched or turned off in QuickTime Player, on iPhone, Apple TV and so on. The look is decided by the playing appQuick. ffmpeg needed
  • When the Japanese translation is included, you can choose “With punctuation (句読点あり)” or “Industry subtitle format (。 omitted, 、 as a space) (字幕の業界書式(。を省き、、は空白))”. The on-screen subtitles do not change.
  • The save location follows the same setting as SRT (by default the same folder as the video). It suggests a name such as 動画名.ja.m4v (動画名 = the video name), and if the same name exists it adds a number instead of overwriting. You can also choose another location with “Change… (変更…)”.
  • When you press “Export (書き出す)”, the progress, elapsed time, estimated time remaining and “Cancel (中止)” appear. Even if you close the screen with “Close and Continue (閉じて続ける)”, the export continues and the progress appears at the top of the window. When it finishes, “Show in Finder (Finderで表示)” appears. If Movie Metadata (an app by the same author that writes information such as the title and plot into videos) is installed, “Open in Movie Metadata (Movie Metadataで開く)” also appears, so you can open the exported video in it right away (when exporting several at once, it appears for each video).
  • For burning in, “Quality and Size (画質と大きさ)” can be chosen from “About the same size as the original video (recommended) (元の動画と同じくらいの大きさ(おすすめ))”, “High quality (about 1.2–1.3 times the original video) (高画質(元の動画の 1.2〜1.3 倍くらい))” and “Compatibility first (H.264, for old TVs, Windows and so on) (互換性重視(H.264。古いテレビ・Windows など向け))”. The first 2 export in HEVC (H.265). At the start of the export it test-exports a few places to estimate the size, and if the file would be too large it compresses a little more. When finished, it shows the sizes of the exported file and the original video side by side.
  • The audio is not re-encoded; it is included as in the original video (if there are several audio tracks in different languages, all are kept).
  • To play HEVC videos on Windows, Microsoft's “HEVC Video Extensions” may be needed. If they will not play, export with “Compatibility first (互換性重視)”.
  • When burning in, you can choose “Blur the original subtitles (元の字幕をぼかす)”. When the video already has subtitles burned in, that area is blurred before the new subtitles are laid on top, so they do not overlap with the original subtitles and become hard to read. The blur lasts from 1 second before a new subtitle appears until 0.7 seconds after it disappears, and scenes without subtitles are not blurred. Even if you make the subtitle background lighter or remove it, the original subtitles become unreadable. The blurred area is the same frame as in “Read the subtitles shown in the picture (画面に映っている字幕を読み取る)”, and you can also set it with “Set Area… (範囲を決める…)” on the export screen. It can also be chosen in “Export Several at Once (まとめて書き出す)”.
  • HDR (10-bit) video is exported in the normal brightness range when burning in.
  • While exporting, the Mac does not go to sleep (the display may turn off).
  • If the export makes no progress at all for 2 minutes or more, it stops and says so. Export again.

Exporting several at once

You can export all episodes of a drama or several films one after another with the same settings. Open it from File (ファイル) → “Export Several at Once… (まとめて書き出す…)” (⇧⌘E) in the menu, or from “Export Other Videos Too… (ほかの動画もまとめて書き出す…)” on the export screen.

  • When a drama episode (a video with S01E02, 第2話 or the like in its name) is open, the episodes of the same drama in the same folder are listed in episode order. With “Add Videos… (動画を追加…)”, you can also add other dramas or films, or the videos of a whole folder, to the same list.
  • The subtitles of each video are read from its saved SRT, just as when you open that video. The list shows for each video whether it is ready, the number of lines without a translation, whether conversion is needed and so on.
  • Videos with unsaved changes and videos already exported with the same settings are listed unchecked. “Open (開く)” opens that video so you can save it. Even if you stop partway, opening it again lists the exported videos unchecked, so you can continue exporting from where you left off.
  • The export method, quality, punctuation and save location are the same for all videos. Below the list, it shows an estimate of the time it will take (about 3–5 minutes for a 1-hour video) and the export size.
  • The export runs separately from the work open in the window. While exporting, you can keep translating or checking other videos. The progress appears at the top of the window.
  • Even if one video cannot be exported, it goes on to the next and shows all the results together at the end. With “Skip This Video (この動画を飛ばす)” or “Stop All (全部やめる)”, the videos already exported remain.
  • For MKV, if there is no converted copy, it is converted before exporting, and the converted copy is deleted after exporting.
Embedded subtitles

Subtitles inside videos, MKV

MKV, WebM and similar files cannot be opened by macOS's playback features. KotobaSync uses the ffmpeg on your Mac to turn them into a playable MP4 before loading them. The original file is only read and is not changed.

Opening MKV and WebM

  • ffmpeg is needed (see Setup).
  • KotobaSync chooses the audio and subtitles before converting (for details, see “Importing subtitles contained in the video” below). Only when there are 2 or more audio tracks and it cannot tell which one has the cast's voices does it ask, before converting, “Which audio track has the cast's voices? (出演者の声は、どの音声ですか)”. Only the chosen audio is put into the MP4 (it is used for playback, transcription and export).
  • By default, the converted video is saved in the same folder as the original video as an MP4 with the same name (LARK.mkv → LARK.mp4). The next time you open it, that MP4 is loaded without converting.
  • The converted MP4 contains no subtitles. So even if you open the MP4, it is treated the same as opening the original MKV next to it, and the subtitles are read from the MKV.
  • Most videos copy the video and audio as they are, so it finishes in about the time it takes to copy the file. Video such as VP9 and AV1 and audio such as DTS, Opus and FLAC are re-encoded, so they take longer.
  • About as much free space as the original file is needed. During conversion, the progress and “Cancel Processing (処理を中止)” appear.

Importing subtitles contained in the video

  • When you open an MKV for the first time, all the text subtitles in it are read during conversion and the subtitles to use as the source text are chosen. The order of choice is: subtitles in the same language as the audio, subtitles in that language with sound-effect descriptions (used with the description lines removed), then English subtitles. If Japanese subtitles are also included, they are placed alongside the source-text lines as the Japanese translation. When there are only Japanese subtitles, they are loaded with their display times and lines as they are, and the video export screen opens.
    • When subtitles have no language tag, the language is judged from the subtitle text.
    • The “forced” tag marks subtitles only for scenes where another language is spoken. Even with this tag, subtitles that have all the dialogue for the whole video are treated as ordinary subtitles.
    • When there are only subtitles in a language different from both the audio and English, they are not loaded and the “What do you want to translate into Japanese from? (何から日本語に訳しますか)” screen opens. For a series, the language chosen for the previous episode is not asked again for the next one.
    • When the subtitles are images only (PGS, VobSub), the “Choose the audio and subtitles to use (使う音声と字幕を選んでください)” screen appears before converting. You can choose from transcribing without extracting the subtitles, source text only, source text and Japanese translation, or Japanese translation only.
  • What was used as the source text appears in “Source: … (原文:…)” above the list and in “Next step (次にすること)”. Pressing “Change Source… (原文を替える…)” lets you switch to subtitles in the video (with language and number of lines), subtitle files nearby, or transcription. If subtitles more accurate than the current source text have been found, they are selected first.
  • The chosen text subtitles are loaded during conversion, and image subtitles (PGS, VobSub) are turned into text with OCR after conversion. The loaded subtitles are written out with names such as LARK.extracted.en.srt and LARK.extracted.ja.srt.
  • From the second time on, the written-out subtitles are loaded. If an SRT saved in KotobaSync is newer, that one is loaded instead, so you can continue editing where you left off.
  • However, when KotobaSync chose the subtitles itself and not a single line has been translated or corrected yet, the subtitles are read again when you reopen the video. If more accurate subtitles exist, it switches to them and tells you in a notice. Subtitles you chose yourself, with “Change Source… (原文を替える…)” or the like, are remembered for each video and not switched.
  • OCR of image subtitles takes from a few minutes to over ten minutes for a 2-hour film, and reading errors may remain, so play the video to check. When you reopen a converted MP4 and the subtitles are images only, a confirmation screen appears and you can import them with “Read with OCR (OCRで読み取る)”.
  • When an MP4 contains subtitles, a confirmation screen appears when you open it.
  • With “Load Subtitles (字幕を読み込む)” → “Load Subtitles in Video… (動画内の字幕を読み込む…)”, you can choose the subtitles to use again.

Japanese subtitles are put into the source-text line whose display time overlaps them the most. English and Japanese subtitles differ in how they are divided and in their times, so lines with a misalignment get a “⇄” mark and their number appears in “Import misalignment (取り込みのずれ)” above the list (an optional check). Pairs where 1 Japanese subtitle spans 2 English lines and one of them has no translation can be made into 1 line with “Merge with Untranslated Neighbor (訳なしの隣の行とまとめる)”. Imported Japanese is not rewritten by later reviews. The mark disappears when you correct the line or press “Mark as Checked (確認済みにする)” in the editing area. Japanese subtitles that do not overlap any source-text line are not imported and are listed on the confirmation screen.

Settings

Settings

Open them with “Settings (設定)” at the top of the window. They are divided into 3 tabs: “Basic (基本)”, “Subtitle Appearance (字幕の見た目)” and “Advanced (詳細)”. The style chosen for each work is not in Settings but on the “Name spellings and how to translate (work notes)… (人名の表記と訳し方(作品メモ)…)” screen and the style check screen.

TabItemDefault
Basic (基本)Translation engine (see Setup). Under “Details (when translating on this Mac) (詳細(このMacで訳すとき))” for Ollama and LM Studio: the local translation unit, and checking meaning and subtitle alignment after generatingChosen automatically on a new Mac · 8 lines · on
Basic (基本)Look up information about the work on Wikipedia when a video is opened. Saving, re-entering and deleting the TMDb API key is also done here—
Basic (基本)Subtitle save location (same folder as the video, or a chosen folder). MP4s converted from MKV and SRTs made from subtitles in videos are also saved hereSame folder as the video
Advanced (詳細)Transcription: recognition method (Whisper, Apple Speech), model, audio languageWhisper · automatic detection
Advanced (詳細)ffmpeg locationFound automatically
Advanced (詳細)AI reread after translation (only when translated with the AI on this Mac, always, never)Only when translated with the AI on this Mac
Advanced (詳細)During full translation, move the video position to the line being translatedOn
Advanced (詳細)Punctuation for delivered Japanese subtitles (with punctuation, industry subtitle format)With punctuation
Subtitle Appearance (字幕の見た目)Text size, position, fine vertical adjustment, background opacity (kept the next time you open the app)28 pt · bottom · no adjustment · 60%
Subtitle Appearance (字幕の見た目)The subtitle background is 2 lines high even for a one-line subtitle, and a single line appears vertically centered. Keep the background shown even where there are no subtitles: when on, that background stays on screen as a band 2 lines high, and the subtitles change on top of it (the band becomes taller only during subtitles of 3 lines or more). It is also included in videos exported with burned-in subtitles. To hide subtitles burned into the picture, set the background opacity to 100% and lay the band over them with the position and fine vertical adjustment (kept the next time you open the app)Off
Subtitle Appearance (字幕の見た目)Add a shadow to the text (returns to the default each time you open the app)On

Updates

  • KotobaSync asks the official site (k386.sub.jp) whether there is a new version shortly after launch if 24 hours or more have passed since the last check, and then once a day after that.
  • When there is a new version, it downloads it in the background and checks the SHA-256, the Developer ID signature and Apple notarization (1.2.1 and later). It never restarts while you work; the new version is put in place the next time you quit the app. The next time you open it, it tells you that it was updated and what changed.
  • To update right away, choose “Check for Updates… (アップデートを確認…)” in the app menu (“ことばシンク” at the top left of the screen) and press “Restart and Update Now (今すぐ再起動して更新)”. If there are unsaved subtitles, it asks you first.
  • Automatic checking can be turned off with “Automatically Check for Updates (アップデートを自動で確認)”, and automatic replacement with “Automatically Install Updates (アップデートを自動でインストール)” (both in the app menu). When automatic replacement is off, a notice with “Update and Relaunch (更新して再起動)”, “Later (あとで)” and “Download Page (ダウンロードのページ)” appears when there is a new version.
  • If you open the app from somewhere other than the Applications folder (such as inside the disk image), or you do not have permission to replace it, it cannot update automatically. Install the new version from the download page.
  • You can check the app's version with “About This App (このアプリについて)” in the app menu.
Troubleshooting

Troubleshooting

When something does not work, the notification briefly says what happened and what to do next. When you contact us, paste the content taken out with “Copy Details (詳しい情報をコピー)”.

First, check that everything in the setup list shows “✓”.

Your guide, Tsumugi
Transcription does not start when I press “2 Make Japanese Subtitles (2 日本語字幕を作る)”

Check that you have downloaded the transcription model. You can download it in “Model (モデル)” in Settings (設定) → the Advanced (詳細) tab. Downloading needs an internet connection.

Transcription is slow

Larger models take longer. If you only want to check that it works, try tiny or base. Long videos are processed 5 minutes at a time, so you can see how much is left in the progress display.

Apple Speech cannot be used

Apple Speech can be used only for languages that can be recognized on the Mac alone. macOS “Speech Recognition” permission is also needed. If it is not available for your Mac or language, set “Recognition Method (認識方式)” back to Whisper.

The app cannot connect to the translation engine

For Ollama, check that the app is installed and a model has been downloaded. For LM Studio, check that “Start server” is on on the “Developer” screen. For Codex, check that you are signed in by running codex login in Terminal. Then press “Refresh Connection and Model List (接続・モデル一覧を更新)” in Settings (設定) → the Basic (基本) tab.

The translation is strange or the meaning is wrong

Translation quality depends on the model you use. If the style check does not feel right, change the style or the notes on how characters talk. Spellings of names can be corrected in the glossary. After translating, the suggestions from “Have AI reread and make suggestions (AIに読み直させて提案を作る)” are also a clue. In the end, play the video to check and correct by hand if needed.

The translation stopped partway

The translated lines remain. Press “2 Continue (N left) (2 続きを作る(残りN件))” to continue from where it stopped. If the translation engine is not responding, check that the engine is running before pressing it.

I cannot open MKV or WebM

ffmpeg is needed. Run brew install ffmpeg in Terminal, then open the file again. If ffmpeg is installed somewhere else, choose it in “ffmpeg Location (ffmpegの場所)” in Settings (設定) → the Advanced (詳細) tab. Conversion needs about as much free space as the original file.

I cannot export with “Add as subtitle tracks (字幕トラックとして入れる)”

Exporting subtitle tracks needs ffmpeg. Without ffmpeg, you can export with “Burn in subtitles (字幕を焼き込む)” (ffmpeg is not needed).

When I reopened the video, the saved Japanese translation did not appear

Saved Japanese subtitles (動画名.generated.ja.srt) are loaded as saved if the number of lines and the times match the source text. When the number of lines or the times do not match, for example because you corrected the source-text times but did not save the source text, they cannot be loaded, and the file that could not be loaded and the reason (such as “The time of subtitle 12 does not match (字幕12の時刻が一致しません)”) are shown. The file is not deleted, so save the source SRT again too, then reopen.

Up to 1.2.8, there was a bug where, if there was a line with two people's short remarks translated briefly (such as “- え?” “- 今?”), the file was not loaded without any notice (fixed in 1.2.9). Up to 1.2.9, translations imported from a film's Japanese subtitles were likewise not loaded if they had lines broken per speaker without “-” or lines with converted units such as “25メートル” (25 meters) (fixed in 1.2.10).

The app crashed and my work may be lost

Unsaved subtitles are saved automatically 3 seconds after a change. Reopen the same video (or SRT), and when “Your previous work remains (前回の作業が残っています)” appears, press “Restore (復元する)”. The 20 most recent autosaves are kept.

When I loaded a saved SRT, the marks and suggestions were gone

Marks and suggestions are saved in the companion file next to the SRT (〜.srt.translation-review.json). If you copied only the SRT somewhere else, copy the companion file to the same place too.

I cannot update / “Could not update (更新できませんでした)” appears

If you open the app from somewhere other than the Applications folder (such as inside the disk image), it cannot update itself from within the app. Copy it to the Applications folder and open it again. When there is no internet connection, or the file could not be verified, nothing is changed. To install right away, replace the app with the new DMG from the download page.

Where are the files the app creates?

Saved SRTs, MP4s converted from MKV and exported M4Vs are, by default, in the same folder as the video. Everything else is in the following places (the folder name is SubtitleStudio for compatibility with earlier versions).

  • Transcription models: ~/Library/Application Support/SubtitleStudio/Models
  • Autosave: ~/Library/Application Support/SubtitleStudio/Autosave
  • Partially saved translations, glossaries, work notes: ~/Library/Application Support/SubtitleStudio/TranslationCheckpoints
  • Settings: ~/Library/Preferences/com.subtitle.studio.plist
Glossary

Terms

SRT
A common subtitle file format that lists subtitle numbers, display times and text. It can be loaded by many video players and editing programs.
Transcription
Listening to a video's audio and turning it into text. KotobaSync runs Whisper (whisper.cpp) on your Mac.
Whisper model
The data used for transcription. Larger models tend to be more accurate but use more time and memory.
Translation engine
Software that produces the Japanese translation. KotobaSync uses Ollama or LM Studio (running on your Mac), or Codex (running in OpenAI's cloud).
ffmpeg
Free software that converts video and audio formats. It is used to convert MKV and similar files and to export subtitle tracks.
MKV
A video file format that can combine video, audio and subtitles in one file. It may contain several subtitle tracks.
Burning in
Drawing the subtitles into the picture itself. They look the same wherever the video is played, but they cannot be turned off.
Subtitle track
Subtitles placed inside the video file, separate from the picture. The playing app can show or hide them and switch languages.
OCR (text recognition)
Reading the text in an image and turning it into text. KotobaSync uses macOS text recognition (Vision) on your Mac.
Glossary
A table for keeping the spellings of names of people, places and so on the same throughout a work.
Work notes
Notes summing up the work's plot, period, mood, how characters talk and so on. They are used to keep the wording of the translation consistent.
Suggestion
A proposed corrected translation that comes out of the review. The translation does not change until you adopt it.
Industry format
The style common in Japanese subtitles for cinemas and streaming. It does not use “。” and shows “、” as a space.