4.0.17-beta.1

Ray headless 4.0.17 - release notes

Ray headless is Ray's subtitle server for a NAS, home server or any always-on box. This release connects it to your Plex, Jellyfin and Emby libraries, lets Ray support help when a job fails on the server, and makes Ray Cloud jobs wait through used-up allowances and dropped connections instead of failing. NVIDIA graphics cards now separate voices for Sunlight too.

Images: techspecs/ray:4.0.17-beta.1-cpu, techspecs/ray:4.0.17-beta.1-cuda, techspecs/ray:4.0.17-beta.1-vulkan (and the moving cpu, cuda, vulkan tags). Guides: NAS install guide · container guide.

Upgrading from 4.0.16-beta.1? Read the upgrade notes first.

New

• Plex, Jellyfin and Emby (Homewide). Ray watches your media server libraries and adds subtitles to every new video, so they show up in the library like any other subtitle. Connect a server in the new Servers tab (owners): Jellyfin and Emby on your network are listed by themselves, Plex connects with Sign in with Plex, and any server connects by its address. Then choose libraries and languages; Subtitle what's already here does the videos a library already has. It works for Ray accounts that include Homewide, is on by default, and RAY_ENABLE_HOMEWIDE=0 turns it off. Servers can also be set where the container starts (RAY_HOMEWIDE_SERVERS). From a terminal: ray-cli api homewide.
• Remote help on the server. When a job fails in Ray Local, owners can ask for remote help in Help (or with Get remote help on the failed job), and Ray support can look into it. Only someone at the server's own terminal lets them in, with ray-cli support approve or ray-cli support request; the dashboard and an API key never can. Ray support can see the server's details and logs and run test jobs, never change settings. It uses no seat. RAY_SUPPORT_SESSIONS=0 turns it off.
• NVIDIA graphics: voices separated for Sunlight. With techspecs/ray:cuda, Sunlight separates voices from the music and background sound on the NVIDIA card before it makes subtitles. The first such job downloads what it needs (about 2 GB).
• Help for everyone. Everyone signed in finds Graphics cards in Help: how well the server's graphics card runs Ray, on the same scale as the Ray app. Owners also get Contact us, which sends a message to Ray support from the server, and the connection test now shows whether each of Ray's services is reachable from the server, with the address to allow in a firewall or ad blocker.
• Copy diagnostics on every failed job, and ray-cli api diagnostics JOB_ID: the details Ray support asks for, never keys, folders or links.
• Watch folders retry failed files. Choose Retry failed files after 1, 3, 6, 12 or 24 hours, at most 3 times, for failures that can pass, like a lost connection or a share that didn't answer. The folder's row shows the next try.
• Several languages in one go. generate FILE --language bs,sr-Latn (and ray-cli api submit) makes one subtitle per language, each with its own name, and reads a subtitle with no language in its name the same way for all of them.
• ray-cli gains api retry JOB_ID, api diagnostics JOB_ID, api homewide (with sync) and support (status, request, approve, end).

Improved

• Ray Cloud jobs wait instead of failing.
  • When the daily limit or the allowance is used up, Ray Cloud jobs from the dashboard, the API and watch folders wait and go again by themselves after the reset or once you add credit. A used-up free trial waits for credit. Nothing is uploaded while a job waits, and Check now (or ray-cli api retry JOB_ID) asks again.
  • When the connection drops or Ray Cloud has a short problem during a job, the job waits for it and carries on. After a restart Ray follows the same Ray Cloud job, with no new upload.
  • Waiting work stays with the Ray account it was made for: after Switch account it never runs, or gets charged, on the other account.
• The Jobs list is kept across restarts (up to 5000 jobs in /config). A job that was running when the server stopped comes back as failed, Stopped when this server stopped, and never runs again by itself.
• Requests wait for an answer. A sign-in request to your Ray app and a request to connect one of your computers no longer run out after a few minutes: they wait until someone answers, and Stop asking takes them back.
• Your devices on Docker's bridge network: a computer added by its address can now be chosen to run jobs.
• A plan without Ray Cloud refuses a Ray Cloud job before anything is uploaded, and Run on says why Ray Cloud can't be chosen.
• Ray Local says when the processor is the reason. A processor without AVX2 is named as the cause, with a hint for virtual machines (set the processor type to host).
• Translations: a few lines Ray can't translate are left out, and the job says how many, instead of failing the whole subtitle. More than 10% still fails.
• Large folders: a watch folder takes in at most 50,000 new videos per look and carries on at the next one, and says so.
• When Ray Local can make out only part of what is said, the job finishes with what it heard and says so, instead of failing.
• Memory in Docker: Ray Local sizes its work to the container's own memory limit, not the whole host's.
• Language versions: Serbian in Latin letters is read as Serbian and keeps its own file name (Movie.sr-Latn.srt), and a Brazilian Portuguese subtitle is converted for a Portuguese (Portugal) pick instead of being shown as one.
• Ray Local reliability: no timer stops work that is still going, files without sound are named up front, and files a job or a busy graphics card still uses are never removed.
• Smaller Windows download: the server zip leaves out what only a window uses (about 55 MB less).

