# 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 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 bedoeld om de DCOP-aanroepen van de collectie, speler, afspeellijst en scripts te beschrijven. Een voorbeeld van de DCOP-aanroep pauzeren ziet er als volgt uit:

&percnt;dcop amarok player pause

### dcop amarok collection

DCOP-aanroep | Actie
--- | ---
query | Met de aanroep query kunt u rechtstreeks database-queries naar &amarok;'s collectie sturen.
scanCollection | De aanroep scanCollection voert een handmatige scan uit op uw collectie.
scanCollectionChanges | De aanroep scanCollectionChanges voert een handmatige scan uit voor wijzigingen in uw collectie.
similarArtists | De aanroep similarArtists geeft de vergelijkbare artiest voor de huidige track terug. De resultaten worden beperkt tot een integere waarde van artists
totalAlbums | De aanroep totalAlbums geeft het totaal aantal albums in uw collectie terug.
totalArtists | De aanroep totalArtists geeft het totaal aantal artiesten in uw collectie terug.
totalCompilations | De aanroep totalCompilations geeft het totaal aantal verzamelalbums in uw collectie terug.
totalGenres | De aanroep totalGenres geeft het totaal aantal genres in uw collectie terug.
totalTracks | De aanroep totalTracks geeft het totaal aantal tracks in uw collectie terug.

### dcop amarok player

