Stremio插件协议入门完全指南:从manifest.json到stream请求(以Gelato源码为例)

原创2026-10-25 12:29:301,681 阅读

Stremio插件协议入门完全指南:从manifest.json到stream请求(以Gelato源码为例)

Stremio 插件协议其实只有几个 GET 请求,但不少新手被 manifest.json、catalog、meta、stream 四个资源绕晕。Gelato 是一个 Jellyfin 插件,它通过 Stremio 插件协议对接 AIOStreams,把外部片源变成 Jellyfin 媒体库里的正片。本文以 Gelato 的源码为蓝本,带你用一次搜索、一次导入、一次播放,把 Stremio 插件协议的完整链路彻底讲清楚。

Gelato 项目横幅:冰淇淋图标与 Gelato 字样的 Stremio 插件协议示例项目

一、Stremio 插件协议速览:4 个请求撑起整个生态

Stremio 插件协议(Add-on Protocol)非常克制:客户端不执行任何插件代码,插件就是一个 HTTP 服务,约定了几类固定路径的 JSON 接口。一次典型的"播放某部影片"会依次触发 4 类请求:

请求 路径形式 作用
manifest /manifest.json 插件"身份证":名称、ID、支持哪些资源
catalog /catalog/{type}/{id}.json 目录列表,也可带 search= 参数当搜索用
meta /meta/{type}/{id}.json 单个条目的元数据:海报、简介、演职员
stream /stream/{type}/{id}.json 可播放的流地址列表(点播时请求)

其中 {type} 通常是 movie 或 series,{id} 是条目的外部标识(如 tt1375666 这类 IMDb ID,或 tmdb:603 这类带前缀的 ID)。

Gelato 把这些请求全部封装在 GelatoStremioProvider.cs 里,URL 拼接逻辑见 BuildUrl 方法:

var url = $"{baseUrl}/{path}{extrasPart}.json";

也就是说,一个 Stremio 插件实例的 base URL 后面直接拼 manifest.json、catalog/movie/xxx.json、stream/movie/tt1375666.json 就能工作——这正是 Gelato 要求用户在设置里填 manifest 完整地址的原因,见 配置页对 manifest.json 的说明。

插件类型如何定义

协议中的媒体类型在 Gelato 里对应一个枚举 StremioMediaType:Movie、Series、Channel、Anime、Tv 等。请求路径中的小写字符串(movie/series)就是由它 ToLower() 得到的。

二、manifest.json:Stremio 插件协议的"总开关"

manifest 是客户端(或 Gelato 这样的消费方)认识一个插件的第一步。Gelato 的模型定义非常直白,见 StremioManifest:

public class StremioManifest
{
    public string Name { get; set; } = "";
    public string Id { get; set; } = "";
    public string Version { get; set; } = "";
    public List<StremioCatalog> Catalogs { get; set; } = new();
    public List<StremioResource> Resources { get; set; } = new();
    public List<string> Types { get; set; } = new();
    // ...
}

各字段的作用:

  • id / name:插件唯一标识与展示名。Gelato 靠它判断实例是不是 AIOStreams,见 IsAioStreams
  • catalogs:目录清单,每项是一个 StremioCatalog,含 type、id、name 和 extra 参数列表
  • resources:声明支持的资源(meta、stream、subtitles 等)及其 ID 前缀,见 StremioResource
  • types:支持的媒体类型,如 ["movie", "series"]

Gelato 读取 manifest 的两个关键用法

1. 找出"可搜索的 catalog"。Stremio 协议里,一个 catalog 只要 extra 中声明了 search 参数,就代表它支持搜索。Gelato 的 StremioCatalog.IsSearchCapable 就一行判断,然后在 读取 manifest 时挑出 movie/series 两个搜索目录:

m.Catalogs?.Where(c =>
        string.Equals(c.Type, type.ToString(), StringComparison.CurrentCultureIgnoreCase)
        && c.IsSearchCapable()
    )

