Skip to main content

Control API

Handles TV remote control.

control.appAlexa​

Signatures​

appAlexa(n_times \ 1, delay \ 100)

Description​

Presses the appAlexa button on the remote control.

control.appDisney​

Signatures​

appDisney(n_times \ 1, delay \ 100)

Description​

Presses the appDisney button on the remote control.

control.appFreevie​

Signatures​

appFreevie(n_times \ 1, delay \ 100)

Description​

Presses the appFreevie button on the remote control.

control.appHulu​

Signatures​

appHulu(n_times \ 1, delay \ 100)

Description​

Presses the appHulu button on the remote control.

control.appNetflix​

Signatures​

appNetflix(n_times \ 1, delay \ 100)

Description​

Presses the appNetflix button on the remote control.

control.appPrime​

Signatures​

appPrime(n_times \ 1, delay \ 100)

Description​

Presses the appPrime button on the remote control.

control.audio​

Signatures​

audio(n_times \ 1, delay \ 100)

Description​

Presses the audio button on the remote control.

control.back​

Signatures​

back(n_times \ 1, delay \ 100)

Description​

Presses the back button on the remote control.

control.chNext​

Signatures​

chNext(n_times \ 1, delay \ 100)

Description​

Presses the chNext button on the remote control.

control.chPrev​

Signatures​

chPrev(n_times \ 1, delay \ 100)

Description​

Presses the chPrev button on the remote control.

control.detectPlaybackNative​

Signatures​

detectPlaybackNative(opts \ [], lua)

Description​

Detect video playback using native device capabilities.

Uses the device's native playback detection to determine if video content is currently playing. Optionally taps at coordinates to trigger playback.

Parameters​

  • opts (table) - Optional parameters

Options​

  • timeout (number) - Maximum time to wait for playback detection in seconds (default: 30)
  • tap (table) - Optional table with x and y coordinates to tap before detection

Returns the elapsed time in seconds when playback is detected. Raises an exception if playback is not detected within the timeout.

Example​

-- Simple playback detection
local elapsed = control.detectPlaybackNative({timeout = 10})
print("Playback detected after " .. elapsed .. " seconds")

-- Tap and then detect playback
local elapsed = control.detectPlaybackNative({
  timeout = 15,
  tap = {x = 960, y = 540}
})

control.display​

Signatures​

display(n_times \ 1, delay \ 100)

Description​

Presses the display button on the remote control.

control.down​

Signatures​

down(n_times \ 1, delay \ 100)

Description​

Presses the down button on the remote control.

control.eject​

Signatures​

eject(n_times \ 1, delay \ 100)

Description​

Presses the eject button on the remote control.

control.enterText​

Signatures​

enterText(text, lua)

enterText(kb_arg, text, sleep \ 100, lua)

Description​

Enters the provided string of text via a given keyboard, or the system keyboard if one is not provided.

Parameters​

  • text (string) - The text to enter using the keyboard

Example​

control.enterText("Hello world!")
local kb = keyboard.basic([[
e h l
n m o
]], "h") -- Sets "h" as the initial key. Will set the top left key by default

control.enterText(kb, "hello")

control.enterTextNative​

Signatures​

enterTextNative(text)

Description​

Enter text using the device's native text input method.

Sends text directly to the device using its native text entry capabilities. This bypasses virtual keyboard navigation and types the text directly.

Supported platforms:

  • iOS / tvOS: via SDK protocol (idevice / PyATV)
  • Android TV / Android Mobile: via ADB input commands (supports escape sequences)
  • Roku: via ECP Lit_ keypresses (remote-py) or Grove ECS/ECP (when Grove drivers are active)

Parameters​

  • text (string) - The text string to enter

Escape Sequences (Android ADB devices)​

On Android devices with ADB support, you can use escape sequences for special keys:

  • <backspace> - Delete previous character
  • <tab> - Tab key
  • <enter> or <return> - Enter/return key
  • <space> - Space key
  • <delete> - Delete next character
  • <up>, <down>, <left>, <right> - Navigation keys

Examples​

-- Works on iOS, tvOS, Android, Roku
control.enterTextNative("Hello World")
control.enterTextNative("[email protected]")

-- Android with ADB: escape sequences are supported
control.enterTextNative("username<tab>password<enter>")
control.enterTextNative("test<backspace><backspace>xt")

