# 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
Win X | Spela
Win C | Paus
Win V | Stanna
Win B | Nästa spår
Win Z | Föregående spår
Win Numeriskt tangentbord + | Öka volym
Win Numeriskt tangentbord - | Minska volym
Win Skift numeriskt + | Sök framåt
Win Skift numeriskt - | Sök bakåt
Win A | Lägg till media
Win P | Växla spellista
Win O | Aktivera skärmvisning
Win M | Tysta volym

Genvägarna i &amarok; är:

Tangentkombination | Åtgärd
Ctrl C | Kopiera
Ctrl Numeriskt tangentbord Enter | Gå till nuvarande
Ctrl D | Köa markerade spår
Ctrl Q | Avsluta
Ctrl Skift Z | Gör om
Ctrl S | Spara spellista
Ctrl A | Markera alla
Ctrl M | Visa menyrad
Ctrl H | Blanda
Ctrl Z | Å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 sex tabeller och är avsett att beskriva DCOP-anrop för samlingen, sammanhangsbläddraren, spelaren, spellistan, spellistebläddraren och skript. Ett exempel på DCOP-funktionen pause skulle se ut så här:

`%`dcop amarok player pause

### dcop amarok collection

DCOP-anrop | Åtgärd
int totalAlbums() | Returnerar det totala antalet album i samlingen.
int totalArtists() | Returnerar det totala antalet artister i samlingen.
int totalCompilations() | Returnerar det totala antalet samlingsalbum i samlingen.
int totalGenres() | Returnerar det totala antalet genrer i samlingen.
int totalTracks() | Returnerar det totala antalet spår i samlingen.
TQString query( TQString sql) | Skickar en fråga till databasen via SQL.
QStringList similarArtists( int artister ) | Returnera liknande artister som det nuvarande spåret, begränsat till antal givet av artister.
void migrateFile( TQString gammal_webbadress, TQString ny_webbadress ) | Flytta en fil i samlingen, och behåll statistiken intakt.
void scanCollection() | Sök igenom samlingen.
void scanCollectionChanges() | Sök enbart igenom samlingen efter ändringar.

### dcop amarok contextbrowser

DCOP-anrop | Åtgärd
void showCurrentTrack() | Visa det nuvarande spåret i sammanhangsbläddraren.
void showLyrics() | Visa sångtextfliken i sammanhangsbläddraren.
void showWiki() | Visa Wikipedia-fliken i sammanhangsbläddraren.

### dcop amarok player

DCOP-anrop | Åtgärd
bool dynamicModeStatus() | Returnera status för dynamiskt läge.
bool equalizerEnabled() | Returnera status för equalizern.
bool isPlaying() | Returnera sant om något spelas nu.
bool randomModeStatus() | Returnera status för slumpmässigt läge
bool repeatPlaylistStatus() | Returnera status för upprepning av spellistan.
bool repeatTrackStatus() | Returnera status för upprepning av spår.
int getVolume() | Returnera volymen i intervallet 0 - 100 %.
int sampleRate() | Returnera samplingsfrekvensen för spåret som för närvarande spelas.
int score() | Returnera poängen för spåret som för närvarande spelas.
int status() | Returnera uppspelningsstatus: 0 - stoppad, 1 - paus, 2 - spelar.
int trackCurrentTime() | Returnerar nuvarande uppspelningsposition i sekunder.
int trackPlayCounter() | Returnerar uppspelningsräknaren för nuvarande sång.
int trackTotalTime() | Returnerar spårlängden i sekunder.
TQString album() | Returnera albumet för spåret som för närvarande spelas.
TQString artist() | Returnera artisten för spåret som för närvarande spelas.
TQString bitrate() | Returnera bithastigheten för spåret som för närvarande spelas (i kilobit per sekund).
TQString comment() | Returnera kommentaren för spåret som för närvarande spelas.
TQString coverImage() | Returnera den kodade webbadressen till nuvarande spårs skivomslag
TQString currentTime() | Returnera positionen för spåret som för närvarande spelas (på formatet [t:]mm:ss).
TQString encodedURL() | Returnera den kodade webbadressen för spåret som för närvarande spelas.
TQString engine() | Returnera nuvarande ljudgränssnitt.
TQString genre() | Returnera genren för spåret som för närvarande spelas.
TQString lyrics() | Returnera sångtexten för spåret som för närvarande spelas.
TQString lyricsByPath( TQString sökväg ) | Returnera sångtext för ett spår enligt sökväg.
TQString nowPlaying() | Titeln på det medium som nu spelas.
TQString path() | Returnera den okodade sökvägen för spåret som för närvarande spelas.
TQString setContextStyle( TQString ) | Ställ in CSS-stilen för sammanhangsbläddraren.
TQString title() | Returnera titeln för spåret som för närvarande spelas.
TQString totalTime() | Returnera totala längden för spåret som för närvarande spelas (på formatet [t:]mm:ss).
TQString track() | Returnera spårnumret.
TQString type() | Returnera filtypen.
TQString year() | Returnera året för spåret som för närvarande spelas.
void configEqualizer() | Växla equalizerns inställningsdialogruta.
void enableDynamicMode(bool aktivera) | Sätt på eller stäng av dynamiskt läge.
void enableOSD(bool aktivera) | Sätt på eller stäng av skärmmeddelanden.
void enableRandomMode(bool aktivera) | Sätt på eller stäng av slumpmässigt läge.
void enableRepeatPlaylist(bool aktivera) | Sätt på eller stäng av upprepa spellista.
void enableRepeatTrack(bool aktivera) | Sätt på eller stäng av upprepa spår.
void mediaDeviceMount() | Ställer in kommandot som används för att montera mediaenheter.
void mediaDeviceUmount() | Ställer in kommandot som används för att avmontera mediaenheter.
void mute() | Växla tyst.
void next() | Motsvarar att klicka på knappen "Nästa".
void pause() | Motsvarar att klicka på knappen "Paus".
void play() | Motsvarar att klicka på knappen "Spela".
void playPause() | Växla tillstånd mellan spela och paus (bra för användare av multimediatangentbord)
void prev() | Motsvarar att klicka på knappen "Föregående".
void queueForTransfer( KURL webbadress ) | Köa filer för överföring till mediaenheten.
void seek(int s) | Sök i spåret till positionen i sekunder.
void seekRelative(int s) | Sök till en position i förhållande till spårets nuvarande position.
void setEqualizer(int, int, int, int, int, int, int, int, int, int, int) | Ställ in equalizerns band
void setEqualizerEnabled( bool active ) | Växla equalizern.
void setEqualizerPreset( TQString namn ) | Ställ in equalizerns förinställning
void setLyricsByPath( TQString webbadress, TQString sångtext ) | Ställ in sångtext för ett spår enligt dess sökväg.
void setScore( int poäng ) | Ställ in poäng för spåret som för närvarande spelas.
void setScoreByPath( TQString webbadress, int poäng ) | Ställ in poäng för ett spår enligt dess sökväg.
void setVolume(int volym) | Ställ in volymen i intervallet 0 - 100 %
void showBrowser( TQString bläddrare ) | Visar bläddrarna i spellistans fönster.
void showOSD() | Visa skärmmeddelanden på skärmen.
void stop() | Motsvarar att klicka på knappen "Stopp".
void transferDeviceFiles() | Överför filer till mediaenheten.
void volumeDown() | Minska volymen med ett rimligt steg.
void volumeUp() | Öka volymen med ett rimligt steg.

