Player

Overview

PlayerScreen manages live HLS stream playback using Roku’s built-in Video node. It layers an info banner, a channel number badge, and ad renderers on top of the video, and handles errors, reconnection, and network loss gracefully.

Video node

Roku’s native Video SceneGraph node plays HLS streams with streamFormat = "hls" and live = true

Channel banner

Info banner shows channel name, number, logo, and live status — auto-hides after 3 s

Number overlay

Digit-key input accumulates a channel number and tunes to it on commit

Watchdog timer

Freeze detection fires every 10 s; restarts the stream if position has not advanced

Starting playback

Playback is initiated by PlayChannel(idx), called either from onChannelIndexChanged() (when MainScene sets m.top.channelIndex) or from user navigation keys inside the player.

sub PlayChannel(idx as Integer)
    channels = m.global.channelList
    ch = channels[idx]

    m.currentIndex = idx
    m.retryCount   = 0

    ' Save resume position to Registry
    GTV_RegSaveLastChannelIndex(idx)
    m.global.currentChannelIndex = idx
    m.global.currentChannelId    = ch.contentId

    playUrl = GTV_NormalizePlayerUrl(ch.url)
    content              = CreateObject("roSGNode", "ContentNode")
    content.url          = playUrl
    content.streamFormat = "hls"
    content.live         = true

    m.video.content = content
    m.video.control = "play"
end sub

URL normalization

GTV_NormalizePlayerUrl rewrites non-standard URL schemes:

Input scheme	Output
`hls://http://...`	`http://...` (pass-through)
`hls://...`	`http://...`
`hlss://https://...`	`https://...` (pass-through)
`hlss://...`	`https://...`
Any other	Unchanged

Channel index persistence

Every time a channel is tuned, its index is written to the Registry:

GTV_RegSaveLastChannelIndex(idx)
' key: REG_KEY_CHANNEL = "lastChannelIndex"

On the next launch, MainScene reads this value to resume the last channel.

Buffer and startup

Constant	Value	Description
`CHANNEL_BUF_MS`	`1200` ms	Initial buffer target before playback begins

During the buffering state, the spinner overlay is shown and the banner displays "Reconectando la transmisión".

Overlay system

The channelBanner node (m.banner) displays channel metadata and a live/status label. Timing constants:

Constant	Value	Description
`BANNER_MS`	`3000` ms	Time banner stays fully visible after appearing
`BANNER_FADE_MS`	`300` ms	Fade-out animation duration

The banner updates statusText reactively based on player state:

Player state	Banner text
`buffering`	`"Reconectando la transmisión"`
`playing`	`"En vivo"`
Channel switch in progress	`"Cambiando canal..."`
Network lost	`"Sin conexión"`
Stream error	`"Error de transmisión"`

Number overlay

The number overlay (m.numberOverlay) accumulates digit key presses. When the user stops pressing digits, numberCommitted fires and OnNumberCommitted() looks up the channel by number and calls PlayChannel:

sub OnNumberCommitted()
    committed = m.numberOverlay.numberCommitted
    target = Val(committed)
    idx = FindChannelIndexByNumber(target)
    if idx >= 0
        PlayChannel(idx)
    else
        m.banner.statusText = "Canal " + committed + " no disponible"
    end if
end sub

Error handling and reconnection

Automatic retry

When OnVideoError() fires and the error is not an auth/inactive signal, PlayerScreen retries up to RETRY_MAX = 3 times with a 2-second delay between attempts:

if m.retryCount < AppConstants().RETRY_MAX
    m.retryCount = m.retryCount + 1
    retryTimer.duration = 2
    retryTimer.control  = "start"
else
    ShowError(GTV_BuildStreamErrorMessage(errCode, errMsg))
end if

After RETRY_MAX failures, an error dialog is shown with Retry and Back options.

Stream restart

RestartStream() clears the Video node’s content, reassigns it, and calls play again — it does not change the channel.

Auto-recoverable errors

GTV_IsAutoRecoverableStreamError classifies timeout, network, and HTTP response errors as auto-recoverable. When network connectivity is restored (via ConnectivityTask), any open error dialog of this type is automatically dismissed and the stream restarts.

Auth/inactive errors from stream

GTV_IsInactiveStreamError inspects the error code and message for inactive-account signals (HTTP 401/403 with inactivo, inactive, subscriberDisabledReason, etc.). If detected:

Playback is stopped.
m.global.authReasonCode is set to AUTH_REASON_INACTIVE or AUTH_REASON_PASSWORD_CHANGED.
m.top.userInactive = true is set — MainScene handles the re-login flow.

Freeze detection

The watchdog timer fires every FREEZE_CHECK_MS = 10000 ms while the video state is "playing". It compares the current playback position against the last recorded position. If they are equal (and the position is valid), the stream is considered frozen and RestartStream() is called:

sub OnWatchdog()
    state = m.video.state
    if state <> "playing" then return

    currentPos = m.video.position
    if currentPos = m.lastPosition and m.lastPosition >= 0
        GTV_Warn("PlayerScreen", "Stream frozen at position " + currentPos.ToStr() + " - restarting")
        RestartStream()
    end if
    m.lastPosition = currentPos
end sub

Constant	Value	Description
`FREEZE_CHECK_MS`	`10000` ms	Watchdog timer interval for freeze detection

Network handling

A netCheckTimer fires periodically during playback. It reads both GTV_IsOnline() (network interface up) and m.global.hasInternet (real internet reachability). Either failure puts the player into the offline state:

Video is stopped.
An offline dialog is shown with a Retry button.
ConnectivityTask is triggered for an immediate reachability probe.

When connectivity is restored, TryRecoverDialogsAfterNetworkRestore() hides the offline dialog and restarts the stream.

Interaction with ads (viewport reduction)

When AdManager activates a Format C ad, it emits videoHeightReduction and videoOffsetY fields. PlayerScreen observes these and adjusts the Video node’s geometry accordingly:

sub OnVideoHeightReduction()
    ApplyVideoViewportState()
    SyncAdViewport()
end sub

sub ApplyVideoViewportState()
    reduction = m.adManager.videoHeightReduction
    offsetY   = m.adManager.videoOffsetY
    newH = m.videoBaseHeight - reduction
    if newH < 480 then newH = 480  ' minimum video height
    m.video.translation = [m.videoBaseX, m.videoBaseY + offsetY]
    m.video.height = newH
end sub

After adjusting the video, SyncAdViewport() pushes the updated viewport rect back to AdManager so ad renderers can reposition themselves relative to the live video area. If all ads are hidden (allAdsHidden event from AdManager), the video is restored to its base dimensions.

OPTIONS key handling

The options key is explicitly not intercepted — it returns false to let the Roku OS handle it. This is a certification requirement:

if key = "options"
    return false
end if

Do not change the options key handler to return true. Intercepting the OPTIONS key fails Roku certification.

Key input summary

Key	Action
`up`	Next channel (index + 1, wraps)
`down`	Previous channel (index − 1, wraps)
`left`	Open channel list overlay
`0`–`9`	Accumulate in number overlay
`OK` (first press)	Show banner, arm settings shortcut
`OK` (second press)	Open settings screen
`back`	Exit player
`options`	Not intercepted — passed to OS

Get Started

Architecture

Core Features

Configuration

Build & Deploy

Reference

Overview

Video node

Channel banner

Number overlay

Watchdog timer

Starting playback

URL normalization

Channel index persistence

Buffer and startup

Overlay system

Channel banner

Number overlay

Error handling and reconnection

Automatic retry

Stream restart

Auto-recoverable errors

Auth/inactive errors from stream

Freeze detection

Network handling

Interaction with ads (viewport reduction)

OPTIONS key handling

Key input summary

​Overview

Video node

Channel banner

Number overlay

Watchdog timer

​Starting playback

​URL normalization

​Channel index persistence

​Buffer and startup

​Overlay system

​Channel banner

​Number overlay

​Error handling and reconnection

​Automatic retry

​Stream restart

​Auto-recoverable errors

​Auth/inactive errors from stream

​Freeze detection

​Network handling

​Interaction with ads (viewport reduction)

​OPTIONS key handling

​Key input summary

Overview

Starting playback

URL normalization

Channel index persistence

Buffer and startup

Overlay system

Channel banner

Number overlay

Error handling and reconnection

Automatic retry

Stream restart

Auto-recoverable errors

Auth/inactive errors from stream

Freeze detection

Network handling

Interaction with ads (viewport reduction)

OPTIONS key handling

Key input summary