# Avancerade funktioner i amaroK

## Snabbtangenter

&amarok; använder snabbtangenter som de flesta andra program. Nedan finns en lista över dessa snabbtangenter och deras olika funktioner. De globala snabbtangenterna kan ställas in genom att högerklicka i spelarfönstret och välja Anpassa globala genvägar... Snabbtangenterna i &amarok; kan anpassas genom att högerklicka i spelarfönstret och välja Anpassa genvägar...

Du kan tilldela multimediatangenter att fungera som snabbtangenter i &amarok;, för att låta tangentbordet styra &amarok;.

De globala genvägarna är:

Tangentkombination | Åtgärd
--- | ---
WinX | Spela
WinC | Paus
WinV | Stanna
WinB | Nästa spår
WinZ | Föregående spår
WinNumeriskt tangentbord + | Öka volym
WinNumeriskt tangentbord - | Minska volym
WinSkiftnumeriskt + | Sök framåt
WinSkiftnumeriskt - | Sök bakåt
WinA | Lägg till media
WinP | Växla spellista
WinO | Aktivera skärmvisning
WinM | Tysta volym

Genvägarna i &amarok; är:

Tangentkombination | Åtgärd
--- | ---
CtrlC | Kopiera
CtrlNumeriskt tangentbord Enter | Gå till nuvarande
CtrlD | Köa markerade spår
CtrlQ | Avsluta
CtrlSkiftZ | Gör om
CtrlS | Spara spellista
CtrlA | Markera alla
CtrlM | Visa menyrad
CtrlH | Blanda
CtrlZ | Ångra

Spellistebläddrarens genvägar är:

Tangentkombination | Åtgärd
--- | ---
Mellanslag | Ladda spellista
F2 | Byt namn på spellista
Backsteg | Ta bort spellista

## DCOP-gränssnittet

AmaroKs DCOP-gränssnitt tillhandahåller ett enkelt sätt att styra amaroK med dina egna skript.

DCOP-gränssnittet i amaroK har många generella funktioner som också finns i andra KDE-program. Det här avsnittet är uppdelat i fyra tabller och är avsett att beskriva DCOP-anrop för samlingen, spelaren, spellistan och skript. Ett exempel på DCOP-funktionen pause skulle se ut så här:

&percnt;dcop amarok player pause

### dcop amarok collection

DCOP-anrop | Åtgärd
--- | ---
fråga | Funktionen query låter dig skicka direkta databasförfrågningar till &amarok;s samling.
scanCollection | Funktionen scanCollection utför en manuell avsökning av din samling.
scanCollectionChanges | Funktionen scanCollectionChanges utför en manuell avsökning av ändringar i din samling.
similarArtists | Funktionen similarArtists returnerar liknande artisten för spåret som för närvarande spelas. Resultatet är begränsat till ett heltalsvärde av artists.
totalAlbums | Funktionen totalAlbums returnerar det totala antalet album i din samling.
totalArtists | Funktionen totalArtists returnerar det totala antalet artister i din samling.
totalCompilations | Funktionen totalCompilations returnerar det totala antalet samlingsalbum i din samling.
totalGenres | Funktionen totalGenres returnerar det totala antalet genrer i din samling.
totalTracks | Funktionen totalTracks returnerar det totala antalet spår i din samling.

### dcop amarok player

