# MediaWarp rewrites Emby and Jellyfin responses to redirect Strm playback

> MediaWarp is a Go reverse proxy that sits in front of Emby Server, Jellyfin or FNTV and modifies the responses the media server returns, so Strm files become 302 redirects, specific clients can be blocked, and the web interface can be restyled. It suits self hosted library operators who want direct links and custom front ends, and it is not a media server.

**AkimioJR/MediaWarp** — Emby/Jellyfin/飞牛影视中间件：优化播放 Strm 文件、自定义前端样式、自定义允许访问客户端、嵌入脚本，推荐配合AutoFilm使用，交流群：https://t.me/AkimioJR_MediaWarp

- Repository: https://github.com/AkimioJR/MediaWarp
- Website: https://blog.akimio.top/posts/1041/
- Stars: 786 · Forks: 80
- Language: Go
- License: NOASSERTION
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/akimiojr-mediawarp

## A proxy that edits the media server's own responses

MediaWarp is described as a reverse proxy placed in front of Emby Server, Jellyfin or FNTV that modifies the responses the original media server returns in order to implement its features. That is the whole architecture, and it explains the design choices. Rather than patching the media server, MediaWarp sits on the network path, receives the client's request, forwards it upstream, and then edits the response on the way back. The consequence is that MediaWarp is media server agnostic within the three families it supports, and the client never knows it is there beyond the address it connects to. The code is Go, with main.go at the repository root and the implementation split into internal/, constants/, custom/, utils/ and static/ directories, plus a config/ directory and a logs/ directory. The dependency list is short and tells you what the proxy does: gin for the HTTP layer, logrus for logging, bigcache for caching, gjson and sjson for reading and rewriting JSON responses, and yaml.v3 for configuration.

## Strm files become redirects so traffic avoids the media server

The headline feature is 302 direct link playback for Strm files, with the traffic not passing through the Emby Server, Jellyfin Server or FNTV server. Two Strm flavours are described. HTTPStrm means the Strm file content is an HTTP link, and a browser visiting that link can download the video file directly; the requirement is that the client can reach the link, while MediaWarp does not need to reach that address at all. AlistStrm means the Strm file content is the path of a video file on AList. Its requirements are narrower and more delicate. The path must be utf-8 encoded. Only services implementing the AList v3 API are supported, and OpenList is compatible with that API. The client does not need to reach the AList server, but MediaWarp does, and it also needs to reach the raw_url attribute of the file on that server. If the storage is a netdisk, that last point can be ignored, though compatibility is poor and transcoding is not supported, which can be mitigated by mounting a real directory. The documentation recommends using it with AutoFilm.

## Client blocking works on User-Agent rather than accounts

The second feature is blocking specific clients from accessing the server, and the mechanism is documented separately in docs/UA.md, a User-Agent reference. That naming tells you the matching is done on the User-Agent header, which has two consequences. It is easy to configure and it is easy to bypass, because a client that sends an unexpected User-Agent string is not identified as the one you blocked. There is no account level or device level identity in this mechanism, so blocking is a filter on request metadata rather than an access control decision. The same caution applies to the embedded scripts, since several of them are keyed to the presence of particular page elements and behaviour. The repository also lists a good set of upstream projects it draws ideas, scripts and front end styles from, including embyExternalUrl, emby-front-end-mod, dd-danmaku, emby-crx, jellyfin-crx and a fontInAss project.

## Front end customisation is by injection, not by theming

The customisation story covers HTML, CSS and JavaScript, and the built in script list shows how far it goes. ExternalPlayerUrl calls an external player for Emby and Jellyfin. crx applies the emby-crx or jellyfin-crx beautification packages. ActorPlus hides cast and crew members who have no avatar. FanartShow displays fanart images. Danmaku adds web danmaku, with dd-danmaku for Emby, jellyfin-danmaku for Jellyfin and a local fn-danmaku.js for FNTV. VideoTogether adds a watch together feature for all three servers. One entry has been removed: the BeautifyCSS option for Emby is struck through as removed, and the documentation redirects anyone who still wants it to the custom Web.Head feature. That detail is worth noting because it shows the project's pattern. Beautification is not a theme engine. It is a set of specific injections that the maintainer writes and updates, on top of a custom HTML, CSS and JavaScript hook where you can add your own.

## Configuration is one file, and the old multi format support is gone

The TODO list shows a lot of checked items, and among them are two entries that describe how configuration works today. Supporting several configuration file formats, with a priority order of JSON over TOML over YAML over YML over Java properties over Java props, is struck through as done and then removed, and the reference is to an example file at config/config.yaml.example. What remains checked is support for pointing at a configuration file with the --config parameter. So in its current state the project expects a single YAML configuration file, and the documented example path is:

