# Caratteristiche avanzate di amaroK

## Scorciatoie tastiera

&amarok; usa scorciatoie di tastiera come la maggior parte delle altre applicazioni. Sotto trovi una lista di queste scorciatoie e le rispettive azioni. Le scorciatoie globali possono essere configurate facendo click con il pulsante destro del mouse nella finestra del lettore e selezionando Configura scorciatoie globali.... Le scorciatoie di &amarok; possono essere configurate facendo click 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
--- | ---
Win X | Play
Win C | Pausa
Win V | Stop
Win B | Prossima traccia
Win Z | Traccia precedente
Win tasto + in tast.num. | Aumenta volume
Win tasto - in tast.num. | Diminuisci volume
Win Shift KP_Add | Cerca in avanti
Win Shift KP_Subtract | Cerca indietro
Win A | Aggiungi file
Win P | Attiva/disattiva playlist
Win O | Mostra OSD
Win M | Volume muto

Le scorciatoie di &amarok; sono:

Combinazione tasti | Azione
--- | ---
Ctrl C | Copia
Ctrl invio in tast.num. | Vai all'attuale
Ctrl D | Accoda tracce selezionate
Ctrl Q | Chiudi
Ctrl Shift Z | Ripeti
Ctrl S | Salva la playlist
Ctrl A | Seleziona tutto
Ctrl M | Mostra la barra dei menu
Ctrl H | Mescola
Ctrl Z | Annulla

Le scorciatoie per il navigatore della playlist sono:

Combinazione tasti | Azione
--- | ---
Barra spazio | Carica playlist
F2 | Rinomina playlist
Tasto di cancellazione a sinistra | Rimuove playlist

## L'interfaccia DCOP

Con l'interfaccia DCOP di amaroK, puoi controllare facilmente amaroK con script tuoi.

L'interfaccia DCOP di amaroK ha molte funzioni generiche che possono essere trovate in altre applicazioni KDE. Questa sezione è divisa in quattro tabelle e descrive le funzioni DCOP del lettore e della playlist. Un esempio della funzione dcop pausa potrebbe essere il seguente:

&percnt;dcop amarok player pause

### dcop amarok collection

Chiamata DCOP | Azione
--- | ---
query | La funzione query permette di inviare interrogazioni direttamente al database della collezione di &amarok;.
scanCollection | La funzione scanCollection esegue una scansione manuale della collezione.
scanCollectionChanges | La funzione scanCollectionChanges esegue una scansione manuale della collezione in cerca di cambiamenti.
similarArtists | La funzione similarArtist mostra l'artista simile per la traccia in riproduzione. I risultati sono limitati ad un valore intero di artisti.
totalAlbums | La funzione totalAlbums mostra il numero totale degli album nella collezione.
totalArtists | La funzione totalArtists mostra il numero totale degli artisti nella collezione.
totalCompilations | La funzione totalCompilations mostra il numero totale di compilation nella collezione.
totalGenres | La funzione totalGenres mostra il numero totale dei generi nella collazione.
totalTracks | La funzione totalTracks mostra il numero totale delle tracce nella collezione.

### dcop amarok player

