MediaWarp 功能总结

核心功能

MediaWarp 是针对媒体服务器的增强工具，旨在优化基于 STRM 文件的流媒体播放体验，解决传统 STRM 方案中存在的带宽瓶颈和兼容性问题。

  1. 流量重定向优化

  • 绕过带宽限制：
    当客户端播放 STRM 文件时，MediaWarp 将客户端请求直接重定向至远程资源（如在线流媒体、远程服务器文件），避免流量经过家庭局域网的 Emby/Jellyfin 服务器，彻底消除宽带上行速率限制。

    • 传统模式：客户端 → Emby服务器 → 远程资源（受上行带宽制约）
    • MediaWarp模式：客户端 → 远程资源（直连加速）

  • 智能回退机制：
    若客户端因以下原因无法直接播放远程资源，MediaWarp 将自动回退至 Emby 服务器推流：

    • 跨域请求被拦截（如浏览器安全策略）
    • 需要身份验证（远程服务要求特定请求头）
    • 格式兼容性问题（如客户端不支持 H.265 编码）
    • 转码需求（客户端需降低分辨率或修改码率）
  1. 高级控制与兼容性
    • 强制禁止转码：
      通过配置可拦截转码请求，强制客户端仅使用原始流（适用于高带宽环境或追求画质场景）。
    • 无缝整合 STRM 文件：
      保留 Emby/Jellyfin 原有媒体库管理逻辑，无需修改 STRM 文件结构或命名规则。

技术优势

场景 传统 STRM 方案 MediaWarp 方案
带宽占用 受家庭宽带上行限制 客户端直连远程资源，带宽零占用
播放延迟 较高（需服务器中转） 低延迟（直连资源）
兼容性处理 依赖服务器硬解/转码 智能切换直连与中转模式
复杂网络适应 弱（受限于服务器网络） 强（客户端自主连接目标资源）

适用场景

  1. 家庭媒体中心优化
    • 解决家庭宽带小上行场景（如 30Mbps 上传）下 4K 原盘播放卡顿问题。
  2. 跨国/跨区域访问加速
    • 客户端直连海外 CDN 资源，避免通过家庭服务器跨国中转。
  3. 混合云媒体库管理
    • 统一管理本地存储、NAS 文件与云存储（如 AWS S3、阿里云 OSS）资源。

通过 MediaWarp，用户既能保留 STRM 文件在媒体库管理中的便利性，又能突破物理带宽限制，实现高效、灵活的流媒体分发。

Wiki

什么是 Strm，MediaWarp 又有什么用

EmbyServer 官方 Wiki 对 Strm 文件的表述：STRM 文件使用指南

STRM 文件使用指南

简介

STRM 文件是一种能让 Emby 媒体服务器将在线音视频流模拟为本地媒体文件的文本文件。只要流媒体格式及传输协议受 Emby 支持，即可通过 STRM 文件实现流畅播放。这类文件本质上是普通的文本文件，仅通过将扩展名改为 .strm 来伪装成特定格式，其内容包含指向流媒体的 URL 或本地文件路径。

支持协议：http、mms、rtsp 等（需 Emby 兼容）

strm 有如下几种情况：

1
>http://host/path/stream

或

1
>mms://host/path/stream

或

1
>rtsp://host/path/stream

或

1
>F:/Movies/Topgun (1986)/Topgun.mp4

或

1
>\\EMBYSERVER\Movies\Topgun (1986)\Topgun.mp4

示例

一个 strm 文件就像是一部电影

1
2
3
>\Movies
  \300 (2006)
     300 (2006).strm

Strm 文件可用于任何类型的视频，例如电影、剧集、音乐视频、家庭录像等等。

.strm 文件名的命名规范应遵循与相关内容类型（电影、剧集等）所使用的规范一致。然后只需将.strm 文件放置在你原本会放置视频文件的位置即可。

目前 Emy、Jellyfin 均支持 strm 文件，Plex 暂不原生支持。一言以蔽之，.strm是一种类似于 Windows .link 的“快捷方式”，文件内容指向了真实文件的存放地址

为什么要用 MediaWarp

当 Emby、Jellyfin 中存在 strm 文件并且指向正确时，客户端即可正确播放，如果资源是在远程服务器，此时 Emby 服务器会先从远程服务器下载资源然后再通过 ffmpeg 推流推送给客户端。如果在互联网中访问家庭局域网中的 Emby，其速度会受到家庭局域网出口的限制，即受到宽带上行速率的限制
使用 MediaWarp 后，当客户端需要访问某个影片时，MediaWarp 会尝试将客户端的请求重定向至远程服务的资源中，此时客户端会直接从远程服务中获取影片资源，流量不再经过 Emby 服务端，即不再受到宽带上行速率的限制
当客户端由于无法正确访问到远程服务器资源，例如浏览器拦截跨域请求、远程服务对请求头进行身份认证、客户端不支持影片资源格式（例如在浏览器中无法播放 H265 编码的视频）抑或是客户端需要转码播放时，客户端会请求推流播放，此时 MediaWarp 会将请求转发至 Emby 服务器，流量会再次经过 Emby 服务器（注：可在 MediaWarp 中配置，强制禁止进行转码，以拦截请求）

