# Muud amaroKi võimalused

## Kiirklahvid

&amarok; kasutab kiirklahve nagu iga muu korralik rakendus. Allpool on ära toodud kiirklahvid ja nendega käivitatavad toimingud. Globaalseid kiirklahve saab seadistada, kui klõpsata hiire parema nupuga mängija aknas ja valida Globaalsete kiirklahvide seadistamine... &amarok;i enda kiirklahve saab seadistada, kui klõpsata hiire parema nupuga mängija aknas ja valida Kiirklahvide seadistamine...

Oma multimeediaklahvide kasutamiseks &amarok;i kiirklahvidena tuleb määrata klaviatuur &amarok;i juhtimiskeskuses.

Globaalsed kiirklahvid:

Klahvikombinatsioon | Toiming
--- | ---
WinX | Esitus
WinC | Paus
WinV | Stopp
WinB | Järgmine pala
WinZ | Eelmine pala
WinKP_Add | Heli juurde
WinKP_Subtract | Heli maha
WinShiftKP_Add | Palas edasiliikumine
WinShiftKP_Subtract | Palas tagasiliikumine
WinA | Lisa andmekandja
WinP | Lugude nimekirja lülitamine
WinO | OSD näitamine
WinM | Heli välja

&amarok;i kiirklahvid:

Klahvikombinatsioon | Toiming
--- | ---
CtrlC | Kopeeri
CtrlKP_Enter | Mine praegusele
CtrlD | Valitud palad järjekorda
CtrlQ | Välju
CtrlShiftZ | Tee uuesti
CtrlS | Salvesta lugude nimekiri
CtrlA | Vali kõik
CtrlM | Menüüriba näitamine
CtrlH | Segatud
CtrlZ | Võta tagasi

Lugude nimekirja sirvija kiirklahvid:

Klahvikombinatsioon | Toiming
--- | ---
Tühikuklahv | Lugude nimekirja laadimine
F2 | Lugude nimekirja ümbernimetamine
Backspace | Lugude nimekirja eemaldamine

## DCOP-liides

amaroKi DCOP-liides võimaldab imelihtsalt juhtida amaroKi tööd enda loodud skriptidega.

amaroKi DCOP-liides pakub mitmeid üldisi funktsioone, mida kasutavad ka muud KDE rakendused. Käesolevas osas kirjeldame neljas tabelis nii muusikakogu, mängija, lugude nimekirja kui ka skriptide DCOP-funktsioone. Näiteks DCOP-funktsioon pause näeb välja selline:

&percnt;dcop amarok player pause

### DCOP ja amaroKi muusikakogu

DCOP-väljakutse | Toiming
--- | ---
query | Väljakutse query lubab saata otsese andmebaasi päringu &amarok;i muusikakogule.
scanCollection | Väljakutse scanCollection uurib läbi sinu muusikakogu.
scanCollectionChanges | Väljakutse scanCollectionChanges uurib sinu muusikakogu võimalikke muudatusi.
similarArtists | Väljakutse similarArtists tagastab parajasti mängitava pala esitajaga sarnased esitajad. Tulemuste arvu saab piirata artists täisarvulise väärtusega.
totalAlbums | Väljakutse totalAlbums tagastab albumite koguarvu sinu muusikakogus.
totalArtists | Väljakutse totalArtists tagastab esitajate koguarvu sinu muusikakogus.
totalCompilations | Väljakutse totalCompilations tagastab kompilatsioonide koguarvu sinu muusikakogus.
totalGenres | Väljakutse totalGenres tagastab žanride koguarvu sinu muusikakogus.
totalTracks | Väljakutse totalTracks tagastab palade koguarvu sinu muusikakogus.

### DCOP ja amaroKi mängija