Chiamata DCOP | Azione
--- | ---
album | La funzione album mostra l'album della traccia in riproduzione.
artist | La funzione artist mostra l'artista della traccia in riproduzione
bitrate | La funzione bitrate mostra il bitrate della traccia in riproduzione.
comment | La funzione comment mostra il commento della traccia in riproduzione.
coverImage | La funzione coverImage mostra l'URL della copertina della traccia attuale.
currentTime | La funzione currentTime mostra la posizione (mm:ss) della traccia in riproduzione.
encodedURL | La funzione encodeURL mostra l'URL della traccia attuale con spazi codificati.
motore | La funzione motore mostra il motore audio attuale.
genre | La funzione genre mostra il genere della traccia in riproduzione.
lyrics | La funzione lyrics mostra i testi in memoria della traccia in riproduzione.
lyricsByPath | La funzione lyricsByPath mostra i testi in memoria di una traccia specificata dal suo percorso.
nowPlaying | La funzione nowPlaying mostra Artista - Titolo della traccia in riproduzione. Se uno dei due tag id3 è vuoto, verrà mostrato solo Artista o Titolo (senza il -).
path | La funzione path mostra il percorso del filesystem alla traccia corrente.
setContextStyle | La funzione setContextStyle regola il tema CSS del Navigatore per contesti specificato nel nome.
title | La funzione title mostra il titolo della traccia in riproduzione.
totalTime | La funzione totalTime mostra la durata totale (mm:ss) della traccia in riproduzione.
traccia | La funzione track mostra il numero della traccia in riproduzione.
year | La funzione year mostra l'anno della traccia in riproduzione.
dynamicModeStatus | La funzione dynamicModeStatus restituisce un valore di vero o falso per indicare se la modalità dinamica è attivata.
equalizerEnabled | La funzione equalizerEnabled restituisce un valore di vero o falso per indicare se l'equalizzatore è attivato.
isPlaying | La funzione isPlaying restituisce un valore di vero o falso per indicare le il lettore è in riproduzione o meno.
randomModeStatus | La funzione randomModeStatus mostra lo stato della modalità casuale con un valore di vero o falso.
repeatPlaylistStatus | La funzione repeatPlaylistStatus mostra lo stato di Ripeti Playlist con un valore di vero o falso.
repeatTrackStatus | La funzione repeatTrackStatus mostra lo stato di Ripeti Traccia con un valore di vero o falso.
getVolume | La funzione getVolume ritorna un valore per il livello del volume specificato da un valore tra 0 e 100.
sampleRate | La funzione sampleRate mostra il campionamento della traccia.
score | La funzione score mostra il punteggio della traccia attuale.
setLyricsByPath | La funzione setLyricsByPath imposta i testi di una traccia specificata dal suo percorso. Usare la funzione lyrics per vedere esempi di impostazione html appropriati.
status | La funzione status ritorna un valore per lo stato del motore, 2 se in uso, 1 se in pausa e 0 se inattivo.
trackCurrentTime | La funzione trackCurrentTime restituisce un valore dell'attuale tempo trascorso della traccia in secondi.
trackPlayCounter | La funzione trackPlayCounter mostra quante volte la traccia è stata riprodotta.
trackTotalTime | La funzione trackTotalTime restituisce un valore della durata totale della traccia attuale in secondi.
configEqualizer | La funzione configEqualizer alza la finestra di configurazione dell'equalizzatore.
enableDynamicMode | La funzione enableDynamicMode è usata per gestire la modalità dinamica con un valore di 0 disabilitata, e 1 abilitata.
enableOSD | La funzione enableOSD permette di gestire l'On-Screen-Display con un valore di vero o falso.
enableRandomMode | La funzione enableRandomMode è usata per gestire la modalità casuale con un valore di 0 disabilitata, e 1 abilitata.
enableRepeatPlaylist | La funzione enableRepeatPlaylist è usata per attivare o meno la modalità di ripetizione playlist con un valore di 0 disabilitata, e 1 abilitata.
enableRepeatTrack | La funzione enableRepeatTrack è usata per attivare o meno la modalità di ripetizione traccia con un valore di 0 disabilitata, e 1 abilitata.
mute | La funzione mute permette di togliere e rimettere il suono alla traccia in riproduzione.
next | La funzione next fa avanzare il lettore di una traccia.
pause | La funzione pause mette in pausa la traccia in riproduzione.
play | La funzione play fa ripartire il lettore da dove fu fermato.
playPause | La funzione playPause fa partire il lettore se questo è attualmente fermo od in pausa. Questa funzione, inoltre, mette in pausa il lettore se era in riproduzione.
prev | La funzione prev muove il lettore indietro di una traccia.
seek | La funzione seek è utilizzata per cercare in un punto specifico in una traccia per un valore specificato di secondi.
seekRelative | La funzione seekRelative è utilizzata per cercare in un punto relativo alla posizione della traccia attuale per un valore specificato in secondi.
setEqualizer | La funzione setContextStyle usa undici interi delimitati da spazi per impostare i valori del cursore dell'equalizzatore. Il range dei valori del cursore va dal più basso -255 al più alto 255. Il primo numero intero è usato per impostare il valore della preamplificazione, i rimanenti impostano i valori di frequenza di risposta della preamplificazione da 60Hz a 16kHz.
setEqualizerEnabled | La funzione setEqualizerEnabled serve ad abilitare l'equalizzatore utilizzando un valore vero o falso.
setScore | La funzione setScore regola il punteggio della traccia specificata tra un valore tra 0 e 100.
setScoreByPath | La funzione setScoreByPath regola il punteggio della traccia specificata dal suo percorso seguito dal suo punteggio specificato da un valore tra 0 e 100.
setVolume | La funzione setVolume regola il volume ad un livello specificato da un valore tra 0 e 100.
showBrowser | La funzione showBrowser mostra un navigatore nella finestra della playlist. Valori corretti per il navigatore sono cantesto, collezione, playlist, media e file.
showOSD | La funzione showOSD fa apparire l'OSD per mostrare le informazioni della traccia attuale.
stop | La funzione stop ferma il lettore se è in riproduzione.
volumeDown | La funzione volumeDown abbassa il volume di uno scalino.
volumeUp | La funzione volumeUp aumenta il volume di uno scalino.

