Troubleshooting

The problems people run into most, and what to do about them.

Your server:

Your platform:

Video stops after about eleven minutes and goes black

This is a known behavior with some Plex server configurations: Plex needs active session reporting to keep a stream alive past its timeout threshold.

The fix: open your Lineup's Configure and, under Server Activity Awareness, turn on Send Coax activity to Plex. Coax then reports playback progress to your server, which keeps the stream running. There is more on that setting in Sending watch history.

My server isn't showing up

Check that the server is running and that your account has access to it.
Plex: if you are on a different network from your server, Coax will try to connect via Plex relay — make sure remote access is enabled in your Plex server settings.
Jellyfin or Emby: double-check the server address you entered when signing in, and make sure the server is reachable from your device's network.
How Coax picks an address, and how to give it one of your own, is in How connections work.

Guide generation fails or seems stuck

Preparing Schedule can take a while on a slow server — Coax is contacting it and gathering content, so give it a moment before assuming something has gone wrong.
If it never finishes, check that your server is up and reachable from another device on your network.
Very large libraries — tens of thousands of items — take longer on the first build. Once a schedule exists it is saved with the Lineup, so later opens are much faster.

A channel is empty or missing

Not every category produces channels for every Lineup. If your libraries have no collections, for example, no Collection channels appear.
If you recently added content, collections, or playlists on your server, use Refresh on the Lineup: see How refreshing works.
Check that the category is actually enabled in the Lineup's Channels Manager.
Some rows need something first: on Jellyfin, Director and Actors need the Coax plugin, and Emby has no Director or Actors channels at all. See The Channels Manager.

Content I expected isn't in the guide

Each schedule is a shuffled selection, so not every item appears in every guide. Refresh for a different mix.
Anything in a collection named NoCoax on your server is excluded on purpose (see Keeping content out of your guide). Check whether the item was added there by accident.
If an age-group limit is set — on the Lineup or in Parental Controls — content above that limit is filtered out.

Playback is poor or keeps buffering

Turn on Show Streaming Type in the Lineup's Configure › Display Settings and watch for the label over the video when a stream starts. If it says Transcode, your server is re-encoding video in real time — that is CPU-intensive and a common cause of buffering. See The stream type indicator.
Move to a faster network connection if you can.
On Apple TV, wired Ethernet is considerably more reliable than Wi-Fi for high-bitrate content.

Audio or subtitles aren't working

Pick a track by hand in Stream Options. Your pick stays for that title.
If the track you expected isn't there, check that the file on your server has it: see Audio and subtitle tracks, and for the formats Coax hands to a server transcode, Codecs and containers.

I've forgotten my parental controls PIN (Apple TV)

There is no PIN recovery, and signing out of your server does not reset the PIN. Email relaxwithcoax@gmail.com and I'll help.

The app isn't reopening my last Lineup

Check that your server is reachable on your current network.
If a Plex server's address has changed — a new IP, say — Coax asks Plex for the new one and reconnects on its own. While it reconnects, Go to Server Selection takes you to the Servers screen instead.

Suggested server settings

Not every Plex server is set up the same way. These are the settings that give Coax the best out-of-the-box experience.

In Plex, open Settings › Transcoder:

Enable HEVC video encoding: on. Coax asks for HEVC. With this off, or with an H.264 target, a reduced-bitrate stream comes back 8-bit SDR instead of HDR.
Enable HDR tone mapping: on if any screen in the house is SDR.
Hardware transcoding: on where the server has an encoder (Plex Pass).
Under Remote Access, leave Limit remote stream bitrate unset or high. Coax starts every stream at full quality and measures the link itself; a server cap forces transcodes that were not needed.

Then Settings › Network › Terminate Sessions Paused for Longer Than: set it to 0. Coax ends a paused channel itself after five minutes. Unless a Lineup sends Coax activity to Plex, Plex cannot tell a paused Coax session from a stalled one and may end a transcode after a few minutes.

Install the Coax plugin from Dashboard › Plugins › Catalog. It is optional: it unlocks Director and Actors channels, and it hands Coax your whole library in one request, so channel setup is faster. Coax offers the install on the Lineups screen when it is missing.

Then Dashboard › Playback › Transcoding:

Hardware acceleration: on where the server has an encoder.
Allow encoding in HEVC format: on, so HDR titles stay HDR when reduced.
Tone mapping: on if any screen in the house is SDR.

