Amarok Website

From Amarok Wiki

Contents 1 Giriş 1.1 Bağlar 2 SVN (Alt sürüm) Sunucusu 3 Başlangıç: Şablonlar 4 DCOP ile Amarok'u kontrol etmek 5 İçerik Menüsü Girişleri 6 Uyarılar 7 Betik Verisine Ulaşmak 8 Betik Yoketmek 9 Paketlemek 9.1 Özellikler dosyası (Spec File) 9.2 Dosya İzinleri 9.3 Dağıtım

Giriş

Betikler Amarok'un kolayca ana kod tabanını değiştirmeden gelişmesini sağlarlar. Betikler eklentilere benzerler, ama adanmış uygulama programlama arayüzü yerine Amarok'un DCOP arayüzünü haberleşmek için kullanırlar. Bu sayede betikler her hangi bir programlama dilinde yazılabilir, Ruby, Python veya bash betik yazma dili gibi. Tavsiye edilen programlama dili Ruby'dir, çünkü kolay öğrenilebilir ve Amarok betiği yazmak için çok uygundur. Ruby programcılığı hakkında sorularınız olursa Amarok takımı size yazdımcı olmaktan mutluluk duyacaktır.

Ek olarak, Amarok özel olaylarda betikleri uyarabilir ve buna göre etki etmelerini sağlayabilir. Bu belgenin ilerleyen kısımlarında uyarı sistemi açıklanacaktır.

Bağlar

Kullanıcı ile etkleşime girmeyen ve kendileri ayrı küçük bir uygulamaymış gibi kullanışlı grafik arayüze sahip betikler yazmak mümkündür. Grafik arayüzlü programcılık için KDE'nin sağladığı bağlardan biri olan Qt için bir Ruby bağ kütüphanesi olan QtRuby kullanılabilir. kurulu bütün olası bağlara bütün kullanıcıların sahip olmadığını unutmamak gerekir. Eğer bir bağ kullanmaya karar verdiyseniz, en yaygın olanını tercihedin. (ör. QtRuby veya PyQt).

Bir betik kayıp bağımlılık ile ilgili bir hata verdiğinde, sizin bulunmasını istediğiniz modülün bulunup bulunmadığını kontrol edin. Eğer bağ kayıpsa, hatayı "kdialog" komut satırı aracı ile hatayı yakalamalısınız, böylece betiğin neden çalışmadığını kullanıcı öğrenir.

Not: kdialog rehberi

Bu Ruby'de kayıp bağımlılık nasıl yakalanır örneği:

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

SVN (Alt sürüm) Sunucusu

Amarok projeleri betik geliştiricilerine proje sunucusunda bir ücresiz SVN hesabı verir account on our project server. SVN programlar geliştirmenize yardımcı olan bir sürüm kontrol sistemidir.Her hangi bir zamanda yaptığınız hatayı düzeltmenizi sağlayan, bir çok geliştiricinin ortak çalışarak bir proje geliştirmesini sağlar. Eğer bir hesap edinmek istiyorsanız, eposta gurubuna yazın amarok@kde.org.

Başlangıç: Şablonlar

Amarok scripts/templates/ dizininde bir kaç dil için şablon betik sağlar. Bunları kendi betiğinize temel olarak kullanabilirsiniz, ve ihtiyacınız olan özelliğe göre geliştirebilirsiniz. Betik yazmanın bir adım ötede lduğunu anlayacaksınız. Örneğin biraz Ruby'de programlama biliyorsanız, kendi betiğinizi yazmanız çok uzun zaman almayacaktır :) Yapılacaklar: Daha çok şablona ihtiyacımız var! Eğer bir tane yaparsanız, eposta grubumuza amarok@kde.org lütfen yollayın .

DCOP ile Amarok'u kontrol etmek

Betikler bazı DCOP işlevleri ile Amarok'u kontrol edebilir. by calling some of its .dcop işlevini çağırmanın en kolay yolu KDE dağıtımının bir parçası olan "dcop" komut satırı aracıdır. Örneğin burada sesi açma örneği var:

 "dcop amarok player volumeUp"

Çoğu betik dilleri dış programların uygulama yapmasına (execute kelimesinin kısaltması) exec() gibi bir işlevle izin verir. Bu yolla "dcop" aracı basitce çağırılabilir.

