# Avancerede amaroK-funktioner

## Genvejstaster

&amarok; bruger tastaturgenveje ligesom de fleste andre programmer. Nedenfor er der en liste af disse genveje og deres respektive handlinger. De globale genveje kan indstilles ved at højreklikke i afspillervinduet og vælge Indstil globale genveje... &amarok;'s genveje kan indstilles ved at højreklikke i afspillerevinduet og vælge Indstil genveje...

Du kan knytte dine multimedie-taster til at virke som genveje for &amarok; og derved gøre dit tastatur til et kontrolcenter for &amarok;.

De globale genveje er:

Tastekombination | Handling
--- | ---
WinX | Spil
WinC | Pause
WinV | Stop
WinB | Næste spor
WinZ | Forrige spor
WinKP_Add | Højere lydstyrke
WinKP_Subtract | Lavere lydstyrke
WinShiftKP_Add | Søg fremad
WinShiftKP_Subtract | Søg tilbage
WinA | Tilføj medie
WinP | Slå spilleliste til og fra
WinO | Vis OSD
WinM | Slå lyd fra

&amarok;'s genveje er:

Tastekombination | Handling
--- | ---
CtrlC | Kopiér
CtrlKP_Enter | Gå til nuværende
CtrlD | Sæt markerede spor i kø
CtrlQ | Afslut
CtrlShiftZ | Annullér fortryd
CtrlS | Gem spilleliste
CtrlA | Markér alle
CtrlM | Vis menulinje
CtrlH | Bland
CtrlZ | Fortryd

Spilleliste-browserens genveje er:

Tastekombination | Handling
--- | ---
Mellemrum | Indlæs spilleliste
F2 | Omdøb spilleliste
Backspace | Fjern spilleliste

## DCOP-Grænsefladen

amaroK's DCOP-grænseflade giver dig en nem måde at kontrollere amaroK med dine hjemmelavede scripter.

DCOP-grænsefladen i amaroK har mange generiske funktioner som også findes i andre KDE-programmer. Dette afsnit er opdelt i fire tabeller og er beregnet til at beskrive DCOP-kald for samlingen, afspilleren, spillelisten og scripter. Et eksempel på DCOP-funktionen pause vil se sådan her ud:

&percnt;dcop amarok player pause

### dcop amarok-samling

DCOP-kald | Handling
--- | ---
forespørgsel | Funktionen query lader dig sende direkte databaseforespørgsler til &amarok;s samling.
scanCollection | Funktionen scanCollection udfører en manuel gennemsøgning af din samling.
scanCollectionChanges | Funktionen scanCollectionChanges udfører en manuel gennemsøgning af ændringer i din samling.
similarArtists | Funktionen similarArtists returnerer lignende kunstnere for sporet som for øjeblikket spilles. Resultatet er begrænset til en heltalsværdi af kunstnere.
totalAlbums | Funktionen totalAlbums returnerer det totale antal albummer i din samling.
totalArtists | Funktionen totalArtists returnerer det totale antal kunstnere i din samling.
totalCompilations | Funktionen totalCompilations returnerer det totale antal samlingsalbummer i din samling.
totalGenres | Funktionen totalGenres returnerer det totale antal genrer i din samling.
totalTracks | Funktionen totalTracks returnerer det totale antal spor i din samling.

### dcop amarok player

