Building on Vega
This page records how Vega OS behaved for Dice Chess on the Vega Virtual Device (SDK 0.24.12112, OS 1.2). Where a statement rests on something else, such as unit tests, Amazon’s documentation or Amazon’s developer forum, it says so. Unless a section says otherwise, nothing here has been checked on a Fire TV Stick, although the game has run on a Fire TV Stick 4K Select since October 6, 2026. The friction log has the steps and evidence for the obstacles linked from this page.
Remote Input & Navigation
Section titled “Remote Input & Navigation”Vega delivers remote keys through several APIs. On SDK 0.24 one of them aborts the app, and two cannot be used together. What each one did on the Virtual Device:
| Channel / API | Behavior on Vega OS | Outcome in Dice Chess TV |
|---|---|---|
UserInputManager.addListener (static) |
Aborts the JavaScript thread with SIGABRT on SDK 0.24. |
Unusable. |
useAddUserInputListenerCallback |
Subscribed to every key, it delivers nothing while useTVEventHandler is also mounted, and reports no error. |
Not used. |
useTVEventHandler |
Delivers the arrows, OK and Back, but cannot claim an event. | Used for the arrows, OK and Menu. |
useKeplerBackHandler |
Claims Back. When no handler returns true, it calls exitApp() itself. |
Used for Back only. |
The Three Names of OK
Section titled “The Three Names of OK”OK does not arrive under a single identifier. Depending on where the key originates, it is reported under three distinct names:
enter: Sent by the Virtual Device when Return is pressed on the computer’s keyboard (measured with a Mac).kpenter: Delivered by the Virtual Device’s on-screen remote skin (KEY_KPENTER). On-screen remote clicks were ignored until this mapping was added.select: The name Amazon’sHWEventdocumentation gives for OK. We found no way to make the Virtual Device send it: its virtual keyboard does not declareKEY_SELECT(FL-08).
Amazon staff said on Amazon’s developer forum on August 31, 2026, in another developer’s bug report, that for React Native 0.83 apps Vega OS 1.2 delivers the raw, lower-case key name, so a remote’s OK arrives as enter, and that a future Vega OS release will normalize it to select. Neither that answer nor the documentation mentions kpenter (FL-03).
native/src/useRemoteInput.ts treats all three names as OK, so the app acts on OK under any of them.
Verification: on the Virtual Device, enter from a Mac keyboard drove a whole turn on September 22, 2026, and on September 24 a diagnostic build that printed raw events showed kpenter from the on-screen remote. kpenter was also checked with KEY_KPENTER sent through the emulator’s gRPC API. A unit test (native/test/input.test.tsx) checks that all three names act as OK; it runs against stand-ins for the Vega packages, so it checks the mapping, not what Vega sends. On a Fire TV Stick 4K Select, a game has been played with the Stick’s own remote (Performance), but which of the three names its OK arrives under has not been recorded.
Handling the Back Button
Section titled “Handling the Back Button”useTVEventHandler sees Back but cannot claim it, and a Back that nothing claims closes the app. Handled only there, Back would cancel nothing and quit (FL-06).
To keep Back from closing the app when a player wants to put a piece down or open the game menu, the app uses useKeplerBackHandler:
- When a piece is selected: Back deselects the piece.
- During a game, with nothing selected or while the opponent plays: Back opens the game menu, and Back again closes it.
- In the rules guide: Back returns to the screen that opened it, the home screen or the game menu, with Rules reference focused.
- In the tutorial or About: Back returns to the home screen, with its first item focused; returning to the option that opened them is #238, still open. In the tutorial, Back first puts down a selected piece.
- On the first launch’s offer of the tutorial: Back goes to the home screen, as Skip does, and never closes the app.
- In Settings and in the choice of opponent and color: Back returns to the screen that opened it. The choice of color comes up only when Play as in Settings is Ask (#352); otherwise OK on an opponent’s card starts the game. On a confirmation, Back does what Cancel does.
- On the home screen: the handler returns
false, anduseKeplerBackHandlercloses the app.
Verification: on the Virtual Device, with Back sent as KEY_BACK through the emulator’s gRPC API on September 24 and 28, 2026, Back put a selected knight down, opened the game menu and closed it, returned from Settings to the home screen with Settings focused, left the rules guide and the tutorial for the home screen, and closed the app from the home screen. On October 5, 2026, vvd press back on the first launch’s offer of the tutorial went to the home screen, and the app stayed open. Unit tests (native/test/screen.test.ts, native/test/input.test.tsx, native/test/tutorial.test.tsx, native/test/tutorialOffer.test.tsx, native/test/playAs.test.tsx) cover the other paths, among them the rules guide opened from the game menu and the choice of color under each Play as.
Event Timing: Press vs Release
Section titled “Event Timing: Press vs Release”Hardware events arrive with eventKeyAction: 0 on press (and repeat while held), and 1 on release.
- Arrows act on the press (
0), so holding one repeats it. - OK and Menu act on the release (
1), so holding OK plays one action, not one per repeat. Back acts on the release too, becauseuseKeplerBackHandler, as its npm package implements it, calls the app’s handler only when Back is released.
Audio Subsystem & Manifest Permissions
Section titled “Audio Subsystem & Manifest Permissions”Dice Chess TV plays ten sound cues, spoken lines for the opponents, the Hot Seat host and the tutorial, and four music themes (one for the menus, three that follow the danger to a king), all through @amazon-devices/react-native-w3cmedia 2.3.2. The observations below identify whether they came from the Virtual Device or a physical Fire TV Stick.
Service Declarations in manifest.toml
Section titled “Service Declarations in manifest.toml”Vega’s service manager refused the media player’s connections to audio services that the manifest did not declare. The app got no error: every cue failed at the sink, and only the device log said why:
missing permission for connection attemptOne probe run without the declarations logged 13 refused connections to com.amazon.audio.stream (FL-18). native/manifest.toml declares five services as [[wants.service]] entries: the four that Amazon’s audio sample declares, and com.amazon.audio.control, which the player’s audio-focus client also needed and which only the device log revealed:
[wants]
[[wants.service]]id = "com.amazon.audio.stream"
[[wants.service]]id = "com.amazon.media.server"
[[wants.service]]id = "com.amazon.media.playersession.service"
[[wants.service]]id = "com.amazon.mediametrics.service"
[[wants.service]]id = "com.amazon.audio.control"com.amazon.inputd.service is deliberately not declared: on the Virtual Device, declaring it made this app exit at start-up (FL-19).
The AudioPlayer Class & Game Usage
Section titled “The AudioPlayer Class & Game Usage”AudioPlayer, notAudio: in the first probe, theAudiocomponent on its default music and media types filled the device log withcould not connect to audioserver, while anAudioPlayerreachedplaying(FL-12). That probe ran before the audio services were declared, so it does not show thatAudiocannot work. The app usesAudioPlayeronly.- Content and usage types: sound effects and spoken lines use
CONTENT_TYPE_SONIFICATIONwithUSAGE_GAME; music usesCONTENT_TYPE_MUSICwithUSAGE_GAME. Both play on the Virtual Device. How these types affect ducking under system sounds has not been tested. - Bare file paths: a file packaged with the app plays from its plain path (e.g.
/pkg/assets/sfx/move.mp3). The same file as afile:///URL fails with error 4, and anhttp://source is refused as insecure. - Event listeners: events arrive only through
addEventListener. Assigning a handler property such asaudio.onplayingis silently ignored. - One clip per player, on a Fire TV Stick: after the Stick’s OS was updated on October 12, 2026 (OS build
2602000051520), settingsrcon a player that had already played took about 100 ms, and now and then it never returned. The JavaScript thread waited inside the media player until the system closed the app as not responding, within a minute of play with sound effects on, in every build back to beta 8. On a fresh player the same call took about 10 ms. The music, which loaded a new theme on a player it had paused, hung the same way after six minutes of play. A player kept for each sound file never hung, but once those players had played, paused or not, the Stick’s load average stayed above 20 and the opponent’s search ran out of time. A paused music player that had loaded a track did the same, and a fresh player for every cue, let go after it, left more and more behind it: within five minutes of play the app had about 270 threads, against about 100 before. So the effects are joined into one file, an audio sprite as Amazon advises for games, which three players, one for each channel, load once and play by offset. A seek asked for just beforeplay()lost the start of a clip on the Virtual Device, and now and then the whole clip, so between clips each channel’s player waits, paused, at the start of a take of the cue it plays most, and that cue only has to play. Each spoken line and each pass of a music theme plays on a fresh player that is let go withdeinitialize()once it is done (#374).
Playback after the OS update
Section titled “Playback after the OS update”The follow-up to the Stick’s OS build 2602000051520, tested on October 14, 2026, with SDK 0.24.12044 in PR #388, established these playback rules:
- Initialize, then load once. Fresh voice and music players initialize before receiving their one
src, then wait forcanplaywith a finite, positive duration before callingplay(). Starting alongside the source load could leave a pipeline without metadata. Spare players are constructed only; they hold no empty native pipeline. Music seeks afterplayingand fades in only after its position progresses. - Finish speech on
ended.play()resolving acknowledges the start request; it does not establish when the audible clip began. A deadline measured from that acknowledgement cut a delayed line short on the Stick. Speech now finishes on nativeendedplus a short tail. A watchdog bounds missing initialization or completion events; replacement, Voices off and loss of focus silence and release the line immediately. - Mute and release completed music without
pause(). Pausing an ended pipeline beforedeinitialize()stalled GStreamer on the updated Stick. An EOF handler defers release until the native notification has returned. The reusable effect sprite players still pause between their clips. - Recover only while audio is wanted. A failed incoming music pass is released while a working theme remains audible. Music off, an absent theme or catalog, and a result hold preserve silence even if either pass fails during a crossfade. Failed roles wait for an explicit request, a settings toggle or a foreground return before retrying. A pass with no position progress times out without fading away the working theme.
The asset generator verifies the vendor MP3 hashes, then strips leading ID3 and appended ID3v2.4 tags, plus trailing ID3v1, from the generated package copies. Tagged inputs intermittently left the updated Stick’s ID3 demuxer without metadata; the direct MPEG audio path avoided that load. Tag boundaries follow the ID3 structure specification. Vendor bytes, locks, credits and licenses stay unchanged, as do the MPEG frames; the packaged music catalog uses the copies’ actual hashes. Decoded PCM SHA-256 matched for all 272 original and packaged MP3s.
The audio work was exercised independently on VVD and the physical Stick: a 600-second playback probe, all six tutorial lessons with all 45 spoken clips reaching native EOF, and eight injected crossfade failure/silence cases on each device. Hardware evidence consists of native events, positions, requested volume ramps, release completions and UI state. Recorded audio is from VVD; no hardware audio recording or direct listening was available. The validation record gives the methods, package checks and scope of each run; native/test/sound.test.ts, music.test.ts and assets.test.ts provide the automated regressions.
Audio lifecycle after the first commit
Section titled “Audio lifecycle after the first commit”PR #479 moves sound and music construction out of rendering and into an effect after React’s first commit. The screens keep stable audio references while the real objects attach. Saved settings, the theme and suspension state are forwarded, and Thinkle’s current startup line waits for attachment. Stopping the line, disabling voices, suspension or disposal cancels it; a consumed line is never replayed on reattachment. Early effect cues are dropped rather than replayed later.
The effect channels release their players on loss of focus, without a preceding pause(). After return, recreation waits briefly unless a cue needs the channels sooner. A launch already reported as background or inactive opens no effect pipelines. Music stops its periodic ticker once fades, ducking and startup have settled, and schedules the next loop seam instead. Unmounting disposes the app’s players.
Local QA builds 53 and 54, built in Release mode and run on a physical Fire TV Stick, checked first and cold launches, saved games and Home returns. They were not published Appstore updates. Build 53 also crossed a music loop seam with native player creation, gain and release events. These checks establish the requested lifecycle behavior; they do not measure startup acceleration or CPU savings, and do not establish what was heard from the TV. The audio lifecycle validation separates the two builds, automated startup regressions, available logs and remaining listening checks. PR #488 then fixed the clipped Thinkle greeting (#482) by advancing tutorial speech only after the decoder’s ended event and the 300 ms tail; on build 56 on a physical Fire TV Stick, the owner confirmed by listening on the television that three cold clean-profile greetings and the sampled tutorial speech sounded complete and clear.
Container & Codec Compatibility
Section titled “Container & Codec Compatibility”Measured on the Virtual Device. The results and the times both come from the first audio probe, three runs per format, with the same result each time (FL-11). That probe ran before the audio services were declared, while the sink was failing, so the times are how long each file took to report playing, not the time to audible sound. MP3 and WAV have played since, in the music probe of September 26 (FL-25), and MP3 in the game:
| Audio format | Result on the Virtual Device | Time to playing (first probe) |
|---|---|---|
| MP3 | Plays | 3–7 ms |
| WAV | Plays | about 3 ms |
| OGG | Fails with error 4 | – |
| M4A | Fails with error 4 | – |
Note: canPlayType() cannot be relied upon on Vega; it returns "probably" for OGG (which fails) and "" for WAV (which plays). Every sound the app ships is an MP3 file, and MP3 has since been heard from the Virtual Device through a computer’s speakers.
Leaving the Foreground
Section titled “Leaving the Foreground”Amazon’s pre-submission test cases ask for no audio from the app on the Fire TV launcher or over the screensaver, and none overlapping another app when switching apps (Test before submission). The app listens to useKeplerAppStateManager and counts itself in front only while it is both active and focused (native/src/App.tsx, #296). On blur, background or inactive, the sound effects, the spoken lines and the music stop, the game ignores the remote, and the opponent’s next step and the danger search hold what was left of their wait; the return picks the turn up where it was. Music comes back 300 ms after the app is both active and focused.
On the Virtual Device, bringing the launcher to the front delivered blur and then background on each of four trips, and the music stopped (FL-28). On a Fire TV Stick 4K Select on October 9, 2026, the app-state manager reported unknown at launch. After Home it received blur and a change to background, but on the return only focus, and a build that waited for the change to active ignored every key after the first return from Home. So the app takes focus as the return (native/README.md, Loss of focus), and its own reports on the Stick then showed it pausing and resuming with the saved game kept. That nothing is heard over the launcher has not yet been confirmed by ear. An Alexa overlay can send blur alone: on the Stick on October 8, 2026, the owner heard the game’s sounds go on over Alexa’s answer while only the music stopped. Since #325 the sound effects and the voices stop on blur too, which native/test/lifecycle.test.tsx checks; a listening check of that on the Stick is still to come.
In the October 14, 2026, audio validation on OS 2.0, Home terminated the background process on both the Stick and VVD. Relaunch restored the saved turn, phase, dice and last move. That run establishes cold-relaunch recovery. The October 14 record preserves its scope.
On October 21, local QA builds 52 and 53 running in Release mode on the physical Stick each kept the same process and saved game across a 180-second Home interval. The build 54 QA follow-up added three same-process returns with exact saves. Warm return is therefore also physical-device evidence, separately from cold recovery. This does not guarantee that the OS will retain a background process. The opponent runtime record and audio lifecycle record identify the builds and methods. Hearing silence over the launcher and Alexa’s answer still requires a listening check.
Icon & Splash Screen Traps
Section titled “Icon & Splash Screen Traps”Two packaging details on Vega were easy to get wrong:
The Launcher Icon (3:2 Crop)
Section titled “The Launcher Icon (3:2 Crop)”The manifest has one icon field. Ours names a 512x512 PNG: icon = "@image/icon.png". On the Virtual Device:
- In system Settings, the entire 1:1 square is displayed.
- On the launcher, the icon is scaled to fill a 3:2 tile, about 304x200 on a 1080p screen, and its top and bottom are cropped.
- Only about the middle two thirds of the icon’s height stay visible there.
So everything that matters in our icon stays between y 100 and y 412 of its 512 pixels, with even side margins. The icon is also opaque: an earlier bare mark on transparency came out distorted on the launcher (FL-16). The launcher on a Fire TV Stick has not been checked.
Verification: native/test/splash.test.ts fails if any artwork in the icon lies outside that band or any of its pixels is transparent. It was checked by enlarging the dice until the test failed.
The Splash Archive (SplashScreenImages.zip)
Section titled “The Splash Archive (SplashScreenImages.zip)”Vega’s animation service reads assets/raw/SplashScreenImages.zip directly when the app launches; nothing in the manifest points at it:
- As Amazon’s splash screen documentation describes, the archive holds a
desc.txtfile (width, height and frame rate, e.g.1920 1080 30, thenc 0 0 _loop) and a_loopdirectory of PNG frames. - Archive root trap:
desc.txtand_loopmust sit at the root of the archive, as that page warns. With a wrapping folder, the animation service on the Virtual Device silently showed nothing. - Deterministic archive:
native/scripts/generate-assets.mjsstamps every entry of the archive with a fixed time and runszipin UTC, so two builds write byte-identical archives wherever they run. - The archive loops: on our Fire TV Stick (Vega OS 1.2), a count of 1 in
desc.txtand a separate hold part both repeated the whole archive, as a public bug report describes. A cool start keeps the splash up for about 2.2 s there, so an animation either repeats or is cut halfway. Ours is a 3.1 s loop that ends where it starts, with the title still in every frame (#289).
Scripted Virtual Device Automation
Section titled “Scripted Virtual Device Automation”To drive the Virtual Device from scripts and coding agents, with nobody at the emulator, Fortemate wrote vega-vvd-driver (vvd), an MIT-licensed tool. It runs on a developer’s machine against a running Virtual Device; CI does not run it.
What we used it for:
- Key presses:
vvd presssendsKEY_KPENTER,KEY_BACKand the arrows through the Android emulator’s gRPCEmulatorController.sendKey, the route the on-screen remote uses. QEMU’ssend-key, the emulator console’sevent sendand the device’sinputd-clireport success and reach no app (FL-08). - Waiting for the screen:
vvd wait-changecompares screenshots and exits 0 as soon as the screen differs from how it looked when the command started, or 1 on timeout, so a script can tell that a press did something. - Frames:
vvd framespolls the emulator’sgetScreenshotand saves each distinct frame it catches; while the screen changes, each screenshot takes 23 to 61 ms. It showed a 220 ms piece slide in flight in 4 to 6 frames, and the dice tumbling in. It is too coarse to count dropped frames, and smoothness on a Fire TV Stick has not been checked.