pyfiretvremote

pyfiretvremote is an asynchronous Python library designed to provide robust control over your Amazon Fire TV devices. It allows you to send remote commands, manage applications, and handle the pairing process programmatically, making it ideal for home automation, custom remote applications, or integration into larger systems.

Features

• Asynchronous Operations: Built with asyncio and httpx for non-blocking network requests.
• Remote Control: Send key presses (up, down, select, home, back, volume, etc.) and media commands (play/pause, next/previous, rewind/fast-forward).
• Pairing and Authentication: Programmatically handle the pairing process with your Fire TV.
• Device Information: Retrieve information about connected Fire TV devices and installed applications.
• Alexa Voice: Speak to Alexa on the Fire TV by streaming PCM audio or a WAV clip to the device's voice channel.
• Context Manager: Use FireTvRemote as an asynchronous context manager for reliable connection management.

Installation

# Installing from PyPI
$ pip install pyfiretvremote

Usage

Pairing a New Device

The easiest way to pair a new device is to use the firetv-pair command-line tool. After installing the package, run the following command and follow the prompts:

$ firetv-pair --host YOUR_FIRETV_IP_ADDRESS

The tool will display a PIN on your TV. Enter the PIN in the terminal, and the tool will print a client_token. Save this token for future use.

Basic Control

Here's how to connect to your Fire TV and send a command using the client_token you obtained during pairing:

import asyncio
from pyfiretvremote import FireTvRemote

async def main():
    # Replace with your Fire TV's IP address and your saved client token
    firetv_host = "YOUR_FIRETV_IP_ADDRESS"
    api_key = "YOUR_API_KEY" # Use the API key configured on your Fire TV
    saved_client_token = "YOUR_SAVED_CLIENT_TOKEN"

    async with FireTvRemote(
        host=firetv_host, 
        api_key=api_key, 
        client_token=saved_client_token
    ) as remote:
        print(f"Connected to Fire TV at {firetv_host}")

        # Example: Send a 'KEY_HOMEPAGE' command
        await remote.send_command("KEY_HOMEPAGE")
        print("Sent KEY_HOMEPAGE command.")

if __name__ == "__main__":
    asyncio.run(main())

Talking to Alexa

Voice is a separate channel from the REST API (a WebSocket on port 9090). The device expects raw 16 kHz, mono, signed 16-bit little-endian PCM, streamed at real-time speed. The library handles the voiceCommand start/stop calls, the WebSocket and the pacing for you:

async with FireTvRemote(host=host, api_key=api_key, client_token=token) as remote:
    # A WAV clip (path or bytes); 8/16-bit PCM, any rate, mono or stereo
    await remote.send_voice_wav("play_stranger_things.wav")

    # Raw PCM you already have
    await remote.send_voice_audio(pcm_bytes)

    # Live audio, e.g. from a microphone
    async with remote.voice_session() as session:
        async for chunk in microphone():
            await session.send(chunk)

The library sends audio only; to say text you need to synthesise it to speech first (for example with a Wyoming/Piper TTS engine). Note the voice socket does not authenticate, so anything on your LAN can open it.

Advanced Usage

For more advanced usage examples, including how to bind keyboard keys to remote control actions, please see the demo script in the scripts/ directory of the project repository.

FireTvRemote API Overview

The FireTvRemote class provides the following key asynchronous methods:

• async with FireTvRemote(...): Connects to the Fire TV and ensures proper disconnection.
  • command_timeout: Optional, seconds before a key or media command is abandoned (default 3.0, matching the official Fire TV app). Other requests use httpx's default timeout.
• send_command(command: str, key_action_type: Optional[str] = None): Sends a key or media command.
  • command: A string representing the key (e.g., "KEY_UP", "KEY_ENTER", "KEY_PLAYPAUSE").
  • key_action_type: Optional, can be "keyDown" or "keyUp" for specific key actions.
• show_authentication_challenge(): Initiates the pairing process, displaying a PIN on the Fire TV.
• verify_pin(pin: str): Verifies the entered PIN and returns a client_token.
• get_apps(): Retrieves a list of installed applications.
• open_app(app_id: str): Opens a specific application by its ID (TODO: Phase 2).
• get_device_info(): Retrieves information about the Fire TV device.
• get_keyboard_info(): Retrieves keyboard-related information.
• open_firetv_settings(): Opens the Fire TV settings (TODO: Phase 2).
• voice_command(action: str): Sends "start" or "stop" to bookend a voice stream.
• voice_session(): Async context manager yielding a VoiceSession with send(pcm).
• send_voice_audio(pcm: bytes) / send_voice_wav(wav: bytes | str): Say a whole utterance to Alexa.
• ring_remotes(): Makes connected remotes ring.
• wake_up(): Restarts the Fire TV's remote control service (via DIAL on port 8009) and returns its status. Call it if commands start failing, e.g. after the TV has been idle.
• voice_command(action: str): Sends a voice command (TODO: Phase 2).
• send_keyboard_string(keyboard_text_request_body): Sends a string to the Fire TV keyboard (TODO).
• send_keyboard_text(keyboard_text_request_body): Sends text to the Fire TV keyboard (TODO).

Contributing

Contributions are welcome! Please refer to the DEVELOPMENT.md for setup and contribution guidelines.