Vega OS용 Amazon Fire TV SDK

Amazon Fire TV: build a native Universal Player app#

Use the DRM-X 6.0 Universal Player SDK to build your own Amazon Fire TV app for Vega OS. The sample uses React Native controls and the native Vega media surface for protected Widevine DASH playback. It does not embed a web page.

Check the device operating system first. This package targets Vega OS 1.2 and armv7; it is not an Android APK. For Android-based Fire OS, use the Android integration path and qualify your target device separately.

Android SDK · Universal Player SDKs

1. Download the customer SDK#

Developer Tools → Device SDKs에서 다운로드하세요. SDK 사용에는 승인된 Professional 평가 계정을 포함하여 유효한 Professional 또는 Enterprise 권한이 필요합니다. Standard에서도 자체 플레이어용 네이티브 APIs를 사용할 수 있습니다. 세션 생성 및 라이선스 갱신 시 SDK 권한을 확인하며 오프라인 라이선스는 계정 서비스 기간을 초과할 수 없습니다.

Console → Developer Tools → Device SDKs · Professional / Enterprise

ZIP에는 SDK 소스, 설정 가능한 샘플 앱, build.py, armv7 .vpkg 설치 파일이 포함됩니다. 다운로드 카드에 출시일과 SHA-256 체크섬이 표시됩니다. Amazon SDK 종속성은 빌드 시 Amazon에서 가져옵니다.

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

2. Prepare the build computer and Fire TV#

Use macOS or native Ubuntu with Amazon Vega CLI 1.3.4 / SDK 0.24.12044, Node.js 20+, Python 3.10+, Git and Java 21+. This release was built on an Apple Silicon Mac with Java 21. Install and authenticate Amazon tooling using its official instructions. A DRM-X subscription does not replace Amazon developer registration or device authorization.

Amazon: run your app on Fire TV · Amazon: native media setup

On Fire TV, open Settings → My Fire TV → Developer Options and enable Developer Mode using Amazon’s current device-authorization flow. Connect USB to the build computer when instructed. Authorize the device and computer; signing in to an Amazon web page alone is not the same as completing the Vega authorization flow.

For LAN testing, enable the device TCP/IP development connection and put Fire TV and the build computer on the same trusted network. Allow the Vega tools in macOS Privacy & Security → Local Network if prompted. Replace FIRE_TV_IP below with the device’s current address. This Vega connection uses VDA, not 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. Try the included native player#

압축을 푼 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

Select a playlist item and press OK. Play next is on by default: when an item ends, the app releases its playback session and starts the next item in order. Shuffle and Repeat are optional. Playback stops after the last item unless Repeat is enabled.

Full screen fills the video surface to the display, preserving the video’s aspect ratio. Controls hide after three seconds while playing. The first navigation or OK press reveals hidden controls without activating a button. Back closes a menu, exits fullscreen, stops playback, then leaves the app.

The number immediately left of Quality, such as 480p or 1080p, follows the active streaming variant. It is not the HDMI display resolution. Quality choices set a maximum resolution, subject to the backend policy and available tracks. Subtitles supports English and Chinese text tracks with a compact font; captions move above visible controls.

4. Configure your app and viewer login#

자체 앱에서는 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"}
  ]
}

Implement authenticateViewer() in authentication.ts using your own viewer sign-in. Return a short-lived viewer Authorization header. Your backend must authenticate that viewer and check course enrollment, purchase or subscription before issuing a playback session. Do not hard-code a viewer token into the app.

Your backend implements Universal Playback Session Contract v1. It owns the Published Content ID mapping, manifest selection and license policy. Keep Site Key, Access Key and other long-lived credentials on the server. The SDK obtains the session, passes the native Widevine license request through the authorized route and releases the session when playback ends.

Universal Playback Session Contract / Web integration · Backend integration examples

The included App.tsx wires configuration and authentication into DrmXUniversalPlayerView. Reuse this component for the complete player, or use UniversalPlayer and SessionClient from the SDK with your own interface. Keep configuration and callback references stable between renders.

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

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

5. Build, install and reopen your app#

Run the build from the extracted source directory. Use a work directory outside SDK source. build.py validates configuration, verifies the pinned Amazon Shaka download, stages the official Vega template, type-checks TypeScript and builds the native armv7 Release package. Choose a build number higher than the installed version.

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를 다시 연결하고 packageId 뒤에 .main을 붙여 launch-app을 실행하세요. 다시 빌드하거나 설치할 필요는 없습니다. Your Apps에 앱이 없으면 CLI를 사용하세요.

6. Troubleshooting#

SDK download denied: check the selected organization and its active Professional or Enterprise subscription. Download authorization is rechecked on the server for every request; copying a download URL does not bypass it.

Connection timeout: confirm the current Fire TV IP, Developer Mode, TCP/IP connection and trusted LAN. On macOS, check Local Network permission for Vega tools. If authorization is required, complete the current Amazon device flow rather than reusing an expired code.

Video with no sound on a monitor: HDMI audio needs speakers or a headphone output connected to headphones/powered speakers. Some monitors, including MSI MD271UL, have no built-in speakers. Test the Fire TV audio format and connected audio device before diagnosing an SDK error.

Playback authorization fails: verify the viewer session, Published Content ID and backend entitlement check. Keep diagnostic reports to SDK version, device/OS, request correlation ID and redacted error code; exclude credentials, signed URLs, viewer headers and license payloads.

7. 다음 단계#

이 개발자 프리뷰는 Vega OS에서 보호된 VOD를 지원합니다. 자막은 일반 텍스트를 사용하며 고급 큐 스타일, 비트맵 자막, 시스템 자막 스타일 재정의는 지원하지 않습니다.

Get the customer SDK · DRM-X 6.0 Multi-DRM · Playback troubleshooting