Jitsi transcription or subtitles not working

This page covers five symptoms in an existing Jigasi/Vosk configuration, using the platform’s stable-11031 setup as its reference. The commands below assume your deployment already uses jigasi-override.yml and vosk.yml; run them from that deployment directory. Use your actual Compose file list if it differs.

For a new installation, read the bridge-based transcription guide. The Jitsi handbook marks Jigasi transcription as deprecated. The same release also provides a separate transcriber.yml: do not apply a custom jigasi overlay blindly to a service named transcriber.

Check the logs first:

docker compose -f docker-compose.yml -f jigasi.yml -f jigasi-override.yml -f vosk.yml logs --tail 200 jigasi vosk

Symptom 1: service-unavailable when enabling subtitles

Possible cause: the stable-11031 jigasi.yml sets JIGASI_MODE=sip. That service is a SIP gateway. The separate transcriber.yml already sets transcriber mode. Also check that the intended service is running and can authenticate; the browser message alone does not prove a mode error. Source: release Compose files.

Fix: override the mode.

# jigasi-override.yml
services:
  jigasi:
    environment:
      - JIGASI_MODE=transcriber
      - JIGASI_TRANSCRIBER_PASSWORD

docker compose -f docker-compose.yml -f jigasi.yml -f jigasi-override.yml -f vosk.yml up -d jigasi

Symptom 2: “SASLError using SCRAM-SHA-1: not-authorized”

Possible cause: the transcriber password is missing or differs from the Prosody account. Confirm the failed account in the logs: a failure for another service account needs a different fix. The hidden domain may differ from hidden.meet.jitsi on your installation.

Fix: set a unique password in .env, ensure it reaches both services, and apply the change during a maintenance window. Recreating Prosody interrupts active meetings. A plain restart does not reload changed Compose environment values:

JIGASI_TRANSCRIBER_PASSWORD=a-long-random-password

docker compose -f docker-compose.yml -f jigasi.yml -f jigasi-override.yml -f vosk.yml up -d --force-recreate prosody jigasi

Symptom 3: transcripts with join events but no words

Possible cause: Jigasi cannot reach the selected speech backend, or its effective configuration points to the wrong one. In our custom setup, Jigasi reads vosk.websocket_url with an underscore; vosk.websocket.url does not configure that property. Inspect the effective configuration locally without sharing credentials. The release’s transcriber template also supports JIGASI_TRANSCRIBER_CUSTOM_SERVICE and JIGASI_TRANSCRIBER_VOSK_URL; a custom properties file is not the only supported route.

Fix for our custom overlay: create this file under the existing ${CONFIG}/jigasi directory, which jigasi.yml mounts as /config. The startup script appends custom-sip-communicator.properties to the generated configuration. Replace conflicting settings rather than configuring both routes differently:

# config/jigasi/custom-sip-communicator.properties
org.jitsi.jigasi.transcription.customService=org.jitsi.jigasi.transcription.VoskTranscriptionService
org.jitsi.jigasi.transcription.vosk.websocket_url=ws://vosk:2700
org.jitsi.jigasi.transcription.DIRECTORY=/config/transcripts
org.jitsi.jigasi.transcription.SAVE_TXT=true

Symptom 4: Vosk keeps restarting

Possible cause: the selected model exceeds available memory. A restart alone is not proof of an out-of-memory failure; inspect the container state and Vosk logs first.

Check: identify the Vosk container with docker compose -f vosk.yml ps -q vosk, then run docker inspect --format '{{.State.OOMKilled}}' <vosk-container-id> with that ID. Do not type the angle-bracket placeholder literally. Check docker stats --no-stream and the host’s available memory too.

Fix: size the host for the actual model plus Jitsi and concurrent sessions. Vosk documents small models using about 300 MB at runtime and large models needing up to 16 GB. Our 16 GB starting point for the larger English setup is not a minimum for every Vosk model or a capacity guarantee.

Symptom 5: captions work, but no transcript file

Check that /config/transcripts exists inside the Jigasi container and is mapped to a host folder, and that SAVE_TXT=true is set. Transcripts are written when the meeting ends.

That path belongs to our custom configuration below. The stock stable-11031 transcriber template uses /tmp/transcripts. Check the effective org.jitsi.jigasi.transcription.DIRECTORY and its volume mapping rather than assuming either path. Source: transcriber template.

Verify the fix

Start a new test meeting, enable transcription and speak a short sentence. Confirm that captions contain speech, then end the meeting and check the configured host transcript folder. Review recent Jigasi and Vosk logs for connection or authentication failures. Remove passwords, tokens, meeting names and participant details before sharing logs.

Full setup

The complete, working configuration is in free self-hosted transcription with Jigasi and Vosk. If you would rather not debug it, our transcription service sets it up on your server, and on our platform it is a one-time $29 feature.