Ruby'de bunu yapmak çok basit, şu komutlarla yapılabilir:

 artist = `dcop amarok player artist`

Burada bir basit Python örneği var:

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

python kullanırken DCOP çağrılara yapmanın başka yollarıda vardır. pyKDEleri dcop veya dcopext modül kullanabilirsiniz. Because of some limitations (ör. amarok.contextbrowser.showLyrics() komutunu çağırabilirsiniz, amarok.contextbrowser.showLyrics(QString)) komutunu değil dcopext 'in düzenlenmiş bir sürümünü kullanmanızı tavsiye ederim. buna bakın

 from dcopext import DCOPClient, DCOPApp
 import sys
 
 # create a new DCOP-Client:
 client = DCOPClient()
 
 # connect the client to the local DCOP-server:
 client.attach()
 
 # create a DCOP-Application-Object to talk to amarok:
 amarok = DCOPApp('amarok', client)
 
 # call a DCOP-function:
 ok, artist = amarok.player.artist()
 
 # Amarok 1.4 and the modified version of dcopext:
 ok, void = amarok.contextbrowser.showLyrics(
     '<lyric artist="Foo" title="Bar" page_url="http://foobar.org">text</lyric>')

Eğer ok == doğru ise çağrı başarılıdır.

İçerik Menüsü Girişleri

Basit bir dcop çağrısı ile parça listesine tasarlanmış menü girişleri ekleyebilirsiniz:

dcop amarok script addCustomMenuItem "MyScript" "MyAction"

Bu girişi basitçe silebilirsiniz!

dcop amarok script removeCustomMenuItem "MyScript" "MyAction"

Betiğin menü girişinin tıklanması beklediğinden emin olun, eğer tıklanmasını beklemiyorsa hiç bir şey yapmayacaktır. Aşağıdaki tasarlanmış menü girişi uyarısına bakınız.

Uyarılar

Amarok bütün çalışan betiklere stdin kanalı aracılığı ile dizgi yazarak uyarılarını yollar. Betik olası olaylara tepki vermesi için sürekli stdin 'i izemesi gerekir. Ayrıca betikler kullanım alanı olmayan şeyleri reddetmek için kullanılabilir.

Burada Amarok'da Ruby ile ana döngü incelemesi ve işlem uyarıları örneği varıdır:

loop do
    message = gets().chomp() #Read message from stdin
    command = /[A-Za-z]*/.match( message ).to_s()

    case command
        when "configure"
            msg  = '"This script does not have configuration options."'
            `dcop amarok playlist popupMessage "#{msg}"`

        when "fetchLyrics"
            args = message.split()

            artist = args[1]
            title  = args[2]

            lyrics = fetchLyrics( artist, title )
            `dcop amarok script showLyrics "#{lyrics}"`
    end
end

Aşağıdaki uyarılar Amarok tarafından gönderilmiştir:

• configure

Betiğe ayarlar diyaloğunu göstermesini söyler. Betiğin depolama ve yükleme ayar seçeneklerini kendi ele almasını söyler. Bir betik başladığında, Amarok onun çalışan dizinini bütü verilerin depolanması gerektiği yere ayarlar.

İPUCU: Betik kullanılmadan önce ayarlanmak zorunda ise, açılışta otoatik olarak ayarlar kullanıcı grafik arayüzünü gösterin.

• engineStateChange: {empty|idle|paused|playing}

Motorun durumunda değişiklik sinyali verir.

• trackChange

yeni bir şarkıya başlandığının siyalleri. Şarkı hakkında daha ileri bilgi sorgusu için betik DCOP işlevlerini kullanabilir. örneğin metadata ve uzunluk.

• volumeChange: {newVolume}

Sinyaler ana ses seviyesinin değişimidir. Ses (volume) 0-100'e kadar değer alabilen bir değişkendir.

Not: Uyarı Amarok 1.3 serisinde eklendi.

• customMenuClicked: {submenu itemTitle paths}

Tasarlanmış parça listesi içerik menüsü ögesi tıklandığında parça listesindeki dosyaların adresine geri döner. Bir betik çok uyarı dinlediğinden Alt menü(submenu) ve öge adı(itemTitle) ayrıca belirlemek amacıyla döner.İçerik mensüne bir öge girmek için DCOP çağrısı 'dcop amarok script addCustomMenuItem( submenu itemTitle )' kullanın. İçerik menüsünden öge çıkarmak için DCOP çağrısı olan 'dcop amarok script removeCustomMenuItem( submenu itemTitle )' kullanın.

