# 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 | Esitusnimekirja 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 esitusnimekiri
CtrlA | Vali kõik
CtrlM | Menüüriba näitamine
CtrlH | Segatud
CtrlZ | Võta tagasi

Esitusnimekirja sirvija kiirklahvid:

Klahvikombinatsioon | Toiming
--- | ---
Tühikuklahv | Esitusnimekirja laadimine
F2 | Esitusnimekirja ümbernimetamine
Backspace | Esitusnimekirja 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 kuues tabelis nii muusikakogu, kontekstisirvija, mängija, esitusnimekirja, esitusnimekirja sirvija 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
--- | ---
int totalAlbums() | Tagastab albumite koguarvu muusikakogus.
int totalArtists() | Tagastab esitajate koguarvu muusikakogus.
int totalCompilations() | Tagastab kompilatsioonide koguarvu muusikakogus.
int totalGenres() | Tagastab žanride koguarvu muusikakogus.
int totalTracks() | Tagastab palade koguarvu muusikakogus.
QString query( QString sql) | Esitab andmebaasile päringu SQL-i vahendusel.
QStringList similarArtists( int artists ) | Tagastab aktiivse pala esitajaga sarnased esitajad, piiranguks 'int artists' antud arv.
void migrateFile( QString oldURL, QString newURL ) | Liigutab kogus faili, jättes statistika muutmata.
void scanCollection() | Uurib muusikakogu.
void scanCollectionChanges() | Uurib muusikakogu puhul ainult muutusi.

### dcop amarok contextbrowser

DCOP-väljakutse | Toiming
--- | ---
void showCurrentTrack() | Näitab kontekstisirvijas aktiivset pala.
void showLyrics() | Näitab kontekstisirvijas sõnade kaarti.
void showWiki() | Näitab kontekstisirvijas Wikipedia kaarti.

### dcop amarok player

DCOP-väljakutse | Toiming
--- | ---
bool dynamicModeStatus() | Tagastab dünaamilise režiimi oleku.
bool equalizerEnabled() | Tagastab ekvalaiseri oleku.
bool isPlaying() | Tagastab 'tõene', kui midagi esitatakse.
bool randomModeStatus() | Tagastab juhusliku režiimi oleku.
bool repeatPlaylistStatus() | Tagastab esitusnimekirja kordamise oleku.
bool repeatTrackStatus() | Tagastab pala kordamise oleku.
int getVolume() | Tagastab helitugevuse vahemikus 0-100%.
int sampleRate() | Tagastab parajasti esitatava pala diskreetimissageduse.
int score() | Tagastab parajasti esitatava pala hinde.
int status() | Tagastab esitamise oleku: 0 - peatatud, 1 - paus, 2 - esitatakse.
int trackCurrentTime() | Tagastab pala esitamiskoha sekundites.
int trackPlayCounter() | Tagastab aktiivse laulu esitamiskorrad.
int trackTotalTime() | Tagastab pala pikkuse sekundites.
QString album() | Tagastab parajasti mängitava pala albumi.
QString artist() | Tagastab parajasti mängitava pala esitaja.
QString bitrate() | Tagastab parajasti mängitava pala bitikiiruse (XX kbps).
QString comment() | Tagastab parajasti mängitava pala kommentaari.
QString coverImage() | Tagastab parajasti mängitava pala kaanepildi URL-i.
QString currentTime() | Tagastab parajasti mängitava pala positsiooni ([h:]mm:ss vormingus).
QString encodedURL() | Tagastab parajasti mängitava pala kodeeritud URL-i.
QString engine() | Tagastab parajasti kasutatatava audiomootori nime.
QString genre() | Tagastab parajasti mängitava pala žanri.
QString lyrics() | Tagastab parajasti mängitava pala sõnad.
QString lyricsByPath( QString path ) | Tagastab pala sõnad määratud asukohast.
QString nowPlaying() | Parajasti mängitava andmekandja pealkiri.
QString path() | Tagastab parajasti mängitava pala kodeerimata asukoha.
QString setContextStyle( QString ) | Määrab kontekstisirvijale CSS-stiili.
QString title() | Tagastab parajasti mängitava pala pealkirja.
QString totalTime() | Tagastab parajasti mängitava pala kogupikkuse ([h:]mm:ss vormingus).
QString track() | Tagastab pala järjekorranumbri.
QString type() | Tagastab failitüübi.
QString year() | Tagastab parajasti mängitava pala aasta.
void configEqualizer() | Ekvalaiseri seadistustedialoogi lülitamine.
void enableDynamicMode(bool enable) | Dünaamilise režiimi lülitamine sisse või välja.
void enableOSD(bool enable) | OSD kuvamise lülitamine sisse või välja.
void enableRandomMode(bool enable) | Juhusliku režiimi lülitamine sisse või välja
void enableRepeatPlaylist(bool enable) | Esitusnimekirja kordamise lülitamine sisse või välja.
void enableRepeatTrack(bool enable) | Pala kordamise lülitamine sisse või välja.
void mediaDeviceMount() | Määrab käsu meediaseadme ühendamiseks.
void mediaDeviceUmount() | Määrab käsu meediaseadme lahutamiseks.
void mute() | Tummuse lülitamine.
void next() | Sama, mis klõps nupule "Järgmine".
void pause() | Sama, mis klõps nupule "Paus".
void play() | Sama, mis klõps nupule "Esitus".
void playPause() | Esituse/pausi oleku lülitamine (sobib multimeediaklaviatuuri kasutajatele).
void prev() | Sama, mis klõps nupule "Eelmine".
void queueForTransfer( KURL url ) | Faili seadmine järjekorda ülekandmiseks meediaseadmele.
void seek(int s) | Hüppamine palas sekunditega määratud positsiooni.
void seekRelative(int s) | Hüppamine palas positsiooni, mis erineb määratud sekundite võrra aktiivsest positsioonist.
void setEqualizer(int, int, int, int, int, int, int, int, int, int, int) | Ekvalaiseri liugurite väärtuste määramine.
void setEqualizerEnabled( bool active ) | Ekvalaiseri lülitamine.
void setEqualizerPreset( QString name ) | Ekvalaiseri valmisseadistuse kehtestamine.
void setLyricsByPath( QString url, QString lyrics ) | Pala sõnade määramine asukoha järgi.
void setScore( int score ) | Parajasti mängitava pala hinde määramine.
void setScoreByPath( QString url, int score ) | Pala hinde määramine asukoha järgi.
void setVolume(int volume) | Helitugevuse määramine vahemikus 0-100%.
void showBrowser( QString browser ) | Sirvijate näitamine esitusnimekirja aknas.
void showOSD() | OSD näitamine ekraanil.
void stop() | Sama, mis klõps nupule "Peata".
void transferDeviceFiles() | Failide ülekandmine meediaseadmele.
void volumeDown() | Helitugevuse vähendamine mõistliku sammu võrra.
void volumeUp() | Helitugevuse suurendamine mõistliku sammu võrra.