总而言之，MediaWarp 定位于服务端于客户端的一个中间件（也就是名字中为什么会带有 Warp），客户端请求原画播放时流量不再经过客户端，需要转码时服务端也能正确推流

HttpStrm

这是 MediaWarp 对 strm 文件中内容形如http://host/path/stream的称谓，也是网络各大论坛中对 strm 文件狭义的称呼方式

AlistStrm

其本质是本地文件，内容形如/Movies/Topgun (1986)/Topgun.mp4（可以使用 AutoFilm的AlistPath模式生成）,与传统本地 strm 文件不同的是，其路径真实存在于 Alist 服务的路径中并且 Emby 服务端可以无法访问 strm 文件内容目录（可以，但不推荐），请求原画播放时，MediaWarp 会尝试将客户端的请求重定向到 Alist 服务器的下载地址，抑或是 Alist 服务器上游的真实地址（网盘），区别在于浏览器是否收到 Alist 的控制，当 Alist 的访问策略是本机代理时，流量会受到 Alist 宽带的限制

安装

二进制可执行文件

在最新发布页面下载适合设备系统、架构的版本并解压，参考其中的config.yaml.example文件配置适合的配置文件，放在相对于可执行文件的./config/目录下，然后直接运行可执行文件

使用 Docker 安装

  1. 安装 Docker Engine 或 Docker Desktop
  2. 在发布页面下对应版本的压缩包，参考其中的config.yaml.example文件配置适合的配置文件，随后需要映射进容器的/config目录下
  3. 启动容器
    • 使用 Docker Run 的方式安装 
      1
      docker run -d --name MediaWarp  -v ./config:/config -v ./logs:/logs -v ./static:/static akimio/mediawarp:0.0.6
    • 使用 Docker Compose 的方式安装 
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      services:
        mediawarp:
          image: akimio/mediawarp:0.0.6
          container_name: MediaWarp
          restart: unless-stopped
          ports:
             - 9000:9000
          volumes:
             - ./mediawarp/config:/config
             - ./mediawarp/logs:/logs
             - ./mediawarp/static:/static
      1
      docker compose up -d

配置文件

目前 MediaWarp 处于初期更新迭代状态，配置文件不稳定，可能不同版本间差异较大，且有不兼容的情况，具体配置以发布对应版本中的config.yaml.example为准

以下配置文件以 0.0.7版本为例，重点解述重要的配置项

多格式配置

MediaWarp 支持多种格式的配置文件，并且优先级不同：JSON > TOML > YAML > YML > Java properties > Java props
可以根据喜好自行选择习惯的格式

媒体服务器类型

MediaServer.Type:，目前仅支持Emby一个选项，Jellyfin 作为 Emby 的开源分支，其行为与 Emby 类似，Type 可以填写 Emby 但服务器使用 Jellyfin，效果不做保障，自行测试

HTTPStrm

TransCode

  • False： playbackInfo 返回的信息表示对应影片不支持转码播放，并移除转码播放链接，但未拦截转码播放的请求，具体情况需要根据客户端实际请求而定
  • True：不做任修改

PrefixList

假设在 Emby 服务器中的路径结构如下

1
2
3
4
5
6
7
8
9
10
Movies/
   200 (2005)/
      200 (2005).strm
    300 (2006)/
      300 (2006).strm
TV/
   400 (20015)/
      400 (2015).strm
    500 (2025)/
      500 (2025).strm

其中/Movies/200 (2005)/200 (2005).strm和/Movies/300 (2006)/300 (2006).strm为 HttpStrm，可在 PrefixList 中增加元素/Movies，表示标记 Movies 目录下的所有文件是 HttpStrm

AlistStrm

TransCode

  • False： playbackInfo 返回的信息表示对应影片不支持转码播放，并移除转码播放链接，但未拦截转码播放的请求，具体情况需要根据客户端实际请求而定
  • True：不做任修改
    当将 Alist 中的内容映射进 Emby 容器中（即 Emby 服务端可直接访问到对应到文件），推荐设置为True，当不希望某个用户进行转码操作时，建议在 Emby 服务器中的进行设置，此时体验最好，当需要原画播放时，流量不经过Emby 服务器，需要转码时 Emby 服务器也能正常推流。当 Emby 服务器无法访问到 Alist 中的文件时（即未进行映射），则服务器无法进行推流转码（容易出现未兼容的流 提示）