DCOP-kald | Handling
--- | ---
album | Funktionen album returnerer albummet for sporet som for øjeblikket spilles.
artist | Funktionen artist returnerer kunstneren for sporet som for øjeblikket spilles.
bitrate | Funktionen bitrate returnerer bithastigheden for sporet som for øjeblikket spilles.
comment | Funktionen comment returnerer kommentaren for sporet som for øjeblikket spilles.
coverImage | Funktionen coverImage returnerer orl'en for nuværende spors omslag.
currentTime | Funktionen currentTime returnerer positionen (mm:ss) for sporet som for øjeblikket spilles.
encodedURL | Funktionen encodedURL returnerer url'en for nuværende spor med mellemrum kodede.
engine | Funktionen engine returnerer nuværende lydgrænseflade.
genre | Funktionen genre returnerer genren for sporet som for øjeblikket spilles.
lyrics | Funktionen lyrics returnerer cachet sangtekst for sporet som for øjeblikket spilles.
lyricsByPath | Funktionen lyricsByPath returnerer cachet sangtekst for et spor som angivet ved sin søgesti.
nowPlaying | Funktionen nowPlaying returnerer Kunstner - Titel for sporet som for øjeblikket spilles. Hvis et af de to ID3-mærker er tomt, vises kun Kunstner eller Titel (uden -).
path | Funktionen path returnerer filsystemets søgesti til nuværende spor.
setContextStyle | Funktionen setContextStyle indstiller sammenhængsbladrerens CSS-tema som angives ved sit navn.
title | Funktionen title returnerer titlen for sporet som for øjeblikket spilles.
totalTime | Funktionen totalTime returnerer den totale tid (mm:ss) for sporet som for øjeblikket spilles.
track | Funktionen track returnerer spornummer for nuværende spor.
year | Funktionen year returnerer året for sporet som for øjeblikket spilles.
dynamicModeStatus | Funktionen dynamicModeStatus returnerer en værdi som er sand eller falsk for at angive om dynamisk tilstand er aktiveret.
equalizerEnabled | Funktionen equalizerEnabled returnerer en værdi som er sand eller falsk for at angive om equalizern er aktiveret.
isPlaying | Funktionen isPlaying returnerer en værdi som er sand eller falsk for at angive om afspilleren spiller noget eller ej.
randomModeStatus | Funktionen randomModeStatus returnerer status for tilfældig tilstand med værdien sand eller falsk.
repeatPlaylistStatus | Funktionen repeatPlaylistStatus returnerer status for gentagelse af spilleliste med værdien sand eller falsk.
repeatTrackStatus | Funktionen repeatTrackStatus returnerer status for gentagelse af spor med værdien sand eller falsk.
getVolume | Funktionen getVolume returnerer en værdi af lydstyrken som angives med en værdi fra 0 til 100.
sampleRate | Funktionen sampleRate returnerer samplingsfrekvensen for nuværende spor.
scoring | Funktionen score returnerer nuværende spors scoring.
setLyricsByPath | Funktionen setLyricsByPath indstiller et spors sangtekst som angives med søgesti. Brug funktionen lyrics til at se eksempler på rigtig formatering af HTML.
status | Funktionen status returnerer en værdi for grænsefladens status. Afspilning angives med 2, pause angives med 1 og tomgang angives med 0.
trackCurrentTime | Funktionen trackCurrentTime returnerer en værdi på nuværende gået tid i sekunder.
trackPlayCounter | Funktionen trackPlayCounter returnerer antal gang nuværende spor har været spillet.
trackTotalTime | Funktionen trackTotalTime returnerer en værdi for nuværende spors totale tid i sekunder.
configEqualizer | Funktionen configEqualizer viser indstillingsvinduet for equalizeren.
enableDynamicMode | Funktionen enableDynamicMode bruges til at skifte dynamisk tilstand med værdien 0 for deaktiveret og 1 for aktiveret.
enableOSD | Funktionen enableOSD lader dig skifte skærmvisningen med en sand eller falsk værdi.
enableRandomMode | Funktionen enableRandomMode bruges til at skifte tilfældig tilstand med værdien 0 for deaktiveret og 1 for aktiveret.
enableRepeatPlaylist | Funktionen enableRepeatPlaylist bruges for at skifte tilstanden for at gentage spillelisten med værdien 0 for deaktiveret og 1 for aktiveret.
enableRepeatTrack | Funktionen enableRepeatTrack bruges til at skifte tilstanden for at gentage spor med værdien 0 for deaktiveret og 1 for aktiveret.
mute | Funktionen mute lader dig slå fra og til for lyd for sporet som for øjeblikket spilles.
next | Funktionen next går et spor fremad i afspilleren.
pause | Funktionen pause holder pause for sporet som for øjeblikket spilles.
play | Funktionen play starter afspilleren hvor den senest stoppede.
playPause | Funktionen playPause starter afspilleren hvis den for øjeblikket er i tilstanden stop eller pause. Funktionen holder også pause hvis afspilleren for øjeblikket spiller et spor.
prev | Funktionen prev går et spor tilbage i afspilleren.
seek | Funktionen seek bruges til at søge til en bestemt position i et spor med en værdi som angives i sekunder.
seekRelative | Funktionen seekRelative bruges til at søge til en position relativt til sporets nuværende position med en værdi som angives i sekunder.
setEqualizer | Funktionen setEqualizer bruger elleve heltal afgrænsede med mellemrum for at indstille equalizerens værdier. Skyderens værdier går fra -255 som mindste værdi til 255 som største. Det første heltal bruges til at indstille forforstærkerens værdi, og de tilbageværende heltal indstiller værdier på forforstærkerens frekvensværdier fra 60 Hz til 16 kHz.
setEqualizerEnabled | Funktionen setEqualizerEnabled bruges til at aktivere equalizeren med en sand eller falsk værdi.
setScore | Funktionen setScore indstiller nuværende spors scoring som angives med en værdi fra 0 til 100.
setScoreByPath | Funktionen setScoreByPath indstiller scoring for et spor som angives med søgesti, fulgt af scoring angivet som et tal fra 0 til 100.
setVolume | Funktionen setVolume justerer lydstyrken til et niveau som angives med en værdi fra 0 til 100.
showBrowser | Funktionen showBrowser viser en browser i spillelistens vindue. Gyldige værdier for browseren er context, collection, playlist, media og file.
showOSD | Funktionen showOSD aktiverer skærmvisningen for at vise information om nuværende spor.
stop | Funktionen stop stopper afspilleren hvis den for øjeblikket afspiller noget.
volumeDown | Funktionen volumeDown justerer lydstyrken nedad et skridt.
volumeUp | Funktionen volumeUp justerer lydstyrken opad et skridt.

