Vega SDK Release Notes

Rate your experience with the Vega SDK

Vega SDK version 0.21

Vega SDK v0.21 introduces significant changes and improvements. Key highlights include:

1. Vega Virtual Device (VVD): Rebranded from "Simulator," featuring an improved user interface (UI), keyboard controls for Fire TV Stick remote functions, and better error handling.
2. Telemetry framework: Comprehensive documentation across all Vega tools, with default-enabled telemetry and simplified opt-out procedures. Enhanced privacy notices and Visual Studio Code (VS Code) integration.
3. Developer tools: Ubuntu 24 support added. Vega Studio is available in VS Code marketplace. Improved error messaging system implemented.
4. Performance analysis: New ESLint Plugin with pre-built performance checks, Perfetto UI integration for system trace analysis, and custom file type editors for data visualization.
5. New performance KPIs: Implemented video/UI frame drop tracking and app event response time measurements, including Input Key Latency for scrolling and consecutive frame drop counts.
6. Developer experience: Improved manifest validation with real-time feedback, better error messaging, and streamlined development workflows.

Authentication is improved with Login with Amazon flows, addressing multiple video playback and caption-related issues, resolving stream freezes, better mid-roll ad transitions, and improved caption positioning challenges.

System stability is improved by fixing critical service registration handling, timer management, and resource conflicts. These improvements provide a more robust and stable development and user experience.

This release requires OS 1.1 (1001010443450) on your Vega Fire TV Stick, which is compatible with the Vega SDK v0.21. You can check your device software version by navigating to My Fire TV > About.

Announcements

Vega private NPM packages moving to the public registry

The Vega NPM packages migrated from our private registry to the public NPM registry, transitioning from the @amzn to @amazon-devices namespace. This change removes token requirements and simplifies development.

Key Benefits for the move

• Simplified development: Developers don't need to configure .npmrc tokens for Vega development.
• Improved library accessibility: Our SDK is more easily accessible through the public registry.
• Streamlined namespaces: There is a temporary period of dual namespace use, but @amzn will sunset for external use.

Sample reference apps are available on Github

Our sample apps have begun moving to Amazon’s Github space for direct download to be accessible without the need for access tokens.

Vega Virtual Device (VVD) enhancements

Vega SDK v0.21 introduces improvements to the Vega Virtual Device (VVD) and Vega CLI (VCLI). You now have streamlined commands, an improved user experience, an updated Vega Studio extension, new keyboard controls, and improved error handling.

Name and command updates

The Vega Virtual Device identifier is now VirtualDevice, replacing the Simulator identifier across all tools and interfaces. Support for the Simulator identifier ends November 2025. Start using VirtualDevice before this change takes effect.

KVD user interface updates

The KVD interface is redesigned to provide:

• Clear messaging that registration is optional unless you're using Amazon services.
• Consistent styling (colors, spacing, and typography).
• Helpful tooltips and informational elements for improved usability.

Vega Studio extension updates

• Simulator is renamed to Vega Virtual Device in the command palette.
• Simulator:TV is renamed to VirtualDevice:Tv in the Devices section.

New keyboard controls

A keyboard mapping functionality was added to the Vega Virtual Device, allowing you to control Fire TV Stick remote functions with keyboard shortcuts. See the Vega Virtual Device documentation for details.

Improved error handling

Detailed error messages replaced the generic result codes when device-related operations fail, helping you diagnose and troubleshoot problems.

Telemetry documentation updates

Updated the telemetry collection and supporting documentation, providing greater transparency and control over data collection in Vega tools.

Key Updates:

• Detailed breakdown of telemetry collection across all Vega tools. These tools include Vega Studio, Vega CLI, Vega Virtual Device, Vega Performance CLI, and the Vega Appium Driver.
• Simplified opt-out procedures for developers.

Important Changes:

• Telemetry is now enabled by default in the Vega SDK.
• New configuration options available in {$KEPLER_SDK_PATH}/state/kepler-telemetry/config.json.
• Improved privacy notices and data usage explanations.
• Integrated with VS Code telemetry settings for Vega Studio users.

