XBMC – O teu primeiro Addon - 1 - (tutorial)

Ultimamente tem sido cada vez maior o interesse da comunidade em torno do XBMC e dos addons portugueses, interesse este bem patente no aumento do número de visitas ao blog e ao fórum. Os developers de addons para o XBMC nem sempre têm tempo para desenvolver mais trabalho ou para corrigir um determinado erro. Na realidade, este consegue ser um trabalho inglório e frustrante. É feito pela comunidade para a comunidade, nos tempos livres e sem lucro envolvido.

Mas vamos por partes (lá para a frente já perceberão porque é frustrante). Afinal, qual é a função de um XBMC addon comum?

Se olharmos para o exemplo de um addon de vídeo, como a rtp play ou o wt, o addon faz essencialmente três coisas:

1- Abre um determinado site

2- Retira a informação essencial que pretendemos obter (exemplo: titulo de um vídeo, thumbnail de um vídeo e endereço do caminho completo para o vídeo)

3- Entrega a informação ao XBMC para este reproduzir o ficheiro (caminho para o video) pretendido.

Posto isto, este post tem como objectivo construir a passo e passo e de forma exaustiva um addon muito simples para listar e reproduzir os vídeos do site: http://www.maisfutebol.iol.pt/videos

Um addon é uma pasta (chamada plugin.video.NOMEDOADDON) com vários ficheiros no interior.

Os principais são o addon.xml e um script desenvolvido em python (addon.py ou default.py ou qualquer outro nome) que contem o código principal do addon. A pasta resources contém outros ficheiros não fundamentais como as imagens dos menus, as definições do addon, as várias traduções do addon.

Neste link podem fazer o download do addon em branco que servirá de base ao desenvolvimento do addon: 

http://enen92.aminhacasadigital.com/plugin.video.maisfutebol.zip

Conteúdo da pasta:

Não se preocupem com o conteúdo da pasta resources (por agora). Vamos olhar apenas para os dois ficheiros principais (addon.xml e addon.py). A imagem fanart e o icon deverão ser editadas se quiserem fazer outro addon (mantendo o nome de ambos os ficheiros!).

Addon.xml

Este é o ficheiro que é iniciado quando o XBMC abre o addon. Contem informações como o nome do addon, a versão, o autor, a descrição, a versão do python que o xbmc deve emular para executar o addon e apresenta o nome do ficheiro principal do addon (desenvolvido em python). Neste caso, addon.py.

Este é um ficheiro xml de fácil leitura e compreensão. Se lerem o parágrafo anterior, perceberão facilmente cada linha deste ficheiro. Se pretenderem fazer um outro addon, alterem os campos óbvios. Atribuam ao nome do addon, o mesmo nome da pasta!

   
    
     
      
     
     
   video   
     
     
   en   
   all   
   
Mais futebol
   
   O meu primeiro addon   
   all   
     
   

Façam download do zip indicado acima e instalem no xbmc:

System → Settings → addons → install from zip file

Se tudo correr bem, deverão receber a informação de que o addon foi instalado:

Se forem agora a Videos → Addons verificarão que o addon já se encontra na lista e que a informação apresentada é aquela que está escrita no ficheiro xml. O icon e a imagem de fundo são respectivamente os ficheiros icon.png e fanart.jpg. Se entrarem no addon, este não fará nada.

Ficheiro addon.py:

O ficheiro principal do addon que contem o código que o xbmc executa quando "entram" no addon. Poderia ter outro nome (por exemplo: aminhacasadigital.py) desde que indicado no ficheiro xml. Para facilitar, dividi o ficheiro do addon “em branco” em 5 partes:

-Bibliotecas a importar e definicoes: onde devem colocar as bibliotecas de python a importar quando o addon é iniciado. Já tem as bibliotecas fundamentais para fazerem o primeiro addon.

-Menus: onde escreverão os menus

-Funcoes: onde escreverão as funcoes necessárias a executar em cada menu

-Funcoes já feitas: funções que já se encontram construídas e que facilitam o vosso trabalho. Deverão, quando construírem as vossas funções chamar estas funções já construídas. Incluem funções como abrir endereços url, adicionar links ou adicionar directorias ao XBMC.

-Modos: variáveis inteiras que permitem ao xbmc saber “onde estamos”.

Será portanto, neste ficheiro que irão trabalhar!

Após instalado o zip, a respectiva pasta será importada para o xbmc. Assim, iremos editar o ficheiro addon.py importado pelo xbmc e não aquele que se encontra no zip. Este ficheiro (após instalação do "addon em branco") localiza-se em:

Windows: 

C:\Users\Username\AppData\Roaming\XBMC\addons\plugin.video.maisfutebol

MAC OS:

/Users/Username/Library/ApplicationSupport/XBMC/addons/plugin.video.maisfutebol

Linux:

/home/user/.xbmc/addons/plugin.video.maisfutebol

Começar a trabalhar!

Abram o ficheiro addon.py no caminho indicado anteriormente. Em Windows podem usar o bloco de notas ou o Notepad++, em Linux o Gedit e em Mac aconselho o TextMate.

Modo None

Quando o addon é iniciado, o addon.xml indica ao XBMC o nome do ficheiro principal (addon.py) e o XBMC executa esse ficheiro. O XBMC procura em primeiro lugar nos modos. O modo inicial é None (variável sem dados associados). Se procurarmos na "secção modos" (no fim do ficheiro addon.py em branco) veremos:

   
if mode==None or url==None or len(url)<1:
   print ""
   CATEGORIES()

Isto significa que quando o addon.py é iniciado, o mode é None e o XBMC vai correr a função que lá está identificada - neste caso, CATEGORIES(). Esta função é uma função que não recebe qualquer argumento, daí os ().
No topo do ficheiro addon.py, temos a função CATEGORIES(), na "secção MENUS":

  
def CATEGORIES():
        print "primeiro addon"

Esta função, neste momento não está a fazer nada. Está apenas a “imprimir” texto que não aparece no XBMC (unicamente nos ficheiros de log).

Queremos que quando o addon seja iniciado, apareça no menu principal do addon (função CATEGORIES() ) um sub-menu chamado “VIDEOS”. Esta função deverá “entregar” ao XBMC um determinado URL onde se irá procurar os vídeos, o MODO que o XBMC deverá executar quando o utilizador entrar nesse sub-menu e (opcional) deverá ter um ICON (para ficar bonito e tal..).
Podemos fazê-lo facilmente utilizando a função que já está construída (funções já feitas), denominada addDir. Esta recebe 4 argumentos (name,url,mode,thumbnail).

Neste caso queremos:

Name = "Videos" --> nome a apresentar no menu
Url = "http://www.maisfutebol.iol.pt/videos" --> url onde será feita a procura de vídeos
Mode = 1 --> modo seguinte
Thumbnail = "http://digitalsherpa.com/wp-content/uploads/2013/04/social-media-marketing-tool.png" (uma imagem retirada da internet)

A função CATEGORIES() ficará então:

  
def CATEGORIES():
    addDir('VIDEOS','http://www.maisfutebol.iol.pt/videos',1,'http://digitalsherpa.com/wp-content/uploads/2013/04/social-media-marketing-tool.png')

Nota: O entalhe (indentation) é importante em python. Se reparerem a linha addDir difere horizontalmente da posição da linha inicial (def...).

Guardando o ficheiro e iniciando o addon no XBMC verificamos que já temos um menú...mas que ainda não faz nada.

O próximo passo será definir o modo 1!

MODO 1 - Criar a função listar_videos(url)

Olhando para o fim do script addon.py (em branco) temos:

  
elif mode==1:
      print ""

Ou seja, mais uma vez não temos nada definido. Quando o XBMC chega ao modo 1 limita-se a "imprimir"...nada. É nosso objectivo que, sempre que o XBMC esteja no modo 1 execute uma determinada função que use/leia como argumento o endereço que definimos há pouco aquando da criação do menu. Desta forma, vamos especificar que, quando no modo 1, o XBMC chame uma função chamada listar_videos(url).

  
elif mode==1:
      print ""
      listar_videos(url)

Não temos esta função definida no código, teremos de a criar.

Na parte que reservei para as funções a construir escrevam:

  
def listar_videos(url):

Esta é a forma correcta de definir uma função em python:

def (de definir) nome_da_função(argumentos):

Queremos que esta função abra o endereço url em causa e armazene o código-fonte da página. Podemos fazê-lo recorrendo à função abrir_url(url) que já está construída e se encontra na secção que reservei para as funções já feitas. Chamamos a função da seguinte forma:

codigo_fonte = abrir_url(url)

A função fica então:

def listar_videos(url):
     codigo_fonte = abrir_url(url)

Recapitulando. Quando clicámos no menu "VIDEOS", o XBMC passou para o modo 1 com a variável url que indicámos na criação do menu. Chegado ao modo 1, o XBMC chama a função listar_videos com a variavel url como argumento, que por sua vez chama a função abrir_url que usa essa variavel url tambem como argumento e armazena o codigo fonte da página na variavel codigo_fonte. Perceberam? Torna-se mais difícil explicar do que entender o funcionamento olhando para o código... :)

E o que é este codigo_fonte?

Se abrirem a página http://www.maisfutebol.iol.pt/videos no vosso browser e forem a ferramentas -> ver código fonte; esse será o "texto" que ficará guardado na variável codigo_fonte.

