【免费下载链接】StreamVault-IPTV

StreamVault is a TV-first free IPTV player for Android TV built with Kotlin, Jetpack Compose, Room, Hilt, and Media3.

项目地址: https://gitcode.com/gh_mirrors/st/StreamVault-IPTV
点击查看 免费下载

StreamVault 是一款面向 Android TV 的免费 IPTV 播放器(基于 Kotlin、Jetpack Compose、Room、Hilt 和 Media3 构建)。如果你想在保持主程序不变的前提下,为 StreamVault 增加外部内容源、播放前 URL 改写、Cast 投屏改写或自定义配置界面,那么 Plugin API 就是官方推荐的扩展方式。本文将带你完整理解插件架构:伴生 APK 如何被发现、Messenger IPC 的 11 条消息如何工作,以及如何用声明式 Schema 让 StreamVault 帮你渲染配置界面。

StreamVault IPTV 播放器界面

StreamVault 插件是什么:伴生 APK 而非代码注入

StreamVault 插件的核心理念是**"伴生 APK"(companion APK)**:

  • 插件是一个独立的 Android 应用,不会向主应用注入任何代码;
  • StreamVault 通过 PackageManager 查询系统中声明了 com.streamvault.plugin.API 这个 action 的 Service,与它们通过 Android Messenger IPC 通信;
  • 这种边界让插件可以随时安装、卸载、更新,并且与 Android 包隔离(package isolation)策略完全兼容。

插件可以增强四类能力(capabilities):

能力说明
provider.m3u暴露一个 M3U 地址,被 StreamVault 作为内容源导入
playback.prepare在播放开始前准备/改写流地址
cast.rewriteUrl在 Google Cast 加载前改写播放地址
configuration.schema提供声明式配置 Schema,由 StreamVault 渲染 UI
configuration.activity提供原生 Activity 作为配置界面

插件包发现机制:三步接入

StreamVault 的插件发现逻辑实现于 StreamVaultPluginManager.kt,核心步骤如下:

  1. 查询:宿主用 Intent("com.streamvault.plugin.API") 调用 queryIntentServices,找到所有导出且带该 intent-filter 的 Service;
  2. 读清单:先通过 MSG_GET_MANIFEST 向插件服务请求清单 JSON;若失败则回退到 Service 的 com.streamvault.plugin.MANIFEST_JSON 元数据,最后才逐个回退到独立的 meta-data 字段;
  3. 建立通道:绑定服务后,所有请求都带 api_version(当前为 1)和 request_id,响应必须原样带回这两个字段。

插件端只需在 AndroidManifest.xml 中声明一个导出 Service:

<service android:name=".MyPluginService" android:exported="true">
    <intent-filter>
        <action android:name="com.streamvault.plugin.API" />
    </intent-filter>
</service>

插件支持三种安装方式:直接 HTTP/HTTPS 的 APK 链接、系统文件选择器选中的本地 APK、或任意手动安装的 APK(在插件页刷新即可检测到)。

StreamVault 插件安装界面

插件清单(Manifest):你的插件名片

下面是官方文档 docs/PLUGIN_API.md 中给出的标准清单示例,也是 MSG_GET_MANIFEST 需要返回的 manifest_json:

{
  "schemaVersion": 1,
  "id": "com.example.plugin",
  "name": "Example Plugin",
  "versionName": "1.0.0",
  "versionCode": 1,
  "description": "Adds external capabilities to StreamVault.",
  "providerName": "Example Provider",
  "configurationMode": "host.schema",
  "configurationActivityAction": "",
  "capabilities": ["provider.m3u", "playback.prepare", "cast.rewriteUrl", "configuration.schema"],
  "playbackUrlSchemes": ["http", "https"],
  "playbackUrlHosts": ["127.0.0.1", "cdn.example.com"]
}