### dcop amarok playlist

DCOP-kald | Handling
--- | ---
saveCurrentPlaylist | Funktionen saveCurrentPlaylist gemmer den nuværende spilleliste som ~/.kde/share/apps/amarok/current.xml.
getActiveIndex | Funktionen getActiveIndex returnerer en heltalsværdi for nuværende spors position i spillelisten.
getTotalTrackCount | Funktionen getTotalTrackCount returnerer det totale antal spor i spillelisten.
addMedia | Funktionen addMedia bruges til at tilføje enkelte filer i spillelisten.
addMediaList | Funktionen addMediaList bruges til at tilføje flere filer i spillelisten.
clearPlaylist | Funktionen clearPlaylist bruges til at rydde hele spillelisten.
playByIndex | Funktionen playByIndex starter afspilning af et spor med dets position i spillelisten.
playMedia | Funktionen playMEDIA starter afspilning af et spor som angives af en url.
popupMessage | Funktionen popupMessage viser en meddelelse i spillelistens vindue. Meddelelsen angives med en QString.
repopulate | Funktionen repopulate fylder spillelisten med spor fra dynamisk tilstand igen.
removeCurrentTrack | Funktionen removeCurrentTrack fjerner nuværende spor fra spillelisten.
saveM3u | Funktionen saveM3u gemmer nuværende spilleliste med formatet M3U. Du skal angive søgestien som filen skal gemmes som, og inkludere værdien 0 eller 1 for at angive om relative søgestier skal skrives eller ej.
setStopAfterCurrent | Funktionen setStopAfterCurrent stopper afspilning af spillelisten efter det nuværende spor er færdigt.
shortStatusMessage | Funktionen shortStatusMessage viser en tekststreng som en meddelelse i statuslinjen.
shufflePlaylist | Funktionen shufflePlaylist gør rækkefølgen af spor i spillelisten tilfældig.
togglePlaylist | Funktionen togglePlaylist ændrer visning af spillelistevinduet, enten til eller fra.

### dcop amarok script

