First start on a clean machine

Who this guide is for

Live Caption Pro has no public installer and no downloadable package: these steps are for people who received access to the source repository. A "clean machine" is a fresh Windows or a Mac with Apple silicon (macOS 14.2 or later) with a clone of the repository and nothing else – the platform checks every prerequisite itself even then. The requirements (graphics card, .NET 10 SDK, PowerShell 7, winget on Windows, Homebrew on macOS) are on the installation page, per platform; this guide is about the order. Where macOS differs, a separate paragraph and command block at the end of the step says how – there the .cmd launchers are paired with clickable .command files.

The steps refer to these names:

1. Checking and completing the environment

The first command changes nothing: it reports what is present, what is missing, and what the command to fix it is.

check-environment.cmd
check-environment.cmd -Components voice
check-environment.cmd -Fix
check-environment.cmd -Fix -Yes

The fix mode (-Fix) asks item by item, saying in advance how large the download is and whether it needs administrator rights – today only the virtual audio cable does; everything else installs as your own user. -Yes also accepts the winget agreements and the CPML licence of the voice engine's XTTS-v2 model (non-commercial use) on your behalf, so give it knowingly. winget itself is a prerequisite the framework cannot supply; on Windows 10 and LTSC editions install it by hand once.

Marks: + present, ! missing and required, - missing but optional, ? undecidable. The exit code is 0 when every required item is present.

On macOS PowerShell 7 comes first: without it no launcher starts. After that the same report runs from check-environment.command (a double-click in the Finder works too). The missing items – the .NET SDK, Python, FFmpeg, the BlackHole virtual cable and the database – the fix mode does not install by itself, because they may ask for an administrator password: it prints the command that installs them, Microsoft's install script (dotnet-install.sh) for the .NET SDK and the Homebrew command for the rest. The .NET SDK can also be installed from Homebrew (below).

brew install --cask powershell
brew install --cask dotnet-sdk
brew install uv
brew install ffmpeg
brew install --cask blackhole-2ch
brew install postgresql@18
./check-environment.command
./check-environment.command -Fix

2. The first start of the account service

All three services authenticate, and users and keys live in the account service – so it starts first. The account service keeps its data in a PostgreSQL database, which the repository's launcher runs in the machine's Docker (this needs Docker Desktop – on Windows with WSL; if it is missing, check-environment.cmd -Fix -Components account installs it, and the launcher prints the command). The order is fixed:

1. Bring up the database: AccountServer\managed-postgres.cmd. The first run asks whether it may create the container, then prepares the database and writes two user environment variables: the connection details and the encryption key of the web sign-in keys – both are secrets. At the end it checks that the account service can really connect.
2. Start the account service in its own, visible window: AccountServer\start-accountserver.cmd. The first start creates an admin user and prints its random password once, here, never to a log. It also prints a secret-free description of the database connection (host, port, database, user). By default the machine API listens on all network interfaces; if it is only needed on this machine, start it with the -HostName localhost switch. If you redirect the output to a file, the password ends up in that file – delete it after reading.
3. Log in at http://127.0.0.1:8101/admin; the interface immediately asks for a new password.
4. Give the clients a key: start-accountserver.ps1 -KeyAdd <user>, or the web Keys page.
5. Review the users and the keys on the interface.
6. Obtain the peer tokens of the three services: setup-account-peers.ps1 -Tokens, then -Check.
7. -Check runs an authenticated test – the only proof that the services really receive a permission snapshot.
8. Activation: setup-account-peers.ps1 -Activate. This writes the LCP_ACCOUNT_URL variable – windows already running do not see it, so close every open window.
9. Restart the services with the daily launcher (step 4); the account service's launcher also brings up the database, before the account service.

AccountServer\managed-postgres.cmd
AccountServer\start-accountserver.cmd
AccountServer\setup-account-peers.ps1 -Tokens
AccountServer\setup-account-peers.ps1 -Check
AccountServer\setup-account-peers.ps1 -Activate

On macOS the database needs no Docker: managed-postgres.command creates a native cluster of its own with Homebrew's postgresql@18 programs, in its own folder under the data root and on the loopback address only. The other steps are the same, with the .command pair instead of the .cmd, with the same switches. On macOS the persistent environment variables go into the user's environment file (~/.config/live-caption-pro/environment), and the launchers read them from it.

AccountServer/managed-postgres.command
AccountServer/start-accountserver.command
AccountServer/setup-account-peers.command -Tokens
AccountServer/setup-account-peers.command -Check
AccountServer/setup-account-peers.command -Activate

If the password is lost, the way out on the same machine is start-accountserver.ps1 -UserPassword admin. Roles and keys are covered by the accounts, keys and permissions guide.

3. The scripts' key

The command-line scripts (subtitling, translation) have their own key, issued by generate-api-key.cmd. The key goes into a persistent user environment variable, one per service (LCP_SCRIPT_KEY_CAPTIONSERVER, …_TRANSLATORSERVER, …_VOICESERVER), and is shown nowhere – not on screen, not in a log.

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

Nothing overwrites an existing key: only -Force replaces it. Windows opened after this see the new variable.

On macOS generate-api-key.command issues it, with the same switches; the key goes into the persistent environment file.

./generate-api-key.command
./generate-api-key.command -Service caption

4. The daily start

The daily start has two steps: first the background services, then the caption window.

launch-system.cmd in the repository root (on macOS launch-system.command) brings up only the four background services, in the fixed order: the account service (with its database before it, if that is the machine's own container), then translator and voice service in parallel, finally the caption server. The order is fixed because the caption server sizes its model pool to the free video memory, so the other two must claim theirs first. Each service starts in its own window, with the same launcher that starts it on its own (for example CaptionServer\start-captionserver.cmd), and the script waits until they really serve (503 loading while the model loads). Whatever is already running is not started again. The first run needs the internet to download the Whisper model; after that everything works offline.

The caption window is started separately by LiveCaption\start-livecaptionpro.cmd (on macOS LiveCaption/start-livecaptionpro-avalonia.command): it publishes the program if it is missing or out of date, and starts it. One caption window runs per machine: if one is already running, the script warns and exits with code 7.

launch-system.cmd
LiveCaption\start-livecaptionpro.cmd
launch-system.cmd -NoTranslator -NoVoice

Services can be skipped with the -NoAccount, -NoTranslator, -NoVoice and -NoCaption switches – that is also how to leave out whatever runs on another machine. On a server machine the daily start is launch-system.cmd alone, without a caption window. The account service is started only if LCP_ACCOUNT_URL points to this machine. Its counterpart for stopping is stop-system.cmd: it stops the four services, not the caption window.

On macOS launch-system.command starts the services in Terminal windows, so a graphical session is needed (this does not work over SSH). Publishing produces a self-contained LiveCaption Pro.app bundle in the LiveCaption/LiveCaption.Avalonia/bin/publish-osx-arm64/ folder; it can also be started from the Finder, or from the Dock after dragging it there, and while it runs it lives in the menu bar. macOS ties recording the microphone and the system audio to a permission, and gives it to whoever is responsible for the launch: the terminal application (Terminal, iTerm) when started from a script, Live Caption Pro itself for the bundle started from the Finder. The program encrypts the keys with a key kept in the macOS Keychain – if the Keychain asks for access, allow it. On a Mac without a display the services run, the caption window does not.

./launch-system.command
LiveCaption/start-livecaptionpro-avalonia.command
./stop-system.command

If you get stuck

The most common symptoms and the ways out are in the troubleshooting guide; if there is no answer there, write to us.