Caratteristiche avanzate di Amarok
Scorciatoie da tastiera
&amarok; usa scorciatoie da tastiera come la maggior parte delle altre applicazioni. Sotto trovi un elenco di queste scorciatoie e le rispettive azioni. Le scorciatoie globali possono essere configurate facendo clic con il pulsante destro del mouse nella finestra del lettore e selezionando Configura scorciatoie globali.... Le scorciatoie di &amarok; possono essere configurate facendo clic con il pulsante destro del mouse nella finestra del lettore e selezionando Configura scorciatoie...
Puoi programmare i tasti multimediali affinché funzionino come scorciatoie per &amarok; facendo divenire la tua tastiera un centro di controllo di &amarok;.
Le scorciatoie globali sono:
Combinazione tasti
Azione
WinX
Riproduci
WinC
Pausa
WinV
Ferma
WinB
Prossima traccia
WinZ
Traccia precedente
Wintasto + in tast.num.
Aumenta volume
Wintasto - in tast.num.
Riduci volume
WinShifttasto + in tast.num
Cerca in avanti
WinShifttasto - in tast.num
Cerca indietro
WinA
Aggiungi file
WinP
Attiva/disattiva playlist
WinO
Mostra OSD
WinM
Volume muto
Le scorciatoie di &amarok; sono:
Combinazione tasti
Azione
CtrlC
Copia
Ctrltasto Invio in tast.num
Vai all'attuale
CtrlD
Accoda tracce selezionate
CtrlQ
Chiudi
CtrlShiftZ
Ripeti
CtrlS
Salva la playlist
CtrlA
Seleziona tutto
CtrlM
Mostra la barra dei menu
CtrlH
Mescola
CtrlZ
Annulla
Le scorciatoie per il navigatore della playlist sono:
Combinazione tasti
Azione
Barra spaziatrice
Carica playlist
F2
Rinomina playlist
Tasto di cancellazione a sinistra
Rimuove playlist
L'interfaccia DCOP
L'interfaccia DCOP di Amarok fornisce un modo semplice per controllare Amarok con script personalizzati.
L'interfaccia DCOP di Amarok ha molte funzioni generiche che possono essere trovate in altre applicazioni di KDE. Questa sezione è divisa in sei tabelle e descrive le funzioni DCOP della collezione, navigatore per contesti, lettore, playlist, navigatore della playlist e script. Un esempio della funzione dcop pausa
potrebbe essere il seguente:
%dcop amarok player pause
dcop amarok collection
Chiamata DCOP
Azione
int totalAlbums()
Restituisce il totale degli album nella collezione.
int totalArtists()
Restituisce il totale degli artisti nella collezione.
int totalCompilations()
Restituisce il totale di compilation nella collezione.
int totalGenres()
Restituisce il totale dei generi nella collezione.
int totalTracks()
Restituisce il totale delle tracce nella collezione.
TQString query( TQString sql )
Interroga il database attraverso SQL.
QStringList similarArtists( int artists )
Restituisce artisti simili alla traccia attuale, limitato a int artisti.
void migrateFile( TQString oldURL, TQString newURL )
Sposta un file nella collezione, mantenendo intatte le statistiche.
void scanCollection()
Scansione della collezione.
void scanCollectionChanges()
Scansione della collezione alla ricerca di modifiche.
dcop amarok contextbrowser
Chiamata DCOP
Azione
void showCurrentTrack()
Mostra la traccia attuale nel navigatore per contesti.
void showLyrics()
Mostra la scheda dei testi nel navigatore per contesti.
void showWiki()
Mostra la scheda di wikipedia nel navigatore per contesti.
dcop amarok player
Chiamata DCOP
Azione
bool dynamicModeStatus()
Restituisce lo stato della modalità dinamica.
bool equalizerEnabled()
Restituisce lo stato dell'equalizzatore.
bool isPlaying()
Restituisce vero se c'è qualcosa in riproduzione.
bool randomModeStatus()
Restituisce lo stato della modalità casuale.
bool repeatPlaylistStatus()
Restituisce lo stato di Ripeti playlist.
bool repeatTrackStatus()
Restituisce lo stato di Ripeti traccia.
int getVolume()
Restituisce il volume in un intervallo compreso tra 0 e 100%.
int sampleRate()
Restituisce il campionamento della traccia attuale.
int score()
Restituisce il punteggio della traccia in riproduzione.
int status()
Restituisce lo stato di riproduzione: 0 - fermato, 1 - in pausa, 2 - in riproduzione.
int trackCurrentTime()
Restituisce la posizione di riproduzione attuale in secondi.
int trackPlayCounter()
Restituisce il contatore di riproduzione per il brano attuale.
int trackTotalTime()
Restituisce la durata della traccia in secondi.
TQString album()
Restituisce l'album della traccia in riproduzione.
TQString artist()
Restituisce l'artista della traccia in riproduzione.
TQString bitrate()
Restituisce il bitrate della traccia in riproduzione.
TQString comment()
Restituisce il commento della traccia in riproduzione.
TQString coverImage()
Restituisce l'URL codificato della copertina della traccia attuale.
TQString currentTime()
Restituisce la posizione della traccia in riproduzione (formato [h:]mm:ss).
TQString encodedURL()
Restituisce l'URL codificato della traccia in riproduzione.
TQString engine()
Restituisce il motore sonoro attuale.
TQString genre()
Restituisce il genere della traccia in riproduzione.
TQString lyrics()
Restituisce il testo della traccia in riproduzione.
TQString lyricsByPath( TQString path )
Restituisce il testo di una traccia in base al percorso.
TQString nowPlaying()
Il titolo dei media in fase di riproduzione.
TQString path()
Restituisce il percorso non codificato della traccia in riproduzione.
TQString setContextStyle( TQString )
Imposta lo stile CSS del navigatore per contesti.
TQString title()
Restituisce il titolo della traccia in riproduzione.
TQString totalTime()
Restituisce la durata della traccia in riproduzione (formato [h:]mm:ss).
TQString track()
Restituisce il numero di traccia.
TQString type()
Restituisce il tipo di file.
TQString year()
Restituisce l'anno della traccia in riproduzione.
void configEqualizer()
Commuta la finestra di configurazione dell'equalizzatore.
void enableDynamicMode(bool enable)
Attiva o disattiva Modalità dinamica.
void enableOSD(bool enable)
Attiva o disattiva visualizzazione OSD.
void enableRandomMode(bool enable)
Attiva o disattiva Modalità casuale.
void enableRepeatPlaylist(bool enable)
Attiva o disattiva Ripeti playlist.
void enableRepeatTrack(bool enable)
Attiva o disattiva Ripeti traccia.
void mediaDeviceMount()
Imposta il comando per montare il dispositivo multimediale.
void mediaDeviceUmount()
Imposta il comando per smontare i dispositivo multimediale.
void mute()
Commuta silenzio.
void next()
Equivale alla pressione del pulsante "Successivo".
void pause()
Equivale alla pressione del pulsante "Pausa".
void play()
Equivale alla pressione del pulsante "Riproduci".
void playPause()
Commuta lo stato riproduci/pausa (buono per utenti di tastiere mm)
void prev()
Equivale alla pressione del pulsante "Precedente".
void queueForTransfer( KURL url )
Accoda file per il trasferimeto al dispositivo multimediale.
void seek(int s)
Va al secondo dato nella traccia.
void seekRelative(int s)
Posizionamento relativo alla traccia attuale.
void setEqualizer(int, int, int, int, int, int, int, int, int, int, int)
Imposta le bande dell'equalizzatore
void setEqualizerEnabled( bool active )
Commuta l'equalizzatore.
void setEqualizerPreset( TQString name )
Imposta la preimpostazione dell'equalizzatore.
void setLyricsByPath( TQString url, TQString lyrics )
Imposta il testo di una traccia in base al suo percorso.
void setScore( int score )
Imposta il punteggio della traccia in riproduzione.
void setScoreByPath( TQString url, int score )
Imposta il punteggio di una traccia in base al suo percorso.
void setVolume(int volume)
Imposta il volume in un intervallo compreso tra 0 e !00%.
void showBrowser( TQString browser )
Mostra i navigatori nella finestra della playlist.
void showOSD()
Mostra la visualizzazione OSD sullo schermo.
void stop()
Equivale alla pressione del pulsante "Ferma".
void transferDeviceFiles()
Trasferire file a un dispositivo multimediale.
void volumeDown()
Riduce il volume di una quantità ragionevole.
void volumeUp()
Aumenta il volume di una quantità ragionevole.
dcop amarok playlist
Chiamata DCOP
Azione
int getActiveIndex()
Restituisce l'indice della traccia attiva. -1 se nessuno.
int getTotalTrackCount()
Restituisce il numero di tracce nella playlist. 0 se nessuna
TQString saveCurrentPlaylist()
Salva la playlist attuale come current.xml e ne restituisce il percorso.
void addMedia( KURL )
Aggiunge media audio specificati dall'URL.
void addMediaList( KURL::List )
Aggiunge alcuni media audio specificati dall'URL.
void clearPlaylist()
Svuota la playlist.
void playByIndex(int)
Avvia la riproduzione della traccia all'indice specificato.
void playMedia( KURL )
Aggiunge media audio specificati dall'URL.
void popupMessage( TQString)
Mostra un messaggio a comparsa temporaneo.
void removeCurrentTrack()
Rimuove l'elemento della traccia attuale dalla playlist.
void repopulate()
Ripopola la playlist con tracce casuali.
void saveM3u( TQString path, bool relativePaths)
Salva la playlist attuale come m3u.
void setStopAfterCurrent( bool )
Abilita/Disabilita la funzionalità "Ferma dopo la traccia attuale".
void shortStatusMessage( TQString)
Mostra un messaggio temporaneo sulla barra di stato.
void shufflePlaylist()
Mescola la playlist
void togglePlaylist()
Commuta la finestra della playlist.
dcop amarok playlistbrowser
Chiamata DCOP
Azione
void addPodcast( TQString )
Aggiunge una voce di podcast al navigatore della playlist.
void scanPodcasts()
Analisi di tutti i podcast alla ricerca di aggiornamenti.
void addPlaylist( TQString )
Aggiunge una playlist al navigatore della playlist.
dcop amarok script
Chiamata DCOP
Azione
bool runScript( TQString name)
Avvia lo script con il dato nome. Restituisce vero in caso di successo.
bool stopScript( TQString name )
Ferma lo script con il dato nome. Restituisce vero in caso di successo.
QStringList listRunningScripts()
Restituisce un elenco di tutti gli script in esecuzione.
void addCustomMenuItem(TQString submenu, TQString itemTitle )
Abilita e imposta il titolo della voce di menu personalizzata.
void removeCustomMenuItem( TQString submenu, TQString itemTitle )
Rimuove l'elemento di menu personalizzato.
TQString readConfig( TQString key)
Restituisce il valore della voce di configurazione AmarokConfig data la chiave.
Opzioni linea di comando
Amarok supporta l'uso delle opzioni standard da riga di comando di Qt e kde. Amarok ha inoltre le proprie opzioni a livello applicazione specifiche.
Le opzioni Qt e kde:
Opzione
Azione
--help
Mostra l'aiuto sulle opzioni.
--help-qt
Mostra le opzioni specifiche di Qt.
--help-kde
Mostra le opzioni specifiche di KDE.
--help-all
Mostra tutte le opzioni.
--author
Mostra le informazioni dell'autore.
-v, --version
Mostra le informazioni della versione.
--license
Mostra le informazioni della licenza.
Le opzioni di Amarok:
Le opzioni di &amarok; sono pensate per essere usate mentre &amarok; è in funzione.
Opzione
Azione
-r, --previous
Salta alla traccia precedente nella playlist.
-p, --play
Inizia a riprodurre la playlist attuale.
-s, --stop
Ferma la riproduzione.
--pause
Mette in pausa la riproduzione.
-f, --next
Salta alla traccia successiva nella playlist.
-a, --append
Aggiungi file/URL alla playlist.
-e, --enqueue
Vedi append, disponibile per retro compatibilità.
--queue
Accoda file/URL dopo la traccia in riproduzione.
-m, --toggle-playlist-window
Attiva/disattiva la finestra della playlist.
--wizard
Lancia l'assistente del primo avvio.
--engine "name"
Avvia &amarok; con il motore "name".
Scrivere script
Scrivere script permette di estendere facilmente &amarok; senza cambiare il codice principale. Gli script sono simili ai plugin ma, invece di una API dedicata, usano l'interfaccia DCOP di &amarok; per comunicare. Ciò rende possibile scrivere script in quasi qualsiasi linguaggio di programmazione come Ruby, Python o PHP. Non solo si possono creare script nel classico linguaggio di programmazione, ma anche in linguaggi compilati come C++ o C. In aggiunta, &amarok; può notificare agli script eventi speciali e farli reagire di conseguenza. Questo sistema di notifiche verrà spiegato nel seguito di questa sezione.
Binding
È possibile scrivere semplici script che non necessitano dell'interazione dell'utente ed è anche possibile creare script con comode GUI che funzionino come piccole applicazioni singole. Per la programmazione delle GUI si può usare uno dei molti binding che KDE offre, per esempio RubyQT, una libreria Qt binding per Ruby. Tuttavia, vale la pena notare che non ogni utente ha tutti i binding disponibili installati. Se si decide di usarne uno, provare ad usarne uno di larga diffusione (p.e. RubyQt o PyQt).
Per fornire delle informazioni quando uno script non funziona per una dipendenza mancante, controllare che nel proprio script che il modulo che si vuole includere esista realmente. Se la dipendenza manca, si potrebbe intercettare l'errore e mostrare una finestra di informazione usando lo strumento da linea di comando "kdialog" in modo che l'utente capisca perché lo script fallisce.
Questo esempio mostra come intercettare una dipendenza mancante in Ruby:
begin
require 'Korundum'
rescue LoadError
error = 'Korundum (KDE bindings for ruby) from tdebindings v3.4 is required for this script.'
`kdialog --sorry '#{error}'`
exit
end
Per iniziare: i modelli
&amarok; fornisce modelli di script per numerose linguaggi nella cartella script/templates/. Si possono usare come base per propri script ed estenderli con le funzionalità di cui si necessita. Si noterà che lo scripting è attualmente abbastanza diretto. Se ad esempio si conosce un po' di programmazione in python, realizzare il proprio script non richiederà molto tempo.
Controllare &amarok; con DCOP
Gli script possono controllare Amarok richiamando alcune delle sue funzioni DCOP. Il modo più semplice per invocare una funzione DCOP è usare lo strumento da riga di comando "dcop", che fa parte di ogni distribuzione di KDE.
Questo è un esempio per aumentare il volume principale:
dcop amarok player volumeUp
La maggior parte dei linguaggi di scripting permette di eseguire programmi esterni con una funzione tipo exec(). In questa maniera lo strumento "dcop" può essere invocato facilmente. Questo è un semplice esempio in Python:
import os
os.system("dcop amarok player volumeDown")
Notifiche
&amarok; invia notifiche a tutti gli script attivi scrivendo stringhe sui loro canale stdin. Lo script dovrebbe quindi costantemente controllare stdin e reagire di conseguenza a ciascuno degli eventi possibili. Gli script possono anche scegliere ignorare tutti gli eventi che per cui non hanno funzioni.
Le seguenti notifiche vengono inviate a &amarok;:
configure
Dice allo script di mostrare la propria finestra di configurazione. Lo script
deve gestire archiviazione e caricamento delle opzioni di configurazione
in proprio. Quando uno script viene avviato, Amarok imposta la propria
cartella di lavoro in quella dove tutti i dati dovrebbero essere archiviati.
engineStateChange:empty|idle|paused|playing
Segnala una variazione nello stato del motore.
trackChange
Segnala l'inizio di una nuova traccia. Lo script può quindi usare le funzioni
DCOP per richiedere ulteriori informazioni sulla traccia, ad es. metadati
e durata.
volumeChangenewVolume
Segnala un cambiamento nel livello del volume principale. Il volume è un intero compreso
tra 0 e 100.
customMenuClicked:submenu itemTitle paths
Restituisce i percorsi dei file selezionati nella playlist quando si fa clic sulla voce del menu contestuale della playlist personalizzata. submenu e itemTitle
vengono inoltre restituiti per scopi di identificazione nel caso in cui uno
script rimanga in ascolto per notifiche multiple.
Per inserire una voce nel menu contestuale bisogna utilizzare la funzione DCOP
'dcop amarok script addCustomMenuItem( submenu itemTitle )'. Per rimuovere
una voce dal menu contestuale bisogna utilizzare la funzione DCOP
'dcop amarok script removeCustomMenuItem( submenu itemTitle )'.
Interruzione script
Prima che &amarok; si chiuda, o quando l'utente ferma uno script con il gestore degli script, &amarok; invia il segnale SIGTERM allo script. Il segnale può essere usato per fare pulizia, come salvataggio di dati o impostazioni di configurazione.
Pacchetti
Il gestore degli script di &amarok; è in grado di installare pacchetti di script scaricati dall'utente da un server web. I pacchetti sono normali tarball (.tar), opzionalmente compressi con bzip2 (.bz2). Si consiglia vivamente di usare un nome file del tipo myscript.amarokscript.tar.bz2, in modo che l'utente possa facilmente identificare il pacchetto come uno script per Amarok.
&amarok; 1.3 accetterà solamente pacchetti di script con l'estensione amarokscript, in modo da usarlo più facilmente fin da subito.
Il contenuto dei pacchetti tarball deve essere organizzato come segue:
myscript/
README
myscript.py (executable)
somemodule.py
foo.data
...
Permessi dei file
Lo script principale deve avere i permessi di esecuzione (+x) impostati, mentre moduli addizionali che vengono caricati dallo script possono non esserlo. Per preservare i permessi dei file nel tarball bisogna usare tar con l'opzione -p:
tar -cf myscript.amarokscript.tar -p myscript
&amarok; non sarà in grado di installare lo script se i permessi non sono correttamente impostati.
Distribuzione
Quando il pacchetto è terminato, si può inviarlo a www.kde-apps.org, ed aggiungere il collegamento nella Pagina Wiki degli script di &amarok;. Per la voce in kde-apps si dovrebbe usare la categoria &amarok; Scripts.