2. 从 resources 读取 ID 前缀。不同插件的 meta 接口接受的 ID 格式不一样(有的只收 tt 开头的 IMDb ID,有的收 tmdb: 前缀),manifest 的 resources 会声明 idPrefixes。Gelato 用 MetaIdPrefixesAsync 读取它,从而在 多 ID 回退查询 中优先尝试插件认得的 ID 格式,避免无效的 404。

📌 协议细节:manifest 是低频资源。Gelato 用带生命周期的缓存策略处理它——过期后在后台静默刷新、失败则保留旧值重试,见 GetManifestAsync。这套"缓存 + 失效"的思路做 Stremio 插件消费方时非常实用。

三、catalog 请求:一次调用,目录导入和搜索全靠它

Stremio 协议没有独立的 search 端点,搜索是 catalog 请求加一个 search= 查询参数。Gelato 的两个入口殊途同归:

  • 目录导入:CatalogImportService 定时任务循环调用 GetCatalogMetasAsync(catalogId, type, search: null, skip: skip),用 skip 翻页直到达到数量上限
  • 搜索:Jellyfin 搜索框输入关键词后,SearchActionFilter 调用 stremio.SearchAsync(searchTerm, ...),它内部找到 manifest 里标记的搜索 catalog,再走同一个 GetCatalogMetasAsync:
var url = BuildUrl(["catalog", mediaType.ToLower(), id], extras);
var r = await GetJsonAsync<StremioCatalogResponse>(url);
return r?.Metas ?? [];

响应结构就是一个 metas 数组,见 StremioCatalogResponse。数组里每项都是简版的 StremioMeta,至少包含 id、type、name、poster、releaseInfo 等字段。

这里藏着一个协议设计要点:catalog 返回的是"预告片目",不是完整元数据。标题、海报、年份都有了,但简介、演职员、上映详情可能缺失——完整的要等 meta 请求。Gelato 的目录导入任务正是如此:先批量插入这些条目进媒体库,需要时再按需拉 meta。

