BrightScript na prática: como funciona a linguagem da Roku

BrightScript é a lin­guagem usa­da para cri­ar canais/apps na platafor­ma Roku (espe­cial­mente nos mod­e­los “lega­dos” e em várias bases de códi­go que ain­da rodam por aí). Ela foi desen­ha­da com um obje­ti­vo bem claro: ser sim­ples de apren­der, estáv­el em dis­pos­i­tivos de TV e efi­ciente para inter­faces e play­back de vídeo. Na práti­ca, BrightScript é menos “lin­guagem acadêmi­ca” e mais “lin­guagem de pro­dução”: você escreve lóg­i­ca de app, con­ver­sa com com­po­nentes (telas, nós, play­er), tra­ta even­tos do con­t­role remo­to e inte­gra APIs/ads.

A seguir, vou te mostrar como BrightScript fun­ciona de ver­dade, do pon­to de vista de quem pre­cisa con­stru­ir um app Roku com qual­i­dade.

---

Gráfico: o fluxo real de um app Roku (dados → UI → player → ads)

Esse é o “cam­in­ho do sinal” den­tro de um app típi­co (VOD ou FAST), do jeito que acon­tece na práti­ca:

        ┌───────────────┐
        │    Main.brs    │
        │ inicia o app   │
        └───────┬───────┘
                │ cria
                ▼
        ┌───────────────┐
        │  HomeScene     │
        │ UI + eventos   │
        └───────┬───────┘
                │ chama
                ▼
        ┌───────────────┐
        │  ApiService    │
        │ request + JSON │
        └───────┬───────┘
                │ retorna itens
                ▼
        ┌───────────────┐
        │ MarkupGrid     │
        │ lista catálogo │
        └───────┬───────┘
                │ usuário seleciona
                ▼
        ┌───────────────┐
        │  PlayerScene   │
        │ Video + estados│
        └───────┬───────┘
                │ (opcional)
                ▼
        ┌───────────────┐
        │ RAF / Ads      │
        │ pre/mid-roll   │
        └───────────────┘

Por que isso é impor­tante?
Porque BrightScript fun­ciona mel­hor quan­do você pen­sa em com­po­nentes + even­tos + esta­dos (não em “telas soltas”).

---

Snippet completo (prático): API → Grid → clique → Player

A ideia aqui é te mostrar um recorte real­ista que aparece em quase todo app Roku:

1) source/main.brs (inicia o app e mostra a cena)

sub Main()
    screen = CreateObject("roSGScreen")
    port = CreateObject("roMessagePort")
    screen.SetMessagePort(port)

    scene = screen.CreateScene("HomeScene")
    screen.Show()

    while true
        msg = wait(0, port)
    end while
end sub

2) components/scenes/HomeScene.brs (carrega catálogo e reage ao clique)

sub init()
    m.grid = m.top.findNode("contentGrid")
    m.grid.observeField("itemSelected", "onItemSelected")
    loadCatalog()
end sub

sub loadCatalog()
    items = ApiService_GetCatalog()

    if items = invalid or items.count() = 0 then
        print "Catálogo vazio ou falha de rede"
        return
    end if

    m.grid.content = BuildGridContent(items)
end sub

sub onItemSelected()
    idx = m.grid.itemSelected
    itemNode = m.grid.content.getChild(idx)

    ' Navega para player com o item escolhido
    m.top.signalBeacon("start") ' opcional para métricas
    m.top.getScene().callFunc("showPlayer", itemNode)
end sub

3) components/services/ApiService.brs (request e JSON defensivo)

function ApiService_GetCatalog() as Object
    url = "https://seusite.com/api/catalog"

    xfer = CreateObject("roUrlTransfer")
    xfer.SetUrl(url)

    rsp = xfer.GetToString()
    if rsp = invalid or rsp = "" then return invalid

    json = ParseJson(rsp)
    if json = invalid or json.items = invalid then return invalid

    return json.items ' normalmente array de itens
end function

4) components/utils/BuildContent.brs (converte JSON em ContentNode)

