# Uitgebreide functies van Amarok

## Sneltoetsen

&amarok; maakt, net als vele andere programma's, gebruik van sneltoetsen. Hier onder ziet u een lijst met sneltoetsen en de bijhorende acties. De globale sneltoetsen kunnen worden ingesteld door met de rechter muisknop op het afspelervenster te klikken en Globale sneltoetsen instellen... te selecteren. De sneltoetsen van &amarok; kunt u instellen door met de rechter muisknop op het afspelervenster te klikken en Sneltoetsen instellen... te selecteren.

U kunt uw multimediatoetsen van uw toetsenbord gebruiken om &amarok; te bedienen.

De globale sneltoetsen zijn:

Toetsencombinatie | Actie
--- | ---
WinX | Afspelen
WinC | Pauze
WinV | Stoppen
WinB | Volgende track
WinZ | Vorige track
WinKP_Add | Volume verhogen
WinKP_Subtract | Volume verlagen
WinShiftKP_Add | Vooruit zoeken
WinShiftKP_Subtract | Achteruit zoeken
WinA | Medium toevoegen
WinP | Afspeellijst aan/uit
WinO | On Screen Display tonen
WinM | Volume dempen

De &amarok;-sneltoetsen zijn:

Toetsencombinatie | Actie
--- | ---
CtrlC | Kopiëren
CtrlKP_Enter | Ga naar huidige
CtrlD | Geselecteerde tracks in een wachtrij plaatsen
CtrlQ | Afsluiten
CtrlShiftZ | Opnieuw
CtrlS | Afspeellijst opslaan
CtrlA | Alles selecteren
CtrlM | Menubalk tonen
CtrlH | Schudden (tracks in de afspeellijst door elkaar husselen)
CtrlZ | Ongedaan maken

De sneltoetsen voor de afspeellijstbrowser zijn:

Toetsencombinatie | Actie
--- | ---
Spatie | Afspeellijst laden
F2 | Afspeellijst hernoemen
Backspace | Afspeellijst verwijderen

## De DCOP-interface

De DCOP-interface van Amarok biedt u een eenvoudige manier om Amarok met behulp van uw eigen aangepaste scripts te besturen.

De DCOP-interface van Amarok heeft vele algemene aanroepen die ook in andere KDE-programma's gevonden kunnen worden. Deze sectie is opgedeeld in zes tabellen en bedoeld om de DCOP-aanroepen van de collectie, contextbrowser, speler, afspeellijst, afspeellijstbrowser en scripts te beschrijven. Een voorbeeld van de DCOP-aanroep voor pauzeren ziet er als volgt uit:

&percnt;dcop amarok player pause

### dcop amarok collection

DCOP-aanroep | Actie
--- | ---
int totalAlbums() | Geeft het totaal aantal albums in de collectie terug.
int totalArtists() | Geeft het totaal aantal artiesten in de collectie terug.
int totalCompilations() | Geeft het totaal aantal verzamelalbums in de collectie terug.
int totalGenres() | Geeft het totaal aantal genres in de collectie terug.
int totalTracks() | Geeft het totaal aantal tracks in de collectie terug.
QString query( QString sql) | Voert een query op de database uit via SQL.
QStringList similarArtists( int artists ) | Geeft vergelijkbare artiesten terug voor de huidige tracks, beperkt tot int artists.
void migrateFile( QString oldURL, QString newURL ) | Verplaatst een bestand binnen de collectie, waarbij de statistieken intact blijven.
void scanCollection() | Doorzoekt de collectie.
void scanCollectionChanges() | Doorzoekt de collectie alleen op wijzigingen.

### dcop amarok contextbrowser

DCOP-aanroep | Actie
--- | ---
void showCurrentTrack() | Toont de huidige track in de contextbrowser.
void showLyrics() | Toont tabblad 'Liedteksten' in de contextbrowser.
void showWiki() | Toont tabblad 'Artiest' in de contextbrowser.

### dcop amarok player