DCOP-kald | Handling
--- | ---
listRunningScripts | Funktionen listRunningScripts lister alle scripter som kører i &amarok;.
runScript | Funktionen runScript starter et script i &amarok; som angivet ved sit navn.
stopScript | Funktionen stopScript stopper et script i &amarok; som angivet ved sit navn.
addCustomMenuItem | Funktionen addCustomMenuItem tilføjer et menupunkt til spillelistens den sammenhængsafhængige menu. Kaldet kræver to QString-parametre, den første for undermenuens navn og den anden for punktets navn i undermenuen. Begge parametre returneres i scripthåndteringens underretningssystem.
removeCustomMenuItem | Funktionen removeCustomMenuItem fjerner menupunkter som blev tilføjet til spillelistens sammenhængsafhængige menu med funktionen addCustomMenuItem. Kaldet bruger samme QString-parametre som addCustomMenuItem.

## Kommandolinje-tilvalg

amaroK understøtter brugen Qt's og kde's standard kommandolinjeflag. amaroK har også sine egne programspecifikke flag.

Qt og kde flag:

Tilvalg | Handling
--- | ---
--help | Vis hjælp om flag.
--help-qt | Vis Qt-specifikke flag.
--help-kde | Vis KDE-specifikke flag.
--help-all | is alle flag.
--author | Vis udviklerinformation.
-v, --version | Vis versionsinformation.
--license | Vis licensinformation.

amaroK-tilvalg:

amarok's flag er designet til at blive brugt mens amaroK kører.

Tilvalg | Handling
--- | ---
-r, --previous | Spring over forrige spor på spillelisten.
-p, --play | Start med af spille den nuværende spilleliste.
-s, --stop | Stop afspilning.
--pause | Hold pause i afspilning.
-f, --next | Spring over det næste spor på spillelisten.
-a, --append | Vedlæg filer/URL'er i spillelisten.
-e, --enqueue | Se append, tilgængelig for bagudkompatibilitet.
--queue | Sætter filer/URL'er i kø efter det spor der afspilles nu.
-m, --toggle-playlist-window | Slå spillelistens vindue til og fra.
--wizard | Start førstekørselsguide.
--engine "navn" | Start &amarok; med "navn"-motoren.

## Skrive scripter

At skrive scripter tillader dig nemt at udvide &amarok; uden at ændre den egentlige kodebase. Scripter ligner plugin, men i stedet for en særlig programmeringsgrænseflade bruger de &amarok;s DCOP-grænseflade til kommunikation. Det gør det muligt at skrive scripter i næsten hvilket som helst programsprog, såsom Ruby, Python eller PHP. Du kan ikke kun oprette scripter med klassiske scriptsprog, men også med kompilerede sprog såsom C++ eller almindelig C. Desuden kan &amarok; underrette scripter om særlige begivenheder og få dem til at reagere i overensstemmelse med dem. Systemet med underretninger forklares senere i afsnittet.

### Bindinger

Det er muligt at skrive enkle scripter som ikke kræver indblanding af brugeren, og det er også muligt at oprette scripter med bekvemme grafiske grænseflader som fungerer som små program i sig selv. For programmering af den grafiske grænseflade kan en af de mange bindinger som KDE sørger for bruges, for eksempel RubyQt, en binding til Qt-biblioteket for Ruby. Det er dog værd at notere at ikke alle brugere har installeret alle tilgængelige bindinger. Hvis du bestemmer dig for at bruge en binding, så forsøg at bruge en af dem som er relativt udbredte (f.eks. RubyQt eller PyQt).

For at give nogen tilbagemelding når et script mislykkes at køre på grund af en afhængighed som mangler, skal du kontrollere i scriptet om modulet du vil inkludere virkelig findes. Hvis afhængigheder mangler, bør du fange fejlen og vise en informationsdialog med kommandolinjeværktøjet "kdialog", så brugeren får rede på hvorfor scriptet mislykkes at køre.

Følgende eksempel viser hvordan en afhængighed som mangler kan fanges i Ruby:

    begin
           require 'Korundum'
    rescue LoadError
           error = 'Korundum (KDE-bindinger for Ruby) fra kdebindings v3.4 kræves af dette script.'
           `kdialog --sorry '#{error}'`
           exit
    end

### Kom i gang: Skabelonerne

&amarok; sørger for skabelonscripter for flere sprog i mappen `scripts/templates/`. Du kan bruge disse scripter som en basis for dine egne, og udvide dem med funktioner du behøver. Du vil bemærke at det i virkeligheden er ganske ligetil at skrive scripter. Hvis du for eksempel véd en del om hvordan man programmerer i Python, tager det ikke lang tid at oprette dit eget script.