function BuildGridContent(items as Object) as Object
    root = CreateObject("roSGNode", "ContentNode")

    for each it in items
        node = root.createChild("ContentNode")
        node.title = it.title
        node.hdPosterUrl = it.poster
        node.url = it.streamUrl ' guardamos a URL para o player
    end for

    return root
end function

5) components/scenes/PlayerScene.brs (player, estados, e tratamento de erro)

sub init()
    m.video = m.top.findNode("video")
    m.video.observeField("state", "onVideoState")
end sub

sub playItem(item as Object)
    content = CreateObject("roSGNode", "ContentNode")
    content.url = item.url
    content.streamFormat = "hls" ' exemplo

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

sub onVideoState()
    st = m.video.state
    print "Player state: "; st

    if st = "error" then
        print "Erro no playback. Exibir fallback e permitir retry."
        ' aqui você poderia mostrar um label de erro na UI
    end if
end sub

✅ Esse con­jun­to já demon­stra o coração do BrightScript:

• Scene ini­cial­iza UI e obser­va even­tos
• Ser­vice faz rede e retor­na dados
• Utils con­verte JSON em Con­tentN­ode
• Play­er obser­va esta­dos e tra­ta fal­has

---

1) O “jeito Roku” de pensar: componentes + eventos

O pon­to cen­tral para enten­der BrightScript é: você não pro­gra­ma “ape­nas funções”; você pro­gra­ma um app ori­en­ta­do a com­po­nentes e even­tos.

Em Roku, quase tudo gira em torno de:

• Com­po­nentes de UI (Scene­Graph, nós, telas)
• Even­tos (teclas do con­t­role, mudanças de esta­do, retorno de rede, timers)
• Ciclo de vida do app (ini­cial­iza, cria cena, roda loop, reage)

Ou seja: BrightScript é a cama­da de lóg­i­ca que conec­ta UI, play­er, rede e anún­cios.

---

2) BrightScript é simples, mas “cheio de detalhes que importam”

Tipagem e val­ores

BrightScript é dinami­ca­mente tipa­da. Os tipos mais comuns:

• String
• Inte­ger / Float
• Boolean
• Object (map/dicionário)
• Array
• Invalid

Na práti­ca, apren­der a tratar invalid é o que sep­a­ra um app estáv­el de um app que que­bra em pro­dução (prin­ci­pal­mente em rede e play­back).

---

3) Estruturas básicas: if/for, funções e escopo

BrightScript tem sin­taxe bem dire­ta:

• if / else
• for each
• while
• func­tion / sub

Func­tion vs Sub

• function retor­na val­or
• sub não retor­na

Isso aju­da a man­ter o códi­go limpo: funções pro­duzem dados, subs exe­cu­tam ações.

---

4) Objetos e Arrays: o coração do app

Asso­cia­tive Array (AA) e Arrays são usa­dos o tem­po todo.

Em stream­ing: JSON → AA/Array → UI → clique → play­back.

O snip­pet aci­ma já mostra esse pipeline de pon­ta a pon­ta.

---

5) Eventos e o controle remoto

A lóg­i­ca é sem­pre: um even­to acon­tece, você não “man­da” na UI, você reage ao que a UI sinal­iza — por isso observeField é tão impor­tante.

---

6) SceneGraph: onde BrightScript vira app moderno

XML = estru­tu­ra visu­al
BrightScript = com­por­ta­men­to, esta­do, nave­g­ação, even­tos

---

7) Rede e APIs: o mundo real

TV tem Wi-Fi ruim, CDN var­ian­do e DNS lento. Por isso:

• time­outs sen­satos
• retries con­tro­la­dos
• fall­back visu­al
• logs úteis
• trata­men­to de invalid

---

8) Playback: estados e edge cases

Se toca vídeo, você pre­cisa obser­var state e tratar:

• buffer­ing
• play­ing
• fin­ished
• error

---

9) Performance e estabilidade

Evite:

• loops pesa­dos no thread de UI
• JSON gigante sem cuida­do
• cri­ar nós demais
• igno­rar invalid

---

10) Como pensar como dev Roku

Foque em 4 pilares:

• Dados → UI
• Even­tos → Nave­g­ação
• Play­er + Ads
• Resil­iên­cia (invalid/timeouts/retry/fallback/log)