DCOP-aanroep | Actie
--- | ---
bool dynamicModeStatus() | Geeft de status terug van de dynamische modus.
bool equalizerEnabled() | Geeft de status van de equalizer terug.
bool isPlaying() | Geeft 'true' terug als er nu iets wordt afgespeeld.
bool randomModeStatus() | Geeft de status van willekeurige modus terug.
bool repeatPlaylistStatus() | Geeft de status van afspeellijst herhalen terug.
bool repeatTrackStatus() | Geeft de status van track herhalen terug.
int getVolume() | Geeft het volume terug in de waarde 0-100%.
int sampleRate() | Geeft de sample rate terug van de track die momenteel wordt afgespeeld.
int score() | Geeft de score terug van de track die momenteel wordt afgespeeld.
int status() | Geeft de status van het afspelen terug: 0 - gestopt, 1 - gepauzeerd, 2 - speelt af.
int trackCurrentTime() | Geeft de huidige afspeelpositie in seconden terug.
int trackPlayCounter() | Geeft de afspeelteller voor de huidige track terug.
int trackTotalTime() | Geeft de tracklengte in seconden terug.
QString album() | Geeft het album van de momenteel afgespeelde track terug.
QString artist() | Geeft de artiest terug van de momenteel afgespeelde track.
QString bitrate() | Geeft de bitrate van de momenteel afgespeelde track terug (XX kbps).
QString comment() | Geeft het commentaar van de momenteel afgespeelde track terug.
QString coverImage() | Geeft het URL-adres van de hoesafbeelding van de huidige track terug
QString currentTime() | Geeft de positie ([u]mm:ss) van de momenteel afgespeelde track terug.
QString encodedURL() | Geeft het gecodeerde URL-adres van de momenteel afgespeelde track terug.
QString engine() | Geeft huidige geluidsengine terug.
QString genre() | Geeft het genre van de momenteel afgespeelde track terug.
QString lyrics() | Geeft de liedteksten van de momenteel afgespeelde track terug.
QString lyricsByPath( QString path ) | Geeft de liedteksten van een track terug op het pad.
QString nowPlaying() | De titel van de nu afgespeelde media.
QString path() | Geeft het niet-gecodeerde pad terug van de momenteel afgespeelde track.
QString setContextStyle( QString ) | Zet de CSS-stijl van de contextbrowser.
QString title() | Geeft de titel van de momenteel afgespeelde track terug.
QString totalTime() | Geeft de totale lengte van de momenteel afgespeelde track terug (in de opmaak [u:]mm:ss).
QString track() | Geeft het tracknummer terug.
QString type() | Geeft het bestandstype terug.
QString year() | Geeft het jaar van de momenteel afgespeelde track terug.
void configEqualizer() | Opent/sluit de configuratiedialoog van de equalizer.
void enableDynamicMode(bool enable) | Zet de dynamische modus aan of uit.
void enableOSD(bool enable) | Zet de OSD-weergave aan of uit.
void enableRandomMode(bool enable) | Zet de willekeurige modus aan of uit.
void enableRepeatPlaylist(bool enable) | Zet het herhalen van de afspeellijst aan of uit.
void enableRepeatTrack(bool enable) | Zet herhalen van de track aan of uit.
void mediaDeviceMount() | Zet het commando voor het aankoppelen (mounten) van een media-apparaat.
void mediaDeviceUmount() | Zet het commando voor het afkoppelen (unmount) van een media-apparaat.
void mute() | Zet het dempen aan of uit.
void next() | Staat gelijk aan het drukken op de knop "Volgende".
void pause() | Staat gelijk aan het drukken op de knop "Pauze".
void play() | Staat gelijk aan het drukken op de knop "Afspelen".
void playPause() | Schakelt de status voor afspelen/pauze om (bedoeld voor gebruikers van multimediatoetsenborden)
void prev() | Staat gelijk aan het drukken op de knop "Vorige".
void queueForTransfer( KURL url ) | Plaats bestand in de wachtrij voor overdracht naar media-apparaat.
void seek(int s) | Spoel door de track tot de positie in seconden.
void seekRelative(int s) | Spoel door een track tot een positie die relatief is aan de huidige trackpositie.
void setEqualizer(int, int, int, int, int, int, int, int, int, int, int) | Zet de equalizerkanalen
void setEqualizerEnabled( bool active ) | Equalizer aan/uit.
void setEqualizerPreset( QString name ) | Zet de voorinstelling van de equalizer
void setLyricsByPath( QString url, QString lyrics ) | Zet de liedteksten van een track aan de hand van diens pad.
void setScore( int score ) | Zet de score van de momenteel afgespeelde track.
void setScoreByPath( QString url, int score ) | Zet de score van een track aan de hand van diens pad.
void setVolume(int volume) | Zet het volume in een bereik van 0-100%.
void showBrowser( QString browser ) | Toont browsers in het afspeellijstvenster
void showOSD() | Toont de onscreendisplay op het beeldscherm.
void stop() | Gelijk aan het klikken op de knop "Stop".
void transferDeviceFiles() | Schrijft bestanden naar het media-apparaat.
void volumeDown() | Verlaagt het volumeniveau met een acceptabele stap.
void volumeUp() | Verhoogt het volumeniveau met een acceptabele stap.