### Kontrollér &amarok; med DCOP

Scripter kan styre amaroK ved at kalde visse af dets DCOP-funktioner. Den enkleste måde at udføre en DCOP-funktion er ved at bruge kommandolinjeværktøjet "dcop", som indgår i alle distributioner af KDE.

Her er et eksempel på hvordan hovedlydstyrken øges:

    dcop amarok player volumeUp

De fleste scriptsprog tillader at eksterne programmer køres, med en funktion såsom exec(). På den måde kan værktøjet "dcop" nemt kaldes. Her er et enkelt eksempel i Python:

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

### Underretninger

&amarok; sender underretninger til alle scripter som kører ved at skrive strenge til deres standardindtastning. Scripterne bør derfor hele tiden overvåge standardindtastningen og reagere på passende måde på hver af de mulige begivenheder. Scripter kan også vælge at ignorere alle begivenheder de ikke har nogen nytte af.

Følgende underretninger sendes af &amarok;:

    configure
    Fortæller scriptet at dets indstillingsdialog skal vises. Scriptet
    skal håndtere opbevaring og indlæsning af indstillingstilvalg selv.
    Når et script startes, indstiller amaroK dets arbejdsmappe til mappen
    hvor al data skal opbevares.

    engineStateChange:empty|idle|paused|playing
    Signalerer en ændring af grænsefladens tilstand.

    trackChange
    Signalerer start af et nyt spor. Scriptet kan derefter bruge DCOP-funktioner
    til at spørge efter yderligere information om sporet, f.eks. metadata og længde.

    volumeChangeny-volym
    Signalerer en ændring af hovedlydstyrken. Lydstyrken er et heltal i
    intervallet 0-100.

    customMenuClicked:undermenu objektnavn søgestier
    Returnerer søgestier til markerede filer i spillelisten når det egne tilvalg
    i spillelistens sammenhængsafhængige menu klikkes. Undermenuen og objektnavnet returneres
    også til identifikationsformål i tilfældet hvor et script lytter efter flere underretninger.
    Brug DCOP-kaldet 'dcop amarok script addCustomMenuItem( undermenu objektnavn )'
    til at indsætte et objekt i den sammenhængsafhængige menuen. Brug
    DCOP-kaldet 'dcop amarok script removeCustomMenuItem( undermenu objektnavn )'
    til at fjerne et objekt fra den sammenhængsafhængige menu.

### Afslutning af script

Inden &amarok; afsluttes, eller når brugeren stopper et script i scripthåndteringen, sender &amarok; signalet SIGTERM til scriptet. Signalet kan indfanges for at udføre oprensningsarbejde, såsom at gemme data eller indstillinger.

### Pakning

Scripthåndteringen i &amarok; kan installere scriptpakker som brugeren har hentet fra internettet. Pakker er blot normale arkiver (.tar), valgfrit komprimerede med bzip2 (.bz2). Vi anbefaler stærkt at bruge et filnavn såsom mit-script.amarokscript.tar.bz2, så brugeren let kan identificere pakken som et script for amaroK.

&amarok; 1.3 accepterer kun scriptpakker med filendelsen amarokscript, det er altså bedre at bruge det lige fra begyndelsen.

Filens indhold skal være organiseret på følgende vis:

    mit-script/
       README
       mit-script.py (kørbar fil)
       en-modul.py
       fil.data
       ...

### Filrettigheder

Hovedscriptet skal have kørerettigheder (+x) indstillede,mens yderligere moduler som scriptet indlæser ikke skal have kørerettigheder. For at bevare filrettigheder i arkivet, skal du bruge tar med flaget -p.

    tar -cf mitt-script.amarokscript.tar -p mit-script

&amarok; kan ikke installere scriptet hvis filrettighederne ikke er rigtigt indstillede.

### Distribution

Når pakken er klar, kan du overføre den til www.kde-apps.org og tilføje linket på &amarok;s Wiki scriptside. For indgangen i kde-apps skal du bruge kategorien &amarok; Scripter.