<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" type="topic" id="guitar-tuner.c" xml:lang="cs">

  <info>

    <title type="text">Kytarová ladička (C)</title>

    <link type="guide" xref="c#examples"/>

    <desc>Jak použít GTK+ a GStreamer k sestavení jednoduché aplikace pro GNOME fungující jako kytarová ladička. Předvedeme si, jako používat návrhář rozhraní.</desc>

    <revision pkgversion="0.1" version="0.1" date="2010-12-02" status="review"/>

    <credit type="author">

      <name>Dokumentační projekt GNOME</name>

      <email its:translate="no">gnome-doc-list@gnome.org</email>

    </credit>

    <credit type="author">

      <name>Johannes Schmid</name>

      <email its:translate="no">jhs@gnome.org</email>

    </credit>

    <credit type="editor">

      <name>Marta Maria Casetti</name>

      <email its:translate="no">mmcasetti@gmail.com</email>

      <years>2013</years>

    </credit>

  </info>

<title>Kytarová ladička</title>

<synopsis>

  
V této lekci vytvoříme program, který přehrává tóny, které můžete použít k ladění kytary. Naučíte se, jak udělat tyto věci:

  <list>

    <item>
Vytvořit základní projekt ve studiu Anjuta.
</item>

    <item>
Vytvořit jednoduché GUI v návrháři GUI ve studiu Anjuta.
</item>

    <item>
Použít GStreamer k přehrání zvuku.
</item>

  </list>

  
Abyste mohli pokračovat v této lekci, budete potřebovat následující:

  <list>

    <item>
Nainstalovanou kopii <link xref="getting-ready">IDE Anjuta</link>
</item>

    <item>
Základní znalosti programovacího jazyka C
</item>

  </list>

</synopsis>

<media type="image" mime="image/png" src="media/guitar-tuner.png"/>

<section id="anjuta">

  <title>Vytvoření projektu ve studiu Anjuta</title>

  
Než začnete s kódováním, musíte ve studiu Anjuta vytvořit nový projekt. Tím se vytvoří všechny soubory, které budete později potřebovat k sestavení a spuštění kódu. Je to také užitečné kvůli udržení všeho pohromadě.

  <steps>

    <item>

    
Spusťte IDE Anjuta a klikněte na <guiseq><gui>Soubor</gui> <gui>Nový</gui> <gui>Projekt</gui></guiseq>, aby se otevřel průvodce projektem.

    </item>

    <item>

    
Na kartě <gui>C</gui> zvolte <gui>GTK+ (jednoduchý)</gui>, klikněte na <gui>Pokračovat</gui> a na několika následujících stránkách vyplňte své údaje. Jako název projektu a složky použijte <file>guitar-tuner</file>.

   	</item>

    <item>

    
Ujistěte se, že <gui>Konfigurovat externí balíčky</gui> je přepnuto na <gui>Zapnuto</gui>. Na následující stránce vyberte v seznamu gstreamer-0.10, aby se knihovna GStreamer zahrnula do vašeho projektu.

    </item>

    <item>

    
Klikněte na <gui>Použít</gui> a vytvoří se vám projekt. Otevřete <file>src/main.c</file> na kartě <gui>Projekt</gui> nebo <gui>Soubor</gui>. Měli byste vidět kód, který začíná řádky:

#include <config.h>

#include <gtk/gtk.h>

    </item>

  </steps>

</section>

<section id="build">

  <title>Prvotní sestavení kódu</title>

  
C je celkem „upovídaný“ jazyk, takže nebuďte překvapeni, že soubor obsahuje poměrně hodně kódu. Většina toho je kód šablony. Načte (prázdné) okno ze souboru s popisem uživatelského rozhraní a zobrazí jej. Dále to podrobněji rozebereme. Pokud jste již pochopili základy, tak tento seznam můžete přeskočit:

  <list>

  <item>

    
Tři řádky #include na začátku vkládají knihovny config (užitečné definice pro sestavení pomocí autotools), gtk (uživatelské rozhraní) a gi18n (internacionalizace). Funkce z těchto knihoven se používají ve zbytku kódu.

   </item>

   <item>

    
Funkce create_window vytvoří nové okno ze souboru GtkBulder (<file>src/guitar-tuner.ui</file>, definováno o pár řádků výše), připojí jeho signály a zobrazí jej v okně. Soubor GtkBuilder obsahuje popis uživatelského rozhraní a jeho prvků. K návrhu uživatelského rozhraní GtkBuilder můžete použít editor přímo ve vývojářském studiu Anjuta.

    
Napojení signálu je způsob, jak definovat, co se má stát, když zmáčknete tlačítko nebo se prostě něco přihodí. Zde je zavolána metoda destroy (a ukončení aplikace) při zavření okna.

   </item>

   <item>

    