### dcop amarok playlist

Chiamata DCOP | Azione
--- | ---
saveCurrentPlaylist | La funzione saveCurrentPlaylist salva l'attuale playlist come ~/.kde/share/apps/amarok/current.xml.
getActiveIndex | La funzione getActiveIndex restituisce un valore intero per la posizione della traccia attuale nella playlist.
getTotalTrackCount | La funzione getTotalTrackCount mostra il numero totale di canzoni nella playlist.
addMedia | La funzione addMedia è usata per aggiungere singoli file alla playlist.
addMediaList | La funzione addMediaList è usata per aggiungere più file alla playlist.
clearPlaylist | La funzione clearPlaylist è usata per pulire l'intera playlist.
playByIndex | La funzione playByIndex fa partire la riproduzione di una traccia dalla sua posizione nella playlist.
playMedia | La funzione playMedia fa partire la riproduzione di una traccia specificata dal suo KURL.
popupMessage | La funzione popupMessage fa apparire una messaggio in una finestra a comparsa in quella della playlist. Il messaggio a popup è specificato con una Qstring.
repopulate | La funzione repopulate ripopola la playlist con tracce dalla modalità dinamica.
removeCurrentTrack | La funzione removeCurrentTrack rimuove la traccia attuale dalla playlist.
saveM3u | La funzione saveM3u salva l'attuale playlist nel formato M3U. Bisogna specificare il percorso dove salvarla, ed includere un valore di 0 o 1 per indicare se scrivere o meno i percorsi relativi.
setStopAfterCurrent | La funzione setStopAfterCurrent ferma la riproduzione della playlist dopo il comletamento della traccia attuale.
shortStatusMessage | La funzione shortStatusMessage mostra una stringa di testo come messaggio nella barra di stato.
shufflePlaylist | La funzione shufflePlaylist rende casuale l'ordine delle tracce nella playlist.
togglePlaylist | La funzione togglePlaylist abilita o meno la finestra della playlist.

### dcop amarok script

Chiamata DCOP | Azione
--- | ---
listRunningScripts | La funzione listRunningScripts elenca tutti gli script di &amarok; attivi.
runScript | La funzione runScript attiverà uno script di &amarok; specificato dal nome.
stopScript | La funzione stopScript fermerà uno script di &amarok; specificato dal nome.
addCustomMenuItem | La funzione addCustomMenuItem aggiunge una voce al menu contestuale della playlist. Ha due QString, la prima per il titolo del sottomenu, la secondo per il titolo della voce nel sottomenu. Entrambe vengono restituite nel sistema di notifica del gestore degli script.
removeCustomMenuItem | La funzione removeCustomMenuItem rimuove una voce aggiunta al menu contestuale della playlist utilizzando la funzione addCustomMenuItem. Usa le stesse QString di addCustomMenuItem.

