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: 


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:

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 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: 


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



26 comentários:

  1. Parabéns! Artigo bem escrito, sucinto o suficiente para não ser cansativo, exaustivo o suficiente para aprender. Já tinha conhecimento de como fazer estes addons e portanto sinto-me à vontade para dizer que está aqui um excelente trabalho. Espero que este empurrão ajude muita gente a iniciar-se nisto para que apareçam cada vez mais e mais addons para esta ferramenta brutal, o XBMC.

    Parabéns! =)

    ResponderEliminar
  2. Faço as minhas palavras as do André Machado. Já tinha visto uns tutoriais de como iniciar nos addons e de facto este tutorial em português está muito bom! Espero que incentive muita gente tal como eu a iniciar nos addons para daqui a uns tempos termos uma biblioteca enorme de addons portugueses.
    Parabéns pelo artigo!

    ResponderEliminar
  3. Obrigado a todos pelas mensagens.

    As respostas aos desafios apresentados na parte final deste post serão publicadas na 6ª feira às 18:00 (dá tempo para vocês tentarem resolver por vós próprios). Esse post conterá mais dois desafios...que serão respondidos num post de Sábado às 17:00. Esse post terá outro desafio que será respondido num outro post talvez a meio da próxima semana.
    Os dois primeiros posts, pelo menos, estão agendados.

    ResponderEliminar
  4. Este comentário foi removido pelo autor.

    ResponderEliminar
  5. muito bem, deve ser facil. eu n tenho paciencia lool
    mas haja alguem que faca ai um addon para o putfilm.com

    forca vcs conseguem abracos

    ResponderEliminar
  6. Impecável. Vou tentar fazer um com base nos passos que descreves.

    Obrigado por partilhares e claro pela tua paciência.

    Abraço,

    ResponderEliminar
  7. Muito bom, parabéns pelo exelente tutorial!

    ResponderEliminar
  8. O link do addon em branco não funciona.

    ResponderEliminar
  9. O link do addon em branco não funciona :S

    ResponderEliminar
  10. Agora era bom com isto fazer um plug in para o filmesonlinegratis.net mas esse deve ser ainda mais dificil!!!

    ResponderEliminar
  11. Sabe bem ver que ainda há quem goste de ensinar sem receber nada em troca;) Hoje já não durmo :P

    ResponderEliminar
  12. vocês têm a certeza que não há um programa para criar addons automaticamente.
    Tipo arrasta-se para dentro do XBMC e depois é só escrever o nome do site?
    É que para um gajo lerdo como eu, todos ates passos parecem muito complicados e The Winter is Coming....

    ResponderEliminar
  13. Era bom que existisse algo assim.
    Mas que tenha conhecimento não ;)

    ResponderEliminar
  14. Vocês têm a certeza que não há uma forma mais simples de fazer isto?
    Tipo um programa que adicione logo Add Ons ao XBMC?
    É que para gajos lerdos e info-excluídos como eu isto é muita fruta...

    ResponderEliminar
  15. O link http://enen92.aminhacasadigital.com/plugin.video.maisfutebol.zip não está funcionando. Poderia reativá-lo?
    Obrigado

    ResponderEliminar
  16. Este comentário foi removido pelo autor.

    ResponderEliminar
  17. Eu gostaria de criar um addon meu. Podes disponibilizar o ficheiro http://enen92.aminhacasadigital.com/plugin.video.maisfutebol.zip que já não se encontra disponivel? Obrigado. Continuação de bom trabalho

    ResponderEliminar
  18. eu tambem ja ando a uma semana atentar e nada os portugueses ja nao ajudam uns aos outros estou perdido

    ResponderEliminar
  19. eu tambem ja ando a uma semana atentar e nada os portugueses ja nao ajudam uns aos outros estou perdido

    ResponderEliminar
  20. Não sei em que versão ia este zip.
    Mas vê se serve:
    https://dl.dropboxusercontent.com/u/14572670/plugin.video.maisfutebol.zip

    ResponderEliminar
    Respostas
    1. Diz que o addon tem dependências e não deixa instalar!!! :S

      Eliminar
    2. O addon já é antigo, poderá necessitar de adaptação nas versões mais recentes do KODI.

      Eliminar
  21. esta muito bem explicado
    mas so gostava de relembrar que toda a lista premium portuguesa é cobrada
    tal nao acontece em outras linguas onde todo conteudo à fornecido free e ainda bem que assim é
    sei que da trabalho pois eu para conseguir os canais sic radical tv cines foi dificil mas contudo estao a trabalhar e as pessoas que os conceberam ja tiraram de suas listas mas contudo consegui apanhar os mesmos e continuam a trabalhar
    e assim vou continuando a minha pesquisa sobre como obter url ou codigo font dos streamings
    ando la perto
    continuacao de uma boa tarde tugas

    ResponderEliminar
  22. Podiam fazer um video no YouTube a explicar gostava mais, mas nao quer dizer dizer que aqui tá mal explicado, mas eu fiquei um bocado confuso, com video era melhor.

    ResponderEliminar