# Caratteristiche avanzate di amaroK

## Scorciatoie da tastiera

&amarok; usa scorciatoie da 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
--- | ---
WinX | Play
WinC | Pausa
WinV | Stop
WinB | Prossima traccia
WinZ | Traccia precedente
Wintasto + in tast.num. | Aumenta volume
Wintasto - in tast.num. | Diminuisci volume
WinShiftKP_Add | Cerca in avanti
WinShiftKP_Subtract | 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
Ctrlinvio 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 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.

The DCOP interface for amaroK has many generic calls that may be found in other KDE applications. This section is divided into six tables and is intended to describe the DCOP calls of the collection, contextbrowser, player, playlist, playlistbrowser and scripts. An example of the pause dcop call would look like:

&percnt;dcop amarok player pause

### dcop amarok collection

Chiamata DCOP | Azione
--- | ---
int totalAlbums() | Returns the total of albums in the collection.
int totalArtists() | Returns the total of artists in the collection.
int totalCompilations() | Returns the total of compilations in the collection.
int totalGenres() | Returns the total of genres in the collection.
int totalTracks() | Returns the total of tracks in the collection.
QString query( QString sql) | Queries the database via SQL.
QStringList similarArtists( int artists ) | Return similar artists of the current tracks, limit to int artists.
void migrateFile( QString oldURL, QString newURL ) | Move a file in the collection, keeping stats intact.
void scanCollection() | Scan the collection.
void scanCollectionChanges() | Scan the collection for changes only.

### dcop amarok contextbrowser

Chiamata DCOP | Azione
--- | ---
void showCurrentTrack() | Show the current track in the context browser.
void showLyrics() | Show the lyrics tab in the context browser.
void showWiki() | Show the wikipedia tab in the context browser.

### dcop amarok player

Chiamata DCOP | Azione
--- | ---
bool dynamicModeStatus() | Return dynamic mode status.
bool equalizerEnabled() | Return the equalizer status.
bool isPlaying() | Return true if something is playing now.
bool randomModeStatus() | Return random mode status.
bool repeatPlaylistStatus() | Return repeat playlist status.
bool repeatTrackStatus() | Return repeat track status.
int getVolume() | Return volume in range 0-100%.
int sampleRate() | Return the sample rate of the currently playing track.
int score() | Return the score of the currently playing track.
int status() | Return playback status: 0 - stopped, 1 - paused, 2 - playing.
int trackCurrentTime() | Return current play position in seconds.
int trackPlayCounter() | Return play counter for current song.
int trackTotalTime() | Return track length in seconds.
QString album() | Return the album of the currently playing track.
QString artist() | Return the artist of the currently playing track.
QString bitrate() | Return the bitrate of the currently playing track (XX kbps).
QString comment() | Return the comment of the currently playing track.
QString coverImage() | Return the encoded URL of the current track's cover image
QString currentTime() | Return the position of the currently playing track ([h:]mm:ss format).
QString encodedURL() | Return the encoded URL of the currently playing track.
QString engine() | Return the current sound engine.
QString genre() | Return the genre of the currently playing track.
QString lyrics() | Return the lyrics of the currently playing track.
QString lyricsByPath( QString path ) | Return the lyrics of a track by path.
QString nowPlaying() | The title of now playing media.
QString path() | Return the unencoded path of the currently playing track.
QString setContextStyle( QString ) | Set the CSS style for the context browser.
QString title() | Return the title of the currently playing track.
QString totalTime() | Return the total length of the currently playing track ([h:]mm:ss format).
QString track() | Return the track number.
QString type() | Return the file type.
QString year() | Return the year of the currently playing track.
void configEqualizer() | Toggle equalizer config dialog.
void enableDynamicMode(bool enable) | Switch Dynamic Mode on or off.
void enableOSD(bool enable) | Switch OSD display on or off.
void enableRandomMode(bool enable) | Switch Random Mode on or off.
void enableRepeatPlaylist(bool enable) | Switch Repeat Playlist on or off.
void enableRepeatTrack(bool enable) | Switch Repeat Track on or off.
void mediaDeviceMount() | Sets the command used for mounting media device.
void mediaDeviceUmount() | Sets the comment used for umounting media device.
void mute() | Toggle mute.
void next() | Equivalent to pressing "Next" button.
void pause() | Equivalent to pressing "Pause" button.
void play() | Equivalent to pressing "Play" button.
void playPause() | Toggle play/pause state (good for mm keyboard users)
void prev() | Equivalent to pressing "Prev" button.
void queueForTransfer( KURL url ) | Queue file for transfer to Media Device.
void seek(int s) | Seek track to seconds position.
void seekRelative(int s) | Seek to a position relative to the current track position.
void setEqualizer(int, int, int, int, int, int, int, int, int, int, int) | Set the equalizer bands
void setEqualizerEnabled( bool active ) | Toggle equalizer.
void setEqualizerPreset( QString name ) | Set the equalizer preset
void setLyricsByPath( QString url, QString lyrics ) | Set the lyrics of a track by it's path.
void setScore( int score ) | Set the score of the currently playing track.
void setScoreByPath( QString url, int score ) | Set the score of a track by it's path.
void setVolume(int volume) | Set volume in range 0-100%.
void showBrowser( QString browser ) | Shows browsers in the playlist window
void showOSD() | Show the OSD display on the screen.
void stop() | Equivalent to pressing "Stop" button.
void transferDeviceFiles() | Transfer files to media device.
void volumeDown() | Decrease volume by a reasonable step.
void volumeUp() | Increase volume by a reasonable step.

