# Características Avançadas do Amarok

## Atalhos do Teclado

O &amarok; usa os atalhos do teclado, como a maioria das outras aplicações; em baixo, encontra-se uma listagem desses atalhos e das suas acções respectivas. Os atalhos globais podem ser configurados se carregar com o &RMB; na janela do Leitor e se seleccionar a opção Configurar os Atalhos Globais.... Os atalhos do &amarok; podem ser configurados se carregar com o &RMB; na janela do Leitor e seleccionar a opção Configurar os Atalhos...

Você poderá atribuir teclas multimédia para funcionarem como atalhos do &amarok;, tornando o seu teclado um centro de controlo do &amarok;.

Os atalhos globais são:

Combinação de Teclas | Acção
Win X | Reproduzir
Win C | Pausa
Win V | Parar
Win B | Próxima Faixa
Win Z | Faixa Anterior
Win KP_Add | Aumentar o Volume
Win KP_Subtract | Diminuir o Volume
Win Shift KP_Add | Avançar
Win Shift KP_Subtract | Recuar
Win A | Adicionar Média
Win P | Comutar a Lista
Win O | Mostrar o OSD
Win M | Volume Silenciado

Os atalhos do &amarok; são:

Combinação de Teclas | Acção
Ctrl C | Copiar
Ctrl KP_Enter | Ir para a Actual
Ctrl D | Colocar na Fila as Faixas Seleccionadas
Ctrl Q | Sair
Ctrl Shift Z | Refazer
Ctrl S | Gravar a Lista de Reprodução
Ctrl A | Seleccionar Tudo
Ctrl M | Mostrar o Menu
Ctrl H | Baralhar
Ctrl Z | Desfazer

Os atalhos do Navegador na Lista de Reprodução são:

Combinação de Teclas | Acção
Espaço | Carregar Listas
F2 | Mudar o Nome da Lista
Backspace | Remover a Lista

## A Interface DCOP

A interface de DCOP do Amarok oferece-lhe uma forma simples de controlar o Amarok com os seus próprios programas personalizados.

A interface de DCOP do Amarok tem várias funções genéricas que poderão ser encontradas noutras aplicações do KDE. Esta secção está dividida em seis tabelas e pretende descrever as funções do DCOP para a colecção, o navegador de contexto, o leitor, a lista, o navegador da lista para os programas. Um exemplo da função de DCOP pause seria semelhante ao seguinte:

`%`dcop amarok player pause

### dcop amarok collection

Chamada DCOP | Acção
int totalAlbums() | Devolve o número total de álbuns na sua colecção.
int totalArtists() | Devolve o número total de artistas na sua colecção.
int totalCompilations() | Devolve o número total de compilações na sua colecção.
int totalGenres() | Devolve o número total de géneros musicais na sua colecção.
int totalTracks() | Devolve o número total de faixas na sua colecção.
QString query( QString sql) | Executa uma pesquisa de SQL na base de dados.
QStringList similarArtists( int artistas ) | Devolve os artistas semelhantes às faixas actuais, limitando a quantidade a 'artistas'.
void migrateFile( QString urlAntigo, QString urlNovo ) | Move um ficheiro na colecção, mantendo as estatísticas intactas.
void scanCollection() | Pesquisa a colecção.
void scanCollectionChanges() | Pesquisa a colecção apenas à procura de alterações.

### dcop amarok contextbrowser

Chamada DCOP | Acção
void showCurrentTrack() | Mostra a faixa actual no navegador de contexto.
void showLyrics() | Mostra a página das letras no navegador de contexto.
void showWiki() | Mostra a página do Wikipedia no navegador de contexto.

### dcop amarok player

