techspecs/ray repository overview

⁠Ray headless

Ray's subtitle server for a NAS, home server or any always-on box: a web dashboard and a Developer API that make, translate, re-time and burn in subtitles on your own hardware (Ray Local) or on Ray's servers (Ray Cloud).

• Subtitles next to your videos (Movie.en.srt beside Movie.mkv) for Plex, Jellyfin and Emby - never replaces a subtitle it didn't make
• Watch folders from the dashboard: every video in a folder, and every new one, gets subtitles
• Sonarr and Radarr: every new episode and movie gets subtitles on import; renames, upgrades and deletes are followed
• A private dashboard for the household: owners and members, each with their own access
• Audio track choice for anime with a dub or films with commentary
• Ray Cloud per job, per folder, or only when the server can't do it itself
• Your PC's graphics card: the server can send the work to Ray on your computers
• Runs as your NAS user with PUID, PGID and UMASK

📖 Step-by-step NAS guide: https://github.com/techspecs/ray-headless/blob/main/docs/nas-install.md⁠

📚 Full container guide: https://github.com/techspecs/ray-headless/blob/main/docs/docker.md⁠

⁠Which image?

Everything also runs on the processor; a graphics card makes Ray Local faster. The cuda image needs --gpus all to start.

⁠Quick start (Docker Compose)

services:
  ray-server:
    image: techspecs/ray:cpu
    container_name: ray-server
    ports:
      - "8787:8787"
    environment:
      PUID: "1000"      # your user id (run `id` on the NAS)
      PGID: "1000"      # your group id
      UMASK: "022"
    volumes:
      - ray-config:/config
      - ray-models:/models
      - ray-data:/data
      - ./out:/out
      - ./media:/media  # your videos; add :ro to keep every subtitle in ./out
    restart: unless-stopped

volumes:
  ray-config:
  ray-models:
  ray-data:

docker compose up -d
docker compose logs ray-server     # the owner key, the line starting with ray_

Then sign in, the first time only:

1. Copy the key from the log: in the box between two lines of =====, the line that starts with ray_ (copy only from ray_ to the end of the line). It is shown only this once and stored hashed.
2. Open http://SERVER-IP:8787/. The page says Set up this Ray server. Paste the key into Paste your API key. On a computer you share, untick Keep me signed in on this browser (under the button). Then choose Sign in.
3. On Create, in the card This server's Ray account, choose Use an email code instead. Type your email under Email, choose Send code, type the 6-digit code under Code from the email and choose Verify. Can your email use more than one Ray account? Choose the one this server should use.
4. Done when a message says Connected this server to your email and the card shows Connected to.

In step 3, Connect with your Ray app works too: you approve on Ray on your Windows PC or Mac (on Docker's default network, once RAY_NEARBY_LAN_SUBNETS is set). Rather approve on Ray than paste a key at all? Turn on Sign in with your Ray app in People (it's off until you do; Ray 4.0.16 or later).

Every step, and what to do when the key is lost: https://github.com/techspecs/ray-headless/blob/main/docs/docker.md#signing-in⁠

The first job downloads what Ray needs (a few GB) into ray-models; after that jobs start right away.

⁠docker run

docker run -d --name ray-server --restart unless-stopped \
  -p 8787:8787 -e PUID=1000 -e PGID=1000 \
  -v ray-config:/config -v ray-models:/models -v ray-data:/data \
  -v "$PWD/out:/out" -v "$PWD/media:/media" \
  techspecs/ray:cpu

For cuda add --gpus all; for vulkan add --device /dev/dri --device /dev/kfd (/dev/kfd lets Sunlight separate voices from the background sound). In Windows PowerShell, end each line with a backtick instead of \.

⁠Volumes

Mount your media too (for example at /media) and use the path inside the container. Read-write lets Ray save subtitles next to your videos; :ro keeps every result in /out.

⁠Good to know

• Private by default: reachable from your network, the dashboard shows nothing until someone signs in, and every API request needs a key or a browser's sign-in.
• API: http://SERVER-IP:8787/v1/... with a key as a Bearer token.
• Upgrading from 4.0.15-beta.1 or earlier: Ray now runs as PUID:PGID (default 1000:1000) and gives /config, /models and /data to that user; results are named after the video; watch folders save next to the videos. Remove RAY_DISABLE_NEARBY_FANOUT if your container still has it.

Details: https://github.com/techspecs/ray-headless/blob/main/docs/docker.md#upgrading-from-an-earlier-image⁠

• TLS: plain HTTP on 8787 - put it behind your reverse proxy for HTTPS.
• Telemetry: crash reporting is on by default; RAY_TELEMETRY=off turns it off.

⁠Tags

• cpu, cuda, vulkan - the latest release of each image.
• <version>-cpu, <version>-cuda, <version>-vulkan - a fixed release you can pin.

Site: https://rayplayer.com⁠ · Docs, CLI and issues: https://github.com/techspecs/ray-headless⁠

Ray is proprietary software. © 2026 TechSpecs. All rights reserved.