DCOP-aanroep | Actie
--- | ---
album | De aanroep album geeft het album van de huidige afgespeelde track terug.
artist | De aanroep artist geeft de artiest van de huidige afgespeelde track terug.
bitrate | De aanroep bitrate geeft de bitrate van de huidige afgespeelde track terug.
comment | De aanroep comment geeft het commentaar van de huidige afgespeelde track terug.
coverImage | De aanroep coverImage geeft het URL-adres van de hoesafbeelding van de huidige track terug.
currentTime | De aanroep currentTime geeft de positie (mm:ss) van de huidige afgespeelde track terug.
encodedURL | De aanroep encodedURL geeft het URL-adres van de huidige afgespeelde track terug, met de spaties gecodeerd.
engine | De aanroep engine huidige geluidsengine terug.
genre | De aanroep genre geeft het genre van de huidige afgespeelde track terug.
lyrics | De aanroep lyrics geeft de gecachte liedteksten van de momenteel afgespeelde track terug.
lyricsByPath | De aanroep lyricsByPathgeeft de gecachte liedteksten van een track terug, welke is opgegeven met diens pad.
nowPlaying | De aanroep nowPlaying geeft Artiest - Titel van de huidige afgespeelde track terug. Als één van de id3-tags leeg is, dan wordt alleen Artiest of Titel teruggegeven (zonder de -).
path | De aanroep path geeft het pad op het bestandsysteem naar de huidige track terug.
setContextStyle | De aanroep setContextStyle stelt het CSS-thema van de Contextbrowser in aan de hand van de opgegeven naam.
title | De aanroep title geeft de titel van de huidige afgespeelde track terug.
totalTime | De aanroep totalTime geeft de totale tijd (mm:ss) van de huidige afgespeelde track terug.
track | De aanroep track geeft het nummer van de huidige afgespeelde track terug.
year | De aanroep year geeft het jaar van de huidige afgespeelde track terug.
dynamicModeStatus | De aanroep dynamicModeStatus geeft de boleaanse waarde true (waar) of false (onwaar) terug om aan te geven of de dynamische modus actief is of niet.
equalizerEnabled | De aanroep equalizerEnabled geeft de waarde true of false (waar of onwaar) terug om aan te geven of de equalizer actief is of niet.
isPlaying | De aanroep isPlaying geeft de boleaanse waarde true (waar) of false (onwaar) terug als de speler resp. wel of niet aan het afspelen is.
randomModeStatus | De aanroep randomModeStatus geeft de status van de willekeurig-modus terug als true (waar) of false (onwaar).
repeatPlaylistStatus | De aanroep repeatPlaylistStatus geeft de status van de afspeelijstherhaling terug als true (waar) of false (onwaar).
repeatTrackStatus | De aanroep repeatTrackStatus geeft de status van de trackherhaling terug als true (waar) of false (onwaar).
getVolume | De aanroep getVolume geeft een waarde tussen de 0 en 100 voor het volumeniveau terug.
sampleRate | De aanroep sampleRate geeft de sample rate van de huidige afgespeelde track terug.
score | De aanroep score geeft de score van de huidige track terug.
setLyricsByPath | De aanroep setLyricsByPath zet de liedteksten van een track opgegeven bij diens pad. Gebruik de aanroep lyrics om voorbeelden van de juiste HTML-opmaak te bekijken.
status | De aanroep status geeft een waarde terug voor de engine-status: 2 voor afspelend, 1 voor gepauzeerd en 0 voor inactief.
trackCurrentTime | De aanroep trackCurrentTime geeft een waarde in seconden voor de resterende tijd van de huidige afgespeelde track terug.
trackPlayCounter | De aanroep trackPlayCounter geeft het aantal keer dat de huidige track is afgespeeld terug.
trackTotalTime | De aanroep trackTotalTime geeft een waarde in seconden terug voor de totale tijd van de track.
configEqualizer | De aanroep configEqualizer opent het configuratievenster van de equalizer.
enableDynamicMode | De aanroep enableDynamicMode wordt gebruikt om de dynamische modus aan of uit te zetten. De waarde 0 schakelt hem uit, de waarde 1 schakelt hem in.
enableOSD | Met de aanroep enableOSD kunt u de On Screen Display aan- of uitzetten door de waarde true (waar) of false (onwaar) mee te geven.
enableRandomMode | De aanroep enableRandomMode wordt gebruikt om de willekeurige modus aan of uit te zetten. De waarde 0 schakelt hem uit, de waarde 1 schakelt hem in.
enableRepeatPlaylist | De aanroep enableRepeatPlaylist wordt gebruikt om het herhalen van de afspeellijst aan of uit te zetten. De waarde 0 schakelt hem uit, de waarde 1 schakelt hem in.
enableRepeatTrack | De aanroep enableRepeatTrack wordt gebruikt om het herhalen van de track aan of uit te zetten. De waarde 0 schakelt hem uit, de waarde 1 schakelt hem in.
mute | Met de aanroep mute kunt u het geluid dempen of activeren.
next | De aanroep next laat de speler naar de volgende track gaan.
pause | De aanroep pause laat de huidige afgespeelde track pauzeren.
play | De aanroep play start de speler vanaf de positie waar hij de laatste keer is gestopt.
playPause | De aanroep playPause start de speler als hij is gestopt, of gepauzeerd. De aanroep laat de speler pauzeren als er momenteel een track wordt afgespeeld.
prev | De aanroep prev laat de speler een track terug gaan.
seek | De aanroep seek wordt gebruikt om een specifiek punt in een track op te zoeken. Dit punt kunt u specificeren met een waarde in seconden.
seekRelative | De aanroep seekRelative wordt gebruikt om te zoeken naar een positie relatief aan de huidige trackpositie, aan de hand van een in seconden opgegeven waarde.

setEqualizer

De aanroep setEqualizer gebruikt elf door spaties gescheiden hele getallen om de waarden van de equalizer-schuifregelaars in te stellen. De waarden van de schuifregelaars liggen tussen -255 als laagste waarden en 255 als hoogste. Het eerste getal wordt gebruikt om de voorversterkwaarde in te stellen, de overige getallen stellen de voorversterk-frequentiewaarden van 60Hz tot 16kHz in.