DCOP-väljakutse | Toiming
--- | ---
album | Väljakutse album tagastab parajasti mängitava pala albumi.
artist | Väljakutse artist tagastab parajasti mängitava pala esitaja.
bitrate | Väljakutse bitrate tagastab parajasti mängitava pala bitikiiruse.
comment | Väljakutse comment tagastab parajasti mängitava pala kommentaari.
coverImage | Väljakutse coverImage tagastab parajasti mängitava pala kaanepildi URL-i.
currentTime | Väljakutse currentTime tagastab parajasti mängitava pala positsiooni (mm:ss).
encodedURL | Väljakutse encodedURL tagastab parajasti mängitava pala tühikutega kodeeritud URL-i.
engine | Väljakutse engine tagastab parajasti kasutatatava audiomootori nime.
genre | Väljakutse genre tagastab parajasti mängitava pala žanri.
lyrics | Väljakutse lyrics tagastab parajasti mängitava pala puhverdatud laulusõnad.
lyricsByPath | Väljakutse lyricsByPath käivitab asukohaga määratud pala puhverdatud laulusõnad.
nowPlaying | Väljakutse nowPlaying tagastab parajasti mängitava pala artisti ja pealkirja kujul Esitaja - pealkiri. Kui üks kahest id3 sildist on tühi, tagastatakse ainult esitaja või pealkiri (ilma -).
path | Väljakutse path tagastab parajasti mängitava pala asukoha failisüsteemis.
setContextStyle | Väljakutse setContextStyle määrab vastavalt nimele kontekstisirvija CSS-teema.
title | Väljakutse title tagastab parajasti mängitava pala pealkirja.
totalTime | Väljakutse totalTime tagastab parajasti mängitava pala kogukestvuse (mm:ss).
track | Väljakutse track tagastab parajasti mängitava pala rajanumbri.
year | Väljakutse year tagastab parajasti mängitava pala aasta.
dynamicModeStatus | Väljakutse dynamicModeStatus tagastab tõeväärtuse, mis näitab, kas dünaamiline režiim on sisse lülitatud.
equalizerEnabled | Väljakutse equalizerEnabled tagastab tõeväärtuse, mis näitab, kas ekvalaiser on sisse lülitatud.
isPlaying | Väljakutse isPlaying tagastab tõeväärtuse, mis näitab, kas mängija esitab parajasti pala või mitte.
randomModeStatus | Väljakutse randomModeStatus tagastab juhusliku režiimi oleku (tõene või väär).
repeatPlaylistStatus | Väljakutse repeatPlaylistStatus tagastab lugude nimekirja kordamise oleku (tõene või väär).
repeatTrackStatus | Väljakutse repeatTrackStatus tagastab pala kordamise oleku (tõene või väär).
getVolume | Väljakutse getVolume tagastab helitugevuse väärtuse vahemikus 0-100.
sampleRate | Väljakutse sampleRate tagastab parajasti mängitava pala diskreetimissageduse.
score | Väljakutse score tagastab parajasti mängitava pala hinnangu.
setLyricsByPath | Väljakutse setLyricsByPath määrab asukohaga antud pala sõnad. Väljakutsega lyrics saab näha korrektse HTML-vormingu näiteid.
status | Väljakutse status tagastab mootori oleku väärtuse: 2 tähendab mängimist, 1 pausi ja 0 jõudeolekut.
trackCurrentTime | Väljakutse trackCurrentTime tagastab parajasti mängitava pala esitamisele seni kulunud aja sekundites.
trackPlayCounter | Väljakutse trackPlayCounter tagastab arvu, mis näitab, mitu korda on parajasti mängitavat pala mängitud.
trackTotalTime | Väljakutse trackTotalTime tagastab parajasti mängitava pala kogukestvuse sekundites.
configEqualizer | Väljakutse configEqualizer toob esiplaanile ekvalaiseri seadistamise akna.
enableDynamicMode | Väljakutse enableRandomMode võimaldab tõeväärtust andes lülitada sisse või välja dünaamilise režiimi (0 - väljas, 1 - sees).
enableOSD | Väljakutse enableOSD võimaldab tõeväärtust andes lülitada OSD sisse või välja.
enableRandomMode | Väljakutse enableRandomMode võimaldab tõeväärtust andes lülitada sisse või välja juhusliku režiimi (0 - väljas, 1 - sees).
enableRepeatPlaylist | Väljakutse enableRepeatPlaylist võimaldab lülitada lugude nimekirja kordamise režiimi (0 - keelatud, 1 - lubatud).
enableRepeatTrack | Väljakutse enableRepeatTrack võimaldab lülitada pala kordamise režiimi (0 - keelatud, 1 - lubatud).
mute | Väljakutse mute võimaldab parajasti mängitava pala tummaks muuta või taas kuuldavaks teha.
next | Väljakutse next käivitab mängijas järgmise pala.
pause | Väljakutse pause peatab parajasti mängitava pala esitamise.
play | Väljakutse play käivitab mängija kohast, kus see peatati.
playPause | Väljakutse playPause käivitab mängija, kui see on parajasti peatatud. Samas peatab see mängija, kui see parajasti pala esitab.
prev | Väljakutse prev käivitab mängijas eelmise pala.
seek | Väljakutsega seek saab liikuda palas sekunditega määratud asukohale.
seekRelative | Väljakutsega seekRelative saab liikuda palas asukohale, mis on määratud sekundites antud erinevusega praegusest asukohast.
setEqualizer | Väljakutse setEqualizer võimaldab määrata ekvalaiseri liuguri väärtuse 11 täisarvu kasutades. Liuguri väärtused on vahemikus -255 (madalaim) kuni 255 (kõrgeim). Esimene täisarv määrab eelmoonutuse väärtuse, üleväänud eelmoonutuse sagedusväärtused vahemikus 60Hz kuni 16kHz.
setEqualizerEnabled | Väljakutse setEqualizerEnabled võimaldab tõeväärtust andes lülitada ekvalaiseri sisse või välja.
setScore | Väljakutse setVolume määrab parajasti esitatava pala hinnangu arvuga vahemikus 0 kuni 100.
setScoreByPath | Väljakutse setScoreByPath määrab asukohaga antud pala hinnangu arvuga vahemikus 0 kuni 100.
setVolume | Väljakutse setVolume muudab helitugevust vahemikus 0-100.
showBrowser | Väljakutse showBrowser näitab sirvijat lugude nimekirja aknas. Kehtivad väärtused on konteksti-, kogu-, lugude nimekirja, andmekandjate ja failisüsteemi sirvija.
showOSD | Väljakutse showOSD näitab parajasti mängitava pala infoga ekraaniesitust (OSD).
stop | Väljakutse stop peatab mängija, kui see parajasti lugu esitab.
volumeDown | Väljakutse volumeDown kahandab helitugevust ühe sammu võrra.
volumeUp | Väljakutse volumeUp suurendab helitugevust ühe sammu võrra.