Not: Bu uyarı uyarı Amarok 1.3 serilerinde eklendi.

• fetchLyrics {artist title}

Sinyaller şuyan çalan parça için şarkı sözü ister. Bu uyarı sadece bir şarkı sözü eklentisine iletilebilir. Bir eklentiyi şarkı sözü eklentisi ilan etmek için Türü=şarkı sözü(type=lyrics) olan özel bir dosya lazım. Bakınız özel dosya.

Şarkıcı ve Başlık dizgileri CGI ile kodlanmıştır, bunun anlamı boşluk, '?', '&', '=', '%' ve diğer özel karakterler, bir CGI-sorgu-dizgi 'sinde mümkün değildir, bunlar %xx olarak gösterilir x 16lık sayı düzeninde karakter değerini temsil eden bbir sayıdır. Şarkıcı ve başlık dizgileri boşda olabilir, böylece eklentiye dizgilerden biri veya hiçbiri geçmeyecektir.

Şarkı sözleri alındığında, Amarok'a dcop metodu amarok.contextbrowser.showLyrics(QString) ile gönderilmelidirler. Bu işlev için parametre şu XML biçindedir:

 <lyric artist="artist name" title="song title" page_url="http://provided.by">
 text text text
 
 text text text
 ...
 </lyric>

Bütün karakterleri gözden kaçırmamayı unutmayın! Bunu hatasız yapmak için XML uygulama arayüzü kullanın(örnek. python modülü xml.dom).

Doğru eşleşme olmadığında, şu biçimde öneride bulunun:

 <suggestions page_url="http://provided.by">
 <suggestion artist="artist name" title="song title" url="http://url.to/the/specific/lyrics" />
 ...
 </suggestions>

Hiç şarkı bulunmadığında:

<suggestions page_url="http://provided.by">
</suggestions>

Şarkı sözü sunucusu ile haberleşme sorunu olduğunda, sadece boş dizgi yollayın.

Not: Bu uyarı Amarok 1.4 serilerinde eklendi.

• fetchLyricsByUrl {url}

Bu uyarı önerilen şarkı sözü tıklandığında yollanır. url uygun önerideki url-özelliğidir ve CGI ile kodlanmıştır. en azından karakterler şöyledir 'ä'. kodlanmasına gerek olmadığında tekrar geri dönüştürmelisiniz.

Not: Bu uyarı uyarı Amarok 1.4 serilerinde eklendi.

• transcode {url} {filetype}

Bir ortam oynatıcısına gönderilmeden önce farklı bir biçime dönüştürülmesi gerektiğinde bu uyarı yollanır.Eğer betik türünü kendi .spec dosyasında 'transcode' (dönüştür) olarak listelerseniz,e bir betik bu isteğe tepki verebilir. bakınız Spec dosyası.

Şöyle bir betik şöyle bir isteğe amarok.mediabrowser.transcodingFinished(QString,QString) dcop metodu ile cevap vermeli,diğer durumda transfer işlemi belirsiz bir süre bloke edilir.kod dönüştürülmesi için betiğe ilk geçecek konu url olmalı, ikinci konu ise dönüştürülmüş dosyanın veya eğer bir hata varsa boş bir dizginin url'si olmalı.

Not: Bu uyarı uyarı Amarok 1.4 serilerinde eklendi.

Betik Verisine Ulaşmak

Amarok betikleri ~/.kde/share/apps/amarok/scripts-data/ dizininde çalışır, bu nedenler bütün ayar dosyaları vb. bu dizine yazılmalı. Eğer diğer berikleride içermeye ihtiyacınız varsa diğer betikleri ana betikle aynı dizine yerleştirin ve şu satırı dosyanın başına ekleyin :

$:.unshift File.join(File.dirname(__FILE__))

python'da betik dosyası gibi basitçe herhangi bir modülü aynı dizine yerleştirin. Python bu dizini arar, şuankini değil. Ama eğer o dizini, sizin betiğinize paketlenmiş bazı dosyaları okumak( resim gibi) için almak isterseniz, şunu kullanabilirsiniz:

import os

scriptfolder = os.path.dirname( os.path.abspath( __file__ ) )

Betik Yoketmek