Fixed

• With the cuda image, videos with music or hard-to-hear dialogue get their subtitles again: in 4.0.16 some of those jobs failed.
• ReTime on the cuda image under Docker Desktop on Windows works again.
• Use your devices: unticking This device no longer fails every job when no other computer can take it.
• ray-cli speed-test no longer shows which country the connection comes from.

Upgrade notes

Update with docker compose pull && docker compose up -d. /config, /models and /data carry over.

• Plex, Jellyfin and Emby (Homewide) and remote help are on after the update. Neither does anything until an owner connects a media server or asks for remote help. To keep them off, set RAY_ENABLE_HOMEWIDE=0 and RAY_SUPPORT_SESSIONS=0.
• Ray Cloud may ask you to confirm it once on this server. A banner with Confirm now holds Ray Cloud jobs until then, and they go by themselves afterwards. Nobody is signed out.
• Keep /config as a volume: the Jobs list and the Ray Cloud jobs that wait for the allowance are kept there across restarts.
• For scripts: a Ray Cloud job on a plan without Ray Cloud is refused when it is added (403 cloud_not_entitled), a job that waits for the allowance stays queued instead of failing, and GET /v1/jobs also lists jobs from before the last restart ("from_before_restart": true).
• Without Docker: Scoop now installs Microsoft's Visual C++ runtime from the extras bucket, so run scoop bucket add extras once. Chocolatey installs this beta with choco install ray-headless --pre. On a Mac, the server moves its settings once to a new place, by itself.

Known limits

• Plex, Jellyfin and Emby: Ray finds Jellyfin and Emby by itself only with host or macvlan networking; on Docker's default bridge network, add them by address. Emby needs the media folder mounted in Ray's container. Connect each media server in one Ray only, or the work and the Ray Cloud use happen twice.
• Sonarr and Radarr renames may drop the -latn from Serbian (Latin) and Romaji subtitle names.
• The one-shot generate never waits for the Ray Cloud allowance: it fails with the reset time.
• Remote help is for Ray Local problems only, and a server restart ends a request.
• A computer with Ray before 4.0.17 still ends a sign-in request after 10 minutes and a connection request after 2 minutes: update Ray there.
• ReTime on the cuda image can't run while other work holds the graphics card.
• Ray Local needs a processor with AVX2.
• Take work from your devices needs host or macvlan networking.
• Sonarr and Radarr connections subtitle new episodes and movies; for the ones you already have, add the folder under Watch folders.

4.0.16-beta.1

Ray headless 4.0.16 - release notes

Ray headless is Ray's subtitle server for a NAS, home server or any always-on box. This release is about making it feel at home on a NAS: subtitles next to your videos, folders and Sonarr / Radarr that subtitle themselves, a private dashboard for the whole household, and files that belong to your NAS user.

Images: techspecs/ray:4.0.16-beta.1-cpu, techspecs/ray:4.0.16-beta.1-cuda, techspecs/ray:4.0.16-beta.1-vulkan (and the moving cpu, cuda, vulkan tags). Guides: NAS install guide · container guide.

Upgrading from 4.0.15-beta.1 or earlier? Read the upgrade notes first.

New