Notes​

  • Native text input may not work in all app contexts
  • For universal compatibility, use control.enterText() with keyboard navigation

control.enterTextPassThrough​

Signatures​

enterTextPassThrough(text, opts \ [], lua)

Description​

Enter text character-by-character using keyboard pass through.

Simulates typing with individual keydown/keyup events, providing more realistic typing behavior than enterTextNative. Uses the same code path as the interactive keyboard pass through feature.

Supported platforms: Roku, iOS, tvOS, Android

Parameters​

  • text (string) - The text to type (supports escape sequences like <backspace>, <enter>)
  • opts (table) - Options: delay (ms between keys, default 50), keyDelay (ms between down/up, default 5), ctrl, shift, alt, meta modifiers

Example​

control.enterTextPassThrough("Hello World")
control.enterTextPassThrough("test<backspace><backspace><backspace><backspace>pass")
control.enterTextPassThrough("a", {ctrl = true})

control.fastForward​

Signatures​

fastForward(n_times \ 1, delay \ 100)

Description​

Presses the fastForward button on the remote control.

control.groupDisc​

Signatures​

groupDisc(n_times \ 1, delay \ 100)

Description​

Presses the groupDisc button on the remote control.

control.guide​

Signatures​

guide(n_times \ 1, delay \ 100)

Description​

Presses the guide button on the remote control.

control.home​

Signatures​

home(n_times \ 1, delay \ 100)

Description​

Presses the home button on the remote control.

control.info​

Signatures​

info(n_times \ 1, delay \ 100)

Description​

Presses the info button on the remote control.

control.input​

Signatures​

input(n_times \ 1, delay \ 100)

Description​

Presses the input button on the remote control.

control.left​

Signatures​

left(n_times \ 1, delay \ 100)

Description​

Presses the left button on the remote control.

control.loadDisc​

Signatures​

loadDisc(n_times \ 1, delay \ 100)

Description​

Presses the loadDisc button on the remote control.

control.longPressDown​

Signatures​

longPressDown(duration_ms \ 800)

Description​

Long presses the longPressDown button.

Unlike other remote commands which take (n_times, delay_ms_between_presses) and tap the key N times, this performs a single CEC hold for duration_ms (clamped to 10000ms max).

Some apps (e.g. TLC GO on Fire TV) need >800ms to register a long press.

control.longPressLeft​

Signatures​

longPressLeft(duration_ms \ 800)

Description​

Long presses the longPressLeft button.

Unlike other remote commands which take (n_times, delay_ms_between_presses) and tap the key N times, this performs a single CEC hold for duration_ms (clamped to 10000ms max).

Some apps (e.g. TLC GO on Fire TV) need >800ms to register a long press.

control.longPressOk​

Signatures​

longPressOk(duration_ms \ 800)

Description​

Long presses the longPressOk button.

Unlike other remote commands which take (n_times, delay_ms_between_presses) and tap the key N times, this performs a single CEC hold for duration_ms (clamped to 10000ms max).

Some apps (e.g. TLC GO on Fire TV) need >800ms to register a long press.

control.longPressRight​

Signatures​

longPressRight(duration_ms \ 800)

Description​

Long presses the longPressRight button.

Unlike other remote commands which take (n_times, delay_ms_between_presses) and tap the key N times, this performs a single CEC hold for duration_ms (clamped to 10000ms max).

Some apps (e.g. TLC GO on Fire TV) need >800ms to register a long press.

control.longPressUp​

Signatures​

longPressUp(duration_ms \ 800)

Description​

Long presses the longPressUp button.

Unlike other remote commands which take (n_times, delay_ms_between_presses) and tap the key N times, this performs a single CEC hold for duration_ms (clamped to 10000ms max).

Some apps (e.g. TLC GO on Fire TV) need >800ms to register a long press.

control.menu​

Signatures​

menu(n_times \ 1, delay \ 100)

Description​

Presses the menu button on the remote control.

control.mute​

Signatures​

mute(n_times \ 1, delay \ 100)

Description​

Presses the mute button on the remote control.

control.next​

Signatures​

next(n_times \ 1, delay \ 100)

Description​

Presses the next button on the remote control.

control.nextDisc​

Signatures​

nextDisc(n_times \ 1, delay \ 100)

Description​

Presses the nextDisc button on the remote control.

control.num0​

Signatures​

num0(n_times \ 1, delay \ 100)

Description​

Presses the num0 button on the remote control.

