# Zaawansowane funkcje programu Amarok

## Skróty klawiszowe

&amarok-mianownik; tak jak większość programów, wykorzystuje skróty klawiszowe; poniżej znajduje się lista tych skrótów i opis ich działania. Aby skonfigurować skróty globalne, wystarczy kliknąć prawym przyciskiem myszy na oknie odtwarzacza i wybrać polecenie Konfiguracja skrótów globalnych.... Podobnie postępujemy chcąc ustalić skróty &amarok-dopelniacz;, tyle, że po kliknięciu wybieramy polecenie Konfiguracja skrótów...

Możesz przyporządkować swoim klawiszom multimedialnym skróty &amarok-dopelniacz;. W ten sposób zamienisz swoją klawiaturę w centrum sterowania programu &amarok-mianownik;.

Skróty globalne:

Kombinacja klawiszy | Działanie
--- | ---
WinX | Odtwarzaj
WinC | Pauza
WinV | Stop
WinB | Następny utwór
WinZ | Poprzedni utwór
WinKP_Add | Podgłośnij
WinKP_Subtract | Przycisz
WinShiftKP_Add | Wyszukaj do przodu
WinShiftKP_Subtract | Wyszukaj do tyłu
WinA | Dodaj media
WinP | Przełącz listę odtwarzania
WinO | Pokaż OSD
WinM | Wycisz

Skróty programu &amarok-mianownik;:

Kombinacja klawiszy | Działanie
--- | ---
CtrlC | Kopiuj
CtrlKP_Enter | Idź do bieżącego utworu
CtrlD | Kolejkuj wybrane utwory
CtrlQ | Zakończ
CtrlShiftZ | Przywróć
CtrlS | Zapisz listę odtwarzania jako...
CtrlA | Zaznacz wszystko
CtrlM | Pokaż pasek menu
CtrlH | Tasuj
CtrlZ | Cofnij

Skróty przeglądarki listy odtwarzania:

Kombinacja klawiszy | Działanie
--- | ---
Spacja | Wczytaj listę odtwarzania
F2 | Zmień nazwę listy odtwarzania
Backspace | Usuń listę odtwarzania

## Interfejs DCOP

Interfejs DCOP umożliwia łatwe zarządzanie programem Amarok, za pomocą samodzielnie stworzonych skryptów.

Interfejs DCOP programu Amarok posiada wiele standardowych funkcji, występujących również w innych programach KDE. Sekcja ta jest podzielona na sześć tabeli i opisuje funkcje interfejsu DCOP odpowiedzialne za kolekcję, przeglądarkę kontekstową, odtwarzacz, listę odtwarzania, przeglądarkę list odtwarzania oraz skrypty. Przykładowe wywołanie funkcji dcop pause będzie miało następującą postać:

&percnt;dcop amarok player pause

### dcop amarok collection

Funkcja DCOP | Działanie
--- | ---
int totalAlbums() | Zwraca całkowitą liczbę albumów w kolekcji.
int totalArtists() | Zwraca całkowitą liczbę wykonawców w kolekcji.
int totalCompilations() | Zwraca całkowitą liczbę kompilacji w kolekcji.
int totalGenres() | Zwraca całkowitą liczbę gatunków w kolekcji.
int totalTracks() | Zwraca całkowitą liczbę utworów w kolekcji.
QString query( QString sql) | Zapytuje bazę danych poprzez SQL
QStringList similarArtists( int wykonawcy ) | Zwraca wykonawców zbliżonych do wykonawcy bieżącego utworu; ograniczone do wykonawców.
void migrateFile( QString staryURL, QString nowyURL ) | Przenosi plik do kolekcji, pozostawiając statystyki niezmienione.
void scanCollection() | Skanuje kolekcję.
void scanCollectionChanges() | Wyszukuje w kolekcji jedynie zmiany.

### dcop amarok contextbrowser

Funkcja DCOP | Działanie
--- | ---
void showCurrentTrack() | Wyświetla bieżący utwór w przeglądarce kontekstowej.
void showLyrics() | Wyświetla kartę tekstów w przeglądarce kontekstowej.
void showWiki() | Wyświetla kartę Wikipedii w przeglądarce kontekstowej.

### dcop amarok player