Funkce main se spustí jako výchozí, když spustíte aplikaci napsanou v jazyce C. Volá pár funkcí, které nastaví a spustí aplikaci. Funkce gtk_main spustí hlavní smyčku GTK, která spustí uživatelské rozhraní a začne naslouchat událostem (jako je kliknutí nebo zmáčknutí klávesy).

   </item>

   <item>

    
Podmíněná definice ENABLE_NLS nastavuje gettext, což je základní konstrukce pro překládání aplikací do národních jazyků. Tyto funkce určují, jak mají překladové nástroje pracovat s vaší aplikací za běhu.

   </item>

  </list>

  
Kód je připravený k použití, takže jej můžete zkompilovat kliknutím na <guiseq><gui>Sestavit</gui> <gui>Sestavit projekt</gui></guiseq> (nebo zmáčknutím <keyseq><key>Shift</key> <key>F7</key></keyseq>).

  
V následujícím okně zmáčkněte <gui>Spustit</gui>, aby se nakonfigurovalo ladicí sestavení. Stačí to udělat jen jednou, pro první sestavení.

</section>

<section id="ui">

  <title>Vytvoření uživatelského rozhraní</title>

  
Popis uživatelského rozhraní se nachází v souboru GtkBuilder. Když chcete uživatelské rozhraní upravit, otevřete <file>src/guitar_tuner.ui</file>. Přepnete se tím do návrháře rozhraní. Navrhované okno je uprostřed, widgety a jejich vlastnosti jsou nalevo a paleta dostupných widgetů je napravo.

  
Rozvržení každého uživatelského rozhraní v GTK+ je provedeno pomocí boxů a mřížek. Zde použijeme svislý GtkButtonBox, do kterého přiřadíme šest GtkButtons, jedno pro každou z kytarových strun.

<media type="image" mime="image/png" src="media/guitar-tuner-glade.png"/>

  <steps>

   <item>

   
Vyberte <gui>GtkButtonBox</gui> z oddílu <gui>Kontejnery</gui> v <gui>Paletě</gui> napravo a vložte jej do okna. V panelu <gui>Vlastnosti</gui> nastavte počet prvků na 6 (pro 6 strun) a orientaci na svislou.

   </item>

   <item>

    
Nyní v paletě zvolte <gui>GtkButton</gui> a vložte jej do první části boxu.

   </item>

   <item>

    
Zatímco je tlačítko stále vybráno, změňte vlastnost <gui>Popisek</gui> na kartě <gui>Widgety</gui> na <gui>E</gui>. Bude se jednat o spodní strunu E.

    </item>

    <item>

     
Přepněte se na kartu <gui>Signál</gui> (uvnitř karty <gui>Widgety</gui>) a podívejte se po signálu clicked tlačítka. Můžete jej použít k napojení na obsluhu signálu, která bude volána, když uživatel na tlačítko klikne. Provede se to kliknutím na signál a vepsáním on_button_clicked do sloupce <gui>Obslužná rutina</gui> a zmáčknutím <key>Enter</key>.

    </item>

    <item>

    
Zopakujte předchozí kroky pro ostatní tlačítka, takže přidáte následujících 5 strun s názvy A, D, G, B a e.

    </item>

    <item>

    
Návrh uživatelského rozhraní uložte (kliknutím na <guiseq><gui>Soubor</gui> <gui>Uložit</gui></guiseq>) a ponechte jej otevřený.

    </item>

  </steps>

</section>

<section id="signal">

  <title>Vytvoření obsluhy signálů</title>

  
V návrháři uživatelského rozhraní můžete nastavit to, že všechna tlačítka budou při kliknutí volat stejnou funkci <gui>on_button_clicked</gui>. Tuto funkci musíme přidat do zdrojového kódu.

  
K tomu otevřete <file>main.c</file> a soubor s uživatelským rozhraním při tom ponechte stále otevřený. Přepněte se na kartu <gui>Signály</gui>, kterou jste již použili pro nastavení názvu signálu. Nyní chytněte řádek, na kterém jste nastavili signál <gui>clicked</gui> a přetáhněte jej do zdrojového kódu na místo mimo kteroukoliv funkci. Do zdrojového kódu se přidá následující kód:

void on_button_clicked (GtkWidget* button, gpointer user_data)

{

}

  
Obsluha signálu má dva argumenty: ukazatel na GtkWidget, který funkci zavolal (v našem případě vždy GtkButton) a ukazatel na nějaká „uživatelská data“, která si můžete nadefinovat, ale zde je nebudeme chtít použít. (Uživatelská data můžete nastavit zavoláním gtk_builder_connect_signals. Normálně se použivá k předání ukazatele na datovou strukturu, ke které můžete potřebovat přístup uvnitř obsluhy signálu.)

  
Prozatím ponecháme obsluhu signálu prázdnou a budeme pracovat na psaní kódu pro vyluzování zvuků.