另一个实用技巧:manifest 的 catalogs<a href="https://link.gitcode.com/i/5b126829981343a153a14daa2c412d47" target="_blank">].extra 里带 isRequired: true 的目录没法直接导入(缺必填参数)。Gelato 用 [IsImportable 判断并跳过这类目录,做插件消费方时这是一个容易踩的坑。

四、meta 请求:把标题变成媒体库条目

点开某个标题时,Stremio 协议要求 /meta/{type}/{id}.json 拿到完整元数据。Gelato 的请求封装在 GetMetaAsync,响应包裹在 StremioMetaResponse 中(注意是 { "meta": {...} } 结构,而不是裸对象)。

StremioMeta 是全文最大的模型,字段映射上就很有"协议实战味":

  • imdb_id / _tmdbId / _tvdbId:跨库 ID,Gelato 用 GetProviderIds 把它们提取成 Jellyfin 的 ProviderIds
  • releaseInfo:可能是 "2007"、"2007-2019"、"2020-" 等任意形态,所以 Gelato 写了 GetYear / GetPremiereDate 多级解析
  • app_extras:AIOStreams 扩展区,含演职员 cast、季海报 seasonPosters 等,见 StremioAppExtras

拿到 meta 之后,Gelato 通过 Jellyfin 的元数据 Provider 机制把它落成库内条目。以电影为例,GelatoMovieMetadataProvider.GetMetadata 的流程就是:

  1. 按 ProviderIds 调 GetMetaAsync 取 meta(带 5 分钟缓存)
  2. EnrichMetaAsync 补充 TMDB 数字发行日期
  3. manager.IntoBaseItem(meta) 转成 Movie 实体入库

这个 Provider 同时也是 Jellyfin 搜索的后端:GetSearchResults 直接把 SearchAsync 的结果包装成 RemoteSearchResult。至此,"在 Jellyfin 里搜索出 AIOStreams 的片源"就完全由 catalog 请求完成了。

五、stream 请求:按下播放键那一刻才发生的事

stream 是 Stremio 协议的核心,也是和 media 库分离的关键:插件只在客户端(或消费方)请求时才给出可播放地址,任何时刻都不下载文件。Gelato 正是靠它实现"按需取流"。

请求与响应模型

请求构造见 GetStreamsAsync:

var url = BuildUrl(["stream", mediaType.ToString().ToLower(), id]);

响应是 { "streams": <a href="https://link.gitcode.com/i/8decb4c6140f73c78487fc41c86858d3" target="_blank">...] },见 [StremioStreamsResponse。每个 StremioStream 的关键字段:

字段 说明
url 直链地址(经 debrid 解析后的 HTTP 地址)
title / name / description 流展示信息
infoHash / fileIdx 种子文件标识,存在即为 P2P 直连流
behaviorHints videoSize、filename、bingeGroup 等提示,见 StremioBehaviorHints
streamData AIOStreams 私有扩展:大小、是否已缓存等

一条流如何变成 Jellyfin 媒体源

Gelato 不会把流地址直接透传,而是把每条流"物化"为媒体库里的一个替代版本(version)。核心逻辑在 GelatoManager.SyncStreams,要点:

  1. 构造请求 URI:StremioUri.FromBaseItem 从库内条目的 ProviderIds 反推出 stremio://movie/tt1375666 这样的地址;剧集则是 series/tt...:季:集 格式
  2. 过滤流:IsValid 剔除坏链接;IsTorrent() 剔除 P2P 直连流(Jellyfin 客户端没有 debrid 客户端帮它解析 infoHash)
  3. 建立映射:每条流用 GetGuid 生成稳定 ID(优先 URL 的 MD5),落成一个隐藏的子条目挂在原片下

两个让播放体验"丝滑"的设计

代理播放:debrid 链接里带着用户的 API key,绝不能出现在返回给客户端的响应里。Gelato 的 MediaSourceExtensions.Stub 把媒体源路径替换为 /stub,强迫客户端通过 Jellyfin 代理拉流,真实 URL 只在服务器侧解析。副作用是 debrid 服务只看到 Jellyfin 这一个出口 IP。

预取:流请求通常是最慢的一环(插件端要过 debrid 解析)。Gelato 用 AheadOfTime 结构体实现"抢跑":在你打开详情页、还差一步点播放时,StartStreamsAhead 就提前发出 stream 请求并缓存答案(30 秒有效);真正同步流时 GetStreamsAsync(StremioUri) 直接取现成结果。另外 StreamFailover 在播放失败时自动换下一条流重试(最多 3 条,见 StreamLinks.MaxStreams)。

六、Stremio 插件协议速查表

你想做的事 请求 协议要点
认识一个插件 GET /manifest.json 读 id、types、catalogs、resources
判断目录能否搜索/导入 看 catalogs[].extra 有 search 可搜索;有 isRequired 则不可直接导入
拉列表/搜索 GET /catalog/{type}/{id}.json?search=xxx&skip=N 同一端点两用,skip 翻页
取完整元数据 GET /meta/{type}/{id}.json 响应包一层 { "meta": ... }
取播放流 GET /stream/{type}/{id}.json 响应包一层 { "streams": [...] };按需请求、不下载
判断 ID 兼容性 看 resources[].idPrefixes 只发插件认得的 ID 前缀,404 少一半

对照源码阅读路线:协议客户端整体在 GelatoStremioProvider.cs(模型全部集中在 文件末尾的 Request Models 区),搜索接入在 Filters/SearchActionFilter.cs,目录导入在 Services/CatalogImportService.cs,元数据落库在 Providers/GelatoMovieMetadataProvider.cs 与 Providers/GelatoSeriesProvider.cs,流同步与代理在 GelatoManager.cs 与 Services/StreamLinks.cs。

写在最后

Stremio 插件协议的全部精华就是四句话:manifest 声明能力,catalog 提供条目,meta 补全详情,stream 按需给链接。读懂 Gelato 的 GelatoStremioProvider.cs,你不仅理解了如何"消费"一个插件,也掌握了自己写插件时该按什么格式响应。协议简单,难的是工程细节——ID 前缀兼容、响应字段类型漂移(数字有时是字符串)、慢请求缓存、凭据脱敏,这些在 Gelato 源码里都有现成答案,值得逐段细读。

登录后查看全文
Gelato