These follow Jellyfin's own guidance. Jellyfin has no paused-session timeout to change.

In Emby, open Settings › Transcoding:

Hardware encoding: on where the server has an encoder.
HEVC encoding: on, so HDR titles stay HDR when reduced.

These follow Emby's own guidance. There is no Coax plugin for Emby, and Emby has no paused-session timeout to change.

Remote access. A server reachable only at home works at home. Away from home needs the server's remote access on, or a tailnet.
Finished scans. Coax reads durations and codecs from the server. An unanalyzed library schedules badly.
Ratings. If you will use Parental Controls, fill them in: see How age groups map to ratings.

Audio and subtitle tracks

Coax plays the tracks your server has. It does not download or generate subtitles, and it cannot add an audio track the file lacks. Put the language, commentary, or subtitle on the server first, embedded or as a sidecar.

Image subtitles (PGS, VobSub) are read into text on the device, so they use Coax's caption style and carry into Picture in Picture. A cue that cannot be read confidently shows as the original image.

Which audio track plays:

The track chosen on the server for that title. Plex remembers your last pick in its own apps; Coax honors it. Jellyfin has no remembered choice, so this step is skipped. Emby has no remembered choice, so this step is skipped.
Otherwise a main track. Commentary, audio description, and isolated scores are never auto-picked.
Then the file's default track, then the first.
If the Lineup has a Preferred Audio Language and the pick is not in it, Coax looks for one that is.

A track you switch to in Stream Options stays for that title, on all your devices.

Subtitles are one three-way setting in Stream Options:

Per-Item (default). Off unless something chose a track: your earlier pick for that title, the Lineup's Preferred Subtitle Language, or a track the server marks default or forced. Pick any track or none; Coax remembers it per title.
On. A subtitle on every program: your language first, then the file's default, then forced, then the first. You can change the track for a title, but not turn it off.
Off. Never, even when the device's Subtitles & Captioning switch is on.

The device's accessibility switch promotes Per-Item to On, the same as Apple's players.

Languages. Each Lineup can carry a Preferred Audio Language and a Preferred Subtitle Language. With neither set, Coax uses the device's language list. "en", "eng", and "en-US" are one language.

On the server: name your tracks, set their language, mark the default, and keep commentary flagged as commentary. An unflagged commentary titled "Track 2" looks like a main track.

Codecs and containers

Coax never re-encodes video on the device. It plays the file as it is, repackages it without touching the picture, or asks the server to transcode. The reasoning is in Concerning Video Players on r/coax.

Format	What happens
MP4, MOV, M4V	Plays directly.
MKV, other containers	Repackaged on the device, video copied bit for bit. No quality loss, no server work.
H.264, HEVC	Native on every Apple device. HEVC 10-bit carries HDR10 through direct play and repackaging.
Dolby Vision 8.1	Plays everywhere.
Dolby Vision 7	Plays as HDR10. The enhancement layer is dropped.
Dolby Vision 5	Plays natively on HDR devices (Apple TV 4K, HDR iPhones and iPads). No fallback: the server cannot transcode it, so an SDR screen or a quality cap has nothing to play. Prefer 8.1.
AV1	Hardware decoders only (the newest iPhone, iPad, Mac, and Apple TV). Elsewhere the server transcodes.
MPEG-2	Server transcode on iPhone, iPad, Apple TV, and Vision Pro. The Mac plays it.
Interlaced (1080i, 480i)	Server transcode, so the server can deinterlace. Deinterlace at rip time.
AAC, AC3, E-AC3, ALAC	Copied as is.
DTS, DTS-HD	The DTS core is decoded on the device to AAC. The lossless layer is unused.
Opus, MP3	Decoded on the device to AAC.
TrueHD, MLP	Not played. The system player cannot, and Coax does not decode it for licensing reasons. Coax plays the AC3 or E-AC3 track beside it instead. A title whose only audio is TrueHD goes to a server transcode.
SRT, WebVTT, ASS	Cleanest subtitles.
PGS, VobSub	Read into text on the device.

Atmos. Apple devices never bitstream TrueHD or DTS-HD; they decode and send PCM. Apple TV passes Dolby Digital and Dolby Digital Plus through. Atmos on Apple TV is E-AC3 with object metadata, and Coax copies E-AC3 untouched, so an E-AC3 Atmos track reaches your receiver. TrueHD Atmos cannot, in any app.