Chamada DCOP | Acção
bool dynamicModeStatus() | Devolve o estado do modo dinâmico.
bool equalizerEnabled() | Devolve o estado do equalizador.
bool isPlaying() | Devolve 'true' se algo estiver a tocar de momento.
bool randomModeStatus() | Devolve o estado do modo aleatório.
bool repeatPlaylistStatus() | Devolve o estado de repetição da lista.
bool repeatTrackStatus() | Devolve o estado de repetição da faixa.
int getVolume() | Devolve o volume num intervalo de 0-100%.
int sampleRate() | Devolve a taxa de amostragem da faixa actualmente em reprodução.
int score() | Devolve a pontuação da faixa actual.
int status() | Devolve o estado de reprodução: 0 - parado, 1 - pausa, 2 - em reprodução.
int trackCurrentTime() | Devolve a posição de reprodução actual em segundos.
int trackPlayCounter() | Devolve o contador de reprodução da música actual.
int trackTotalTime() | Devolve o tamanho da faixa em segundos.
QString album() | Devolve o álbum da música que está a tocar de momento.
QString artist() | Devolve o artista da faixa actual.
QString bitrate() | Devolve a taxa de amostragem em bits da faixa actual (XX kbps).
QString comment() | Devolve o comentário da música a tocar de momento.
QString coverImage() | Devolve o URL codificado da imagem de capa da faixa actual.
QString currentTime() | Devolve a posição ([h:]mm:ss) da música a tocar de momento.
QString encodedURL() | Devolve o URL codificado da faixa actual.
QString engine() | Devolve o motor de áudio actual.
QString genre() | Devolve o género da música a tocar de momento.
QString lyrics() | Devolve as letras da faixa actual.
QString lyricsByPath( QString local ) | Devolve as letra de uma faixa pela sua localização.
QString nowPlaying() | O título da faixa actualmente em reprodução.
QString path() | Devolve o local não-codificado da faixa actual.
QString setContextStyle( QString ) | Define o estilo de CSS para o navegador de contexto.
QString title() | Devolve o título da faixa actual.
QString totalTime() | Devolve o tamanho total da música a tocar de momento (no formato [h:]mm:ss).
QString track() | Devolve o número da faixa.
QString type() | Devolve o tipo de ficheiro.
QString year() | Devolve o ano da música a tocar de momento.
void configEqualizer() | Activa ou desactiva a janela de configuração do equalizador.
void enableDynamicMode(bool activar) | Activa ou desactiva o Modo Dinâmico.
void enableOSD(bool activar) | Activa ou desactiva a visualização OSD.
void enableRandomMode(bool activar) | Activa ou desactiva o Modo Aleatório.
void enableRepeatPlaylist(bool activar) | Activa ou desactiva a Repetição da Lista.
void enableRepeatTrack(bool activar) | Activa ou desactiva a Repetição da Faixa.
void mediaDeviceMount() | Muda o comando usado para montar o dispositivo multimédia.
void mediaDeviceUmount() | Muda o comando usado para desmontar o dispositivo multimédia.
void mute() | Coloca o som em silêncio ou activo de novo.
void next() | Equivalente a carregar no botão "Próximo".
void pause() | Equivalente a carregar no botão "Pausa".
void play() | Equivalente a carregar no botão "Tocar".
void playPause() | Alterna entre o estado de reprodução/pausa (bom para teclados multimédia)
void prev() | Equivalente a carregar no botão "Anterior".
void queueForTransfer( KURL url ) | Coloca o URL para ser transferido para o Dispositivo Multimédia.
void seek(int s) | Coloca a faixa na posição absoluta indicada em segundos.
void seekRelative(int s) | Coloca a faixa na posição relativa à actual em segundos.
void setEqualizer(int, int, int, int, int, int, int, int, int, int, int) | Configura as bandas do equalizador
void setEqualizerEnabled( bool activo ) | Comuta o equalizador.
void setEqualizerPreset( QString nome ) | Configura as predefinições do equalizador
void setLyricsByPath( QString url, QString letras ) | Atribui as letras de uma faixa pelo seu local.
void setScore( int pontos ) | Configura a pontuação da faixa actual.
void setScoreByPath( QString url, int pontos ) | Configura a pontuação de uma faixa pelo seu local.
void setVolume(int volume) | Configura o volume num intervalo de 0-100%.
void showBrowser( QString navegador ) | Mostra os navegadores na janela da lista de reprodução
void showOSD() | Mostra a visualização OSD no ecrã.
void stop() | Equivalente a carregar no botão "Parar".
void transferDeviceFiles() | Transfere os ficheiros para o dispositivo multimédia.
void volumeDown() | Diminui o volume de forma razoável.
void volumeUp() | Aumenta o volume de forma razoável.

### dcop amarok playlist

Chamada DCOP | Acção
int getActiveIndex() | Devolve o índice da faixa actual ou -1 se não existir.
int getTotalTrackCount() | Devolve o número de faixas na lista de reprodução. 0 se forem nenhumas.
QString saveCurrentPlaylist() | Grava a lista actual em 'current.xml' e devolve o seu local.
void addMedia( KURL ) | Adiciona conteúdos multimédia com base no seu URL.
void addMediaList( KURL::List ) | Adicionas alguns conteúdos multimédia com base nos seus URLs.
void clearPlaylist() | Limpa a lista de reprodução.
void playByIndex(int) | Começa a tocar a faixa correspondente ao índice indicado.
void playMedia( KURL ) | Adiciona conteúdos multimédia com base no seu URL.
void popupMessage( QString) | Mostra uma mensagem temporária.
void removeCurrentTrack() | Remove o item da faixa actual da lista de reprodução.
void repopulate() | Volta a preencher a lista de reprodução com faixas aleatórias.
void saveM3u( QString local, bool locaisRelativos) | Grava a lista de reprodução actual como M3U.
void setStopAfterCurrent( bool ) | Activa/desactiva a funcionalidade "Parar Após a Faixa Actual".
void shortStatusMessage( QString) | Mostra uma mensagem temporária na barra de estado.
void shufflePlaylist() | Baralha a lista de reprodução.
void togglePlaylist() | Activa ou desactiva a janela da lista de reprodução.