### dcop amarok playlist

DCOP-aanroep | Actie
--- | ---
int getActiveIndex() | Geeft de index terug van de momenteel afgespeelde track. -1 indien geen.
int getTotalTrackCount() | Geeft het aantal tracks in de afspeellijst terug. 0 indien geen.
QString saveCurrentPlaylist() | Slaat de huidige afspeellijst op naar current.xml en geeft het pad ervan terug.
void addMedia( KURL ) | Voegt geluidsmedia toe, opgegeven bij het url-adres.
void addMediaList( KURL::List ) | Voegt enkele geluidsmedia toe, opgegeven door het URL-adres.
void clearPlaylist() | Wist de afspeellijst.
void playByIndex(int) | Start het spelen van de track bij de opgegeven index.
void playMedia( KURL ) | Voegt geluidsmedia toe, opgegeven bij het url-adres.
void popupMessage( QString) | Toont een tijdelijk bericht.
void removeCurrentTrack() | Verwijdert de huidige track uit de afspeellijst.
void repopulate() | Vult de afspeellijst opnieuw met willekeurige tracks.
void saveM3u( QString path, bool relativePaths) | Slaat de huidige afspeellijst op als m3u.
void setStopAfterCurrent( bool ) | Activeert/deactiveert de functie "Stoppen na huidige track".
void shortStatusMessage( QString) | Toont een tijdelijk bericht op de statusbalk.
void shufflePlaylist() | Haalt de afspeellijst door elkaar.
void togglePlaylist() | Opent/sluit het afspeellijstvenster.

### dcop amarok playlistbrowser

DCOP-aanroep | Actie
--- | ---
void addPodcast( QString ) | Voegt een podcast-item toe aan de afspeellijstbrowser.
void scanPodcasts() | Doorzoekt alle podcasts voor nieuwe versies.
void addPlaylist( QString ) | Voegt een afspeellijst toe aan de afspeellijstbrowser.

### dcop amarok script

DCOP-aanroep | Actie
--- | ---
bool runScript( QString name) | Start het script met de opgegeven naam. Geeft 'true' terug bij succes.
bool stopScript( QString name) | Stopt het script met de opgegeven naam. Geeft 'true' terug bij succes.
QStringList listRunningScripts() | Geeft een lijst terug van alle momenteel draaiende scripts.
void addCustomMenuItem(QString submenu, QString itemTitle ) | Activeert een aangepast menuoptie en stelt de titel ervan in.
void removeCustomMenuItem(QString submenu, QString itemTitle ) | Verwijdert een aangepaste menuoptie.
QString readConfig( QString key) | Geeft de waarde van een AmarokConfig configuratie-item terug van de opgegeven toets.

## Commandoprompt-opties

Naast de standaard-commando's van Qt en KDE heeft Amarok ook zijn eigen opties.