⚠️ 一个最容易踩的坑:playbackUrlSchemes / playbackUrlHosts 是 playback.prepare 和 cast.rewriteUrl 的前置过滤器。如果清单里这两个列表为空或缺失,插件就不会拥有任何带 host 的 URL——即使这个 URL 正是它自己生成的(比如指向本地 http://127.0.0.1:<port>/... 代理的播放地址),也收不到 MSG_PREPARE_PLAYBACK。想全量匹配请显式使用 "*"。

此外,这两个字段只能从完整的 MANIFEST_JSON 中读取,不支持单独的 meta-data 回退字段。

Messenger IPC:11 条消息一览

所有消息常量定义在 StreamVaultPluginContract.kt,主机侧的发送逻辑见 PluginMessengerClient.kt:

ID消息名用途
1MSG_GET_MANIFEST返回 manifest_json
2MSG_SET_ENABLED用 enabled 开关插件功能
3MSG_GET_STATUS返回 status_label 和可选 message
4MSG_GET_PROVIDER_URL返回 url 与可选 provider_name
5MSG_PREPARE_PLAYBACK准备 input_url,命中时置 handled
6MSG_REWRITE_CAST_URL改写 input_url,命中时返回 output_url
7MSG_GET_CONFIGURATION_SCHEMA返回 configuration_schema_json
8MSG_GET_CONFIGURATION_VALUES返回 configuration_values_json
9MSG_SET_CONFIGURATION_VALUES持久化 configuration_values_json
10MSG_RUN_CONFIGURATION_ACTION执行 configuration_action_id
11MSG_STOP_PLAYBACK释放由 output_url 标识的播放会话

关键行为约定:

  • handled 机制:即使通过了 scheme/host 过滤,插件在具体 URL 无法处理时仍应返回 handled=false,StreamVault 会继续询问其他插件或回退原始 URL;
  • magnet 链接:若没有任何启用中的插件接管,主机直接失败,绝不解开未解析的 magnet 传给播放器。插件必须只把流媒体服务绑定在 127.0.0.1,且 output_url 必须是带端口的回环 HTTP 地址;
  • 会话释放:播放结束时主机用精确的 output_url 发送 MSG_STOP_PLAYBACK,投递是尽力而为的,插件还需自行清理过期/被遗弃的会话。

声明式配置:让 StreamVault 替你画 UI

这是 Plugin API 里对新手最友好的部分。选定 host.schema 模式后,插件只需描述字段和动作,视觉外壳、验证提示、焦点行为全部由 StreamVault 负责:

{
  "schemaVersion": 1,
  "title": "Example Plugin",
  "sections": [
    {
      "id": "connection",
      "title": "Connection",
      "fields": [
        { "key": "serverUrl", "type": "url", "label": "Server URL", "required": true },
        { "key": "token", "type": "password", "label": "Token", "secret": true },
        { "key": "quality", "type": "select", "label": "Preferred quality",
          "options": [ { "value": "auto", "label": "Auto" }, { "value": "1080p", "label": "1080p" } ] }
      ]
    }
  ],
  "actions": [
    { "id": "testConnection", "label": "Test connection", "refreshAfterRun": true }
  ]
}

支持的字段类型共 8 种:info、text、password、url、number、boolean、select、textarea。保存时流式字段会连同 success / message 回传,校验失败应返回 success=false 并附上用户可读的 message。

下面是 StreamVault 实际渲染出的声明式配置界面效果(必填项缺失时会有红框与错误提示):

StreamVault 插件声明式配置界面

host.schema 还是 activity?

场景推荐模式
字段、开关、下拉、简单动作为主host.schema
运行时仪表盘、源管理增删改、频道测试、内嵌日志、配对/登录流程activity

选择 activity 时需要声明 configurationActivityAction 并导出对应 Activity(带 DEFAULT category)。官方参考示例是 HaP 插件:它用 Activity 模式承载运行状态、源管理、频道测试与日志等富交互界面。注意:不要为不完整或过期的 Schema 声明 configuration.schema——如果 configurationMode 是 activity,StreamVault 只会打开 Activity,不会再加载宿主渲染的 Schema。

发布前检查清单

按官方 PLUGIN_API.md 的 Integration Checklist,发布前请逐项确认:

  1. ✅ 恰好暴露一个 com.streamvault.plugin.API Service;
  2. ✅ MSG_GET_MANIFEST 返回完整清单,且 Service 元数据与运行时清单保持同步(作为回退);
  3. ✅ 明确选定 host.schema 或 activity 作为主配置模式;
  4. ✅ 只声明完整实现过的 capabilities;
  5. ✅ 在插件内部对用户输入的 URL 与密钥做校验后再持久化;
  6. ✅ IPC 失败时返回用户可读的错误消息;
  7. ✅ 在真机(含 Chromecast 等 TV 设备与手机)上验证:安装、启用、停用、配置、provider URL、播放准备、Cast URL 改写全链路。

小结

StreamVault 的 Plugin API 用"伴生 APK + Messenger IPC + 声明式配置"三件套,在 Android 包隔离的约束下实现了完整的插件化扩展:

  • 想加内容源?实现 provider.m3u,返回一个 M3U 地址即可;
  • 想做磁力/代理播放?实现 playback.prepare,记得声明 playbackUrlSchemes / playbackUrlHosts;
  • 想省掉配置界面开发?用 host.schema 声明式 Schema,8 种字段类型覆盖绝大多数设置场景。

建议结合本文与仓库内文档逐步实践:先看 docs/PLUGIN_API.md 的完整协议细节,再对照 StreamVaultPluginContract.kt 确认消息常量,就能开始构建你的第一个 StreamVault 插件了 🚀

【免费下载链接】StreamVault-IPTV

StreamVault is a TV-first free IPTV player for Android TV built with Kotlin, Jetpack Compose, Room, Hilt, and Media3.

项目地址: https://gitcode.com/gh_mirrors/st/StreamVault-IPTV
点击查看 免费下载
Logo

北京人形旗下天工造物具身智能开源社区,聚焦具身天工与慧思开物两大平台

更多推荐