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



36 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
  23. Ainda funciona esse tutorial? a forma de pegar os links dos sites continuam do mesmo jeito? ou teve alguma alteração?... Eu até consigo cliar o menu filmes, mas nao estou conseguindo de jeito algum listar os videos do site.

    ResponderEliminar
    Respostas
    1. oi amigo sera que você poderia me passar o arquivo deixe um link ai por favor

      Eliminar
  24. Podem ativar de novo o link de download?Gracias!

    ResponderEliminar
  25. alguem poderia disponibilizar o link do plugin gostaria muito de fazer meu proprio addon

    ResponderEliminar
  26. Olá pessoal, Espero que essa versão ajude, editei como se fosse a original
    http://www.mediafire.com/file/pmi4rqnc1j2shs6/plugin.video.maisfutebol.zip

    Bons estudos!

    ResponderEliminar
    Respostas
    1. Vale lembrar que a página do maisfutebol mencionada no tutorial não tem mais a mesma estrutura!

      Eliminar
  27. Gostaria de criar um Addon com login e senha

    ResponderEliminar
  28. Onde devo upar meus próprios vídeos??
    Quero fazer um addon totalmente "meu".
    Sem pegar link de terceiros, quero garantir que os vídeos estarão sempre on.

    ResponderEliminar
  29. pessoal estou viciado nessa área, to tentando criar meus própios ADDONS até mesmo porque sou designer e aditor, mas sempre amei a área de TI. adoro linguagem de programação. por favor gente quem tiver mas artigos ou tutoriais como o de cima ensinando sobre criação de ADDONS por favor compartilhe, vamos crescer essa área ainda mas no Brasil

    ResponderEliminar