DCOP-anrop | Åtgärd
--- | ---
album | Funktionen album returnerar albumet för spåret som för närvarande spelas.
artist | Funktionen artist returnerar artisten för spåret som för närvarande spelas.
bitrate | Funktionen bitrate returnerar bithastigheten för spåret som för närvarande spelas.
comment | Funktionen comment returnerar kommentaren för spåret som för närvarande spelas.
coverImage | Funktionen coverImage returnerar webbadressen till nuvarande spårs skivomslag.
currentTime | Funktionen currentTime returnerar positionen (mm:ss) för spåret som för närvarande spelas.
encodedURL | Funktionen encodedURL returnerar webbadressen för nuvarande spår med mellanslag kodade.
engine | Funktionen engine returnerar nuvarande ljudgränssnitt.
genre | Funktionen genre returnerar genren för spåret som för närvarande spelas.
lyrics | Funktionen lyrics returnerar cachad sångtext för spåret som för närvarande spelas.
lyricsByPath | Funktionen lyricsByPath returnerar cachad sångtext för ett spår som anges av sin sökväg.
nowPlaying | Funktionen nowPlaying returnerar Artist - Titel för spåret som för närvarande spelas. Om någon av de båda ID3-taggarna är tom, visas bara Artist eller Titel (utan -).
path | Funktionen path returnerar filsystemets sökväg till nuvarande spår.
setContextStyle | Funktionen setContextStyle ställer in sammanhangsbläddrarens CSS-tema som anges med sitt namn.
title | Funktionen title returnerar titeln för spåret som för närvarande spelas.
totalTime | Funktionen totalTime returnerar den totala tiden (mm:ss) för spåret som för närvarande spelas.
track | Funktionen track returnerar spårnummer för nuvarande spår.
year | Funktionen year returnerar året för spåret som för närvarande spelas.
dynamicModeStatus | Funktionen dynamicModeStatus returnerar ett värde som är sant eller falskt för att ange om dynamiskt läge är aktiverat.
equalizerEnabled | Funktionen equalizerEnabled returnerar ett värde som är sant eller falskt för att ange om equalizern är aktiverad.
isPlaying | Funktionen isPlaying returnerar ett värde som är sant eller falskt för att ange om spelaren spelar upp något eller inte.
randomModeStatus | Funktionen randomModeStatus returnerar status för slumpmässigt läge med värdet sant eller falskt.
repeatPlaylistStatus | Funktionen repeatPlaylistStatus returnerar status för upprepning av spellista med värdet sant eller falskt.
repeatTrackStatus | Funktionen repeatTrackStatus returnerar status för upprepning av spår med värdet sant eller falskt.
getVolume | Funktionen getVolume returnerar ett värde på volymen som anges med ett värde från 0 till 100.
sampleRate | Funktionen sampleRate returnerar samplingsfrekvensen för nuvarande spår.
poäng | Funktionen score returnerar nuvarande spårets poäng.
setLyricsByPath | Funktionen setLyricsByPath ställer in ett spårs sångtext som anges med sökväg. Använd funktionen lyrics för att se exempel på riktig formatering av HTML.
status | Funktionen status returnerar ett värde på gränssnittets status. Uppspelning anges med 2, paus anges med 1 och overksam anges med 0.
trackCurrentTime | Funktionen trackCurrentTime returnerar ett värde på nuvarande förfluten tid i sekunder.
trackPlayCounter | Funktionen trackPlayCounter returnerar antal gånger nuvarande spår har spelats.
trackTotalTime | Funktionen trackTotalTime returnerar ett värde på nuvarande spårs totala tid i sekunder.
configEqualizer | Funktionen configEqualizer visar inställningsfönstret för equalizern.
enableDynamicMode | Funktionen enableDynamicMode används för att växla dynamiskt läge med värdet 0 för inaktiverat och 1 för aktiverat.
enableOSD | Funktionen enableOSD låter dig växla skärmvisningen med ett sant eller falskt värde.
enableRandomMode | Funktionen enableRandomMode används för att växla slumpläget med värdet 0 för inaktiverat och 1 för aktiverat.
enableRepeatPlaylist | Funktionen enableRepeatPlaylist används för att växla läget för att upprepa spellistan med värdet 0 för inaktiverat och 1 för aktiverat.
enableRepeatTrack | Funktionen enableRepeatTrack används för att växla läget för att upprepa spår med värdet 0 för inaktiverat och 1 för aktiverat.
mute | Funktionen mute låter dig stänga av och sätta på ljudet för spåret som för närvarande spelas.
next | Funktionen next går framåt ett spår i spelaren.
pause | Funktionen pause gör paus för spåret som för närvarande spelas.
play | Funktionen play startar spelaren där den senast stoppades.
playPause | Funktionen playPause startar spelaren om den för närvarande är i läget stopp eller paus. Funktionen gör också paus om spelaren för närvarande spelar ett spår.
prev | Funktionen prev går bakåt ett spår i spelaren.
seek | Funktionen seek används för att söka till en viss position i ett spår med ett värde som anges i sekunder.
seekRelative | Funktionen seekRelative används för att söka till en position relativt till spårets nuvarande position med ett värde som anges i sekunder.
setEqualizer | Funktionen setEqualizer använder elva heltal avgränsade med mellanslag för att ställa in equalizerns värden. Skjutreglagens värden går från -255 som minsta värde till 255 som största. Det första heltalet används för att ställa in förförstärkarens värde, och återstående heltal ställer in värden på förförstärkarens frekvenssvar från 60 Hz till 16 kHz.
setEqualizerEnabled | Funktionen setEqualizerEnabled används för att aktivera equalizern med ett sant eller falskt värde.
setScore | Funktionen setScore ställer in nuvarande spårets poäng som anges med ett värde från 0 till 100.
setScoreByPath | Funktionen setScoreByPath ställer in poäng för ett spår som anges med sökväg, följt av pong angivet som ett tal från 0 till 100.
setVolume | Funktionen setVolume justerar volymen till en nivå som anges med ett värde från 0 till 100.
showBrowser | Funktionen showBrowser visar en bläddrare i spellistans fönster. Giltiga värden för bläddraren är context, collection, playlist, media och file.
showOSD | Funktionen showOSD aktiverar skärmvisningen för att visa information om nuvarande spår.
stop | Funktionen stop stoppar spelaren om den för närvarande spelar upp någonting.
volumeDown | Funktionen volumeDown justerar volymen neråt ett steg.
volumeUp | Funktionen volumeUp justerar volymen uppåt ett steg.