Funkcja DCOP | Działanie
--- | ---
bool dynamicModeStatus() | Zwraca status trybu dynamicznego.
bool equalizerEnabled() | Zwraca status equalizera.
bool isPlaying() | Zwraca wartość prawda, jeśli coś jest odtwarzane.
bool randomModeStatusf() | Zwraca status trybu losowego.
bool repeatPlaylistStatus() | Zwraca status trybu powtarzania listy odtwarzania.
bool repeatTrackStatus() | Zwraca status trybu powtarzania utworu.
int getVolume() | Zwraca siłę głosu z przedziału 0-100%.
int sampleRate() | Zwraca częstotliwość próbkowania aktualnie odtwarzanego utworu.
int score() | Zwraca ocenę aktualnie odtwarzanego utworu.
int status() | Zwraca status odtwarzania: 0 - stop, 1 - pauza, 2 - odtwarzanie.
int trackCurrentTime() | Zwraca bieżącą pozycję odtwarzania wyrażoną w sekundach.
int trackPlayCounter() | Zwraca liczbę odtworzeń bieżącego utworu.
int trackTotalTime() | Zwraca długość utworu w sekundach.
QString album() | Zwraca album, z którego pochodzi aktualnie odtwarzany utwór.
QString artist() | Zwraca wykonawcę aktualnie odtwarzanego utworu.
QString bitrate() | Zwraca średnią bitowa aktualnie odtwarzanego utworu (XX kbps).
QString comment() | Zwraca komentarz na temat aktualnie odtwarzanego utworu.
QString coverImage() | Zwraca kodowany adres URL do obrazu okładki aktualnie odtwarzanego utworu.
QString currentTime() | Zwraca pozycję aktualnie odtwarzanego utworu (format [h:]mm:ss).
QString encodedURL() | Zwraca kodowany adres URL aktualnie odtwarzanego utworu.
QString engine() | Zwraca informację o bieżącym silniku audio.
QString genre() | Zwraca informację o gatunku muzyki, do którego należy aktualnie odtwarzany utwór.
QString lyrics() | Zwraca tekst aktualnie odtwarzanego utworu.
QString lyricsByPath( QString ścieżka ) | Zwraca tekst utworu określony ścieżką.
QString nowPlaying() | Nazwa medium w trakcie odtwarzania.
QString path() | Zwraca niekodowaną ścieżkę aktualnie odtwarzanego utworu.
QString setContextStyle( QString ) | Ustala styl CCS dla przeglądarki kontekstowej.
QString title() | Zwraca tytuł aktualnie odtwarzanego utworu.
QString totalTime() | Zwraca całkowitą długość aktualnie odtwarzanego utworu (format [h:]mm:ss).
QString track() | Zwraca numer utworu.
QString type() | Zwraca typ pliku.
QString year() | Zwraca rok aktualnie odtwarzanego utworu.
void configEqualizer() | Przełącza okno konfiguracyjne equalizera.
void enableDynamicMode(bool włączony) | Włącza lub wyłącza tryb dynamiczny.
void enableOSD(bool włączony) | Włącza lub wyłącza wyświetlanie OSD.
void enableRandomMode(bool włączony) | Włącza lub wyłącza tryb losowy.
void enableRepeatPlaylist(bool włączony) | Włącza lub wyłącza tryb powtarzania listy.
void enableRepeatTrack(bool włączony) | Włącza lub wyłącza tryb powtarzania utworu.
void mediaDeviceMount() | Ustawia polecenie służące do montowania urządzenia odtwarzającego.
void mediaDeviceUmount() | Ustawia polecenie służące do odmontowania urządzenia odtwarzającego.
void mute() | Przełącza wyciszanie.
void next() | Równoznaczne z naciśnięciem przycisku "Dalej".
void pause() | Równoznaczne z naciśnięciem przycisku "Pauza".
void play() | Równoznaczne z naciśnięciem przycisku "Odtwarzaj".
void playPause() | Przełącza pomiędzy odtwarzaniem a pauzą (wygodne dla użytkowników klawiatur mm).
void prev() | Równoznaczne z naciśnięciem przycisku "Poprzedni".
void queueForTransfer( KURL url ) | Kolejkuj plik przed przesłaniem do urządzenia odtwarzającego.
void seek(int s) | Wyszukaj w utworze według pozycji w sekundach.
void seekRelative(int s) | Wyszukuje pozycję względną do bieżącej pozycji utworu.
void setEqualizer(int, int, int, int, int, int, int, int, int, int, int) | Ustawia częstotliwości equalizera.
void setEqualizerEnabled( bool aktywny ) | Przełącza equalizer.
void setEqualizerPreset( QString nazwa ) | Ustawia domyślną konfigurację equalizera.
void setLyricsByPath( QString url, QString tekst ) | Ustawia tekst utworu określonego przez ścieżkę.
void setScore( int ocena ) | Ustawia ocenę aktualnie odtwarzanego utworu.
void setScoreByPath( QString url, int wynik ) | Ustawia ocenę utworu określonego przez ścieżkę.
void setVolume(int głośność) | Ustawia głośność w przedziale 0-100%.
void showBrowser( QString przeglądarka ) | Wyświetla przeglądarki w oknie listy odtwarzania.
void showOSD() | Wyświetla OSD na ekranie.
void stop() | Równoznaczne z naciśnięciem przycisku "Stop".
void transferDeviceFiles() | Transferuje pliki do urządzenia odtwarzającego.
void volumeDown() | Zmniejsza głośność o rozsądną wielkość.
void volumeUp() | Zwiększa głośność o rozsądną wielkość.

