Amazon Fire TV SDK（Vega OS）

Amazon Fire TV：构建原生 Universal Player 应用#

使用 DRM-X 6.0 Universal Player SDK，为 Vega OS 的 Amazon Fire TV 构建自己的应用。示例使用 React Native 控件和 Vega 原生视频显示组件，播放受 Widevine 保护的 DASH 视频，不嵌入网页。

请先确认设备操作系统。本安装包面向 Vega OS 1.2 和 armv7，不是 Android APK。使用 Android 系统的 Fire OS 设备应参考 Android 集成方案，并单独测试目标设备。

Android SDK · Universal Player SDKs

1. 下载客户 SDK#

登录 DRM-X 控制台，选择您的组织，打开 Integrations，找到 Amazon Fire TV (Vega OS)。下载 SDK ZIP 需要有效的 Professional 或 Enterprise 订阅。Trial、Standard、已过期或已暂停的订阅无法下载。此教程向所有用户开放。

控制台 → Integrations · Professional / Enterprise

ZIP 包含 SDK 源码、可配置的示例应用、build.py、自动化测试、兼容性验证说明和已测试的 armv7 .vpkg 安装包。下载卡片显示发布日期和 SHA-256 校验值，请先校验再解压。构建过程中从 Amazon 获取其 SDK 依赖。

shasum -a 256 drmx-firetv-sdk-20260921.1.zip
cd drmx-firetv-vega-sdk

2. 准备构建电脑和 Fire TV#

使用 macOS 或原生 Ubuntu，安装 Amazon Vega CLI 1.3.4 / SDK 0.24.12044、Node.js 20+、Python 3.10+、Git 和 Java 21+。本版本在 Apple Silicon Mac 上使用 Java 21 构建。请按照 Amazon 官方说明安装工具并完成授权。DRM-X 订阅不能代替 Amazon 开发者注册或设备授权。

Amazon：在 Fire TV 上运行应用 · Amazon：原生视频环境配置

在 Fire TV 上打开 Settings → My Fire TV → Developer Options，按照 Amazon 当前的设备授权流程启用 Developer Mode。按提示通过 USB 连接构建电脑，并完成设备和电脑授权；仅登录 Amazon 网页并不等于已完成 Vega 授权。

通过局域网测试时，请启用设备的 TCP/IP 开发连接，并让 Fire TV 与构建电脑处于同一可信网络。macOS 提示访问本地网络时，请在 Privacy & Security → Local Network 中允许 Vega 工具。将以下 FIRE_TV_IP 替换为设备的当前地址。此 Vega 连接使用 VDA，不使用 Android ADB。

export PATH="$HOME/vega/bin:/opt/homebrew/bin:/opt/homebrew/opt/openjdk@21/bin:$PATH"
export FIRE_TV_IP="YOUR_FIRE_TV_IP"
vega exec vda connect "$FIRE_TV_IP:5555"
vega device list

3. 运行随包提供的原生播放器#

在解压后的 SDK 目录中，安装随包提供的 build 9 安装包并启动。示例使用 DRM-X 公开演示视频目录，应用中不需要 Site Key 或 Access Key。此安装包用于开发测试，尚未在 Amazon Appstore 上架。

vega device install-app -d "$FIRE_TV_IP:5555" \
  --packagePath installer/drmx-firetv-native-build9_armv7.vpkg
vega device launch-app -d "$FIRE_TV_IP:5555" \
  --appName com.haihaisoft.drmx.firetv.main

选择播放列表中的视频并按 OK。Play next 默认开启：视频结束后，应用释放当前播放会话，再按顺序播放下一项。可选开启 Shuffle 和 Repeat；未开启 Repeat 时，最后一项结束后停止播放。

Full screen 将视频显示区域扩展至全屏，并保持视频宽高比。播放时，控件在三秒无操作后自动隐藏。首次按方向键或 OK 只显示隐藏的控件，不会触发按钮。Back 依次用于关闭菜单、退出全屏、停止播放和离开应用。

Quality 左侧的数值（例如 480p 或 1080p）表示当前活动视频轨道的分辨率，不是 HDMI 显示输出分辨率。画质选项设置分辨率上限，仍受后端策略和可用轨道限制。Subtitles 支持英文和中文字幕文本轨道，采用较小字体；控件显示时，字幕会移至控件上方。

4. 配置应用和观看者登录#

编辑 app-config.json，设置应用名称、唯一的反向域名格式 packageId、品牌颜色、HTTPS 会话接口、maximumHeight，以及包含 Published Content IDs 的播放列表。客户应用必须将 publicDemoAuthentication 设为 false，默认配置仅用于公开演示。