### dcop amarok playlist

Chiamata DCOP | Azione
--- | ---
int getActiveIndex() | Return the index of the currently active track. -1 if none.
int getTotalTrackCount() | Return number of tracks in playlist. 0 if none.
QString saveCurrentPlaylist() | Saves the current playlist to current.xml and returns its path.
void addMedia( KURL ) | Add audio media specified by the url.
void addMediaList( KURL::List ) | Add some audio media specified by the url.
void clearPlaylist() | Clears the playlist.
void playByIndex(int) | Starts playing the track at the specified index.
void playMedia( KURL ) | Add audio media specified by the url.
void popupMessage( QString) | Shows a temporary popup message.
void removeCurrentTrack() | Removes the current-track item from the playlist.
void repopulate() | Repopulate the playlist with random tracks.
void saveM3u( QString path, bool relativePaths) | Saves the current playlist as m3u.
void setStopAfterCurrent( bool ) | Enables/disables the "Stop After Current Track" feature.
void shortStatusMessage( QString) | Shows a temporary message on the statusbar.
void shufflePlaylist() | Shuffles the playlist.
void togglePlaylist() | Toggle the Playlist-window.

### dcop amarok playlistbrowser

Chiamata DCOP | Azione
--- | ---
void addPodcast( QString ) | Add a podcast entry to the playlist browser.
void scanPodcasts() | Scan all podcasts for updates.
void addPlaylist( QString ) | Add a playlist to the playlist browser.

### dcop amarok script

Chiamata DCOP | Azione
--- | ---
bool runScript( QString name) | Starts the script with the given name. Returns true on success.
bool stopScript( QString name) | Stops the script with the given name. Returns true on success.
QStringList listRunningScripts() | Returns a list of all currently running scripts.
void addCustomMenuItem(QString submenu, QString itemTitle ) | Enables and sets custom menu item title.
void removeCustomMenuItem(QString submenu, QString itemTitle ) | Removes the custom menu item.
QString readConfig( QString key) | Returns a AmarokConfig configuration entry value from the given key.

## 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
    Tells the script to show its configuration dialog. The script must handle the
    storing and loading of configuration options by itself. When a script is
    started, amaroK sets its working directory to the folder where all data
    should be stored.

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

    trackChange
    Signals the start of a new track. The script may then use DCOP functions to
    query further information about the track, e.g. metadata and the length.

    volumeChangenewVolume
    Signals a change of the master volume level. The volume is an integer with a
    range of 0-100.

    customMenuClicked:submenu itemTitle paths
    Returns the paths to selected files in the playlist when the custom playlist
    context menu item is clicked. The submenu and itemTitle are also returned for
    identification purposes in case a script is listening for multiple notifications.
    To insert an item into the context menu use the DCOP call
    'dcop amarok script addCustomMenuItem( submenu itemTitle )'. To remove an
    item from the context menu use the DCOP call
    '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

When the package is finished, you can upload it to www.kde-apps.org, and add the link to the &amarok; Wiki Scripts Page. For the kde-apps entry you should use the &amarok; Scripts category.