</section>

<section id="gstreamer">

  <title>Roury systému GStreamer</title>

  
GStreamer je základní multimediální rámec GNOME. Můžete jej použít k přehrávání, nahrávání a zpracování videa, zvuku, vysílání z webové kamery a podobně. Zde jej použijeme ke generování tónu s jednou frekvencí.

  
Koncepčně GStreamer funguje následovně: Vytvoříte rouru (pipeline) obsahující různé prvky zpracující směrem od zdroje (source) do cíle (sink), tj. výstupu. Zdrojem může být například soubor s obrázkem, videosoubor nebo hudební soubor, výstupem pak widget nebo zvuková karta.

  
Na cestě mezi zdrojem a cílem můžete použít různé filtry a převodníky k vytvoření efektů, převodníky formátů atd. Každý prvek roury má vlastnosti, které můžete použít ke změně jeho chování.

  <media type="image" mime="image/png" src="media/guitar-tuner-pipeline.png">

    
Příklad roury systému GStreamer.

  </media>

</section>

<section id="pipeline">

  <title>Vytvoření roury</title>

  
V tomto příkladu použijeme jako zdroj tónový generátor nazývaný audiotestsrc a výstup pošleme do výchozího systémového zvukového zařízení autoaudiosink. Nastavit potřebujeme jen frekvenci tónového generátoru. Ta je přístupná přes vlastnost freq zmíněného audiotestsrc.

  
Vložte do <file>main.c</file> následující řádek, hned pod řádek #include <gtk/gtk.h>:

  #include <gst/gst.h>

  
Tímto se vloží knihovna GStreamer. Potřebujete také přidat řádek inicializující GStreamer. Vložte následující kód na řádek nad volání gtk_init do funkce main:

  gst_init (&argc, &argv);

  
Pak nakopírujte následující funkci do <file>main.c</file> nad prázdnou funkci on_button_clicked:

  static void

play_sound (gdouble frequency)

{

	GstElement *source, *sink;

	GstElement *pipeline;

	pipeline = gst_pipeline_new ("note");

	source   = gst_element_factory_make ("audiotestsrc",

	                                     "source");

	sink     = gst_element_factory_make ("autoaudiosink",

	                                     "output");

	/* nastaví frekvenci */

	g_object_set (source, "freq", frequency, NULL);

	gst_bin_add_many (GST_BIN (pipeline), source, sink, NULL);

	gst_element_link (source, sink);

	gst_element_set_state (pipeline, GST_STATE_PLAYING);

	/* zastaví to po 500 ms */

	g_timeout_add (LENGTH, (GSourceFunc) pipeline_stop, pipeline);

}

  <steps>

    <item>

    
Prvních pět řádků vytvoří prvky GStreamer typu zdroj a cíl (GstElement) a prvek typu roura (který bude použit jako kontejner pro první dva prvky). Roura dostane název „note“. Zdroj je pojmenován „source“ a je nastaven jako audiotestsrc. Cíl je pojmenován „output“ a je nastaven jako autoaudiosink (výchozí výstup zvukové karty).

    </item>

    <item>

    
Volání g_object_set nastaví vlastnost freq zdrojového prvku na frequency, která byla předána jako argument funkci play_sound. Jedná se o frekvenci tónu v hertzích. Správné frekvence nadefinujeme později.

    </item>

    <item>

    
gst_bin_add_many vloží zdroj a cíl do roury. Roura je GstBin, což je zase jen prvek, který může obsahovat více dalších prvků GStreamer. Obecně můžete přidat tolik prvků, kolik chcete, pomocí předáním více argumentů do gst_bin_add_many.

    </item>

    <item>

    
Následně je gst_element_link použito k propojení prvků navzájem, takže výstup prvku source (tón) putuje do vstupu prvku sink (což je výstup do zvukové karty). gst_element_set_state je použito ke spuštění přehrávání nastavením stavu roury na přehrávání (GST_STATE_PLAYING).

    </item>

  </steps>

</section>

<section id="stop">

  <title>Zastavení přehrávání</title>

  
Nechceme ale hrát nějaký tón navždycky, takže poslední věcí, kterou play_sound udělá, je, že zavolá g_timeout_add. Tím se nastaví časový limit pro zastavení zvuku. Čeká v délce LENGTH milisekund a pak zavolá funkci pipeline_stop, která vrátí FALSE, jinak by se v jejím volání pokračovalo.

  
Nyní budeme psát funkci pipeline_stop, která je volána z g_timeout_add. Vložte následující kód nad funkci play_sound:

#define LENGTH 500 /* Délka přehrávání v ms */

static gboolean

pipeline_stop (GstElement* pipeline)

{

	gst_element_set_state (pipeline, GST_STATE_NULL);

	g_object_unref (pipeline);

	return FALSE;

}

  
Zavolání gst_element_set_state zastaví přehrávání roury a g_object_unref zruší odkazy na rouru, zlikviduje ji a uvolní její paměť.

