Appendix: the file clients

LiveCaption gives live captions of what is being said right now. If you want to subtitle or translate existing files instead – a recorded lecture, a whole video folder, a subtitle file or a document –, the product's command-line clients are the tool. They use the same servers as LiveCaption: the caption service (captionserver) and the translator (translatorserver).

This appendix gives an overview; the detailed, step-by-step description is in two guides on the website: Batch subtitling a video folder into SRT and Translating subtitle files, markdown and resource files.

What you need

• The servers: for subtitling the caption service, for translation the translator must be running – on your machine or on the network. Starting them is described in the Daily start and stop chapter of the server manual.
• A key: the servers authenticate every request. The scripts have their own key, issued into a persistent environment variable by the generate-api-key launcher in the product's root folder; the subtitling scripts call it themselves if they find no key.
• FFmpeg: the subtitling client uses it to extract the audio from a video. If it is missing, the client offers to download it.
• PowerShell 7: the scripts run on it. On Windows the .cmd launchers can be started with a double click, on macOS their .command twins from the Finder; from a terminal, call the .ps1 script (pwsh).

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

The first line asks for a key for every service, the second for the caption service only, the third replaces an existing one too. On macOS the same is generate-api-key.command.

Subtitling one file

The caption service's launchers are in the CaptionServer folder. For a single video or audio file you can choose between two:

Launcher	How it works	When
transcribe	splits the audio into pieces cut at silences, and sends the pieces in parallel	when several people share the server, or the server runs without a graphics card
transcribe-whole	sends the whole audio in a single request	for the best quality of one file: no cutting, no context lost

Both have language-bound variants (transcribe-hu, transcribe-en, transcribe-whole-hu, transcribe-whole-en) that set the speech language in advance. On Windows you can simply drag the file onto the launcher.

Subtitling a folder

transcribe-folder subtitles every audio and video file in a folder. It starts a separate client for each file, skips the files already done (those with an .srt newer than the source next to them), and sums up at the end.

.\transcribe-folder.ps1 "C:\videos" -Whole -Language hu -Recurse
.\transcribe-folder.ps1 "C:\videos" -Clients 4 -Windows
pwsh ./transcribe-folder.ps1 ~/Movies/lectures -Whole -Language hu,en

The main switches:

• -Whole: whole mode, for the best quality.
• -Language: the speech language – a code (hu) fixes it, auto asks for detection, a candidate list like hu,en detects among those only.
• -Recurse: the files of the subfolders too.
• -Clients: how many files run at once; by default the script matches it to the server's capacity.
• -Filter and -Force: filtering by file name, and overwriting finished subtitles.
• -Windows and -Quiet: a separate window per client, or summary lines only – for unattended runs.

Before starting, the script checks once: is FFmpeg there, and can the server be reached? If something is missing, the batch does not start, and you get one readable error – not one for every file. Ctrl+C stops the run.

The subtitle file's name

The subtitles go next to the input, marked with the language: lecture.mp4 → lecture.hu.srt in Hungarian, lecture.eng.srt in English. Most players (VLC, Plex, Jellyfin, Kodi) find subtitles named like this on their own. With detection, the name is decided after detection; if there is no recognisable speech, the name is lecture.srt. The -NoLanguageSuffix switch leaves the language mark out.

Translating subtitles and documents

There are three translation clients; their launchers are in the TranslatorServer folder:

Launcher	What it translates	What stays unchanged
translate-subtitle	subtitles: .srt, .vtt, .ass/.ssa	the timing, the number of blocks, the formatting tags – only the text changes
translate-markdown	markdown documents: .md	the structure, the code, the link targets; comments in code blocks are translated by default
translate-resx	resource files: .resx, PowerShell messages.psd1	the keys, the placeholders ({0}); by default only the missing keys are translated

Do not type the key on the command line (it would end up in the shell history); put it in an environment variable, and give the variable's name with the -ApiKeyEnv switch:

$env:LCP_TRANSLATE_KEY = "lcp_..."
TranslatorServer\translate-subtitle.cmd "C:\videos\01 - Introduction.eng.srt" -ApiKeyEnv LCP_TRANSLATE_KEY
TranslatorServer\translate-markdown.cmd "C:\docs\README.md" -ApiKeyEnv LCP_TRANSLATE_KEY --to hu

--from and --to set the language pair, --server the translator's address (by default http://127.0.0.1:8080). Without an output name, the translation goes next to the input, with the language code swapped: 01 - Introduction.eng.srt → 01 - Introduction.hu.srt. Given a folder, the whole folder is translated; files already done are skipped, and the same command resumes an interrupted run.

The --check switch checks, without translation and without a server, that the file can be written back without a change; --dry-run shows what would be translated, without translating.

Exit codes

The clients and the scripts exit with the same codes, so other scripts can use them as conditions:

Code	What it means
0	done, everything succeeded
1	wrong usage (a bad switch, an unknown model or language), or only the help was asked for
2	the input file does not exist
3	FFmpeg cannot be run or stopped with an error (subtitling only)
4	another error; for a folder run: at least one file failed
5	the user interrupted it (Ctrl+C)
6	the server cannot be reached, or returned a permanent error

Where next

• Step by step: Batch subtitling a video folder into SRT
• Step by step: Translating subtitle files, markdown and resource files
• Issuing keys and their rights: Keys and permissions