### dcop amarok playlist

Funkcja DCOP | Działanie
--- | ---
int getActiveIndex() | Zwraca listę aktywnych utworów. -1 jeśli ich brak.
int getTotalTrackCount() | Zwraca liczbę utworów na liście. 0 jeśli ich brak.
QString saveCurrentPlaylist() | Zapisuje bieżącą listę do current.xml i zwraca ścieżkę do pliku.
void addMedia( KURL ) | Dodaje media dźwiękowe określone przez URL.
void addMediaList( KURL::List lista ) | Dodaje pewne media dźwiękowe określone przez URL.
void clearPlaylist() | Oczyszcza listę odtwarzania.
void playByIndex(int) | Uruchamia odtwarzanie utworu według określonego indeksu.
void playMedia( KURL ) | Dodaje media dźwiękowe określone przez URL.
void popupMessage( QString) | Wyświetla czasową wiadomość wyskakującą.
void removeCurrentTrack() | Usuwa bieżący utwór z listy odtwarzania.
void repopulate() | Zapełnia listę przypadkowymi utworami.
void saveM3u( QString ścieżka, bool relatywneŚcieżki) | Zapisuje bieżącą listę jako m3u.
void setStopAfterCurrent( bool ) | Włącza i wyłącza funkcję "Zatrzymaj po bieżącym utworze".
void shortStatusMessage( QString) | Wyświetla tymczasowy komunikat na pasku stanu.
void shufflePlaylist() | Tasuje listę odtwarzania.
void togglePlaylist() | Włącza/wyłącza okno listy odtwarzania.

### dcop amarok playlistbrowser

Funkcja DCOP | Działanie
--- | ---
void addPodcast( QString ) | Dodaje pozycję podcast do przeglądarki list.
void scanPodcasts() | Wyszukaje aktualizacje wszystkich podcastów.
void addPlaylist( QString ) | Dodaje listę odtwarzania do przeglądarki list.

### dcop amarok script

Funkcja DCOP | Działanie
--- | ---
bool runScript( QString nazwa) | Uruchamia skrypt o danej nazwie. Zwraca wartość prawda, jeśli operacja się powiedzie.
bool stopScript( QString nazwa) | Zatrzymuje skrypt o danej nazwie. Zwraca wartość prawda, jeśli operacja się powiedzie.
QStringList listRunningScripts() | Zwraca listę aktualnie uruchomionych skryptów.
void addCustomMenuItem(QString podmenu, QString tytułPozycji ) | Włącza i ustala własną nazwę pozycji w menu.
void removeCustomMenuItem(QString podmenu, QString tytułPozycji ) | Usuwa własną pozycję z menu.
QString readConfig( QString klucz) | Zwraca wartość konfiguracyjną AmarokConfig z podanego klucza.

## Opcje wiersza poleceń

Amarok obsługuje standardowe funkcje wiersza poleceń Qt oraz kde, posiada także opcje wykorzystywane tylko przez niego samego.

Opcje Qt i kde:

