techspecs/ray repository overview

⁠Ray (headless)

Ray's on-device subtitle & transcription engine in a container - the same /v4 Developer API the desktop app serves (/v1 remains as a permanent alias), without a GUI. Generate, translate, retime and burn-in subtitles locally (or via Ray Cloud), with a built-in web dashboard.

⁠Which image should I use?

Two questions decide it:

1. What GPU is in the machine? NVIDIA → cuda, AMD/Intel → vulkan, none → cpu.
2. NVIDIA? The cuda image runs fully on the GPU on a Linux host and on Windows/Docker Desktop (WSL2). AMD/Intel? GPU acceleration in Docker needs a Linux host; on Windows/macOS Docker Desktop the vulkan/cpu images run on CPU - use the desktop app if you want GPU there.

So: NVIDIA → cuda (Linux or Windows/Docker Desktop) · Linux + AMD/Intel → vulkan · anything else → cpu.

The cpu and vulkan images run the full pipeline on CPU when no GPU is present - GPU is an acceleration, not a requirement. The cuda image is the exception: it links the NVIDIA runtime and requires --gpus all to start (for a CPU-only host, use the cpu or vulkan image). Pick the image that matches your GPU vendor; the engine uses the GPU automatically when the card is present.

Telemetry: crash reporting is on by default (self-hosted Sentry); set RAY_TELEMETRY=off to disable.

• NVIDIA → cuda. The NVIDIA path in Docker - GPU-accelerated on Linux and under Docker Desktop/WSL2 alike.
• AMD / Intel → vulkan. The container user is in the video/render groups; if your host uses different gids add --group-add "$(getent group render | cut -d: -f3)".
• cpu works anywhere and needs no special flags.

⁠Quick start

docker volume create ray-config
docker volume create ray-models
docker volume create ray-data

# 1) Sign in once (emailed one-time code) - stored on the ray-config volume.
docker run -it --rm -v ray-config:/config techspecs/ray:cuda login

# 2) Start serving. On first boot the server prints a generated API key in its log.
docker run -d --name ray-server --gpus all -p 8787:8787 \
    -v ray-config:/config -v ray-models:/models -v ray-data:/data \
    -v "$PWD/out:/out" -v "$PWD/media:/media:ro" \
    techspecs/ray:cuda
docker logs ray-server            # grab the printed API key (stored hashed in /config)

(For the vulkan image swap --gpus all for --device /dev/dri; for cpu, drop both.)

⁠Web dashboard

Open http://your-host:8787/ in a browser. Paste the API key once, then sign in to your Ray account, drag-and-drop videos (or point at a server-side path in a mounted volume), pick languages / model / where to process, and watch jobs live. It's a single self-contained page - no CDN, works air-gapped.

⁠One-shot mode

docker run --rm --gpus all \
    -v ray-config:/config -v ray-models:/models -v ray-data:/data \
    -v "$PWD/out:/out" -v "$PWD/media:/media:ro" \
    techspecs/ray:cuda generate /media/movie.mkv --language es --quality best

⁠Watch-folder mode (auto-subtitle a media library)

docker run -d --name ray-watch --gpus all \
    -v ray-config:/config -v ray-models:/models -v ray-data:/data \
    -v /srv/media:/media \
    techspecs/ray:cuda watch /media --lang nl

⁠Volumes

Media to subtitle is mounted (read-only is fine - Ray never modifies your files) and submitted by its in-container path. Finished subtitles are written to /out, not back into the media folder.

⁠Notes

• Seat: one container = one seat. Sign in with login, or set RAY_ACCOUNT_EMAIL + RAY_ACCOUNT_LICENSE_KEY.
• Cold start: the image ships the engine, not the models - the first job downloads what it needs into /models (multiple GB). Progress shows in docker logs and the dashboard.
• TLS: the server speaks plain HTTP on 8787 - put it behind your reverse proxy (Caddy/nginx/Traefik) and bind the port to localhost.
• Telemetry: on by default; RAY_TELEMETRY=off disables it.

⁠Tags

• techspecs/ray:cpu, techspecs/ray:cuda, techspecs/ray:vulkan - moving latest per variant.
• techspecs/ray:<version>-<variant> (e.g. 4.0.15-beta.1-cuda) - immutable, digest-pinnable.