Opties van Qt en KDE:

Optie | Actie
--- | ---
--help | Toont een samenvatting van opties die vanaf de prompt kunnen worden meegegeven aan het commando.
--help-qt | Toont een lijst met Qt-specifieke opties.
--help-kde | Toont een lijst met KDE-specifieke opties.
--help-all | Toont een lijst met alle opties.
--author | Toont informatie over de auteur.
-v, --version | Toont versie-informatie.
--license | Toont informatie over de licentie.

De opties van Amarok:

De &amarok;-opties kunnen ook worden gebruikt als &amarok; al draait.

Optie | Actie
--- | ---
-r, --previous | Gaat naar de vorige track in de afspeellijst.
-p, --play | Start het afspelen van de huidige afspeellijst.
-s, --stop | Stopt het afspelen.
--pause | Pauzeert het afspelen.
-f, --next | Gaat naar de volgende track in de afspeellijst.
-a, --append | Voegt bestanden/URL-adressen toe aan de afspeellijst.
-e, --enqueue | Zie append, beschikbaar voor neerwaartse compatibiliteit.
--queue | Plaatst bestanden/URL-adressen in de wachtrij achter de huidige afgespeelde track.
-m, --toggle-playlist-window | Opent/sluit het afspeellijstvenster.
--wizard | Start de Configuratie-assistent.
--engine "naam" | Start &amarok; met de engine "naam".

## Scripts schrijven

Met scripting kunt u &amarok; op eenvoudige wijze uitbreiden zonder dat u de broncode van het programma zelf hoeft te wijzigen. Scripts kunt u vergelijken met plugins, met als verschil dat er geen gebruik wordt gemaakt van een 'dedicated plugin API', maar van &amarok;'s DCOP-interface voor de communicatie. Dit maakt het mogelijk om scripts te schrijven in vrijwel elke programmeertaal, zoals Ruby, Python of PHP. U kunt niet alleen scripts schrijven in klassieke scripttalen, maar ook in gecompileerde talen zoals C++ of C. Aanvullend kan &amarok; de scripts waarschuwen bij speciale gebeurtenissen en ze hierop laten reageren. Dit waarschuwingssysteem zal later in deze sectie worden uitgelegd.

### Bindingen

U kunt eenvoudige scripts schrijven die geen interactie van de gebruiker nodig hebben, en scripts schrijven met comfortabele GUI's die zelf als een volwaardig programma reageren. Voor het programmeren van een GUI kunt u gebruik maken van één van de vele bindingen die KDE levert, zoals RubyQt, een Qt-bibliotheekbinding voor Ruby. Een nadeel van bindingen is dat niet iedere gebruiker ze allemaal hebben geïnstalleerd. Als u dus een binding wilt gebruiken, kies er dan een die vrij goed verspreid is, zoals RubyQt of PyQt.

Om enige informatie te ontvangen als een script niet kan draaien vanwege een ontbrekende afhankelijkheid, laat uw script controleren of de module die u wilt insluiten echt bestaat. Als de afhankelijkheid ontbreekt, dan moet u de foutmelding opvangen en met behulp van het commandoregelprogramma "kdialog" in een informatiedialoog laten weergeven. De gebruiker kan dan zien waarom het script niet wil draaien.

Dit voorbeeld laat zien hoe u een ontbrekende afhankelijkheid in Ruby kunt opvangen:

    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

### Het begin: de sjablonen

In de map `scripts/templates/` van &amarok; vindt u enkele scriptsjablonen voor diverse talen. U kunt deze scripts gebruiken als basis voor uw eigen scripts en ze uitbreiden met de functionaliteit die u nodig hebt. U zult merken dat het schrijven van scripts vrij eenvoudig is. Bijvoorbeeld als u een beetje weet van programmeren in Python, dan zal het schrijven van uw eigen script niet veel moeite kosten.

### &amarok; besturen met DCOP