### DCOP ja amaroKi lugude nimekiri

DCOP-väljakutse | Toiming
--- | ---
saveCurrentPlaylist | Väljakutse saveCurrentPlaylist salvestab aktiivse lugude nimekirja failina ~/.kde/share/apps/amarok/current.xml.
getActiveIndex | Väljakutse getActiveIndex tagastab täisarvu, mis näitab parajasti mängitava pala positsiooni lugude nimekirjas.
getTotalTrackCount | Väljakutse getTotalTrackCount tagastab palade koguarvu lugude nimekirjas.
addMedia | Väljakutsega addMedia saab üksikfaile lugude nimekirja lisada.
addMediaList | Väljakutsega addMediaList saab mitu faili korraga lugude nimekirja lisada.
clearPlaylist | Väljakutsega clearPlaylist saab puhastada kogu lugude nimekirja.
playByIndex | Väljakutse playByIndex käivitab positsiooniga lugude nimekirjas määratud pala mängimise.
playMedia | Väljakutse playMedia käivitab KURL-iga määratud pala mängimise.
popupMessage | Väljakutse popupMessage avab lugude nimekirja aknas hüpiksõnumi, mille sisu määrab QString.
repopulate | Väljakutse repopulate täidab dünaamilises režiimis lugude nimekirja uuesti paladega.
removeCurrentTrack | Väljakutse removeCurrentTrack eemaldab parajasti mängitava pala lugude nimekirjast.
saveM3u | Väljakutse saveM3u salvestab aktiivse lugude nimekirja M3U vormingus. Lisaks tuleb määrata salvestamise asukoht ning anda väärtus 0 või 1, mis osutab sellele, kas kirjutatakse suhtelisse asukohta või mitte.
setStopAfterCurrent | Väljakutse setStopAfterCurrent peatab lugude nimekirja esitamise pärast parajasti mängitava pala lõppu.
shortStatusMessage | Väljakutse shortStatusMessage näitab tekstistringi sõnumina olekuribal.
shufflePlaylist | Väljakutsega shufflePlaylist saab muuta palade järjekorra lugude nimekirjas juhuslikuks.
togglePlaylist | Väljakutse togglePlaylist lülitab lugude nimekirja akna näitamise sisse või välja.

### DCOP ja amaroKi skriptid

