Subtitling a video folder to SRT

How it works

Batch subtitling is server–client: the caption server (captionserver) loads the Whisper models once – onto the graphics card, if there is one – and serves several clients in parallel; the client (captionclient) sends the video's audio in chunks cut at silence or in one piece, and writes an SRT subtitle next to the video. The transcribe-folder.ps1 script starts a separate client for every media file in the folder, skips the files already done (an .srt newer than the source exists), and sums up at the end.

Preparations

The caption server authenticates, so the account service has to be running – the first start guide describes that. The scripts have their own key, issued by generate-api-key.cmd into a persistent environment variable; the transcribe* scripts call it themselves if they find no key.

generate-api-key.cmd
generate-api-key.cmd -Service caption
generate-api-key.cmd -Service caption -Force

The client needs FFmpeg to extract the audio; if it is missing, the client's own installer supplies it (captionclient --install-ffmpeg), and the preflight check also offers the download.

Starting the server

cd CaptionServer
.\start-captionserver.ps1
.\start-captionserver.ps1 -Preload large-v3 -Tune

The server runs in one window, Ctrl+C stops it. By default it loads and measures the models listed in its settings; -Tune measures the best pool size at start-up, that is, how many chunks it processes at once. start-captionserver.cmd starts it with a double click. If it is not running, the batch's preflight check offers to start it and waits for it to load.

Subtitling the folder

.\transcribe-folder.ps1 "C:\videok" -Whole -Language hu -Recurse
.\transcribe-folder.ps1 "C:\videok" -Clients 4 -Windows
.\transcribe-folder.ps1 "C:\videok" -Clients 3 -Whole

The more important switches:

• -Clients auto (the default): the number of clients is the smallest of the server's pool, the number of files and 16, and the pool is divided among the clients. With a manual -Clients <n> every client asks for the whole pool, and the surplus requests queue on the server.
• -Recurse: subfolders too.
• -Whole: whole mode – the file goes in a single request, for the best quality. In a batch always give it as a switch.
• -Language hu: the subtitle's language; auto asks for detection, the hu,en candidate list detects only among these.
• -Filter, -Force: filtering by file name, and overwriting finished subtitles.

The same with a double click: transcribe-folder.cmd.

The preflight check

Before starting the clients, the script runs the client once in check mode (captionclient --check): it looks at FFmpeg, the server's reachability, and asks for the pool size. If it finds a fault, the batch does not start, and stops with the client's exit code – one readable report instead of N clients' errors. This is the batch's only point that can ask questions; for unattended runs give the -Yes or the -NonInteractive switch, or use the -Quiet view. If the server is not ready within ten minutes, the batch stops with 6, but the server keeps loading: start the batch again.

The three views

Ctrl+C also stops the running clients gracefully – except in the -Windows view, where the script stops them by force.

The subtitle file's name

The subtitle goes next to the input, with the language mark: eloadas.mp4 → eloadas.hu.srt in Hungarian, eloadas.eng.srt in English. Players (VLC, Plex, Jellyfin, Kodi) find a subtitle named like this by themselves. In detection mode the name is decided after detection; if there is no recognisable speech, the name is a plain eloadas.srt. -NoLanguageSuffix leaves the mark out. Sources with the same name and a different extension get separate names: talk.mp4 → talk.hu.srt, talk.wav → talk.wav.hu.srt.

Exit codes

The batch script ends with 0 if every file succeeded, with 1 on a bad parameter, otherwise with 4, and lists the failed files' codes and logs. If the preflight check fails, the script stops with its code. The client's codes:

Translating the finished files: translating subtitles and documents.