Best choice: MP4 or MKV, H.264 or HEVC (10-bit for HDR), AAC, AC3, or E-AC3 audio, text subtitles, progressive video. Keep the AC3 or E-AC3 track beside the TrueHD one, and prefer Dolby Vision 8.1 over Profile 5.

When a server transcode is needed, the Plex transcoder settings above decide whether HDR survives it.

When a server transcode is needed, hardware acceleration and HEVC encoding keep it close to the source.

When a server transcode is needed, hardware encoding and HEVC encoding keep it close to the source.

How Plex connections work

A Plex server publishes several addresses: local, remote, and a relay through Plex. Coax tests them, picks the fastest one that works, local first, and checks again when your network changes.

A Custom connection is an address you type yourself. It always wins, even when a local address answers faster, so a Tailscale or reverse-proxy address stays in use wherever you are. To add one on iPhone, iPad, Mac, or Apple TV: Settings › Servers, open the server's connection options, choose Custom…, and enter the address. Manual… picks one of the server's own addresses instead, and Automatic in the same menu goes back to letting Coax choose.

A Jellyfin server has one address in Coax: the one you entered when you signed in. At home that is usually the local address. To watch away from home, sign in with an address that reaches the server from anywhere, such as a Tailscale address or your public hostname.

An Emby server has one address in Coax: the one you entered when you signed in. At home that is usually the local address. To watch away from home, sign in with an address that reaches the server from anywhere, such as a Tailscale address or your public hostname.

What Coax asks of your server

Your server works only for what someone is watching right now. A Lineup with three hundred channels costs nothing until you tune one, and then it costs one stream.

Building a schedule is metadata. A burst of small requests at the first build, then at most once an hour per Lineup, from the one device that built it (see How refreshing works). Your other devices read the result from iCloud. No transcoder, no meaningful CPU.

Watching a channel costs one of three things, decided per title. Stream Options shows which.

Direct play. The file as it is. Bandwidth is the file's bitrate. MP4 and MKV both get this, because Coax repackages MKV itself.
Direct stream. The server repackages without re-encoding, for the few cases the device cannot. Light CPU.
Transcode. The server re-encodes the video. A 4K HEVC transcode is a full core or more without a hardware encoder. Coax asks for it only for a Quality cap below the file, a remote link that cannot carry it, a video the device cannot decode (MPEG-2, interlaced, TrueHD-only), or Force Transcode.

Audio Coax converts on the device (DTS, Opus, MP3) costs the server nothing.

Bandwidth at home is the file's bitrate: roughly 5 to 15 Mbps for 1080p, 15 to 50 Mbps for a 4K Blu-ray rip. Away from home, Coax starts at full quality and steps down when the link cannot keep up.

Devices. Each device that is watching is one stream. Changing channels ends the previous stream. Quit Coax normally; a force-quit mid-transcode can leave the server finishing a stream nobody is watching.

Poster art is cached on the device. Playback progress goes back to the server, a few bytes a minute, when a Lineup sends Coax activity, which is off by default.

For a modest server: H.264 or HEVC with AAC, AC3, or E-AC3, hardware transcoding on, Quality at Full. Then almost everything is direct play.

Stream Options

In full screen: the gear on iPhone and iPad, Watch › Stream Options on the Mac, press right on the Apple TV remote. Audio and subtitle picks are remembered for the title you made them on; Quality and its two switches apply to every channel.

Quality. Full plays the file as it is. High, Medium, and Low cap the picture at 1080p, 720p, and 480p and ask the server to transcode. Coax starts at Full and steps down only when the link cannot keep up, so Full is right for most people. Two switches, here and in Settings › Playback: Always Play Full Quality waits for a buffer rather than dropping a stream, and Force Transcode transcodes everything, the thing to try when a file will not play. They exclude each other.
Audio. The file's tracks, with Coax's pick marked. Tracks are named by language, codec, and channel count, and extras are labeled for what they are.
Subtitles. Off, Per-Item, or On, plus the track list. See audio and subtitle tracks.

Stream Options cannot add a track the file does not have.

Something else is wrong

Get in touch and I'll help:

Email relaxwithcoax@gmail.com
Post on r/coax
Find me on Mastodon