{
  "appName": "My Video App",
  "packageId": "com.example.video.firetv",
  "accentColor": "#6488ff",
  "sessionEndpoint": "https://video.example.com/api/drmx/playback-session",
  "maximumHeight": 1080,
  "publicDemoAuthentication": false,
  "playlist": [
    {"contentId": "YOUR_PUBLISHED_CONTENT_ID", "title": "Lesson 1", "contentType": "vod"}
  ]
}

在 authentication.ts 中对接您自己的观看者登录，实现 authenticateViewer()，返回短期有效的观看者 Authorization 请求头。后端必须验证观看者身份，并检查课程权限、购买记录或订阅后，才签发播放会话。不要将观看者令牌硬编码到应用中。

您的后端应实现 Universal Playback Session Contract v1，负责 Published Content ID 映射、manifest 选择和许可证策略。Site Key、Access Key 等长期有效的凭据必须保留在服务器端。SDK 获取播放会话，通过已授权的路由传递原生 Widevine 许可证请求，并在播放结束时释放会话。

Universal Playback Session Contract / Web 集成 · 后端集成示例

随包提供的 App.tsx 将配置和身份验证接入 DrmXUniversalPlayerView。可复用该组件获得完整播放器，也可使用 SDK 中的 UniversalPlayer 和 SessionClient 构建自己的界面。请在重复渲染时保持配置对象与回调引用稳定。

import {DrmXUniversalPlayerView} from './sdk/UniversalPlayerView';
import configuration from './app-config.json';
import {authenticateViewer} from './authentication';

export const App = () => <DrmXUniversalPlayerView
  configuration={configuration}
  authenticateViewer={authenticateViewer}
/>;

5. 构建、安装和重新打开应用#

在解压后的源码目录中执行构建，并将工作目录放在 SDK 源码之外。build.py 会验证配置、校验固定版本的 Amazon Shaka 下载内容、准备官方 Vega 模板、检查 TypeScript 类型，然后构建原生 armv7 Release 安装包。更新已安装应用时，应使用更高的构建编号。

node --test tests/*.test.cjs
python3 build.py --work "$HOME/Developer/MyFireTVBuild" --build-number 10
vega device install-app -d "$FIRE_TV_IP:5555" \
  --packagePath "$HOME/Developer/MyFireTVBuild/DrmXFireTV/build/armv7-release/drmx-firetv-sample_armv7.vpkg"
vega device launch-app -d "$FIRE_TV_IP:5555" \
  --appName com.example.video.firetv.main

重新打开已安装的应用时，只需重新连接 VDA，再执行 launch-app；appName 为您的 packageId 加 .main。不需要重新构建或安装。部分 Vega 固件不会在 Your Apps 中显示侧载的开发应用，也可能没有 Open App 按钮；本教程已验证通过 CLI 启动。

6. 常见问题#

SDK 下载被拒绝：检查当前选择的组织及其 Professional 或 Enterprise 订阅是否有效。服务器每次下载都会重新检查权限，复制下载地址不能绕过校验。

连接超时：确认 Fire TV 当前 IP、Developer Mode、TCP/IP 连接和可信局域网。macOS 用户还应检查 Vega 工具的 Local Network 权限。若需要授权，请重新完成 Amazon 设备授权流程，不要继续使用已过期的验证码。

显示器有画面但无声音：HDMI 音频需要通过扬声器播放，或从耳机接口连接耳机／有源音箱。部分显示器（包括 MSI MD271UL）没有内置扬声器。请先检查 Fire TV 音频格式和已连接的音频设备，再排查 SDK。

播放授权失败：检查观看者会话、Published Content ID 和后端权限校验。诊断报告仅需提供 SDK 版本、设备／操作系统、请求关联 ID 和已脱敏的错误码；不要包含凭据、签名 URL、观看者请求头或许可证内容。

7. 已测试范围和发布前检查#

1.0.0-preview.3 / build 9 已在一台 Vega OS 1.2 armv7 Fire TV 上测试。原生受保护 VOD 点播的视频和声音已得到确认；设备事件验证了顺序播放下一项、全屏、控件三秒自动隐藏、英文／中文字幕选择，以及活动的 1920×1080 视频轨道。21 项自动化测试及原生构建／类型检查全部通过。

此版本为开发预览版，不代表所有 Fire TV 或显示器都已完成兼容性验证。发布前应测试自己的后端、内容、遥控器焦点、音频／字幕轨道、网络恢复和设备生命周期。这些测试不能证明 HDCP／输出安全等级、4K/HDR、直播、离线或 Appstore 上架能力。纯文本字幕不保留复杂的字幕样式，也不支持位图字幕；不应用系统字幕样式覆盖设置。

获取客户 SDK · DRM-X 6.0 Multi-DRM · 播放故障排查