### dcop amarok playlist

DCOP-väljakutse | Toiming
--- | ---
int getActiveIndex() | Tagstab aktiivse pala indeksi või -1, kui seda pole.
int getTotalTrackCount() | Tagastab palade arvu esitusnimekirjas või 0, kui seal pole ühtegi pala.
QString saveCurrentPlaylist() | Salvestab aktiivse esitusnimekirja failina current.xml ja tagastab selle asukoha.
void addMedia( KURL ) | Lisab URL-iga määratud audioandmekandja.
void addMediaList( KURL::List ) | Lisab mitu URL-iga määratud audioandmekandjat.
void clearPlaylist() | Puhastab esitusnimekirja.
void playByIndex(int) | Alustab pala esitamist määratud indeksist.
void playMedia( KURL ) | Lisab URL-iga määratud audioandmekandja.
void popupMessage( QString) | Näitab ajutist hüpikdialoogi.
void removeCurrentTrack() | Eemaldab aktiivse pala esitusnimekirjast.
void repopulate() | Täidab esitusnimekirja uuesti juhuslike paladega.
void saveM3u( QString path, bool relativePaths) | Salvestab aktiivse esitusnimekirja m3u-failina.
void setStopAfterCurrent( bool ) | Lülitab sisse/välja võimaluse "Peata pärast aktiivset pala".
void shortStatusMessage( QString) | Näitab ajutist teadet olekuribal.
void shufflePlaylist() | Segab esitusnimekirja järjekorra.
void togglePlaylist() | Lülitab esitusnimekirja akna näitamist.

### dcop amarok playlistbrowser

DCOP-väljakutse | Toiming
--- | ---
void addPodcast( QString ) | Lisab esitusnimekirja sirvijasse Podcasti kirje.
void scanPodcasts() | Uurib kõigi Podcastide uuendusi.
void addPlaylist( QString ) | Lisab esitusnimekirja sirvijasse esitusnimekirja.

### dcop amarok script

DCOP-väljakutse | Toiming
--- | ---
bool runScript( QString name) | Käivitab määratud nimega skripti. Õnnestumise korral tagastab 'tõene'.
bool stopScript( QString name) | Peatab määratud nimega skripti. Õnnestumise korral tagastab 'tõene'.
QStringList listRunningScripts() | Tagastab kõigi parajasti töötavate skriptide nimekirja.
void addCustomMenuItem(QString submenu, QString itemTitle ) | Kehtestab ja määrab kohandatud menüüelemendi nime.
void removeCustomMenuItem(QString submenu, QString itemTitle ) | Eemaldab kohandatud menüüelemendi.
QString readConfig( QString key) | Tagastab AmarokConfigi seadistuskirje väärtuse antud võtme põhjal.

## 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 esitusnimekirjas eelmisele palale.
-p, --play | Alustab esitusnimekirja mängimist.
-s, --stop | Katkestab taasesituse.
--pause | Peatab taasesituse.
-f, --next | Hüppab esitusnimekirjas järgmisele palale.
-a, --append | Lisab failid/URL-id esitusnimekirja.
-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 | Esitusnimekirja 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 esitusnimekirja valitud failide asukohad,
    kui klõpsatakse kohandatud esitusnimekirja 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.