### dcop amarok playlistbrowser

Chamada DCOP | Acção
void addPodcast( QString ) | Adiciona um item de Podcast ao navegador de contexto.
void scanPodcasts() | Procura todas as actualizações de Podcast's.
void addPlaylist( QString ) | Adiciona uma lista de reprodução ao navegador da lista.

### dcop amarok script

Chamada DCOP | Acção
bool runScript( QString nome ) | Inicia o programa com o nome indicado. Devolve 'true' em caso de sucesso.
bool stopScript( QString nome ) | Pára o programa com o nome indicado. Devolve 'true' em caso de sucesso.
QStringList listRunningScripts() | Devolve uma lista com todos os programas actualmente em execução.
void addCustomMenuItem(QString submenu, QString tituloItem ) | Activa e atribui um título ao item de menu personalizado.
void removeCustomMenuItem(QString submenu, QString tituloItem ) | Remove o item de menu personalizado.
QString readConfig( QString chave ) | Devolve um valor de item do AmarokConfig com base na chave indicada.

## Opções da Linha de Comandos

O Amarok suporta a utilização das opções normais da linha de comandos para o Qt e o &kde;. O Amarok tem também as suas opções específicas da aplicação.

As opções do Qt e do kde:

Opção | Acção
--help | Mostra a ajuda acerca das opções.
--help-qt | Mostra as opções específicas do Qt.
--help-kde | Mostra opções específicas do KDE.
--help-all | Mostra todas as opções.
--author | Mostra informações sobre o autor.
-v, --version | Mostra a versão.
--license | Mostra informações acerca da licença.

As opções do Amarok:

As opções do &amarok; foram concebidas para ser utilizadas enquanto o &amarok; está a correr.

Opção | Acção
-r, --previous | Passa à faixa anterior na lista de reprodução.
-p, --play | Para de tocar a lista de músicas actual.
-s, --stop | Para a reprodução.
--pause | Pausa a reprodução.
-f, --next | Passa para a próxima faixa na lista de reprodução.
-a, --append | Adicionar ficheiros/URLs à lista de reprodução.
-e, --enqueue | Veja 'append', disponível por razões de compatibilidade.
--queue | Coloca ficheiros/URLs na lista a seguir à faixa actual.
-m, --toggle-playlist-window | Activa ou desactiva a janela da lista de músicas.
--wizard | Lança o assistente da Primeira Execução.
--engine "nome" | Inicia o &amarok; como o motor "name".

## Criação de 'Scripts'

A programação permite-lhe extender o &amarok; facilmente sem ter de alterar o código principal. Os programas ou 'scripts' são semelhantes a 'plugins', mas em vez de terem uma API de 'plugins' dedicada, eles usam apenas a interface de DCOP do &amarok; para a comunicação. Isto torna possível criar 'scripts' em qualquer linguagem de programa, como o Ruby, o Python ou o PHP. Não só poderá criar programas nas linguagens de 'scripting' clássicas, como também em linguagens compiladas, como em C++ ou em C simples. Para além disso, o &amarok; poderá notificar os 'scripts' para certos eventos e fazer com que estes reajam de acordo com essa situação. Este sistema de notificação será explicado mais tarde nesta secção.

### Interfaces

É possível criar programas simples que não necessitem de interacção com o utilizador, assim como também possível criar programas com GUIs confortáveis que se comportem como pequenas aplicações independentes. Para a programação da GUI, poderá ser usada uma das várias interfaces que o KDE oferece, como por exemplo o RubyQt, uma interface para a biblioteca do Qt em ruby. Contudo, deve ser claro que nem todos os utilizadores têm as interfaces disponíveis instaladas. Se optar por usar uma interface, tente usar uma das que seja mais usada (p.ex., o RubyQt ou o PyQt).

Para mostrar alguma reacção, quando algum programa se recusa a correr devido a uma dependência em falta, verifique por favor o seu programa para saber se o módulo que deseja incluir existe de facto. Se faltar essa dependência, deverá capturar o erro e mostrar uma janela de informação, usando a ferramenta da linha de comandos "kdialog", para que o utilizador aprenda porque é que o programa não funciona.

Este exemplo mostra como capturar uma dependência em falta no Ruby:

    begin
           require 'Korundum'
    rescue LoadError
           error = 'É necessário o Korundum (interface para o KDE em Ruby) do kdebindings v3.4 neste programa.'
           `kdialog --sorry '#{error}'`
           exit
    end