### dcop amarok playlist

DCOP-anrop | Åtgärd
int getActiveIndex() | Returnera index för spåret som för närvarande är aktivt. -1 om inget.
int getTotalTrackCount() | Returnera antal spår i spellistan. 0 om inga.
TQString saveCurrentPlaylist() | Sparar den nuvarande spellistan i nuvarande.xml och och returnerar dess sökväg.
void addMedia( KURL ) | Lägg till ljudmedium angivet av webbadressen.
void addMediaList( KURL::List ) | Lägg till några ljudmedia angivna av webbadressen.
void clearPlaylist() | Rensar spellistan.
void playByIndex(int) | Börjar spela spåret vid angivet index.
void playMedia( KURL ) | Lägg till ljudmedium angivet av webbadressen.
void popupMessage( TQString) | Visar ett tillfälligt skärmmeddelande.
void removeCurrentTrack() | Tar bort nuvarande spår från spellistan.
void repopulate() | Fyll i spellistan igen med slumpmässiga spår.
void saveM3u( TQString sökväg, bool relativ_sökväg) | Sparar nuvarande spellista som m3u.
void setStopAfterCurrent( bool ) | Aktiverar eller inaktiverar funktionen "Stoppa efter aktuellt spår".
void shortStatusMessage( TQString) | Visar ett tillfälligt meddelande på statusraden.
void shufflePlaylist() | Blandar spellistan.
void togglePlaylist() | Växla spellistans fönster.

### dcop amarok playlistbrowser

DCOP-anrop | Åtgärd
void addPodcast( TQString ) | Lägg till en podradiosändning i spellistebläddraren.
void scanPodcasts() | Sök igenom alla podradiosändningar efter uppdateringar.
void addPlaylist( TQString ) | Lägg till en spellista i spellistebläddraren.

### dcop amarok script

DCOP-anrop | Åtgärd
bool runScript( TQString namn) | Startar skriptet med angivet namn. Returnerar sant om det lyckas.
bool stopScript( TQString namn) | Stoppar skriptet med angivet namn. Returnerar sant om det lyckas.
QStringList listRunningScripts() | Returnerar en lista med skript som för närvarande kör.
void addCustomMenuItem(TQString undermeny, TQString objekttitel ) | Aktiverar och ställer in titeln för eget menyalternativ.
void removeCustomMenuItem(TQString undermeny, TQString objekttitel ) | Tar bort det egna menyalternativet.
TQString readConfig( TQString nyckel) | Returnerar värdet av en inställningspost från AmarokConfig för angiven nyckel.

## 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 tdebindings 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.