Scripts kunnen Amarok besturen door enkel van zijn DCOP-functies aan te roepen. De eenvoudigste manier om een DCOP-functie aan te roepen is met behulp van het commandoregelprogramma "dcop". Dit programma is onderdeel van elke KDE-distributie.

Hier is een voorbeeld voor het verhogen van het hoofdvolume:

    dcop amarok player volumeUp

Met de meeste scripttalen kunt u externe programma's uitvoeren met een functie als exec(). Op deze manier kan het programma "dcop" eenvoudig worden aangeroepen. Hier is een klein voorbeeld in Python:

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

### Waarschuwingen

&amarok; stuurt waarschuwingen naar alle draaiende scripts door tekenreeksen naar hun stdin-kanaal te schrijven. Het script moet daarom constant stdin volgen, en reageren op elke mogelijke gebeurtenis. Scripts kunnen er ook voor kiezen om gebeurtenissen die ze niet kunnen gebruiken te negeren.

De volgende waarschuwingen worden door &amarok; verzonden:

    configure
    vertelt het script om zijn configuratiedialoog te tonen. Het script moet
    de configuratie-opties zelf opslaan en laden. Als een script wordt gestart
    zet Amarok de werkmap ervan op de map waarin alle gegevens moeten
    worden opgeslagen.

    engineStateChange:empty|idle|paused|playing
    signaleert een wijziging in de status van de engine.

    trackChange
    signaleert de start van een nieuwe track. Het script kan dan de DCOP-functies
    gebruiken om verdere informatie over de track op te vragen, zoals metadata
     en de lengte.

    volumeChangenewVolume
    signaleert een wijziging in het niveau van het hoofdvolume. Het volume is een heel getal in het bereik
    van 0-100.

    customMenuClicked:submenu itemTitle paths
    geeft het pad naar de geselecteerde bestanden in de afspeellijst als de
    aangepaste optie in het contextmenu van de afspeellijst wordt aangeklikt. Het submenu
    en item-titel worden ook gegeven voor identificatiedoeleinden in het geval een script naar
    meerdere notificaties luistert.
    Om een aangepaste optie toe te voegen aan het contextmenu gebruikt u de DCOP-aanroep
    'dcop amarok script addCustomMenuItem( submenu itemTitle ). Om een optie uit het contextmenu
    te verwijderen gebruikt u de DCOP-aanroep
    'dcop amarok script removeCustomMenuItem( submenu itemTitle )'.

### Scriptterminatie

Voordat &amarok; afsluit, of als de gebruiker een script stopt met de Scriptbeheerder, stuurt &amarok; het signaal SIGTERM naar het script. Dit signaal kan worden opgevangen om wat schoonmaakwerk uit te voeren, zoals het opslaan van gegevens of configuratie-instellingen.

### Packaging

&amarok;'s Scriptbeheerder kan scriptpakketten installeren die de gebruiker heeft gedownload van een webserver. Pakketten zijn gewoon normale tar-archieven (.tar), optioneel gecomprimeerd met bzip2 (.bz2). Wij adviseren het gebruik van bestandsnamen als myscript.amarokscript.tar.bz2, zodat de gebruiker het pakket meteen kan identificeren als een amarok-script.

&amarok; 1.3 zal alleen scriptpakketten accepteren met de amarokscript-extensie.

De inhoud van de tar-archieven moet als volgt zijn georganiseerd:

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

### Bestandstoegangsrechten

Het hoofdscript moet de uitvoerrechten ingesteld hebben (+x), terwijl aanvullende modules die het script laat niet uitvoerbaar moeten zijn. Om de bestandstoegangsrechten in het tar-archieven te behouden gebruikt u tar met de vlag '-p':

    tar -cf myscript.amarokscript.tar -p myscript

&amarok; kan het script niet installeren als de toegangsrechten niet correct zijn ingesteld.

### Distribueren

Als het pakket klaar is kunt u het uploaden naar www.kde-apps.org en de hyperlink toevoegen aan &amarok;'s Wiki Scripts Page. Bij kde-apps.org toevoegt u het script toe aan de categorie &amarok; Scripts.