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 WinX Reproduzir WinC Pausa WinV Parar WinB Próxima Faixa WinZ Faixa Anterior WinKP_Add Aumentar o Volume WinKP_Subtract Diminuir o Volume WinShiftKP_Add Avançar WinShiftKP_Subtract Recuar WinA Adicionar Média WinP Comutar a Lista WinO Mostrar o OSD WinM Volume Silenciado Os atalhos do &amarok; são: Combinação de Teclas Acção CtrlC Copiar CtrlKP_Enter Ir para a Actual CtrlD Colocar na Fila as Faixas Seleccionadas CtrlQ Sair CtrlShiftZ Refazer CtrlS Gravar a Lista de Reprodução CtrlA Seleccionar Tudo CtrlM Mostrar o Menu CtrlH Baralhar CtrlZ 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 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 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. 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. 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. 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. 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. 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. 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". 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. É 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 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. 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") 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 )'. 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. 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 ... 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. 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;.