O próximo passo na construção da função é retirar desta variável codigo_fonte apenas a informação que pretendemos (o título dos vídeos, o endereço onde encontrar esses vídeos e os icons de cada vídeo (opcional).

Na pagina web, atentem no nome d primeiro vídeo. À data que escrevo este post, o primeiro vídeo listado chama-se "Guardiola em Munique....blablabla".

Procuremos essas palavras no código fonte apresentado no browser:

Facilmente chegamos à conclusão que o "estilo de código" presente no código fonte da página é idêntico para qualquer um dos vídeos, alterando-se apenas o nome, endereço e imagem (óptimo...trabalho facilitado). Temos ali toda a informação que queremos obter! O endereço da página onde está o vídeo (em href), a imagem (em img src) e o título (entre ><).

Ora reparem no trecho do código fonte do primeiro vídeo:

<li><a class="" href="/videos/video/13901725/1"><span class="player"></span><img src="http://www.maisfutebol.iol.pt/multimedia/oratvi/multimedia/imagem/id/13901385/180x135"

alt="Guardiola em Munique: «Uma honra imensa»" />Guardiola em Munique: «Uma honra imensa»<br /><em>2013-06-24</em></a></li>

Deste trecho do código fonte queremos fazer isto...

<li><a class="" href="(QUERO GUARDAR)"><span class="player"></span><img src="(QUERO GUARDAR)"

alt="(NÃO ME INTERESSA)" />(QUERO GUARDAR)<br /><em>(NAO ME INTERESSA)</em></a></li>

Para o fazer (em Python), recorremos à biblioteca re (importada logo no inicio do addon - import re – vejam as primeiras linhas do ficheiro). RE significa regular expressions.

É tão simples como substituir o (QUERO GUARDAR) por (.+?) e o NAO ME INTERESSA por apenas .+?

Desta forma, neste caso a regular expression é (atentar no paragrafo \n !):

<li><a class="" href="(.+?)"><span class="player"></span><img src="(.+?)"\n

alt=".+?" />(.+?)<br /><em>.+?</em></a></li>

Adicionemos então a seguinte linha à função:

match = re.compile('<li><a class="" href="(.+?)"><span class="player"></span><img src="(.+?)"\n alt=".+?" />(.+?)<br /><em>.+?</em></a></li>').findall(codigo_fonte)

A variável match será uma matriz da seguinte forma:

[(1º valor 1º entrada, 2 º valor 1º entrada, 3º valor 1º entrada),(1º valor 2º entrada, 2º valor 2º entrada, 3º valor, 2º entrada) ….........] , em que cada linha corresponde aos 3 valores (url,thumbnail e titulo) retirados de cada entrada idêntica ao trecho de código-fonte que analisámos...

Pretendemos seguidamente que exista um ciclo, um comando que seja chamado cada vez que for encontrada uma entrada deste género no código_fonte. Algo assim: 

Para entrada 1 (podemos-lhe chamar url), entrada 2 (pudemos-lhe chamar img), entrada 3 (podemos chamar-lhe titulo) na variavel match → adicionar um novo sub-menu que envie o xmbc para o modo seguinte (modo 2) com um novo URL (o url da página onde está o vídeo). Em Python, é quase traduzido à letra:

for url,img,titulo in match:
    addDir(titulo,'http://www.maisfutebol.iol.pt' + url,2,img)

Notar que o valor que fica na variável url é da forma /videos/video/13901725/1 quando o url correcto que o XBMC deverá abrir é http://www.maisfutebol.iol.pt/videos/video/13901725/1. Como tal, temos de adicionar a parte inicial manualmente!

A função listar_videos(url) já está completa. Fica definida da seguinte forma:

def listar_videos(url):
    codigo_fonte = abrir_url(url)
    match=re.compile('<li><a class="" href="(.+?)"><span class="player"></span><img src="(.+?)"\n alt=".+?" />(.+?)<br /><em>.+?</em></a></li>').findall(codigo_fonte)
    for url, img, titulo in match:
         addDir(titulo,'http://www.maisfutebol.iol.pt'+url,2,img)

Se salvarmos o ficheiro e entrarmos de novo no sub-menu 'VIDEOS', veremos que as entradas já se encontram listadas!

MODO 2 - Encontrar o endereço do vídeo e “entregar” ao XBMC:

Encontrar o endereço completo do caminho do ficheiro de vídeo nem sempre é fácil. Em primeiro lugar convém procurar no código fonte da página onde se encontra o vídeo por “.flv” ou “.mp4” que são as extensões de ficheiros de vídeo mais comuns ou por “rtmp” que é um dos protocolos de streaming mais usados.

Abram o url onde está o 1º vídeo (http://maisfutebol.iol.pt/videos/video/13901725/1) no browser e procurem por essas palavras: mp4, flv, rtmp, m3u8....

Neste caso, o stream de vídeo é rtmp, o que dificulta um pouco a tarefa...

No código fonte da página encontramos o seguinte:

content="https://www.iol.pt/flashplayers/jwplayer_5_9.swf?file=mp4%3A13901725-L-500k&amp;streamer=rtmp%3A%2F%2Fvideo1.iol.pt%2Fvod&amp;config=https%3A%2F%2Fwww.iol.pt%2Fconfig_fb.xml%3Fsite%3Dmaisfutebol%26scheme%3Dhttps" /><meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7" />

Apesar de grande parte da informação poder estar neste pedaço do código-fonte, raramente é tão linear. Aconselho-vos a usar as seguintes ferramentas para determinar este tipo de endereços: urlhelper (http://www.urlhelper.com/), streamtransport (http://www.streamtransport.com/), rtmpdump(http://rtmpdump.mplayerhq.hu/) ou wireshark (http://www.wireshark.org/).

O url final obtido no programa urlhelper é o seguinte:

rtmp://video1.iol.pt:80/vod/mp4:13901725-L-500k

Não era assim tão linear....

Ninguém garante que este endereço seja sempre idêntico. Basta o webmaster alterar o servidor (video1.iol.pt) ou a porta (80) e o addon deixará de funcionar. Imaginem que isso acontece todas as semanas. Já perceberam o primeiro parágrafo do tutorial? 

Aproveitemos no entanto a informação disponível no trecho anterior para construir o endereço final do vídeo. Tal e qual como fizemos há pouco:

match = re.compile('file=(.+?)&amp;streamer=(.+?)amp;config.+?\n.+?<meta http-equiv="X-UA-Compatible"').findall(codigo_fonte)

É importante substituir o “%3A” por “:” e o “%2F” por “/” para o endereço ficar correcto. Caso contrário teríamos:

mp4%3A13901725-L-500k e rtmp%3A%2F%2Fvideo1.iol.pt%2Fvod

Quando aquilo que desejamos é

mp4:13901725-L-500k e rtmp://video1.iol.pt/vod

A substituição é conseguida em Python fazendo: VARIAVEL.replace(“expressao antiga”,”expresao nova”).

A única “função já construída” do "addon em branco" que ainda não referi é a addLink. Serve para adicionar uma entrada ao menu do XBMC que corresponde a um ficheiro multimédia, tal que, quando a executamos, o XBMC começa a reproduzir o ficheiro. Podemos pensar na função addDir como a criação de uma “nova pasta” e a addLink como a criação de um “novo ficheiro” (multimédia).

Para adicionar um ficheiro multimédia (link) ao XBMC usamos a função: addLink(nome,url,iconImage).

Bem, chega de paleio, vamos construir a função.....

Comecemos por definir nos Modos, o modo 2 que chamará a função que desejarmos. Chamei-lhe encontrar_fontes(url).

elif mode==2:
      print ""
      encontrar_fontes(url)

...e definimos esta função de acordo com a informação apresentada acima e outra cujo funcionamento já foi devidamente explicado neste tutorial.

def encontrar_fontes(url):
    codigo_fonte = abrir_url(url)
    match = re.compile('file=(.+?)&amp;streamer=(.+?)amp;config.+?\n.+?<meta http-equiv="X-UA-Compatible"').findall(codigo_fonte)
    for ficheiro, streamer in match:
        ficheiro = ficheiro.replace('%3A',':')
        streamer = streamer.replace('%3A',':')
        streamer = streamer.replace('%2F','/')
 #NOTA: nesta altura a variavel streamer é rtmp://video1.iol.pt/vod&
        match = re.compile('rtmp://(.+?)/(.+?)&').findall(streamer)
        for rtmp,app in match:
            addLink('Assistir Vídeo','rtmp://' + rtmp + ':80/' + app + '/' + ficheiro,'')

Se tudo correr bem...

Podes fazer o download do addon.py final aqui: 

http://enen92.aminhacasadigital.com/addon.py

Trabalho para casa :) :

- Adiciona a data ao menu dos vídeos

- Adiciona um sub-menu (addDir) de “Página seguinte” na listagem de vídeos

- Escapa o passo intermédio de “encontrar fontes” fazendo a “ponte” entre o modo 1 e o “addLink”.

- Tenta fazer o mesmo com outro site da tua preferência

Dúvidas ou questões coloquem de preferência no tópico dedicado a este post no fórum do blog: http://forum.aminhacasadigital.com/viewtopic.php?f=9&t=230

Espero ver o addon do Maisfutebol concluído por um de vocês brevemente :)

Até breve,

Miguel Borges de Freitas