### Introdução: Os Modelos

O &amarok; oferece modelos de programas em várias linguagens na pasta `scripts/templates/`. Poderá usar estes programas como base para os seus próprios 'scripts', assim como extendê-los com a funcionalidade que necessita. Irá reparar que a programação é, de facto, bastante intuitiva; por exemplo, se souber programar mais ou menos em Python, a criação do seu programa não irá levar muito tempo.

### Controlar o &amarok; com o DCOP

Os programas poderão controlar o Amarok, invocando algumas das suas funções de DCOP. A forma mais simples de invocar uma função do DCOP é usando o utilitário da linha de comandos "dcop", que faz parte de qualquer distribuição do KDE.

Aqui está um exemplo para aumentar o volume-mestre:

    dcop amarok player volumeUp

A maioria as linguagens de programação permitem executar programas externos, com uma função do tipo exec(). Desta forma, o utilitário "dcop" poderá ser invocado facilmente. Aqui está um exemplo simples em Python:

    import os
     os.system("dcop amarok player volumeDown")

### Notificações

O &amarok; envia notificações para todos os programas em execução, escrevendo mensagens para o seu canal de 'stdin'. O programa deverá, deste modo, vigiar constantemente o 'stdin', de modo a reagir de acordo com cada um dos eventos possíveis. Os programas também poderão optar por ignorar qualquer evento que não necessitem.

Serão enviadas as seguintes notificações pelo &amarok;:

    configure
    Diz ao programa para mostrar a sua janela de configuração. O programa deverá
    lidar com o carregamento e gravação das suas opções de configuração. Quando
    um programa é iniciado, o Amarok muda a sua pasta de trabalho para a pasta
    onde todos os dados deverão estar gravados.

    engineStateChange:empty|idle|paused|playing
    Assinala uma mudança no estado do motor.

    trackChange
    Assinala o início de uma faixa nova. O programa poderá então usar as
    funções de DCOP para obter mais informações sobre a faixa, p.ex., os
    meta-dados e o tamanho.

    volumeChangenovoVolume
    Assinala a mudança do nível de volume-mestre. O volume é um número inteiro
    de 0-100.

    customMenuClicked:submenu tituloItem locais
    Devolve as localizações dos ficheiros seleccionados na lista de reprodução
    quando o item do menu de contexto da lista de reprodução for carregado. O
    submenu e o tituloItem são também devolvidos por razões de identificação,
    no caso de um programa estar à espera de várias notificações.
    Para inserir um item no menu de contexto, use a chamada de DCOP
    'dcop amarok script addCustomMenuItem( submenu tituloItem )'. Para remover
    um item do menu de contexto, use a chamada de DCOP
    'dcop amarok script removeCustomMenuItem( submenu tituloItem )'.

### Finalização do 'Script'

Antes de o &amarok; sair, ou quando o utilizador parar um 'script' com o Gestor de 'Scripts', o &amarok; envia o sinal SIGTERM para o programa. Este sinal poderá ser capturado para fazer algum trabalho de limpeza, como a gravação dos dados ou das opções de configuração.

### Empacotamento

O Gestor de 'Scripts' do &amarok; é capaz de instalar pacotes de programas que o utilizador tenha obtido de um servidor da Web. Os pacotes são ficheiros comprimidos perfeitamente normais (.tar), opcionalmente comprimidos com o bzip2 (.bz2). Recomenda-se em grande medida que use um nome de ficheiro do tipo o-meu-programa.amarokscript.tar.bz2, para que o utilizador consiga identificar facilmente o pacote como um programa do Amarok.

O &amarok; 1.3 só irá aceitar pacotes de 'scripts' com a extensão 'amarokscript', por isso é melhor é usá-la logo desde o início.

O conteúdo do pacote deverá estar organizado da seguinte forma:

    myscript/
       README
       o-meu-programa.py (executável)
       um-modulo.py
       xpto.data
       ...

### Permissões dos ficheiros

O programa principal deverá ter permissões de execução (+x) activas, enquanto os módulos adicionais que o programa carregar não deverão ser executáveis. Para preservar as permissões do ficheiro no pacote, deverá usar o 'tar' com a opção '-p':

    tar -cf o-meu-programa.amarokscript.tar -p o-meu-programa

O &amarok; não será capaz de instalar o programa se as permissões não estiverem definidas correctamente.

### Distribuir

Quando o pacote estiver terminado, poderá enviá-lo para o www.kde-apps.org e adicionar a referência à Página de 'Scripts' do Wiki do &amarok;. Para o item do 'kde-apps', deverá usar a categoria de 'Scripts' do &amarok;.