• Sign in with your Ray app. Off until an owner turns it on at the top of People (or sets RAY_APP_SIGNIN=on). Then the owner of the server's Ray account signs in by approving on Ray 4.0.16 or later on a Windows PC or Mac, with no key to paste. With RAY_APP_SIGNIN=on from the first start, the same approval also sets a new server up and connects it to your Ray account (proven with the key from the server log once, or with RAY_OWNER_EMAIL in the compose file). Works on the server's own network; keys keep working everywhere.
• Sign-in links. In People, add someone "with a sign-in link": they open it once and they're in, no key to copy. Links work once, within 24 hours. Owners can see every signed-in browser and sign it out.
• This server's Ray account. A simpler card: see which Ray account the server uses, Switch account or Disconnect; connect with your Ray app or an emailed code.
• Subtitles next to your videos (library mode). Ray saves Movie.en.srt right beside Movie.mkv, where Plex, Jellyfin and Emby find it. Tick Save next to the video for a job; watch folders and Sonarr / Radarr do it by default. Ray never replaces a subtitle it didn't make: when it can't write there, the result goes to the output folder and the job says why.
• Results named after the video. Movie.en.srt instead of a job id, with the language codes media servers read: two letters whenever the language has them (Movie.nl.srt), plus the region for a regional variant (Movie.pt-BR.srt, Movie.zh-Hant.srt). A taken name becomes Movie (2).en.srt: nothing is ever overwritten.
• Watch folders from the dashboard. Add, pause, change and remove folders in the new Watch folders tab, no restart and no config files. Each folder has its own languages, burn-in, where subtitles go, audio language, and Ray Local or Ray Cloud. In Docker a new folder must be in a volume you shared with the container (or hold such volumes); Ray's own folders are refused.
• Sonarr and Radarr. The new Connections tab connects them through their built-in Webhook: every new episode and movie gets subtitles on import. Ray follows renames, better copies and deletes for the subtitles it made, learns when Sonarr sees your folders under another path, and catches up on what arrived while it was off.
• A private dashboard, and access for everyone. Reachable from your network, the dashboard shows nothing until someone signs in. People gives each person their own access: owners manage the server, members add and follow their own jobs. A member's job can't use files in Ray's own or system folders, a path with a . or .. folder in it, or (while members see only their own jobs) other people's results.
• Browse the server's folders. No more copying paths from a terminal: every field that takes a path on the server suggests folders and files as you type, and Browse next to it shows the server's folders, with the subtitle languages already next to each video. In Docker it shows only the folders you shared with the container, never Ray's own folders or the system's. Owners can type a path the way the NAS names it (/volume1/video/Movies) and Ray offers the one inside the container.
• Favorite and recent folders. Owners save favorite folders with the heart in Browse, and each shows its free space; everyone gets their Recent folders. From Browse on Create, Watch this folder (owners) opens Add a watch folder with that folder filled in.
• What each member can browse. In People, Can browse is Favorites only (All favorites or Only these) or Everywhere: the folders a member can browse and use for jobs, retries included. Uploading always works. Who can use it, under Edit on a favorite, chooses the members for one folder. Make owner and Make member in a person's More menu change their role, and Ray keeps their folder setting for when they're a member again. RAY_BROWSE=owners lets only owners browse, RAY_BROWSE=off turns it off, and MCP apps browse only with an owner's key.
• Remove and Clear finished in the Jobs list, optionally deleting the result files Ray made.
• Run as your NAS user. PUID, PGID and UMASK, like other NAS apps: everything Ray writes belongs to you.
• Choose the audio track. For anime with an English dub or films with a commentary track: an Audio track picker for a single video, a preferred audio language for folders (RAY_AUDIO_LANGUAGE for the whole server). When the language doesn't decide, Ray asks you in the Jobs list or uses the video's default, as you choose; it never guesses. Translate can also start from a subtitle track inside the video.
• Ray Cloud per watch folder, and Use Ray Cloud if Ray Local can't for folders and connections.
• Use your devices. A NAS without a graphics card can send the work of making subtitles to Ray on your Windows PC or Mac (4.0.15 or later) and get the subtitles back. Only the audio of each video and its file name leave the server; you approve each computer on the computer itself.
• Take work from your devices. The other way round: a busy computer can pass its next job to the server (host or macvlan networking). The file a computer sends stays on the server only until its job ends.
• Guided tours. The ? menu replays short tours of the dashboard, Your devices and Connections.
• Help tab. Owners can test the server's connection to Ray (download, upload and latency, and what they mean for Ray Cloud uploads and downloads) and copy the server's details for Ray support. Also ray-cli speed-test in the container.
• AMD graphics: voices separated for Sunlight. With techspecs/ray:vulkan, pass /dev/kfd as well as /dev/dri, and Sunlight separates voices from the background sound on the graphics card. The first such job prepares the card, which can take several minutes; later jobs start right away. Each job says when voices couldn't be separated and the subtitles were made from the full soundtrack.
• ray-cli gains api keys (with keys folders and keys role), api browse, api favorites, api tracks, api devices, api connections, and --audio-track, --audio-language, --subtitle-track, --run-on and --model moonlight|sunlight on api submit.
• The API also answers under /v4 (the same routes as /v1).