control.num1​

Signatures​

num1(n_times \ 1, delay \ 100)

Description​

Presses the num1 button on the remote control.

control.num2​

Signatures​

num2(n_times \ 1, delay \ 100)

Description​

Presses the num2 button on the remote control.

control.num3​

Signatures​

num3(n_times \ 1, delay \ 100)

Description​

Presses the num3 button on the remote control.

control.num4​

Signatures​

num4(n_times \ 1, delay \ 100)

Description​

Presses the num4 button on the remote control.

control.num5​

Signatures​

num5(n_times \ 1, delay \ 100)

Description​

Presses the num5 button on the remote control.

control.num6​

Signatures​

num6(n_times \ 1, delay \ 100)

Description​

Presses the num6 button on the remote control.

control.num7​

Signatures​

num7(n_times \ 1, delay \ 100)

Description​

Presses the num7 button on the remote control.

control.num8​

Signatures​

num8(n_times \ 1, delay \ 100)

Description​

Presses the num8 button on the remote control.

control.num9​

Signatures​

num9(n_times \ 1, delay \ 100)

Description​

Presses the num9 button on the remote control.

control.ok​

Signatures​

ok(n_times \ 1, delay \ 100)

Description​

Presses the ok button on the remote control.

control.options​

Signatures​

options(n_times \ 1, delay \ 100)

Description​

Presses the options button on the remote control.

control.pause​

Signatures​

pause(n_times \ 1, delay \ 100)

Description​

Presses the pause button on the remote control.

control.play​

Signatures​

play(n_times \ 1, delay \ 100)

Description​

Presses the play button on the remote control.

control.playPause​

Signatures​

playPause(n_times \ 1, delay \ 100)

Description​

Presses the playPause button on the remote control.

control.power​

Signatures​

power(n_times \ 1, delay \ 100)

Description​

Presses the power button on the remote control.

control.powerOff​

Signatures​

powerOff()

Description​

Presses the powerOff button on the remote control.

control.powerOn​

Signatures​

powerOn()

Description​

Presses the powerOn button on the remote control.

control.prev​

Signatures​

prev(n_times \ 1, delay \ 100)

Description​

Presses the prev button on the remote control.

control.prevDisc​

Signatures​

prevDisc(n_times \ 1, delay \ 100)

Description​

Presses the prevDisc button on the remote control.

control.rewind​

Signatures​

rewind(n_times \ 1, delay \ 100)

Description​

Presses the rewind button on the remote control.

control.right​

Signatures​

right(n_times \ 1, delay \ 100)

Description​

Presses the right button on the remote control.

control.sequence​

Signatures​

sequence(key_sequence, opts \ [], lua)

Description​

Executes a sequence of key events provided as a string.

Parameters​

  • key_sequence (string) - String of key codes to execute (L=left, R=right, U=up, D=down, E=enter, B=back)
  • opts (table) - Optional parameters

Options​

  • :delay (number) - The delay between key presses in milliseconds (default: 100)
  • :confirm (boolean) - Whether to press enter after the sequence (default: false)

Example​

control.sequence("LLRR")
control.sequence("UUDDLRLR", delay: 200, confirm: true)
control.sequence("UUDDLRLREB", delay: 200)

control.settings​

Signatures​

settings(n_times \ 1, delay \ 100)

Description​

Presses the settings button on the remote control.

control.sortDisc​

Signatures​

sortDisc(n_times \ 1, delay \ 100)

Description​

Presses the sortDisc button on the remote control.

control.stop​

Signatures​

stop(n_times \ 1, delay \ 100)

Description​

Presses the stop button on the remote control.

control.swipe​

Signatures​

swipe(start_x, start_y, end_x, end_y, duration \ 300)

Description​

Perform a swipe gesture from one coordinate to another.

Creates a swipe motion from the starting coordinates to the ending coordinates over the specified duration.

Parameters​

  • start_x (number) - Normalized starting X coordinate (0 to 1)
  • start_y (number) - Normalized starting Y coordinate (0 to 1)
  • end_x (number) - Normalized ending X coordinate (0 to 1)
  • end_y (number) - Normalized ending Y coordinate (0 to 1)
  • duration (number) - Swipe duration in milliseconds (default: 300)

Example​

-- Swipe from left to right
control.swipe(0.1, 0.2, 0.4, 0.2, 500)

