<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" type="guide" style="task" id="guitar-tuner.js" xml:lang="fr">
  <info>
  <title type="text">Guitar Tuner (JavaScript)</title>
    <link type="guide" xref="js"/>
    <revision version="0.1" date="2012-03-09" status="stub"/>

    <credit type="author copyright">
      <name>Susanna Huhtanen</name>
      <email>ihmis.suski@gmail.com</email>
      <years>2012</years>
    </credit>

    <desc>Utilisation de Gtk+ et de GStreamer pour construire une application d'accordeur de guitare simple pour GNOME.</desc>
  </info>

  <title>2 Accordeur de guitare</title>

    <synopsis>
      <p>Dans ce tutoriel, nous allons construire une petite application, Accordeur de guitare, utilisant JavaScript, GTK+ et GStreamer. Pour écrire et lancer tous les exemples de code vous-même, vous avez besoin d'un éditeur pour écrire le code, de Terminal et d'un ordinateur sur lequel GNOME 3 ou supérieur est installé. Dans ce guide, nous illustrerons les éléments suivants :</p>
   <list>
      <item><p> <link xref="#gstreamer">Les pipelines GStreamer</link> </p></item>
      <item><p> <link xref="#script">Script de lancement de l'application</link> </p></item>
      <item><p> <link xref="#imports">Bibliothèques à importer</link> </p></item>
      <item><p> <link xref="#mainwindow">Création de la fenêtre principale de l'application</link> </p></item>
      <item><p> <link xref="#buttons">Les boutons pour les sons</link> </p></item>
      <item><p> <link xref="#playSound">Création des sons avec GStreamer</link> </p></item>
      <item><p> <link xref="#connecting">Connexion des boutons à playSound</link> </p></item>
      <item><p> <link xref="#guitarjs">Le programme complet</link> </p></item>
      <item><p> <link xref="#terminal">Exécution de l'application à partir de Terminal</link> </p></item>
    </list>
  </synopsis>
  <p>Après avoir suivi ce tutoriel, vous devriez voir ceci sur votre écran :</p>
  <media type="image" mime="image/png" src="media/guitar-tuner.png"/>
  <section id="gstreamer">
    <title>Les pipelines GStreamer</title>
    <p>GStreamer est l'architecture multimédia de GNOME — vous pouvez vous en servir pour des jeux, des enregistrements, pour traiter des flux vidéo, audio, de webcam entre autres. Ici, nous allons nous en servir pour émettre des tonalités à une seule fréquence.</p>
    <p>Le concept de GStreamer est le suivant : il y a création d'un <em>pipeline</em> contenant plusieurs éléments de traitement en provenance d'une <em>source</em> à destination d'un <em>collecteur</em> (sortie). La source peut être un fichier image, une vidéo ou un fichier musical, par exemple, et la sortie un élément graphique ou une carte son.</p>
    <p>Entre la source et le collecteur, vous pouvez appliquer différents filtres et convertisseurs pour prendre en charge les effets, les conversions de format et ainsi de suite. Chaque élément du pipeline possède des propriétés pouvant être utilisées pour modifier son comportement.</p>
    <media type="image" mime="image/png" src="media/guitar-tuner-pipeline.png">
      <p>Un exemple de pipeline GStreamer.</p>
    </media>
  </section>
  <section id="script">
    <title>Script de lancement de l'application</title>
    <code mime="application/javascript" style="numbered"><![CDATA[
  #!/usr/bin/gjs]]></code>
    <p>Cette ligne indique comment lancer le script. Elle doit être la première ligne de code et le script doit être exécutable. Pour donner les bonnes permissions, allez dans Terminal et lancer dans le dossier correct la commande : chmod +x nomduscript. Vous pouvez aussi utiliser le gestionnaire de fichiers graphique. Déplacez-vous dans le bon dossier où se trouve votre code, faites un clic-droit sur le fichier, sélectionnez Propriétés, cliquez sur l'onglet Permissions et cochez la case pour permettre l'exécution du fichier comme un programme.</p>
  </section>
  <section id="imports">
    <title>Bibliothèques à importer</title>
    <code mime="application/javascript" style="numbered"><![CDATA[
var Gtk = imports.gi.Gtk;
var Gst = imports.gi.Gst;

const Mainloop = imports.mainloop;]]></code>
    <p>Afin que le programme fonctionne, vous devez importer quelques  bibliothèques d'introspection GObject à utiliser. Pour faire une interface graphique, nous avons besoin de Gtk et pour que Gstreamer fonctionne, nous avons besoin de Gst. Elles sont importées au début afin de pouvoir les utiliser partout ensuite. Nous importons également au début une boucle principale Mainloop pour prendre en charge le délai à utiliser avec les sons d'accordage.</p>
    </section>
  <section id="mainwindow">
    <title>Création de la fenêtre principale de l'application</title>
    <code mime="application/javascript" style="numbered"><![CDATA[
Gtk.init(null, 0);
Gst.init(null, 0);

var guitarwindow = new Gtk.Window({type: Gtk.WindowType.TOPLEVEL, border_width: 100});
guitarwindow.title = "Guitar Tuner";
guitarwindow.connect("destroy", function(){Gtk.main_quit()});

guitarwindow.show();
Gtk.main();]]></code>
    <p>L'importation de Gtk et Gst n'est pas suffisante, nous devons les initialiser afin qu'elles fonctionnent. Lorsque c'est fait, nous devons créer la fenêtre de l'application. Plus tard, nous allons placer tous les boutons pour faire les sons dans cette fenêtre. Afin que la fenêtre s'affiche, nous devons lui dire de s'afficher et nous avons besoin de lancer le code avec Gtk.main().</p>
  </section>
  <section id="buttons">
   <title>Les boutons pour les sons</title>
   <code mime="application/javascript" style="numbered"><![CDATA[
var guitar_box = new Gtk.ButtonBox ({orientation: Gtk.Orientation.VERTICAL, spacing: 10});

var E = new Gtk.Button({label: "E"});
var A = new Gtk.Button({label: "A"});
var D = new Gtk.Button({label: "D"});
var G = new Gtk.Button({label: "G"});
var B = new Gtk.Button({label: "B"});
var e = new Gtk.Button({label: "e"});

guitar_box.add(E);
guitar_box.add(A);
guitar_box.add(D);
guitar_box.add(G);
guitar_box.add(B);
guitar_box.add(e);

guitarwindow.add(guitar_box);

guitar_box.show_all();]]></code>
   <p>Puisque Gtk.Window ne peut contenir qu'un seul élément graphique, nous devons créer quelque chose en dessous pour pouvoir ajouter tous les boutons nécessaires à l'intérieur. Dans cet exemple, nous utilisons Buttonbox. Après la création de Buttonbox,  nous créons les boutons avec les étiquettes nécessaires. Après l'obtention des boutons, nous devons les ajouter au Buttonbox et celui-ci doit être ajouté au Gtk.Window et tout ce qui est dans Buttonbox doit être affiché.</p>
   <p>Après cette étape, vous devriez voir s'afficher une fenêtre à l'écran avec les 6 boutons. Pour l'instant, les boutons n'ont aucune action et nous verrons cela plus tard. Pour pouvoir connecter les signaux des boutons à quelque chose, il nous faut d'abord coder ce quelque chose.</p>
  </section>
  <section id="playSound">
   <title>Création des sons avec GStreamer</title>
   <code mime="application/javascript" style="numbered"><![CDATA[
var frequencies = {E: 369.23, A: 440,	D: 587.33,	G: 783.99,	B: 987.77,	e: 1318.5}

function playSound(frequency){
  var pipeline = new Gst.Pipeline({name: "note"});
  var source = new Gst.ElementFactory.make("audiotestsrc","source");
  var sink = new Gst.ElementFactory.make("autoaudiosink","output");

  source.set_property('freq', frequency);
  pipeline.add(source);
  pipeline.add(sink);
  source.link(sink);
  pipeline.set_state(Gst.State.PLAYING);

  Mainloop.timeout_add(500, function () {
    pipeline.set_state(Gst.State.PAUSED);
	  return false;
  });
}]]></code>
   <p>La chose à faire en premier est de décider quel son doit être émis à l'appui sur un bouton. La liste des fréquences gère cela. Ensuite, il nous faut émettre les sons avec la fonction playSound, à laquelle nous donnons en entrée une fréquence (définie par les variables fréquences). Construisons d'abord un pipeline, une source et un collecteur. Définissons la fréquence pour la source, ajoutons la source et le collecteur au pipeline et faisons le jouer. Enfin, utilisons la constante Mainloop pour arrêter l'émission du son après 500ms.</p>
   <p>Maintenant, nous avons la bonne méthode pour émettre un son après appui sur un bouton. Faisons ensuite la connexion entre l'appui sur un bouton et l'émission du son correct relié à ce bouton.</p>
  </section>
  <section id="connecting">
   <title>Connexion des boutons à playSound</title>
   <code mime="application/javascript" style="numbered"><![CDATA[
E.connect("clicked", function() {
  playSound(frequencies.E);
});
A.connect("clicked", function(){
  playSound(frequencies.A);
});
D.connect("clicked", function(){
  playSound(frequencies.D);
});
G.connect("clicked", function(){
  playSound(frequencies.G);
});
B.connect("clicked", function(){
  playSound(frequencies.B);
});
e.connect("clicked", function(){
  playSound(frequencies.e);
});]]></code>
   <p>The method of connecting button clicks to playSound with the correct tune is by using the connect method of the button widget. So we choose a button to be connected and type E.connect("clicked", function(){playSound(frequencies.E);}); The connect tells that when pushing E, something should happen. The "clicked" tells the type of something happening to E and then in the function(){}; we the playSound happen with the correct tune that should be associated to the button.</p>
  </section>
  <section id="guitarjs">
    <title>Le programme complet</title>
    <p>Voici donc ce que donne toutes les parties assemblées. Lorsque vous exécutez ce code, vous devriez être capable d'accorder votre guitare (si vous avez correctement calibré vos haut-parleurs).</p>
      <code mime="application/javascript" style="numbered"><![CDATA[
#!/usr/bin/gjs
var Gtk = imports.gi.Gtk;
var Gst = imports.gi.Gst;

const Mainloop = imports.mainloop;

Gtk.init(null, 0);
Gst.init(null, 0);

var guitarwindow = new Gtk.Window({type: Gtk.WindowType.TOPLEVEL, border_width: 100});
guitarwindow.title = "Guitar Tuner";
guitarwindow.connect("destroy", function(){Gtk.main_quit()});

var guitar_box = new Gtk.ButtonBox ({orientation: Gtk.Orientation.VERTICAL, spacing: 10});

var E = new Gtk.Button({label: "E"});
var A = new Gtk.Button({label: "A"});
var D = new Gtk.Button({label: "D"});
var G = new Gtk.Button({label: "G"});
var B = new Gtk.Button({label: "B"});
var e = new Gtk.Button({label: "e"});

var frequencies = {E: 369.23, A: 440,	D: 587.33,	G: 783.99,	B: 987.77,	e: 1318.5}


function playSound(frequency){
  var pipeline = new Gst.Pipeline({name: "note"});

  var source = new Gst.ElementFactory.make("audiotestsrc","source");
  var sink = new Gst.ElementFactory.make("autoaudiosink","output");

  source.set_property('freq', frequency);
  pipeline.add(source);
  pipeline.add(sink);
  source.link(sink);
  pipeline.set_state(Gst.State.PLAYING);

  Mainloop.timeout_add(500, function () {
    pipeline.set_state(Gst.State.PAUSED);
	  return false;
});
}

E.connect("clicked", function() {
  playSound(frequencies.E);
});
A.connect("clicked", function(){
  playSound(frequencies.A);
});
D.connect("clicked", function(){
  playSound(frequencies.D);
});
G.connect("clicked", function(){
  playSound(frequencies.G);
});
B.connect("clicked", function(){
  playSound(frequencies.B);
});
e.connect("clicked", function(){
  playSound(frequencies.e);
});

guitar_box.add(E);
guitar_box.add(A);
guitar_box.add(D);
guitar_box.add(G);
guitar_box.add(B);
guitar_box.add(e);

guitarwindow.add(guitar_box);

guitar_box.show_all();
guitarwindow.show();
Gtk.main();]]></code>
  </section>

<section id="terminal">
  <title>Exécution de l'application à partir de Terminal</title>
  <p>Pour lancer cette application, ouvrez Terminal, allez dans le dossier où votre application est enregistrée et lancez</p> <screen> <output style="prompt">$</output><input>GJS_PATH=`pwd` gjs guitarTuner.js</input> </screen>
    </section>

<section id="impl">
 <title>Implémentation de référence</title>
 <p>Si vous rencontrez des difficultés avec ce tutoriel, comparez votre programme à ce <link href="guitar-tuner/guitar-tuner.js">programme de référence</link>.</p>
</section>


</page>
