Why the subtitle Quven generated isn't next to your film in Docker

A tester running Quven Server in Docker on Ubuntu wrote to us this week with a question we hadn’t answered anywhere. They had asked the player for a subtitle on a film that had none. The server generated one from the dialogue, the player listed it as generated from the audio, and it played. Then they opened the film’s folder on the host, expecting to find the subtitle file next to the video, and there was nothing there. So where had it gone?

Their server log had the answer, in two lines that arrive one after the other. The first says that the generated subtitle asset was stored for the audio stream they chose. The second is a warning: the portable copy of a transcribed subtitle could not be written, and the server keeps its own. Under it is the reason, IOException: Read-only file system, on a path under /media.

Two copies, and only one of them is needed

When Quven produces a subtitle, it keeps the result in its own store. On an ordinary installation that store sits under the application data folder; in the container it’s inside the quven-data volume. Every client will play the subtitle from there, which is why the tester’s player listed the track and played it without any trouble.

Separately, the server tries to write a second copy beside the video, as an ordinary sidecar file. That copy exists for your benefit, and Quven itself never reads it back. It means the text can travel with the film if you move the folder to another machine, or hand it to somebody who doesn’t use Quven at all. If the copy can’t be written, the server will log the warning above and carry on. There’s no setting for it, because nothing about playback depends on it.

The same applies to every subtitle Quven produces, whichever way it was produced. A track translated into another language, an image subtitle recognised into text, and a track you’ve corrected in the cue editor all take the same path: stored in the data volume, and copied beside the film when the folder allows it.

Why the folder didn’t allow it

The Compose file published up to 1.1.21 mounts your media with read_only: true. That was deliberate. It’s the guarantee that the server can catalogue and play your library and can’t modify a byte of it, whatever happens inside the container. What the line also does, and what our guide never said, is stop the sidecar copy. The tester had followed the guide exactly, and the guide had left that part out.

What we changed

From 1.1.22 the published Compose file mounts your media so that copy can land. The guarantee didn’t disappear, it moved into your hands. QUVEN_MEDIA_READ_ONLY=true in your own .env closes the mount again, and because that setting lives in a file we never overwrite, it survives the next upgrade. Deleting a line from compose.yaml never did, since the guide asks you to download that file again with every release.

Two things are worth knowing whichever way you leave it. The container runs as user 10001, so the media directory on the host must be writable by that uid. Without that the copy will fail again, with a permission error instead of a read-only one. And Quven still won’t touch your video files. What it writes beside them is the subtitle it made for you, under the name of the film it belongs to, which is the only thing it has ever written into a library folder and the only thing it will write into yours. Nothing else goes there.

If you are on an older bundle

Open compose.yaml, delete the read_only: true line under the media bind, make the directory writable by uid 10001, and recreate the container with docker compose up -d. Upgrading will do the same thing without the edit, and it will keep doing it, which an edit to a file you download again every release cannot promise.

Frequently asked questions

Does the generated subtitle still work if the copy beside the film fails?

Yes. The server keeps the subtitle in its own store inside the data volume, and every client plays it from there. The copy beside the film is an extra you can do without, and the warning in the log is the only sign it was skipped.

Which subtitles does this affect?

All the ones Quven produces: transcribed from the audio, translated into another language, recognised from an image track, or corrected in the cue editor. They’re stored the same way and copied beside the film the same way.

How do I get the files next to my videos?

On 1.1.22 and later they should arrive on their own, as long as the media directory is writable by uid 10001. On an older bundle, remove read_only: true from the media bind in compose.yaml and recreate the container with docker compose up -d. Without a writable directory the copy fails again with a permission error.