## Opzioni linea di comando

amaroK supporta l'uso delle opzioni standard dei comandi di linea di Qt e kde. amaroK ha inoltre le proprie opzioni specifiche.

Le opzioni Qt e kde:

Opzioni | 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 costruite per essere usate mentre &amarok; è in funzione.

Opzioni | Azione
--- | ---
-r, --previous | Salta alla traccia precedente nella playlist.
-p, --play | Inizia a riprodurre l'attuale playlist.
-s, --stop | Ferma la riproduzione.
--pause | Mette in pausa la riproduzione.
-f, --next | Salta alla prossima traccia nella playlist.
-a, --append | Accoda 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 dopo nella propria 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).

In modo da fornire un ritorno di informazioni quando uno script non funziona per una mancata dipenenza, controllare che nel proprio script se il modulo che si vuole includere realmente esiste. Se la dipendenza manca, si potrebbe prendere l'errore e mostrare una finestra di informazione usando lo strumento linea di comando "kdialog" in modo che l'utente capisca perché lo script fallisce.

Questo esempio mostra come recuperare una dipendenza mancante in Ruby:

    begin
           require 'Korundum'
    rescue LoadError
           error = 'Korundum (KDE bindings for ruby) from kdebindings v3.4 is required for this script.'
           `kdialog --sorry '#{error}'`
           exit
    end

### Incominciare: i modelli

&amarok; fornisce modelli di script per numerose linguaggi nella cartella `scripts/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. La via più semplice per invocare una funzione DCOP è usare l'utilità linea di comando "dcop", che fa parte di ogni distribuzione 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 l'utlità "dcop" può essere invocata 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 canali stdin. Lo script dovrebbe quindi costantemente controllare stdin e reagisce 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 spedite 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 venire archiviati.

    engineStateChange:empty|idle|paused|playing
    Segnala una variazione nello stato del motore.

    trackChange
    Segnala l'inizio di un nuovo brano. Lo script può allora usare le funzionalità
    DCOP per richiedere ulteriori informazioni sul brano tipo le meta informazioni
    e la lunghezza.

    volumeChangenewVolume
    Segnala un cambiamento nel livello del volume principale. Il volume è un numero intero compreso
    tra 0 e 100.

    customMenuClicked:submenu itemTitle paths
    Ritorna il percorso dei file selezionati nella playlist quando la voce del menu
    contestuale della playlist personalizzata viene premuto. Il sottomenu e itemTitlevengono anche restituiti per identificare copi in caso uno script stia in ascolto
    per molteplici notifiche.
    Per inserire una voce nel menu contestuale bisogna usare la funzione DCOP
    'dcop amarok script addCustomMenuItem( submenu itemTitle )'. Per rimuovere
    una voce del menu contestuale bisogna usare la funzione DCOP
    'dcop amarok script removeCustomMenuItem( submenu itemTitle )'.

### Stop degli script

Per 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 preso per fare pulizia nel lavoro, come salvare dati o configurare di impostazioni.

### Pacchetti

Il Gestore degli script di &amarok; è capace di installare pacchetti di script scricati dall'utente da un web server. Normalmente si tratta di pacchetti tarball (.tar), opzionalmente compressi con bzip2 (.bz2). Si raccomanda caldamente di usare un nome di file 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 dal bell'inizio.

Il contenuto dei pacchetti tarball deve venire organizzato come segue:

    myscript/
       README
       myscript.py (executable)
       somemodule.py
       foo.data
       ...

### Permessi del file

Lo script principale deve avere i permessi di scrivibile (+x) impostati, mentre moduli addizionali che vengono caricati dallo script possono non esserlo. Per preservare i permessi del 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ò spedirlo a www.kde-apps.org, ed aggiungere il link nella Pagina Wiki degli script di &amarok;. Per la voce in kde-apps si dovrebbe usare la categoria script di &amarok;.