Reference / Archive & integrations
Telegram Media OCR & Audio Transcription
Recognize captured images and audio with a local worker; keep derived text linked to its source file.
TgWitness / Documentation · Investigation
Open a media.saved journal record, choose Recognize attachment, then select
OCR or transcription under More tools → Ask the archive (named Machine recognition
while archive AI is off). Processing is manual and local.
There is no cloud media mode or automatic upload. Original attachment bytes and
media_sha256 remain unchanged; recognized text is explicitly marked as machine
recognition and stored separately with the source hash, engine/model version,
language, parameters and completion time. Transcripts retain returned timestamps.
Search these results using Search recognized text and the OCR/transcript filter, or choose recognized text as the source of a Journal best-match search. Both match word forms through an in-memory index. This is a separate derived-data search; it does not silently turn machine recognition into original Telegram text or add it to signed events.
Set up the optional worker#
Version 1 requires a Linux host with a local Docker daemon. Windows installations can run TgWitness inside a Linux VM/WSL environment with its own local daemon. The panel never decodes an untrusted attachment itself.
docker build -f deploy/media-worker/Dockerfile -t tgwitness-media:local .
export TGWITNESS_MEDIA_IMAGE=tgwitness-media:local
Set these variables in the TgWitness service environment and restart it. The
daemon socket defaults to /var/run/docker.sock; rootless deployments can set
TGWITNESS_DOCKER_SOCKET. The worker explicitly uses that Unix socket rather
than a remote Docker context. Do not expose a Docker API to panel users or mount
its socket inside the recognition container.
For transcription, separately install a CTranslate2-compatible Whisper model,
then set TGWITNESS_WHISPER_MODEL_DIR to its directory. The worker loads it with
local_files_only=True; the selected model and input are mounted read-only.
See the engine's model-loading documentation.
The supplied OCR image includes English and Russian trained data. Build another
language into your image when needed; language codes follow
Tesseract's CLI.
No model is fetched while processing. Build/download setup may use the network;
each actual recognition container has networking disabled. Install the image
before enabling it; runtime uses --pull=never.
Bounds and recovery#
The container runs as an unprivileged user with a read-only root, dropped
capabilities, no-new-privileges, one CPU, 2 GiB memory, a PID limit and a bounded
temporary filesystem. Only a verified copy of the selected file and an optional
model directory are mounted. The collector's database, vault and session are
not mounted. The Docker runtime flags
enforce these limits; this remains a container boundary, not a hardware enclave.
Files are limited to 50 MiB, images to 20 million pixels, audio to 30 minutes with a known duration, and processing to five minutes. One worker runs at a time, with at most 20 queued/running jobs and 100 retained jobs per workspace. Cancel stops the container; retry creates a new job linked to the prior attempt. Interrupted jobs are marked after restart. Processing can fail when a model cannot fit the configured limits; it does not silently run without isolation.