Opcja | Działanie
--- | ---
--help | Wyświetla pomoc na temat opcji.
--help-qt | Wyświetla opcje właściwe QT.
--help-kde | Wyświetla opcje właściwe KDE.
--help-all | Wyświetla wszystkie opcje.
--author | Wyświetla informacje na temat autora.
-v, --version | Pokazuje informacje o wersji.
--license | Wyświetla informacje na temat licencji.

Opcje Amarok:

Opcje &amarok-dopelniacz; są zaprojektowane do korzystania z nich podczas działania programu.

Opcja | Działanie
--- | ---
-r, --previous | Przechodzi do poprzedniego utworu na liście odtwarzania.
-p, --play | Rozpoczyna odtwarzanie bieżącej listy odtwarzania.
-s, --stop | Zatrzymanie odtwarzania.
--pause | Pauzuje odtwarzanie.
-f, --next | Przechodzi do następnego utworu na liście odtwarzania.
-a, --append | Dołącza pliki/adresy URL do listy odtwarzania.
-e, --enqueue | Zobacz append, dostępny na potrzeby wstecznej kompatybilności
--queue | Kolejkuj pliki/adresu URL po aktualnie odtwarzanym utworze.
-m, --toggle-playlist-window | Włącza/wyłącza okno listy odtwarzania.
--wizard | Uruchamia asystenta pierwszego uruchamiania.
--engine "name" | Uruchamia program &amarok-mianownik; z silnikiem o nazwie...

## Pisanie skryptów

Skrypty pozwalają na poszerzenie możliwości &amarok-dopelniacz; bez zmiany głównego kodu. Skrypty przypominają wtyczki, ale zamiast dedykowanej wtyczki API, wykorzystują one do komunikacji interfejs DCOP &amarok-dopelniacz;. Umożliwia to pisanie skryptów w prawie każdym języku programowania, jak np. Ruby, Python lub PHP. Każdy może tworzyć skrypty, nie tylko w klasycznych językach skryptowych, ale również w językach programowania jak C++ lub C. Dodatkowo, &amarok-mianownik; może powiadamiać skrypty o specjalnych zdarzeniach i sprawiać, że będą działać w odpowiedni sposób. Ten system powiadamiania będzie wyjaśniony w dalszej części tej sekcji.

### Powiązania dla języków skryptowych

Możliwe jest tworzenie prostych skryptów, które nie wymagają interakcji z użytkownikiem, można także tworzyć skrypty z przyjaznym interfejsem, które zachowują się jak samodzielne programy. Przy programowaniu interfejsu może być wykorzystane jedno lub więcej powiązań dostarczonych przez KDE, np. RubyQt, biblioteka powiązania dla języka Ruby. Traci to jednak jakąkolwiek wartość, jeśli nie każdy z użytkowników ma zainstalowane wszystkie dostępne powiązania. Jeśli zdecydujesz się na użycie powiązania, wybierz jedno z bardziej rozpowszechnionych (np. RubyQt lub PyQt).

Aby otrzymywana była informacja zwrotna, w sytuacji gdy jakiś skrypt nie działa z powodu brakującej zależności, musisz sprawdzić w skrypcie czy moduł, który chcesz dołączyć rzeczywiście istnieje. Jeśli brak jest zależności, powinieneś wychwycić błąd i wyświetlić okno informacyjne za pomocą programu "kdialog". Dzięki temu użytkownik dowie się, czemu jego skrypt nie działa.

Ten przykład pokazuje jak wychwycić brakującą zależność w języku Ruby:

    begin
           require 'Korundum'
    rescue LoadError
           error = 'Korundum (powiązania KDE dla języka Ruby) z pakietu kdebindings v3.4 są wymagane przez ten skrypt.'
           `kdialog --sorry '#{error}'`
           exit
    end

### Podstawowe informacje o szablonach

&amarok-mianownik; udostępnia szablony skryptów dla wielu języków w katalogu `scripts/templates/`. Możesz użyć tych skryptów jako podstawy Twoich własnych skryptów i poszerzyć je o pożądane funkcje. Przekonasz się, że tworzenie skryptów jest teraz rzeczywiście łatwe. Np. jeśli znasz nieco język Python; stworzenie skryptu nie zajmie Ci wiele czasu.

### Zarządzanie &amarok-narzednik; za pomocą interfejsu DCOP

Poprzez odwołania do niektórych funkcji DCOP, skrypty mogą zarządzać programem Amarok. Najprostszym sposobem wywołania funkcji DCOP jest użycie linii poleceń "dcop", która jest częścią każdej dystrybucji KDE.

