Directory watcher

Optional directory watcher (roadmap G2) notices new files in a monitored inbox and runs New → Import for transcripts (and queues audio for later Transcribe → Import). Default off. Configure in Settings → Watcher or via config_dir/watcher.json / TRANSCRIPTX_WATCHER_* env.

Behaviour

Kind

Mode

Action

Transcript (.json/.srt/.vtt/.txt/.html)

auto_import (default when enabled)

Stabilize → classify → admit_and_register

Transcript

offer / ignore

Record/skip only

Audio

offer (default)

Queue as queued_transcription (no silent STT)

Audio

auto_transcribe

Rejected until host STT (theme H) is available

Audio

ignore

Skip

Inbox files are never deleted or modified. Admission always copies into app imports/ then uses the managed import path (canonical JSON + sidecar + originals + index). The watcher does not scan the managed transcripts library.

Ops notes

  • Runs only while transcriptx-web is running (in-process supervisor). Stopping the container stops watching.

  • Docker: watch a mounted inbox such as /mnt/transcript-inbox (HOST_TRANSCRIPT_INBOX_DIR). Paths must be absolute inside the container.

  • Debounce (~2s) plus size/mtime stability checks before admit; identity is re-checked at admit time (fail closed if the file moved/grew).

  • Job records and activity live under data_dir/watcher/ (see STORAGE.md).

  • Prefer Settings UI for enablement; env overrides are for automation.

Host-side helper (inbox-watch)

The in-app watcher does not convert audio or run STT. For that, use the host script scripts/inbox-watch.py documented under Host inbox watcher (inbox-watch) in host-stt.md:

  • --watch-audio — ffmpeg 16 kHz mono 64k MP3 into recordings, then whispermlx-missing (optional --skip-serial leaves Auto-merge groups untranscribed)

  • --watch-transcripts — copy new JSON/SRT/VTT/txt/html into a transcripts dest if the stem is missing

  • --admit (default off) — after the above, run python -m transcriptx.admit_originals so new originals/ files enter the managed library (admit_and_register). Enable with --admit, "admit_to_library": true in .transcriptx/inbox-watch.json, or INBOX_WATCH_ADMIT=1 in repo .env. Needs a native TranscriptX Python (admit_python / --admit-python / INBOX_WATCH_ADMIT_PYTHON).

  • --auto-name / --auto-link — after admit, auto-write speaker-map names and/or create auto_identified profile links when voice + text fusion is confident (INBOX_WATCH_AUTO_NAME / INBOX_WATCH_AUTO_LINK). --auto-name implies admit and defaults auto-link on. In-app Settings → Speakers knobs (config_dir/identify.json) apply to G2 auto-import. Operator reference: auto-identify.md.

  • Terminal UX — same Review / Processing / Run summary shape as analysis CLI feedback (Terminal feedback)

It runs on the Mac host (outside transcriptx-web) and does not import transcriptx in-process. G2 stays the in-app auto-import path. Both can run; do not point them at the same inbox unless you intend double handling of transcripts (G2 admits, host copies — and --admit would admit the copies).