### dcop amarok playlist

DCOP-anrop | Åtgärd
--- | ---
saveCurrentPlaylist | Funktionen saveCurrentPlaylist sparar den nuvarande spellistan som ~/.kde/share/apps/amarok/current.xml.
getActiveIndex | Funktionen getActiveIndex returnerar ett heltalsvärde för nuvarande spårs position i spellistan.
getTotalTrackCount | Funktionen getTotalTrackCount returnerar det totala antalet spår i spellistan.
addMedia | Funktionen addMedia används för att lägga till enstaka filer i spellistan.
addMediaList | Funktionen addMediaList används för att lägga till flera filer i spellistan.
clearPlaylist | Funktionen clearPlaylist används för att rensa hela spellistan.
playByIndex | Funktionen playByIndex startar uppspelning av ett spår med dess position i spellistan.
playMedia | Funktionen playMEDIA startar uppspelning av ett spår som anges av en webbadress.
popupMessage | Funktionen popupMessage visar ett meddelande i spellistans fönster. Meddelandet anges med en QString.
repopulate | Funktionen repopulate fyller spellistan med spår från dynamiskt läge igen.
removeCurrentTrack | Funktionen removeCurrentTrack tar bort nuvarande spår från spellistan.
saveM3u | Funktionen saveM3u spara nuvarande spellista med formatet M3U. Du måste ange sökvägen som filen ska sparas som, och inkludera värdet 0 eller 1 för att ange att relativa sökvägar kan skrivas eller inte.
setStopAfterCurrent | Funktionen setStopAfterCurrent stoppar uppspelning av spellistan efter det nuvarande spåret är klart.
shortStatusMessage | Funktionen shortStatusMessage visar en textsträng som ett meddelande i statusraden.
shufflePlaylist | Funktionen shufflePlaylist gör ordningen av spår i spellistan slumpmässig.
togglePlaylist | Funktionen togglePlaylist ändrar visning av spellistefönstret, antingen av eller på.

### dcop amarok script