Oto przykład jak zwiększyć głośność:

    dcop amarok player volumeUp

Większość języków skryptowych zezwala na wykonywanie zewnętrznych programów, z funkcją typu exec(). W ten sposób narzędzie "dcop" może być łatwo wywołane. Oto prosty przykład z języka Python:

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

### Powiadomienia

&amarok-mianownik; wysyła powiadomienia do wszystkich uruchomionych skryptów poprzez wprowadzenie napisów do kanału stdin. Skrypt powinien zatem nieustannie monitorować stdin i odpowiednio reagować na każde z możliwych zdarzeń. Skrypty mogą również zignorować każde, nieistotne dla nich zdarzenie.

&amarok-mianownik; wysyła następujące powiadomienia:

    configure
    Nakazuje skryptowi wyświetlenie okna konfiguracyjnego. Skrypt musi obsługiwać
    samodzielnie przechowywanie i wczytywanie opcji konfiguracyjnych. Kiedy skrypt
    jest uruchomiony, amaroK przenosi jego katalog roboczy do katalogu w którym
    powinny być przechowane wszystkie dane.

    engineStateChange:empty|idle|paused|playing
    Sygnalizuje zmianę stanu silnika.

    trackChange
    Sygnalizuje rozpoczęcie nowego utworu. Skrypt może wykorzystać funkcje DCOP do
    zapytań o dalsze informacje o utworze, np o metadane i o długość.

    volumeChangenewVolume
    Sygnalizuje zmianę poziomu głośności. Poziom głośności jest liczbą całkowitą z
     zakresu 0-100.

    customMenuClicked:submenu itemTitle paths
    Zwraca ścieżki do wybranych plików listy odtwarzania, po kliknięciu w menu
    kontekstowym listy odtwarzania użytkownika. W celach identyfikacyjnych zwracane są również podmenu i tytuł,
    na wypadek gdyby skrypt oczekiwał licznych powiadomień.
    Aby umieścić element w menu kontekstowym, użyj funkcji DCOP
    'dcop amarok script addCustomMenuItem( podmenu tytułPozycji )'. Aby usunąć element z
    menu kontekstowego, użyj funkcji DCOP
    'dcop amarok script removeCustomMenuItem( podmenu tytułPozycji )'.

### Zakończenie skryptu

Zanim &amarok-mianownik; zostanie zamknięty lub kiedy użytkownik zatrzyma skrypt w menedżerze skryptów, &amarok-mianownik; wysyła do skryptu sygnał SIGTERM. Sygnał może być zatrzymany w celu wykonania prac porządkowych, typu zapisanie danych czy opcji konfiguracyjnych.

### Pakowanie

Menedżer skryptów &amarok-dopelniacz; potrafi instalować paczki skryptów, które użytkownik pobrał z serwera WWW. Paczki to zwykłe tarball (.tar), opcjonalnie skompresowane za pomocą bzip2 (.bz2). Gorąco zachęcamy do używania nazw takich jak myscript.amarokscript.tar.bz2, tak aby użytkownik zidentyfikował paczkę jako skrypt programu Amarok.

&amarok-mianownik; 1.3 zaakceptuje jedynie paczki z rozszerzeniem amarokscript, więc lepiej używać tego rozszerzenia już teraz.

Zawartość tarball musi być zorganizowana w sposób następujący:

    myscript/
       README
       mojskrypt.py (program wykonywalny)
       modul.py
       foo.data
       ...

### Zezwolenia pliku

Główny skrypt musi posiadać zestaw zezwoleń wykonawczych (+x), podczas gdy dodatkowe moduły wczytywane przez skrypt nie powinny być wykonawcze. Aby chronić zezwolenia pliku w tarball, powinieneś użyć tar z -p flag:

    tar -cf myscript.amarokscript.tar -p myscript

&amarok-mianownik; nie będzie w stanie zainstalować skryptu, jeśli zezwolenia nie będą poprawnie ustawione.

### Dystrybucja

Kiedy paczka jest skończona, możesz wysłać ją do www.kde-apps.orgi umieścić odnośnik w &amarok-narzednik; Wiki Scripts Page. Przy wpisach kde-apps powinieneś użyć kategorii &amarok; Scripts.