For details, see Manage Telemetry in Vega Tools.

This update reflects our commitment to transparency and developer choice in the telemetry collection and improves the Vega development experience.

Vega Web App update

For WebView developers, you must modify your package.json file. For details, see Vega Web App dependency update.

Developer tools

Vega v0.21 introduces the following Vega developer tools improvements:

• Added Ubuntu 24 support to Vega Virtual Device.
• Added Vega Studio to the VS Code marketplace.
• Added ESLint Plugin. ESLint Plugin uses pre-built performance checks in Vega Studio tooling (CLI and UI). These checks automatically detect common code-level issues, such as FlatList usage, missing splash screens, or console.logs. Checks are categorized as must-have (errors) and good-to-have (warnings). Developers can submit test proofs and confirm to Appstore teams that they’ve passed must-have tests during app submission.
• Added new Performance Monitoring KPIs. These KPIs include implementing video/UI frame drop tracking and app event response time measurements to better evaluate playback smoothness and interaction responsiveness.
  • 3+ and 5+ Video Consecutive Dropped Fames: This feature counts instances where the app drops 5 or more consecutive frames during video playback, indicating significant playback disruptions.
  • 5+ Consecutive UI Dropped Frames: This feature counts instances where the app drops 5 or more consecutive frames during scrolling interactions, causing significant UI stuttering. For example, when vertical or horizontal scrolling.
  • App Event Response Time - Focus: This feature measures the scheduling latency between the native UI thread and JavaScript thread for focus events (onFocus/onBlur). Scheduling delays over 200 ms indicate JavaScript thread congestion, which affects the app's responsiveness.
• Added Input Key Latency (Scrolling) tracking KPI measurement to improve app fluidity assessment.
• Added custom editors for specific file types, enabling developers to visualize data through double-clicking files in the IDE.
• Added an improved error messaging system. This system provides actionable, detailed feedback for environment setup issues, enabling developers to independently troubleshoot using CLI and Vega Studio performance tools.
• Added an improved Vega manifest validation. This real-time validation for Vega manifest.toml files provides immediate feedback on errors and formatting issues directly in VS Code.
• Integrated Perfetto UI directly within Vega Studio as part of the Performance Extension. Perfetto UI enables one-click access to system trace analyses without additional setup requirements, similar to the existing Chrome DevTools integration.

Vega Web App dependency update

If you develop your app with WebView, modify your application package.json file to include the following dependency.

"dependencies": {
    "@amzn/webview": "^3.0.0",
    --------------------
},

To install app dependencies, run the following command.

npm install

For more information, see Vega Web App Overview.

Developer libraries

• Developer Library Porting Guidelines: Added a developer library porting guideline. You now have detailed input for the library developer when adding Vega support to your libraries.

Improvements