DCOP-anrop | Åtgärd
--- | ---
listRunningScripts | Funktionen listRunningScripts listar alla skript som kör i &amarok;.
runScript | Funktionen runScript startar ett skript i &amarok; som anges med sitt namn.
stopScript | Funktionen stopScript stoppar ett skript i &amarok; som anges med sitt namn.
addCustomMenuItem | Funktionen addCustomMenuItem lägger till ett menyalternativ i spellistans sammanhangsberoende meny. Anropet kräver två QString-parametrar, den första för undermenyns namn och den andra för alternativets namn i undermenyn. Båda parametrarna returneras i skripthanteringens underrättelsesystem.
removeCustomMenuItem | Funktionen removeCustomMenuItem tar bort menyalternagtiv som lagts till i spellistans sammanhangsberoende meny med funktionen addCustomMenuItem. Anropet använder samma QString-parametrar som addCustomMenuItem.

## Kommandoradsalternativ

AmaroK stöder användning av de vanliga Qt- och KDE-kommandoradsväljarna. AmaroK har också sina egna programspecifika väljare.

Väljarna för Qt och KDE:

Väljare | Åtgärd
--- | ---
--help | Visa hjälp om väljare.
--help-qt | Visa Qt-specifika väljare.
--help-kde | Visa KDE-specifika väljare.
--help-all | Visa alla väljare.
--author | Visa information om upphovsman.
-v, --version | Visa versionsinformation.
--license | Visa licensinformation.

AmaroK-väljare:

&amarok;-väljarna är avsedda att användas medan &amarok; kör.

Väljare | Åtgärd
--- | ---
-r, --previous | Gå till föregående spår i spellistan.
-p, --play | Börja spela nuvarande spellista.
-s, --stop | Stoppa uppspelning.
--pause | Gör paus i uppspelning.
-f, --next | Gå till nästa spår i spellistan.
-a, --append | Lägg till filer eller webbadresser sist i spellistan.
-e, --enqueue | Se append, tillgänglig för att fungera ihop med tidigare versioner.
--queue | Köa filer eller webbadresser efter spåret som för närvarande spelas.
-m, --toggle-playlist-window | Växla spellistans fönster.
--wizard | Kör startguiden.
--engine "namn" | Starta &amarok; med gränssnittet "namn".

## Skriva skript

Att skriva skript låter dig enkelt utöka &amarok; utan att ändra den huvudsakliga kodbasen. Skript liknar insticksprogram, men istället för ett särskilt programmeringsgränssnitt använder de &amarok;s DCOP-gränssnitt för kommunikation. Det gör det möjligt att skriva skript i nästan vilket programspråk som helst, som Ruby, Python eller PHP. Du kan inte bara skapa skript med klassiska skriptspråk, utan också med kompilerade språk som C++ eller vanlig C. Dessutom kan &amarok; underrätta skript om särskilda händelser och få dem att reagera i enlighet med dem. Systemet med underrättelser förklaras senare i avsnittet.

### Kopplingar

Det är möjligt att skriva enkla skript som inte kräver inblandning av användaren, och det är också möjligt att skapa skript med bekväma grafiska gränssnitt som fungerar som små program i sig själv. För programmering av det grafiska gränssnittet kan en av de många kopplingarna som KDE tillhandahåller användas, till exempel RubyQt, en koppling till Qt-biblioteket för Ruby. Det är dock värt att notera att inte alla användare har installerat alla tillgängliga kopplingar. Om du bestämmer dig för att använda en koppling, försök att använda någon av dem som är relativt spridda (t.ex. RubyQt eller PyQt).

För att ge något gensvar när ett skript misslyckas köra på grund av ett beroende som saknas, kontrollera i skriptet om modulen du vill inkludera verkligen finns. Om beroendet saknas, bör du fånga felet och visa en informationsdialogruta med kommandoradverktyget "kdialog", så att användaren får reda på varför skriptet misslyckas med att köra.

Följande exempel visar hur ett beroende som saknas kan fångas i Ruby:

    begin
           require 'Korundum'
    rescue LoadError
           error = 'Korundum (KDE-kopplingar för Ruby) från kdebindings v3.4 krävs för det här skriptet.'
           `kdialog --sorry '#{error}'`
           exit
    end

### Komma igång: Mallarna

&amarok; tillhandahåller mallskript för flera språk i katalogen `scripts/templates/`. Du kan använda dessa skript som en bas för dina egna, och utöka dem med funktioner du behöver. Du kommer att märka att det i själva verket är ganska rättframt att skriva skript. Om du till exempel vet en del om hur man programmerar i Python, tar det inte lång tid att skapa ditt eget skript.