DCOP-väljakutse | Toiming
--- | ---
listRunningScripts | Väljakutse listRunningScripts näitab kõigi töötavate &amarok;i skriptide nimekirja.
runScript | Väljakutse runScript käivitab nimega määratud &amarok;i skripti.
stopScript | Väljakutse stopScript peatab nimega määratud &amarok;i skripti.
addCustomMenuItem | Väljakutse addCustomMenuItem lisab menüükirje lugude nimekirja kontekstimenüüsse. Väljakutse kasutab argumendina kaht QStringi, millest esimene määrab alammenüü nime, teine kirje nime alammenüüs. Mõlemad QStringid tagastatakse skriptihalduri märguannete süsteemis.
removeCustomMenuItem | Väljakutse removeCustomMenuItem eemaldab menüükirje, mis on lugude nimekirja lisatud väljakutsega addCustomMenuItem. Väljakutse kasutab samu QStringe, mida kasutab addCustomMenuItem.

## Käsurea võtmed

amaroK toetab standardseid Qt ja KDE käsurea võtmeid, kuid pakub ka mõningaid spetsiifilisi võtmeid.

Qt ja KDE võtmed:

Võti | Toiming
--- | ---
--help | Näitab abiteadet võtmete kohta.
--help-qt | Näitab Qt spetsiifilisi võtmeid.
--help-kde | Näitab KDE spetsiifilisi võtmeid.
--help-all | Näitab kõiki võtmeid.
--author | Näitab infot autori kohta.
-v, --version | Näitab versiooni.
--license | Näitab litsentsi.

amaroKi võtmed:

&amarok;i võtmed on mõeldud kasutamiseks &amarok;i töötamise ajal.

Võti | Toiming
--- | ---
-r, --previous | Hüppab lugude nimekirjas eelmisele palale.
-p, --play | Alustab lugude nimekirja mängimist.
-s, --stop | Katkestab taasesituse.
--pause | Peatab taasesituse.
-f, --next | Hüppab lugude nimekirjas järgmisele palale.
-a, --append | Lisab failid/URL-id lugude nimekirja.
-e, --enqueue | Vaata append (kasutusel tagasiühilduvuse nimel).
--queue | Seab failid/URL-id järjekorda parajasti mängitava pala järele.
-m, --toggle-playlist-window | Lugude nimekirja akna lülitamine.
--wizard | Käivitab esimese korra nõustaja.
--engine "nimi" | Käivitab &amarok;i mootoriga "nimi".

## Skriptide kirjutamine

Skriptid võimaldavad &amarok;ki väga lihtsalt laiendada ilma selle põhikoodi muutmata. Skriptid sarnanevad selles mõttes pluginatele, kuid erinevalt spetsiaalsest pluginate API-st kasutavad nad kommunikatsiooniks &amarok;i DCOP-liidest. Nii on skripte võimalik kirja panna peaaegu mis tahes programmeerimiskeeles (nt. Ruby, Python, PHP). Skripte saab luua mitte ainult klassikalistes skriptikeeltes, vaid ka keerukamates keeltes, näiteks C++ või puhas C. Lisaks võib &amarok; edastada skriptidele teatud sündmuste korral märguande, mis paneb neid midagi tegema. Seda selgitame käesolevas osas edaspidi.

### Seosed

Võimalik on kirjutada nii lihtsaid skripte, mis ei vaja kasutaja sekkumist, kui ka graafilise kasutajaliidesega skripte, mis tegutsevad justkui omaette väikesed rakendused. Viimaste korral saab kasutada mõnda arvukatest seostes, mida KDE pakub, näiteks Qt teegi seost Ruby jaoks RubyQt. Tuleb siiski märkida, et mitte kõigil kasutajatel ei pruugi kõik seosed paigaldatud olla. Kui otsustad mõnda seost kasutada, ürita pruukida mõnda levinumat (nt. RubyQt või PyQt).

Tagasiside saamiseks, kui skripti töö peaks ebaõnnestuma puuduva sõltuvuse tõttu, lisa palun skripti kontroll, kas moodul, mida soovid kasutada, on ka tegelikult olemas. Kui seda pole, peaks skript veast aru saama ning näitama infodialoogi (käsureatööriista "kdialog" abil), et kasutaja saaks teada, miks skript ei töötanud.

Üks näide, kuidas tuvastada puuduv sõltuvus Ruby korral:

    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

### Alustamine: mallid

&amarok; pakub mitmes keeles skriptimalle kataloogis `scripts/templates/`. Neid saab kasutada alusena enda skripti loomisel. Küllap märkad, et skriptide loomine on üsna lihtne: kui sa tunned näiteks vähegi programmeerimist Pythoni keeles, ei ole vastava skripti loomine kuigi pikk tegevus.