Amarok kapatılmadan önce veya kullanıcı betiği betik yöneticisi ile kapatmadan önce, Amarok betik işlemine SIGTERM sinyali yollar. içerik menüsü girişlerini kaldırmak, yada veri kaydetmek ve yapılandırma ayarları gibi işleri temizlerken bu sinyal yakalanabilir.

Burada Ruby'de bir örnek var:

 def cleanup()
     puts( "Script was terminated." )
     `dcop amarok script removeCustomMenuItem #{scriptName} #{actionName}`
 end
 
 
 trap( "SIGTERM" ) { cleanup() }

yada python'da:

 import signal
 
 def cleanup(signum, frame):
    print 'Script was terminated.'
    amarok.script.removeCustomMenuItem(scriptName, actionName)
 
 signal.signal(signal.SIGTERM, cleanup)

PyQt kullandığınız zaman, oturum yöneticisine, betiğin oturum durumunu ele almaması için danışmak önemlidir, çünkü aksi taktirde hem Amarok hemde KDE tarafından betik başlatılır, zamanla işlemden kayıba sonuçlanır:

 class MyScript (QApplication):
   def saveState(self):
     # script is started by amarok, not by KDE's session manager
     sessionmanager.setRestartHint(QSessionManager.RestartNever)

Paketlemek

Amarok'un Betik yöneticisi bir web sunucusundan indirilen paketlerin kurulumuna olanak verir. Paketler sadece normal tarball'lerdir (.tar), o bzip2 (.bz2) ile sıkıştırılmışda olabilirler. dosya uzantısı .amarokscript.* olamalı, örneğin myscript.amarokscript.tar.bz2.

tarball'ların içeriği şunun gibi düzenlenmelidir:

myscript/
   BENİOKU
   LİSANS
   myscript.rb (çalıştırılabilir)
   myscript.spec (Amarok 1.4 özelliği)
   somemodule.rb
   foo.png
   ...

NOT: amarok 1.3.4'da olduğu gibi BENİ OKUbasit HTML etiketlerini destekler, böylece belge güzelce biçimlendirilebilir. Biz bunu bir KAboutDialog widget'inde gösterdik. Ayrıca eğer lisans dosyası KAboutDialog'da bir lisans sekmesi içeirir. lisans sekmesi HTML yazımını desteklemez.

Özellikler dosyası (Spec File)

(Bu Amarok 1.4'de yeni bir özellik)

bir özellikler{spec(ification) file} dosyası betik hakkında ek bilgi sağlamak için eklenebilir. Bu temelde basit bir INI sitilli metin dosyası, çoğu UNIX yapılandırma dosyası gibi. Şu anahtar/değer özellikleri şuanda desteklenmektedir:

name = <betiğiğn adı>
type = {generic|lyrics|transcode|score}

Bir özellik dosyası(spec file) kaybolduğunda yada isim özelliği belirlenmediğinde, betiğin adı isim olarak kullanılır. özellik dosyası çalıştırılabilir betik dosyası gibi aynı temel isme sahip olmalıdır ama ".spec" uzantısı ile olmalıdır. örneğin: "myscript.spec".

Şarkı sözü, dönüştür ve puan türünde betikler için Amarok sadece sürekli çalışan her türden bir tanesini dikkate alır.

şarkı sözü eklentileri şu tanımlanan özelliklere sahip olabilir(not [Şarkı sözleri lyrics]-bölümü):

 [Lyrics]
 add_url = <http://url.to/add/lyrics/page/of/the/lyrics/service>
 site = <name of the lyrics-service>
 site_url = <http://url.of/the/lyrics/service>

Dosya İzinleri

Ana betiğin çalıştırılabilir (+x) izinler setine sahip olmalıdır, betiğin yüklediği ek modüller çalıştırılabilir olmamalıdır. tarball'daki dosya izinerini korumak için, tar 'ı -p bayrağı ile kullanmalısınız:

tar -cf myscript.amarokscript.tar -p myscript

Eğer izinler doğru ayarlanmadıysa Amarok betiği kuramayacaktır.

Dağıtım

Paket bittiğinde kde-apps.org adresine yükleyebilirsiniz, ve Wiki'ye köprüsünü ekleyiniz (Scripts). kde-apps girişi için Amarok Scripts kategorisi bölümünü kullanın. Eğer betiğiniz Amarok Betik yöneticisi ile kurulabilir değilse bu kategoriyi kullanmayın .