Developer Console

Handling HDMI Events (Fire TV)

Application developers are responsible for handling capability and state changes for all connected devices, including events about TVs, AVRs, and Bluetooth speakers. Failing to handle these events leads to unnecessary network and CPU usage, exceeding a user’s data limitations / restrictions enforced by their network provider (data caps). Using up bandwidth will degrade performance of other devices connected to the same network as well. If playback continues indefinitely, it will keep the device from entering the sleep state, preventing important software updates.

HDMI state changes

Applications may receive HDMI state change notifications for several possible reasons. For example, because the TV was powered OFF, TV input was switched to another HDMI port, the HDMI cable was physically disconnected, or the HDMI settings were adjusted on the video receiver.

  • Applications must pause video playback when an HDMI disconnection event is received. Apps playing live content (or any content that cannot be paused) must return to the details page and stop playing content. When an HDMI sink reconnection event message is received, playback should remain paused until the user presses the PLAY button on the remote.
  • Applications playing only audio may continue to play even after the HDMI disconnection event is received, provided they confirm that an audio output device is still available (like a connected Bluetooth speaker).

Available APIs

There are various ways to listen to changes in the HDMI state. The preferred way from Android Marshmallow (Fire OS 6) is through the AudioDeviceCallback APIs. These APIs are faster and provide more information about the state change than intents.

Applications targeting Fire OS 5 can only listen for the intent ACTION_HDMI_AUDIO_PLUG that has an extra EXTRA_AUDIO_PLUG_STATE indicating the HDMI connection state (plugged-in or unplugged).

Applications targeting all Fire OS versions should decide which solution to use based on the runtime API level support of the platform.

Additional notes

Smart TVs may choose not to notify the connected Fire TV device that a different input was selected, or even that the TV was turned off. This supports a faster switch between TV inputs. However, in such cases there is no reliable way to decide if the output of the Fire TV device is visible to the customer.

When a notification about reconnection is received, applications playing encoded content must check if the audio capabilities have been changed. It is possible that playback was started while the Fire TV was connected to a Dolby Atmos capable Audio-video receiver, and the HDMI cable was unplugged from the receiver and then reconnected to a PCM-only capable television.

For further details, please check the Output State Change Requirements sections of the Requirements for Multimedia Applications page.

Last updated: Oct 30, 2020