• Added a bug report tool that gathers diagnostic information about your system, devices, and logs. The tool saves this information as a file on your computer that you can attach when you submit a support ticket. See Set Up and Use Vega Studio for details.
• Added the following Appium commands: push_file, pull_file, install_app, activate_app, terminate_app, and remove_app. See Appium Commands for descriptions and usage.
• Added Application Not Responding (ARN)-timeout management in debug flows. This management can prevent Lifecycle Manager (LCM) from killing apps during line-by-line native debugging sessions.
• Improved caption window positioning and text alignment within border padding. Improved vertical stacking logic and line adjustment calculations, to prevent text overlap and border sticking.
• Improved Login with Amazon (LWA) experience on TV operating systems by improving the consent page display and visual scaling. Users now enjoy better readability and a more accessible authentication experience on their TV screens.
• Fixed authentication failures associated with Login with Amazon (LWA) flows, when you enable parental controls on devices.
• Fixed a UI thread hang by resolving the broken mutex lock in React Native for Vega Thread Monitor. The lock caused deadlock issues in Platform Data Manager.
• Fixed the app navigation crash by resolving stack navigator's animation issues. Removed the need to disable animations (animationEnabled: false) as a workaround.
• Fixed the TimingModule issue where clearInterval occasionally cleared incorrect timers due to handle reuse in ARNTimer. The fix resolves timer management's race conditions and orphaned setInterval instances.
• Fixed the UI flickering issue during home tile navigation in the app, providing smooth transitions without visual artifacts.
• Fixed an app crash that occurred when enabling subtitles during Video On Demand (VOD) content playback.
• Fixed a video freeze after mid-roll ads by resolving the Application Not Responding (ANR) issue caused by deadlock during media player deinitialization.
• Fixed a video stream's freezing issues by removing redundant configuration overrides. Corrected track buffer seek logic for proper gap handling during playback.
• Fixed an app crash during content playback by adding synchronization to prevent race conditions in caption track management.
• Fixed the ServiceRegistrar connection handling issue by preserving pending connections during the failed unbind operations. Implemented timeout management for stale connections, providing proper service recovery.
• Fixed the music playback issues by resolving a resource management conflict. Previously, map service was incorrectly terminated by LCM. Improved coordination between Resource Manager and Lifecycle Manager to prevent premature service termination.
• Fixed a green screen artifact during video playback that occurred after upgrading to React Native w3cmedia package version 2.1.80.
• Fixed a black screen issue that occurred when powering on TV. The issue happened after switching between apps and switching off. Provided correct app state restoration and launcher visibility.
• Fixed an app crash that occurred when playing extended HLS content by resolving the stability issue
• Fixed a caption text clipping issue by removing unnecessary window padding, when the auto window size calculates for text display.
• Fixed the non-functioning media control buttons used in an app.
• Fixed an app crash that occurred when playing VOD content, when Message Router command was running simultaneously with the enforce-security command.
• Fixed the subtitle alignment and missing text issues in apps for caption cues with identical start/end times.

Known issues

• The performance tools in binary form don't work on the latest Ubuntu OS versions (22, 24).

  Workaround: Reach out to your Amazon contact or leave a question in the forum to receive a zip file and installer script. The file and script lets you run performance pools with Python source codes on Ubuntu devices.

• Activity Monitor doesn't display hot functions of Debug variant apps when launching through Vega Studio.

  Workaround: Launch the app through the VLCM command to observe the hot functions:

  Copy code Copied to clipboard.

  vlcm launch-app orpheus://<App URL>
  

• An app might crash during extended video playback (1-2 hours) due to map iterator's race conditions.
• React Navigation theme background defaults to white on release builds when using react-navigation core, although debug builds work correctly.
• Apps might experience Low Memory Killer (LMK) termination during ad playback transitions in a non-logged-in state.
• Shaka Player might stall when seeking to the end of a video using right D-pad navigation.
• Using BackHandler.exitApp() followed by a quick app relaunch causes crashes in release builds or Cannot initialize hmrClient twice error in debug mode.
• App might launch without displaying a splash screen, affecting user experience during app startup. The root cause is still unknown.
• A focus property hierarchy in JSON RPC response doesn't align with actual focused elements, impacting Appium selector functionality.
• Closed captions intermittently blink and change positions during live TV broadcasts using real-time generated captions, affecting readability.

• The stop and status actions do not work properly for Vega Virtual Device (VVD) on Ubuntu systems. This means users can't stop VVD using standard CLI commands or Vega Studio.

  Workaround: Right-click the VVD app icon and select "close" or the "x" button in the VVD user interface.

• Virtual devices might unexpectedly terminate after launch when certain USB hubs or docking stations connect to the host machine.

  Workaround:

  1. Disconnect all USB hubs from your host machine.
  2. Disconnect any docking stations from your host machine.
  3. Restart the Virtual Device.

• Performance tools compatibility on Ubuntu. Perf CLI binary files might not work correctly on Ubuntu systems. Users experiencing issues should use the provided patch bundle as a workaround.

  Workaround:

  1. Download the patch bundle and install the script
  2. Run the following.

     Copy code Copied to clipboard.

      sudo chmod +x install_bundle.sh && ./install_bundle.sh
     

  3. The script installs the bundle into your SDK.

Last updated: Oct 09, 2025