</section>

<section id="tones">

  <title>Definice tónů</title>

  
Když uživatel klikne na tlačítko, chceme zahrát správný zvuk. Nejdříve ze všeho potřebujeme znát frekvence pro šest kytarových strun, které jsou definovány (na začátku <file>main.c</file>) následovně:

/* Řetězce pro jednotlivé frekvence */

#define NOTE_E 329.63

#define NOTE_A 440

#define NOTE_D 587.33

#define NOTE_G 783.99

#define NOTE_B 987.77

#define NOTE_e 1318.5

  
Nyní oživíme obsluhu signálu, kterou jsme zadeklarovali již dříve po názvem on_button_clicked. Mohli bychom mít napojená všechna tlačítka na různé obslužné funkce, ale to by vedlo ke zbytečné duplicitě kódu. Místo toho použijeme popisek každého z tlačítek ke zjištění, na které tlačítko bylo kliknuto:

/* Zpětná volání pro tlačítka */

void on_button_clicked (GtkButton* button,

                        gpointer user_data)

{

	const gchar* text = gtk_button_get_label (button);

	if (g_str_equal (text, _("E")))

	    play_sound (NOTE_E);

	else if (g_str_equal (text, _("A")))

	    play_sound (NOTE_A);

	else if (g_str_equal (text, _("G")))

	    play_sound (NOTE_G);

	else if (g_str_equal (text, _("D")))

	    play_sound (NOTE_D);

	else if (g_str_equal (text, _("B")))

	    play_sound (NOTE_B);

	else if (g_str_equal (text, _("e")))

	    play_sound (NOTE_e);

}

  
Ukazatel na GtkButton, na které bylo kliknuto je předán jako argument (button) do on_button_clicked. Text tohoto tlačítka můžeme získat pomocí gtk_button_get_label.

  
Text se porovnává s notami, které máme pomocí g_str_equal a play_sound je voláno s příslušnou frekvencí odpovídající notě. Tím se zahraje tón a my máme konečně fungující kytarovou ladičku!

</section>

<section id="run">

  <title>Sestavení a spuštění aplikace</title>

  
Celý kód by nyní měl být připravený k fungování. Klikněte na <guiseq><gui>Sestavit</gui> <gui>Sestavit projekt</gui></guiseq>, aby se vše znovu sestavilo a pak na <guiseq><gui>Spustit</gui> <gui>Spustit</gui></guiseq>, aby se aplikace spustila.

  
Pokud jste tak ještě neučinili, zvolte aplikaci <file>Debug/src/guitar-tuner</file> v dialogovém okně, které se objeví. Nakonec klikněte na <gui>Spustit</gui> a užijte si ji!

</section>

<section id="impl">

 <title>Ukázková implementace</title>

 
Pokud v této lekci narazíte na nějaké problémy, porovnejte si svůj kód s tímto <link href="guitar-tuner/guitar-tuner.c">ukázkovým kódem</link>.

</section>

<section id="next">

  <title>Další postup</title>

  
Zde je pár nápadů, jak byste mohli tuto jednoduchou ukázku rozšířit:

  <list>

   <item>

   
Přidat do programu možnost cyklicky procházet tóny.

   </item>

   <item>

   
Naučit program přehrávat nahrávky vybrnkání jednotlivých reálných kytarových strun.

   
Abychom to mohli udělat, potřebujeme sestavit mnohem složitější rouru GStreamer, která umožní načíst a přehrát hudební soubory. Budete muset zvolit prvky GStreamer typu <link href="http://gstreamer.freedesktop.org/documentation/plugins.html">dekodér a demultiplexor</link> podle formátu souborů s vašimi zvukovými nahrávkami – například MP3 používá jiné prvky než Ogg Vorbis.

   
Můžete také potřebovat prvky propojit mnohem komplikovanějším způsobem. Toho lze dosáhnout pomocí <link href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/manual/html/chapter-intro-basics.html">konceptů GStreamer</link>, které jsme v této lekci neprobírali. Mezi ně patří například <link href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/manual/html/section-intro-basics-pads.html">přípojné body</link>. Hodit se vám může také příkaz <cmd>gst-inspect</cmd>.

   </item>

   <item>

   
Automaticky analyzovat tóny, které uživatel zahraje.

   
Mohli byste připojit mikrofón a nahrávat z něj zvuky pomocí <link href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-good-plugins/html/gst-plugins-good-plugins-autoaudiosrc.html">vstupního zdroje</link>. Zjistit, který tón je přehráván, by vám možná pomohla <link href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-good-plugins/html/gst-plugins-good-plugins-plugin-spectrum.html">spektrální analýza</link>.

   </item>

  </list>

</section>

</page>