FAQ and troubleshooting

The questions that come up most in issues and discussions. If yours is not here, open an issue.

General

Does Muxarr re-encode my files? Is there quality loss?

No. Muxarr copies the video and audio unchanged and leaves out only the tracks you chose to remove. That is what makes it fast and lossless. When an MKV only needs new names or flags, it does not even rewrite the file; the metadata is edited in place.

Does Muxarr rename or move files?

No, never. Not the filename, not the folder, not the extension; renaming is Sonarr's and Radarr's job. Post-processing is not a rename feature either: it runs whatever command you give it after a conversion, nothing more. See post-processing.

How do I get Plex, Emby or Jellyfin to notice the changed file?

Add the server under Settings › Notifications with the Completed trigger. Muxarr then asks it to refresh after each conversion. Details under Plex, Emby and Jellyfin.

Which files does Muxarr handle?

MKV, WebM, MP4 and M4V. Files stay in their own format; Muxarr does not turn MKV into MP4 or the other way round. One difference: an MKV that only needs new names or flags is edited in place, while an MP4 is always rewritten, still without re-encoding. If the MP4 was set up for streaming (fast start), it stays that way.

Can I run Muxarr on a Raspberry Pi or a small NAS?

Yes. Since nothing is re-encoded, the work is mostly disk I/O. Images are published for amd64 and arm64.

How do I update?

With Docker Compose: docker compose pull followed by docker compose up -d in the folder with your compose file. Your database and settings live in the /config volume and are migrated automatically on start; keep that volume mounted, and back it up before a big update if you like to be careful.

Languages and tracks

The Original Language of my files shows "-"

Muxarr learns the original language from Sonarr and Radarr, so first check that they are connected under Settings › Integrations. Files that already existed get their language on the next sync, which runs once a day; new imports get it instantly through the webhook. If a title is not in Sonarr or Radarr at all, Muxarr has no way to know.

A foreign film lost its original soundtrack

Either Original Language is missing from the profile's audio list, or Muxarr did not know the original language for that file (see above). Add the row, make sure Sonarr or Radarr is connected, click Force in the Library (or Analyze File on that one file), and check the preview on the file's page before you queue it again. Muxarr always keeps at least one audio track, so the file is not silent, but it may have kept the dub rather than the original.

What about tracks with no language tag?

A file with exactly one untagged audio track is treated as the original language, provided Muxarr knows what that is and Assume undetermined language is original language is on (it is by default for audio). With several untagged tracks Muxarr does not guess. To keep untagged tracks unconditionally, add Undetermined to the language list. To fix the tags for a whole season at once, use batch edit.

German subtitles if available, otherwise English?

That is exactly what fallback languages are for: put German first, add English below it and click its button. See Fallback languages.

Why was a forced subtitle kept?

Forced subtitles are the ones for foreign dialogue and signs, and they are kept whenever their language is on your list, because you generally want them with the matching audio. They never count as "having" a language for fallback purposes, so a forced-only track does not block a fallback. If a specific file should lose one, use Custom Conversion.

The commentary or SDH track was kept even though I remove them

Muxarr keeps a commentary or SDH track when it is the only track that language has, so the language does not disappear entirely. Two regular tracks plus a commentary: the commentary goes. Just a commentary: it stays. Same for SDH, where a forced subtitle does not count as the regular alternative.

VFQ, VFF, Latino, Castellano: can Muxarr tell dubs apart?

Yes. Muxarr recognises regional variants from language tags and from track names, and lets you list French (Canada), Spanish (Latin America) and friends as languages of their own. See Regional variants.

I changed a flag or name in batch edit and it came back after a rescan

Muxarr reads flags such as forced, SDH and commentary back from track names on every scan, because many releases only carry them in the name. If the name still says "SDH", the flag returns. Change or clear the name in the same edit; batch edit points this out when it applies.

Files on disk

What are .muxtmp and .muxbak files?

.muxtmp is the new file being written; .muxbak is the original during the swap. Both exist only for seconds in normal operation. If Muxarr was killed mid-swap you may find one lying around; on the next start it cleans up: temp files are deleted, and a .muxbak whose original is missing is restored. Do not delete a .muxbak by hand if the original is gone, it is your file.

What about hardlinks and seeding?

When Sonarr or Radarr import by hardlink, the download and the library file are two paths to the same data on disk. Two things can then go wrong: a metadata edit done in place changes the seeding copy as well, and the torrent fails its hash checks; a full rewrite leaves the seed alone but splits the link, so the file now takes twice the space. Turn on Skip hardlinked files in the profile and Muxarr leaves those files out of scans and conversions until only one link remains, typically once you stop seeding and the download is removed. Files that are hardlinked but not skipped show a icon in the Library.

What does a scan warning mean?

ffprobe reported a problem while reading the file: a truncated stream, an odd container element, and so on. The file was still scanned. Filter the Library on Has Scan Warning to find them and check the probe output at the bottom of the file's page. Usually the file plays fine and converts fine.

Where does Muxarr keep its data?

Everything is in the /config volume, in an SQLite database. Back that folder up and you have your profiles, settings and history. It is the same layout the linuxserver containers use, so Muxarr sits next to Sonarr and Radarr without surprises.

Older versions kept the database in /data. That still works, and Muxarr shows a small yellow bar at the top while it does. Moving over is a one-line change:

• You mounted a folder at /data: change that line to :/config, same host folder, and restart. Nothing is copied or moved; the database is simply used from its new path. To roll back, point it at :/data again.
• Your appdata folder is empty (you never mounted one, or you mounted /config on a version that ignored it): the database sits in a Docker volume. Stop the container, run docker cp muxarr:/data/. /path/to/appdata/ before removing it, then mount that folder at /config.
• Already recreated the container and Muxarr starts empty? The old database is still in a dangling volume: docker volume ls, then copy muxarr.db out of /var/lib/docker/volumes/<id>/_data into your appdata folder.

When something goes wrong

A conversion failed

Open the conversion and read the log; the reason is normally in the last lines. Common ones:

• Permission denied: PUID and PGID are the user and group the container runs as; that user needs write access to the media folder.
• No space left: the new file is written next to the original, so you need free space for one more copy of the largest file.
• Validation failed: the result did not match the plan (a missing track, a wrong duration). The original is untouched. Open the file in the Library, click Analyze File and queue it again; if it keeps failing, open an issue with the log.
• Timed out: raise Conversion timeout under Processing, or set it to 0.

Nothing gets converted after a download

Check, in this order:

1. The Sonarr or Radarr card shows Webhook Active. If not, click Connect Webhook.
2. Muxarr URL is an address Sonarr and Radarr can actually reach.
3. The file's folder is covered by a profile, taking path mappings into account if the containers see different paths.
4. Auto-queue files for conversion is on.
5. The queue is not paused (there is a banner on the Conversions page when it is).
6. The Logs page, filtered to warnings (WRN) and errors (ERR).

The Library says a file needs work, but queueing does nothing

The toast after queueing tells you why: a conversion is already queued or running for it, the file is not reachable right now (an unmounted share), or it became hardlinked since it was scanned and the profile skips those.

Bazarr and Muxarr fight over the same file

Both react to imports. Give Bazarr a head start with the Processing delay (60 seconds by default). Muxarr also does not use external subtitle files, so Bazarr's .srt files next to the video are never touched.

Login keeps asking on my LAN, or never asks from outside

Trust the local network decides by the client address. Behind a reverse proxy every request comes from the proxy, so make sure it forwards X-Forwarded-For; otherwise everyone looks local, or nobody does.