Add headless CLI for autonomous subtitle sync pipelines

Introduces assy-cli with five subcommands (sync, shift, batch, config,
version), JSON output mode, structured exit codes, and a slim Docker
image - so AutoSubSync can run in CI/CD, scheduled jobs, and containers
without a display or Qt event loop.

The sync engine logic was extracted from SyncProcess into a new
sync_core module that knows nothing about Qt; SyncProcess is now a thin
adapter that wires Qt signals to sync_core callbacks. The pairing logic
moved to a new pairing module the GUI re-imports. utils.py drops its
top-level QtWidgets/QtGui imports so the CLI never loads Qt display
libraries at runtime.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Aidenir

Dockerfile.cli

@@ -0,0 +1,39 @@
+# Slim, headless image for autonomous pipeline use of AutoSubSync.
+# Contains only what the CLI needs - no X11, VNC, or Qt display deps.
+# main/cli.py is engineered to not load PyQt6 QtWidgets/QtGui at runtime,
+# so the slim image works even though PyQt6 is still a transitive install dep.
+
+# --- Builder stage: compile native deps (webrtcvad etc.) ---
+FROM python:3.11-slim-bookworm AS builder
+
+ENV PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY pyproject.toml README.md ./
+COPY main ./main
+RUN python -m pip install --prefix=/install .
+
+# --- Runtime stage: just glibc + libstdc++ + the installed wheels ---
+FROM python:3.11-slim-bookworm
+
+ENV PYTHONUNBUFFERED=1
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        ca-certificates \
+        libstdc++6 \
+        libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /install /usr/local
+
+WORKDIR /data
+VOLUME ["/data"]
+
+ENTRYPOINT ["assy-cli"]
+CMD ["--help"]

README.md

@@ -157,6 +157,59 @@ To access the GUI, open your web browser and go to: [http://localhost:6080](http
 4. Select output location
 5. Click `Start`
 
+### Command-line interface (`assy-cli`)
+
+For autonomous pipelines, CI/CD, scheduled jobs, and Docker, AutoSubSync ships a
+fully-featured CLI that never starts a Qt event loop or requires a display.
+
+```bash
+# Auto-sync one subtitle (machine-readable output)
+assy-cli sync video.mkv subs.srt -o synced.srt --json
+# {"ok": true, "input": "subs.srt", "output": "synced.srt", "tool": "ffsubsync", ...}
+
+# Shift a subtitle by 1.5 seconds
+assy-cli shift subs.srt 1500 -o shifted.srt
+
+# Batch sync a folder of pairs and continue past failures
+assy-cli batch --folder ./episodes --continue-on-error --json
+
+# Two-folder pairing with explicit output dir
+assy-cli batch --video-dir ./videos --subtitle-dir ./subs -o ./out --json
+
+# Pick a sync engine per call
+assy-cli sync video.mkv subs.srt -t alass
+
+# Inspect or persist user config
+assy-cli config path
+assy-cli config get sync_tool
+assy-cli config set sync_tool alass
+```
+
+| Subcommand | Purpose |
+|---|---|
+| `sync` | Auto-sync one subtitle to a video or reference subtitle |
+| `shift` | Shift subtitle timing by milliseconds |
+| `batch` | Process many pairs from `--folder`, `--video-dir`+`--subtitle-dir`, or repeated `--pair` |
+| `config` | `get` / `set` / `unset` / `list` / `path` for the user config JSON |
+| `version` | Print version |
+
+**Exit codes:** `0` success · `1` at least one sync failed · `2` usage or config error · `130` SIGINT.
+
+**JSON mode** (`--json`) writes structured results to stdout (one object per sync; for `batch`, NDJSON plus a final `{"summary": ...}` line) while human-readable logs go to stderr. Pipe straight into `jq`:
+
+```bash
+assy-cli sync video.mkv subs.srt --json | jq -r '.output'
+```
+
+**Run from Docker** with no display:
+
+```bash
+docker build -f Dockerfile.cli -t autosubsync-cli .
+docker run --rm -v "$PWD:/data" autosubsync-cli sync /data/video.mkv /data/subs.srt -o /data/out.srt
+```
+
+Or via compose: `docker compose --profile cli run --rm assy-cli sync /data/video.mkv /data/subs.srt`.
+
 ## `Features`
 
 ### Automatic Synchronization

docker-compose.yml

@@ -15,3 +15,15 @@ services:
       - DISPLAY=:0
       - QT_QPA_PLATFORM=xcb
     restart: unless-stopped
+
+  # Headless CLI image for autonomous pipelines.
+  # Build:  docker compose build assy-cli
+  # Usage:  docker compose run --rm assy-cli sync /data/video.mkv /data/sub.srt
+  assy-cli:
+    build:
+      context: .
+      dockerfile: Dockerfile.cli
+    image: autosubsync-cli
+    volumes:
+      - $PWD:/data
+    profiles: ["cli"]   # only spun up when explicitly invoked