```bash
./config/config.yaml.example
```

The other checked items show the feature set in practice: the 302 redirect for HTTPStrm and for AlistStrm, client blocking, the web front end beautification options, the embedded JavaScript, and caching of images and subtitles for performance. There is also ART subtitle to ASS conversion, marked as Emby only. Two items are still open. ASS subtitle font subsetting with embedded fonts is not done, and Plex adaptation is not done. Playback of transcoded netdisk content is listed as done but restricted to FNTV in AListStrm mode.

## Features the maintainer explicitly dropped

The TODO list is unusual in recording the reasons for abandoning features, and those reasons are the most useful engineering notes in the repository. Using Redis for data caching was dropped because the demand was small, and the note says anyone who needs it can use the caching in Nginx or another reverse proxy. Multi-server transcoding and streaming was dropped for the same reason. Optimising the library scanning experience in Infuse mode with MySQL, PostgreSQL or Redis was dropped, with a pointer to another project for anyone who wants to implement it. Multi-server load balancing was dropped too, with the observation that putting a load balancer in front of the server may be better. That last note is worth internalising. MediaWarp is a rewriting proxy for a single upstream, not a cluster node. If you are running several media servers and want them behind one address, that is a load balancer job, and MediaWarp's own position is that it should not try to be one.

## Where to get the build and how to keep up with it

The repository does not carry install instructions in the README itself, and it points instead at a tutorial document at blog.akimio.top/posts/1041/. A Docker image is published at akimio/mediawarp, and the repository carries a docker/ directory along with a .gitmodules file and a config/ directory, so a container image and a from source build are both the expected path. The project is written in Go with module path github.com/AkimioJR/MediaWarp, requiring go 1.26.1 with toolchain go1.26.6, which means a recent Go toolchain is needed to build it. Documentation lives in the repository as well: docs/UpdateLog.md for the changelog, docs/DEV.md for development notes and docs/UA.md for the User-Agent reference. Release history shows v0.2.5 on 2026-09-29 and v0.2.4 on 2026-06-08, plus a pre-release build in late September, and the last push was on 2026-10-01. The project is not archived and carries badges inviting pull requests and issues, with a Telegram group linked for discussion. The licence is a custom one that GitHub cannot classify, so read the LICENSE file before you put this in front of a library.

## Conclusion

Adopt MediaWarp when you run Emby, Jellyfin or FNTV with Strm libraries and want playback traffic to bypass the media server, when you need to block specific clients by User-Agent, and when you want to change the web interface without patching the server. Do not adopt it as a replacement for the media server, as a Plex adapter, since Plex support is an open TODO item, or as a transcoding solution, since netdisk transcoding works only in FNTV AListStrm mode. Verify first that your AList or OpenList instance exposes the v3 API and that the raw_url attribute is reachable from MediaWarp, that your strm paths are utf-8 encoded, and that the licence in the LICENSE file matches what you are willing to run in front of your library.

## FAQ

### What does MediaWarp do for Strm files?

It lets them play through a 302 redirect so the traffic does not pass through the Emby Server, Jellyfin Server or FNTV server. Two modes are described, HTTPStrm where the strm content is an HTTP link, and AlistStrm where the strm content is a path to a file on an AList v3 API compatible service such as OpenList.

### Can I use MediaWarp with Plex?

Not yet. The TODO list marks Emby, Jellyfin and FNTV adaptation as done and leaves Plex adaptation unchecked, so Plex is an open item rather than a supported target.

### What does MediaWarp need from an AList server?

Only services implementing the AList v3 API are supported, and OpenList is compatible with that API. The client does not need to reach the AList server, but MediaWarp does, and it also needs to reach the raw_url attribute of the file, with strm paths encoded in utf-8.

### How do I configure MediaWarp?

Configuration is a YAML file, with an example at config/config.yaml.example, and the path can be given with the --config parameter. An earlier item covering JSON, TOML, YAML and Java properties formats with a priority order is struck through as removed, so the multi format support is no longer part of the project.

### Can MediaWarp handle transcoding for netdisk playback?

Only in the FNTV AlistStrm mode. The TODO list marks playback of transcoded netdisk content as supported for that combination only, and the AlistStrm section notes that compatibility is currently poor and transcoding is not supported, which can be mitigated by mounting a real directory.

## Sources

- [AkimioJR/MediaWarp on GitHub](https://github.com/AkimioJR/MediaWarp)
- [Issues](https://github.com/AkimioJR/MediaWarp/issues)
- [Project website](https://blog.akimio.top/posts/1041/)
- [README](https://github.com/AkimioJR/MediaWarp/blob/main/README.md)
- [Releases](https://github.com/AkimioJR/MediaWarp/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/akimiojr-mediawarp