-- Quick upward swipe
control.swipe(0.2, 0.4, 0.2, 0.1)

control.swipePoint​

Signatures​

swipePoint(start_point, end_point, duration \ 300, lua)

Description​

Perform a swipe gesture from one coordinate to another.

Coordinates are in range of 0 <= x, y <= 1, representing normalized coordinates relative to the screen size, where (0,0) is the top-left corner and (1,1) is the bottom-right corner.

Parameters​

  • start_point ({x, y} or {x=X, y=Y}) - starting point of the swipe gesture, each component is a number in range [0, 1], representing normalized coordinates relative to the screen size.
  • end_point ({x, y} or {x=X, y=Y}) - starting point of the swipe gesture, each component is a number in range [0, 1], representing normalized coordinates relative to the screen size.
  • opts (table) - Optional parameters

Options​

  • async - If true, performs the tap asynchronously without blocking (default: false)

Example​

-- Swipe from left to right
control.swipePoint({0.1, 0.2}, {0.4, 0.2}, 500)
control.swipePoint({x = 0.1, y = 0.2}, {x = 0.4, y = 0.2}, 500)

-- Quick upward swipe
control.swipePoint({0.2, 0.4}, {0.2, 0.1})
control.swipePoint({x = 0.2, y = 0.4}, {x = 0.2, y = 0.1})

control.tap​

Signatures​

tap(x, y, opts \ [], lua)

Description​

Perform a tap gesture at the specified screen coordinates.

Coordinates are in range of 0 <= x, y <= 1, representing normalized coordinates relative to the screen size, where (0,0) is the top-left corner and (1,1) is the bottom-right corner.

Parameters​

  • x (number) - normalized X coordinate (0 to 1)
  • y (number) - normalized Y coordinate (0 to 1)
  • opts (table) - Optional parameters

Options​

  • async - If true, performs the tap asynchronously without blocking (default: false)

Example​

-- Tap at coordinates at 50%, 50% of the screen
control.tap(0.5, 0.5)

-- Async tap
control.tap(0.5, 0.5, {async = true})

control.tapAndHold​

Signatures​

tapAndHold(x, y, hold_ms \ 800)

Description​

Perform a long press gesture at the specified screen coordinates.

Touches down at the coordinates, holds for the specified duration, then releases.

Coordinates are in range of 0 <= x, y <= 1, representing normalized coordinates relative to the screen size, where (0,0) is the top-left corner and (1,1) is the bottom-right corner.

Parameters​

  • x (number) - normalized X coordinate (0 to 1)
  • y (number) - normalized Y coordinate (0 to 1)
  • hold_ms (number) - hold duration in milliseconds (default: 800)

Example​

-- Long press at center of screen for 800ms
control.tapAndHold(0.5, 0.5)

-- Long press for 1.5 seconds
control.tapAndHold(0.5, 0.5, 1500)

control.tapPoint​

Signatures​

tapPoint(point, opts \ [], lua)

Description​

Perform a tap gesture at the specified screen coordinates given as a point.

Coordinates are in range of 0 <= x, y <= 1, representing normalized coordinates relative to the screen size, where (0,0) is the top-left corner and (1,1) is the bottom-right corner.

Parameters​

  • point ({x, y} or {x=X, y=Y}) - point to tap on the screen, each component is a number in range [0, 1], representing normalized coordinates relative to the screen size.
  • opts (table) - Optional parameters

Options​

  • async - If true, performs the tap asynchronously without blocking (default: false)

Example​

-- Tap at coordinates at 50%, 50% of the screen
control.tapPoint({0.5, 0.5})
control.tapPoint({x = 0.5, y = 0.5})

-- Async tap
control.tapPoint({x = 0.5, y = 0.5}, {async = true})

control.time​

Signatures​

time(n_times \ 1, delay \ 100)

Description​

Presses the time button on the remote control.

control.topMenu​

Signatures​

topMenu(n_times \ 1, delay \ 100)

Description​

Presses the topMenu button on the remote control.

control.up​

Signatures​

up(n_times \ 1, delay \ 100)

Description​

Presses the up button on the remote control.

control.volumeDown​

Signatures​

volumeDown(n_times \ 1, delay \ 100)

Description​

Presses the volumeDown button on the remote control.

control.volumeUp​

Signatures​

volumeUp(n_times \ 1, delay \ 100)

Description​

Presses the volumeUp button on the remote control.