Improved

• Ray Local on small servers. Ray checks the memory that is free right now before each job. When the quality you picked doesn't fit but a lighter one does, the job runs the lighter one and says so; when nothing fits, it fails with a clear reason and what to do. RAY_LOCAL_PROCESSOR=cpu makes Ray Local always use the processor. The dashboard says when the graphics are integrated and Ray Local uses the processor.
• The dashboard follows the Ray app's design, works on a phone, and is easier to use with a keyboard.
• Settings that can't be saved are explained. When /config isn't writable, the log names the folder and the user, the dashboard says so, and Ray refuses what it couldn't keep (a sign-in, a sign-in link, a new key) instead of forgetting it at the next start. Until you fix it, the server still works for the run: the owner key from the first start works until the server stops (while /config holds no key, each start makes a new one), keys from RAY_DEVAPI_KEY_HASH work at every start, a key you remove stays removed while the server runs, and the installation ID in Copy diagnostics stays the same for the whole run.
• Without Docker, the server makes its first key. Started with --host 0.0.0.0 or RAY_DEVAPI_EXPOSE=1 and no key yet, ray serve makes an owner key, shows it once in its terminal (as the Docker image does in its log) and opens to your network. RAY_DEVAPI_GENERATE_KEY=0 skips that, and so does setting RAY_DEVAPI_KEY_HASH yourself.
• Clearer messages about keys. A key put in RAY_DEVAPI_KEY_HASH in place of its hash (it starts with ray_) is skipped with a warning that shows how to make the hash, and the line sha256sum prints is taken as it is. Outside Docker the server also warns when RAY_API_KEY is set where it starts and isn't one of its keys: that is the key the ray command and ray-cli send, and the server never reads it. On a server with no key, the dashboard's API key dialog says a key typed there stays in that browser and protects nothing.
• Result files never replace another file, and names that are too long for a folder are shortened instead of failing the job.
• The settings file in /config is private to the user Ray runs as.
• A server without any key refuses requests made by other websites.
• The image uses a UTF-8 locale, so ray-cli in docker exec and file names with accents or other scripts behave.

Fixed

• Connecting the server from your computer works with current Ray apps: Connect with your Ray app replaces Sign in with a nearby device on the account card, lists your computers by name (never their addresses), and the guide explains Docker's bridge and host networking for it.
• A job that combines creating...

4.0.15-beta.1

Ray Headless 4.0.15-beta.1

First public beta of Ray Headless - local, on-device subtitle generation, translation and retiming as a server + thin CLI, plus container images. No account UI required; drive it over the local Developer API.

Components

• ray-server - the local engine (subtitle generation, device selection, model management).
• ray-cli - thin client for the server (ray-cli api <command> --port <N>).

Install options

Platform	Asset
Linux (portable)	Ray-4.0.15-beta.1-x86_64.AppImage
Linux (server bundle)	ray-headless-linux-x64-4.0.15-beta.1.tar.gz
Linux (Debian/Ubuntu)	ray-headless_4.0.15-beta.1_amd64.deb
macOS (Apple Silicon)	ray-headless-macos-arm64-4.0.15-beta.1.tar.gz / ray-headless-4.0.15-beta.1.pkg
Windows (x64)	ray-headless-windows-x64-4.0.15-beta.1.zip
CLI only (Linux / macOS arm64 / Windows)	ray-cli-*-4.0.15-beta.1.*

Docker

Images on Docker Hub (techspecs/ray), run with the matching GPU flags:

• techspecs/ray:cpu - portable, CPU only.
• techspecs/ray:cuda - NVIDIA GPU (run with --gpus all); fully GPU-accelerated.
• techspecs/ray:vulkan - cross-vendor GPU on native Linux (run with --device /dev/dri).

Versioned tags: techspecs/ray:4.0.15-beta.1-{cpu,cuda,vulkan}.

Developer API

The local API is served under /v4 (the leading digit tracks the app major version); /v1 remains a permanent alias. GET /v4/health for readiness; POST /v4/subtitles to generate. See the README for the full route list and the API-key note.

Verifying downloads

SHA256SUMS is included; check with sha256sum -c SHA256SUMS.

This is a beta - please file issues on the tracker.