Amazon Fire TV SDK（Vega OS）

使用 DRM-X Universal Player 构建原生 Amazon Fire TV 应用：了解 SDK 下载资格，查看界面截图，完成 Vega 环境准备、观看者身份验证、参数配置、构建和真机测试。

查看 Markdown 在线示例更新于 2026-09-21

按照 SDK ZIP 中的 DEMO-QUICKSTART.md 试用 PHP 演示。使用您自己的内容时，请先完成网站/后端集成，再按照 MOBILE-AND-TV-APPS.md 将应用连接到同一套登录系统和观看权限规则。

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

Amazon Fire TV Vega Universal Player，构建版本 9 — Fire TV build 9 的真实截图，处于播放前状态。左侧是播放列表，右侧显示播放控件和当前画质；视频轨道尚未激活时，画质显示为短横线。

1. 下载客户 SDK#

在 Developer Tools → Device SDKs 下载。使用 SDK 需要有效的 Professional 或 Enterprise 权限，包括已获批准的 Professional 评估账户。Standard 仍可通过原生 APIs 构建自己的播放器。创建会话和续订许可证时会检查 SDK 权限；离线许可证的有效期不会超过账户服务期。

Console → Developer Tools → Device SDKs · Professional / Enterprise

ZIP 包含 SDK 源码、可配置的示例应用、build.py 和 armv7 .vpkg 安装包。下载卡片显示发布日期和 SHA-256 校验值。构建时会从 Amazon 获取 Amazon SDK 依赖。

shasum -a 256 drmx-firetv-sdk-20260930.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 12 安装包并启动。示例使用 DRM-X 公开演示视频目录，应用中不需要 Site Key 或 Access Key。此安装包用于开发测试，尚未在 Amazon Appstore 上架。

vega device install-app -d "$FIRE_TV_IP:5555" \
  --packagePath installer/drmx-firetv-native-build12_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 依次用于关闭菜单、退出全屏、停止播放和离开应用。

Amazon Fire TV Vega Universal Player 全屏播放控件 — 播放前的真实全屏界面截图。这些截图展示应用布局，并未截取解密后的视频；测试设备会阻止受保护播放画面的截图。

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

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

对于您自己的应用，请编辑 app-config.json，并在 authentication.ts 中实现 authenticateViewer()。设置应用名称、packageId、HTTPS 会话端点和播放列表。保持 publicDemoAuthentication 为 false。demo-config.json 仅用于评估。

{
  "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，使用 packageId 加上 .main。无需重新构建或安装。如果应用未出现在 Your Apps 中，请使用 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. 后续步骤#

此开发者预览版支持 Vega OS 上的受保护 VOD 点播。字幕使用纯文本，不支持丰富的字幕样式、位图字幕或系统字幕样式覆盖。

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