### &amarok;i juhtimine DCOP-i abil

Skriptidega saab amaroKi tegevust juhtida, kutsudes välja selle DCOP-funktsioone. Lihtsaim viis DCOP-funktsiooni väljakutsumiseks on kasutada käsureautiliiti "dcop", mis kuulub alati KDE koosseisu.

Toome näite peamise helitugevuse suurendamise kohta:

    dcop amarok player volumeUp

Enamik skriptikeeli võimaldab käivitada väliseid programme (näiteks funktsiooniga exec()). Nii saab utiliiti "dcop" üsna lihtsalt välja kutsuda. Toome ühe lihtsa näite Pythoni keeles:

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

### Märguanded

&amarok; võib saata kõigile töötavatele skriptidele märguandeid, kirjutades vastava stringi nende standardsisendi kanalisse. Seepärast peab skript pidevalt jälgima oma standardsisendit ja võimalike märguannete puhul vajalikult tegutsema. Skriptid võivad küll ka mitte tegutseda teatud sündmuste puhul, kui need neid ei puuduta.

&amarok; saadab järgmisi märguandeid:

    configure
    Annab skriptile korralduse näidata oma seadistustedialoogi.
    Skript peab seadistusvalikute salvestamise ja laadimisega ise toime tulema.
    Skripti käivitamisel määrab amaroK selle töökataloogi kataloogiks,
    kuhu salvestada kõik andmed.

    engineStateChange:empty|idle|paused|playing
    Annab märku mootori oleku muutumisest.

    trackChange
    Annab märku uue pala algusest. Skript võib seejärel kasutada DCOP-funktsioone
    pala kohta täiendava info hankimiseks (nt. metaandmed, pikkus).

    volumeChangenewVolume
    Annab märku peamise helitugevuse muutumisest.
    Helitugevus on täisarv vahemikus 0 kuni 100.

    customMenuClicked:submenu itemTitle paths
    Tagastab lugude nimekirja valitud failide asukohad,
    kui klõpsatakse kohandatud lugude nimekirja kontekstimenüü mõnda kirjet.
    Tagastatakse ka alammenüü ja elemendi nimi, mida läheb vaja juhul,
    kui skript jälgib mitmeid märguandeid.
    Elemendi lisamiseks kontekstimenüüsse kasuta DCOP-väljakutset
    'dcop amarok script addCustomMenuItem( submenu itemTitle )'.
    Elemendi eemaldamiseks kontekstimenüüst kasuta DCOP-väljakutset
    'dcop amarok script removeCustomMenuItem( submenu itemTitle )'.

### Skripti töö lõpetamine

Enne seda, kui &amarok; töö lõpetab või kui kasutaja peatab skripti skriptihalduris, saadab &amarok; skriptile signaali SIGTERM. Selle signaali saamisel peab skript ette võtma vajalikud toimingud, näiteks salvestama andmed või seadistused.

### Pakkimine

&amarok;i skriptihaldur oskab paigaldada skriptipakke, mida kasutaja on veebist alla laadinud. Pakid on pakitud tavaliselt (.tar), lisaks on võimalik tihendada neid ka bzip2-ga (.bz2). Me soovitame tungivalt kasutada failinime kujul minuskript.amarokscript.tar.bz2, et kasutajad saaksid kohe aru, et tegemist on just amaroKi skriptiga.

&amarok; 1.3 tunnustab ainult laiendiga amarokscript skriptipakke, nii et mõistlik oleks seda igal juhul kasutada.

Paki sisu peab olema järgmine:

    minuskript/
       README
       minuskript.py (käivitatav fail)
       mingimoodul.py
       foo.data
       ...

### Failiõigused

Põhiskriptil peab olema käivitamise õigus (+x), teised moodulid aga, mida skript laeb, ei tohi olla käivitamisõigusega. Failiõiguste säilitamiseks pakis tuleks see pakkida võtmega -p:

    tar -cf minuskript.amarokscript.tar -p minuskript

&amarok; ei saa skripti paigaldada, kui õigused ei ole korrektsed.

### Levitamine

Kui oled paki valmis teinud, võid laadida selle saidile www.kde-apps.org ja lisada lingi &amarok;i Wiki skriptileheküljele. Saidil kde-apps tuleks kasutada kategooriat &amarok; Scripts.