### Styra &amarok; med DCOP

Skript kan styra amaroK genom att anropa vissa av dess DCOP-funktioner. Det enklaste sättet att utföra en DCOP-funktion är genom att använda kommandoradsverktyget "dcop", som ingår i alla distributioner av KDE.

Här är ett exempel på hur huvudvolymen ökas:

    dcop amarok player volumeUp

De flesta skriptspråk tillåter att yttre program körs, med en funktion som exec(). På så sätt kan verktyget "dcop" enkelt anropas. Här är ett enkelt exempel i Python:

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

### Underrättelser

&amarok; skickar underrättelser till alla skript som kör genom att skriva strängar till deras standardinmatning. Skripten bör därför hela tiden bevaka standardinmatningen och reagera på lämpligt sätt på var och en av de möjliga händelserna. Skript kan också välja att ignorera alla händelser de inte har någon nytta av.

Följande underrättelser skickas av &amarok;:

    configure
    Talar om för skriptet att dess inställningsdialogruta ska visas. Skriptet
    måste hantera lagring och inläsning av inställningsalternativ självt.
    När ett skript startas, ställer amaroK in dess arbetskatalog till katalogen
    där all data ska lagras.

    engineStateChange:empty|idle|paused|playing
    Signalerar en ändring i gränssnittets tillstånd.

    trackChange
    Signalerar start av ett nytt spår. Skriptet kan därefter använda DCOP-funktioner
    för att fråga efter ytterligare information om spåret, t.ex. metadata och längd.

    volumeChangeny-volym
    Signalerar en ändring av huvudvolymen. Volymen är ett heltal med
    intervallet 0-100.

    customMenuClicked:undermeny objektnamn sökvägar
    Returnerar sökvägar till markerade filer i spellistan när det egna alternativet
    i spellistans sammanhangsberoende meny klickas. Undermenyn och objektnamnet returneras
    också i identifieringssyfte i fallet då ett skript lyssnar på flera underrättelser.
    Använd DCOP-anropet 'dcop amarok script addCustomMenuItem( undermeny objektnamn )'
    för att infoga ett objekt i den sammanhangsberoende menyn. Använd
    DCOP-anropet 'dcop amarok script removeCustomMenuItem( undermeny objektnamn )'
    för att ta bort ett objekt från den sammanhangsberoende menyn.

### Avslutning av skript

Innan &amarok; avslutas, eller när användaren stoppar ett skript i skripthanteringen, skickar &amarok; signalen SIGTERM till skriptet. Signalen kan fångas för att utföra upprensningsarbete, som att spara data eller inställningar.

### Paketering

Skripthanteringen i &amarok; kan installera skriptpaket som användaren har laddat ner från en webbserver. Paketen är bara normala arkiv (.tar), valfritt komprimerade med bzip2 (.bz2). Vi rekommenderar starkt att använda ett filnamn som mitt-skript.amarokscript.tar.bz2, så att användaren lätt kan identifiera paketet som ett skript för amaroK.

&amarok; 1.3 accepterar bara skriptpaket med filändelsen amarokscript, det är alltså bättre att använda det ända från början.

Arkivets innehåll måste vara organiserat på följande sätt:

    mitt-skript/
       README
       mitt-skript.py (körbar fil)
       en-modul.py
       fil.data
       ...

### Filrättigheter

Huvudskriptet måste har körrättigheter (+x) inställda,medan ytterligare moduler som skriptet laddar inte ska ha körrättigheter. För att bevara filrättigheter i arkivet, ska du använda tar med väljaren -p.

    tar -cf mitt-skript.amarokscript.tar -p mitt-skript

&amarok; kan inte installera skriptet om inte filrättigheterna är riktigt inställda.

### Distribution

När paketet är klart, kan du ladda upp det till www.kde-apps.org och lägga till länken på &amarok;s Wiki skriptsida. För posten kde-apps ska du använda kategorin &amarok; Scripts.