StrmTool settings PRO · MAX

StrmTool is the built-in extension that handles .strm files: it decides how each video reaches the player, keeps direct links, and reads media info ahead of time. This page explains every setting and suggests a value. For how to write a .strm file and the main ideas, read strm and cloud drives first.

On this page

Turn it on
Settings
Local paths and addresses
Local network and outside
Reading in the background
Common problems

Turn it on#

Open Plugins and find StrmTool under Built-in features. Turn it on and open its settings. It needs PRO. Without a license the extension stops and shows License required; your settings are kept and take effect again when the license returns. .strm files still play meanwhile, always forwarded through the server.

Settings#

Setting	What it does	Suggested
Default delivery	How videos reach the player in libraries that do not choose their own. Proxy through the server: the server fetches the file and streams it on. Redirect the player: the player fetches it from the link directly, so it must be able to reach the link. Redirect on the local network, proxy outside: direct at home, forwarded away from home.	Leave on Proxy if you are unsure. Use Redirect on the local network, proxy outside when your home upload is small and the drive is reachable from your local network.
Address rewrite rules	One rule per line, `prefix => replacement`. The first rule whose prefix matches the start of an address is applied before the address is used, for example to swap an internal host name for a public one. Lines starting with `#` are comments. Only the first match applies, and it is plain text matching, not a pattern. Applies to addresses, not to local paths.	Empty. Add a rule when a redirect points at an internal address that players outside cannot reach.
User-Agent sent to the remote	Sent when the server itself connects, and only to the address's own host. Empty uses the server's default. In redirect mode the player connects by itself, so this is not used; the lookup for the direct link uses the player's own User-Agent.	Empty, unless the drive refuses the default.
Cookie sent to the remote	Same conditions as the User-Agent, and never sent when a player is redirected. Stored encrypted and never shown again.	Empty, unless the drive needs a login cookie. For these sources use forwarding, not redirect.
Direct link cache	Looks up the drive's direct link once and reuses it for about three minutes (shorter if the link says it expires sooner): faster start, fewer requests to the drive. Only used when the player is redirected. Changing the rewrite rules makes old cached links expire by themselves.	On. Turn it off if playback from outside is refused with a 403.
Read the next episode while playing	When an episode starts, read the next one's media info in the background. Works for libraries whose Reading media info is not On playback.	On.
Read when a detail page is opened	When an item is opened and its video info is still missing, read it in the background. It only reads sources not yet read, in libraries whose Reading media info is not On playback.	Off by default. Turn it on if first playback of items you open is slow.
Pre-read media info	Reads the video info of remote links ahead of time: after scans, in the background, for the next episode and when a detail page is opened, so the first playback starts faster. Off leaves only local-path files pre-read; the first play still reads the file on the spot.	On.
Save results as files	Saves each result as a small file in the server's data folder, so it can be reused when items are removed and added again or the database is rebuilt. The Media info cache plugin keeps more (tracks, chapters, intro and credits marks) and restores it before a scan; both can be on, at the cost of some disk.	On. Add Media info cache if you want to keep intro and credits marks after a rebuild.

Each library can choose its own Default delivery under STRM playback in its settings: Follow the default, Proxy through the server, Redirect the player, or Redirect on the local network, proxy outside. A change applies the next time a video is delivered.

Local paths and addresses#

A local path (the .strm file holds a path starting with /): always forwarded by the server, read only from folders the administrator has allowed. Rewrite rules and redirects do not apply.
A web address (http:// or https://): forwarded or redirected according to the delivery setting, after rewrite rules are applied.

Local network and outside#

With Redirect on the local network, proxy outside, the server decides per connection. A connection on port 5797 from a private address counts as local and gets a direct link. A connection that arrives on the outside-access port 5798, or from a public address, is forwarded by the server. If the server cannot tell, it forwards. A redirect only works if the player can reach the address, so an internal address needs a rewrite rule. Behind a reverse proxy, set up trusted proxies so the right side is chosen; see Remote access.

Only playback is redirected. The web player's streams, reading media info, casting and anything that needs repackaging always go through the server.

Reading in the background#

New items (added within the last 7 days) are read first; older unread ones are not queued automatically. The scheduled task Read media info of unread sources works through that backlog every night between 02:00 and 05:00, and you can also start it by hand. Playing an item or opening its page moves it to the front of the queue. If the drive answers 403 or 429, reading for that library pauses for a while.

The StrmTool page shows how it is running: Reads succeeded, Reads failed, Reading now, Link cache hits, Link cache misses and Fell back to direct redirect. The counts start from zero when the server starts.

Common problems#

Playback from outside returns 403. The drive may tie its links to the player's address. Turn Direct link cache off, or use forwarding for that library.
The player cannot reach the redirect. The address points to an internal host. Add a rewrite rule, or choose forwarding.
A read fails with "The link is gone (404)". Check the link inside the .strm file and that the file is still on the drive.
A read fails with "The link does not return a video". Open the link in a browser and check what it returns.
“The remote source cannot be reached”, and the address uses a custom host name (for example nas.lan:5678). A name you added to the NAS's own /etc/hosts does not reach a Docker container: the container has its own name lookup, and it may resolve the name to 127.0.0.1, which is the container itself. Give the container the name in compose.yaml, under the server service, using the machine's address on your local network (here 192.168.1.10):

yaml server: extra_hosts: - "nas.lan:192.168.1.10"

Then run docker compose up -d. To check, run docker exec <container name> getent hosts nas.lan; it should print that address. Instead of extra_hosts, you can also use an address rewrite rule that swaps the name for the address: http://nas.lan:5678/ => http://192.168.1.10:5678/. - First playback is slow. Turn Pre-read media info on, set the library's Reading media info to Background or During scan, and let the nightly task finish the backlog.

See also Media info cache and PRO features.