Repository navigation
4.0.16-beta.1
Pre-release
Pre-release
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. WithRAY_APP_SIGNIN=onfrom 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 withRAY_OWNER_EMAILin 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.srtright besideMovie.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.srtinstead 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 becomesMovie (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=ownerslets only owners browse,RAY_BROWSE=offturns 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,PGIDandUMASK, 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_LANGUAGEfor 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-testin the container. - AMD graphics: voices separated for Sunlight. With
techspecs/ray:vulkan, pass/dev/kfdas 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(withkeys foldersandkeys role),api browse,api favorites,api tracks,api devices,api connections, and--audio-track,--audio-language,--subtitle-track,--run-onand--model moonlight|sunlightonapi 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=cpumakes 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
/configisn'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/configholds no key, each start makes a new one), keys fromRAY_DEVAPI_KEY_HASHwork 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.0orRAY_DEVAPI_EXPOSE=1and no key yet,ray servemakes 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=0skips that, and so does settingRAY_DEVAPI_KEY_HASHyourself. - Clearer messages about keys. A key put in
RAY_DEVAPI_KEY_HASHin place of its hash (it starts withray_) is skipped with a warning that shows how to make the hash, and the linesha256sumprints is taken as it is. Outside Docker the server also warns whenRAY_API_KEYis set where it starts and isn't one of its keys: that is the key theraycommand andray-clisend, 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
/configis 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-cliindocker execand 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 subtitles with ReTime or burn-in keeps the language it was asked for.
- A ReTime step right after creating subtitles no longer fails the whole job when it can't match: it keeps the subtitles as made and carries on.
- The one-shot
generatenever touches the watch folders of a server sharing its/config. - A watch folder on a network share that stops answering no longer keeps the server from shutting down.
- Subtitles made on the processor (the
cpuimage) no longer end with a stray "[End of text]" line, and translations made from them don't either. 4.0.15 could leave that line in English subtitles and their translations: ask for those again from the dashboard and Ray makes new ones (a watch folder doesn't redo a video it already did). - On a graphics card with 8 GB, the first Sunlight job after Ray downloads what it needs no longer fails saying the graphics card isn't available.
- Making subtitles on the processor (the
cpuimage, orRAY_LOCAL_PROCESSOR=cpu) no longer stops a long video as "stopped responding" while Ray is still working on it. - A translation on the graphics card no longer fails with "close some apps to free memory" right after another step used the card: Ray checks the card's free memory again first, and when there really is no room, it says so.
- A subtitle file picked on the server as the video (its path, like an
.srtnext to the movie) is refused when you add the job, with a hint to translate it instead, in the dashboard,ray-cliand MCP apps (the API answerssubtitle_file_not_media). - Making subtitles for a video with no sound now fails saying the video has no audio track, instead of suggesting you close apps.
- When the model Ray uses to check a subtitle it found isn't on the server, Ray no longer downloads subtitles it can't check. It makes the subtitles itself.
- Use your devices: on Ray 4.0.16 the computer's Allow Ray Nearby? shows how long is left (a request lasts 2 minutes) and closes when it runs out. On Ray 4.0.15 it stayed on screen after running out, and Allow then did nothing: ask again from the dashboard and answer within 2 minutes.
- Use your devices: with Ray 4.0.16 on the computer, nothing of the server's job stays there: the audio goes when the job ends and the subtitles once the server has them (Ray 4.0.15 kept both for at least a day). A send that stopped partway goes 15 minutes after its last part arrived.
- Use your devices: with Ray 4.0.16 on the computer, Ray there no longer freezes for a few seconds when the server's job arrives. On a computer with two NVIDIA graphics cards, its name in Your devices now shows the one Ray Local uses, unless you named it yourself.
Upgrade notes
Update with docker compose pull && docker compose up -d. /config, /models and /data carry over.
- Ray now runs as
PUID:PGID, default1000:1000, and gives/config,/modelsand/datato that user when it starts. If you had given those folders to another account and made them writable for everyone, setPUID/PGIDto that account first. If you start the container with--user, nothing changes. - Subtitles next to your videos need the media mounted read-write, writable by
PUID. Watch folders now save next to the videos by default; with a read-only (:ro) mount their subtitles keep going to/outand each job says why. SetRAY_OUTPUT=outto keep watch folder results in/out(Sonarr and Radarr connections have their own Save subtitles setting). - Results are named after the video, with two-letter language codes whenever the language has one: Chinese is
Movie.zh.srt(or.zh-Hans/.zh-Hant), not.cmn. Files from earlier versions are left as they are. - The dashboard is private. Anyone opening it needs to sign in; API requests need a key.
- The one-shot
generateserver listens on port18787(it was8788, which Ray apps on the same machine use). Only matters if you setRAY_GENERATE_PORTor firewall loopback ports. - API times are UTC with a
Z(2026-09-27T14:03:11Z), not the server's local time without an offset. Scripts that readcreated_atand friends may need a look. ray-clikeeps a server address that ends in/v1or/v4and adds/v1to one without a version, so the sameray-cliworks with older and newer servers.RAY_DISABLE_NEARBY_FANOUTis no longer set by the image. Older images set it, and some container managers copied it into the container's settings; remove it there to use your devices. While it is set, every job stays on the server.- Members you already have keep every folder they could use, and show as Everywhere under Can browse in People (this happens once, at the first start of 4.0.16). People you add from now on start at Favorites only: until an owner saves a favorite folder they may use, they can only upload files. Change anyone on their row in People.
- Without Docker,
--host 0.0.0.0orRAY_DEVAPI_EXPOSE=1with no key now makes a key and opens the server to your network. Before, such a server stayed on its own computer. The key is printed once where the server's output goes (its terminal, or for a systemd service its log, likejournalctl --user -u ray-server), and from then on the dashboard asks for a key on that computer too. SetRAY_DEVAPI_GENERATE_KEY=0to keep it on its own computer instead. - A macOS LaunchAgent keeps none of the server's output, so a key it makes is never shown. If yours already has
--host 0.0.0.0and the server has no key yet, stop it before you update (launchctl bootout gui/$(id -u)/io.techspecs.ray-server). After the update, runray serve --host 0.0.0.0once in a terminal, copy the key from its box, stop it with Ctrl+C, then start the LaunchAgent again (the README'slaunchctl bootstrapline). If the key was already made out of sight, stop the LaunchAgent the same way, start once in a terminal with your own key's hash inRAY_DEVAPI_KEY_HASH(the README shows how), sign in with that key and remove the lost Owner key in People.
Known limits
- Take work from your devices needs host or macvlan networking; on Docker's default bridge network your computers can't find the server yet.
- Sonarr and Radarr connections subtitle new episodes and movies; for the ones you already have, add the folder under Watch folders.
- Ray Local doesn't use integrated or Intel graphics: use the
cpuimage there. - With an NVIDIA graphics card (the
cudaimage), Sunlight doesn't separate voices from the background sound yet: it makes the subtitles from the full soundtrack, and each job says so. AMD cards do separate voices (pass/dev/kfd). - Sign in with your Ray app is off until an owner turns it on, and works from the server's own network only (Tailscale addresses count as outside). Approving needs Ray 4.0.16 or later on a computer; the Ray phone apps can't approve it yet.
- Browsing the server's folders always needs a key: a server that runs without any key never lists its folders, not even to a browser on its own computer.