setEqualizerEnabled | Met de aanroep setEqualizerEnabled kunt u via een true- of false-waarde de equalizer resp. aan- of uitzetten.
setScore | De aanroep setScore zet de score van de huidige track op de opgegeven waarde tussen de 0 en 100.
setScoreByPath | De aanroep SetScoreByPath zet de score van een track gespecificeerd aan de hand van diens pad, gevolgd door de score, opgegeven door een getal tussen de 0 en 100.
setVolume | De aanroep setVolume past het volume aan aan de opgegeven waarde tussen de 0 en 100.
showBrowser | De aanroep showBrowser toont een browser in het afspeellijstvenster. Geldige browserwaarden zijn context, collection, playlist, media en file.
showOSD | De aanroep showOSD opent de On-Screen-Display om de huidige trackinformatie te tonen.
stop | De aanroep stop stopt de speler als deze momenteel een track afspeelt.
volumeDown | De aanroep volumeDown zet het volumeniveau een stap lager.
volumeUp | De aanroep volumeUp zet het volumeniveau een stap hoger.

### dcop amarok playlist

DCOP-aanroep | Actie
--- | ---
saveCurrentPlaylist | De aanroep saveCurrentPlaylist slaat de huidige afspeellijst op als ~/.kde/share/apps/amarok/current.xml.
getActiveIndex | De aanroep getActiveIndex geeft een heel getal terug voor de positie van de huidige track in de afspeellijst.
getTotalTrackCount | De aanroep getTotalTrackCount geeft het totaal aantal tracks in de afspeellijst terug.
addMedia | De aanroep addMedia wordt gebruikt om een bestand toe te voegen aan de afspeellijst.
addMediaList | De aanroep addMediaList wordt gebruikt om meerdere bestanden toe te voegen aan de afspeellijst.
clearPlaylist | De aanroep clearPlaylist wordt gebruikt om de volledige afspeellijst te wissen.
playByIndex | De aanroep playByIndex begint het afspelen van een track aan de hand van diens positie in de afspeellijst.
playMedia | De aanroep playMEDIA start het afspelen van een track, gespecificeerd door diens KURL-adres.
popupMessage | De aanroep popupMessage opent een bericht in het afspeellijstvenster. Het berichtvenster wordt gespecificeerd door een QString.
repopulate | De aanroep repopulate vult de afspeellijst met tracks uit de dynamische modus.
removeCurrentTrack | De aanroep removeCurrentTrackverwijdert de huidige track uit de afspeelijst.
saveM3u | De aanroep saveM3u slaat de huidige afspeellijst op in het M3U-formaat. U dient het pad waar het bestand zal worden opgeslagen te specificeren en de waarde 0 of 1 in te sluiten om aan te geven of het een relatief pad betreft of niet.
setStopAfterCurrent | De aanroep setStopAfterCurrent stopt het afspelen van de afspeellijst nadat de huidige track is afgelopen.
shortStatusMessage | De aanroep shortStatusMessage toont een tekstbericht in de statusbalk.
shufflePlaylist | De aanroep shufflePlaylist schudt de tracks in de afspeellijst door elkaar.
togglePlaylist | De aanroep togglePlaylist opent het afpeellijstvenster, of sluit deze.

### dcop amarok script

DCOP-aanroep | Actie
--- | ---
listRunningScripts | De aanroep listRunningScripts geeft een lijst met alle draaiende &amarok;-scripts terug.
runScript | De aanroep runScript start het &amarok;-script dat is opgegeven met diens naam.
stopScript | De aanroep stopScript stopt het &amarok;-script dat is opgegeven met diens naam.
addCustomMenuItem | De aanroep addCustomMenuItem voegt een menuoptie toe aan het contextmenu van de afspeellijst. Deze aanroept neemt twee QStrings, de eerste voor de titel van het submenu, en de tweede voor de titel van de optie in het submenu. Beide QStrings worden teruggegeven in het notificatiesysteem van de scriptbeheerder.
removeCustomMenuItem | De aanroep removeCustomMenuItem verwijdert menuopties die zijn toegevoegd aan het contextmenu van de afspeellijst met behulp van de aanroep addCustomMenuItem. Deze aanroep gebruikt dezelfde QStrings als addCustomMenuItem.

## 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 laden en opslaan. 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 is 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.