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

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

    <desc>Use GTK+ and GStreamer to build a simple guitar tuner application for GNOME.</desc>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Luc Rebert,</mal:name>
      <mal:email>traduc@rebert.name</mal:email>
      <mal:years>2011</mal:years>
    </mal:credit>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Alain Lojewski,</mal:name>
      <mal:email>allomervan@gmail.com</mal:email>
      <mal:years>2011-2012</mal:years>
    </mal:credit>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Luc Pionchon</mal:name>
      <mal:email>pionchon.luc@gmail.com</mal:email>
      <mal:years>2011</mal:years>
    </mal:credit>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Bruno Brouard</mal:name>
      <mal:email>annoa.b@gmail.com</mal:email>
      <mal:years>2011-12</mal:years>
    </mal:credit>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Luis Menina</mal:name>
      <mal:email>liberforce@freeside.fr</mal:email>
      <mal:years>2014</mal:years>
    </mal:credit>
  </info>

  <title>Guitar tuner</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">GStreamer pipelines</link> </p></item>
      <item><p> <link xref="#script">Script for running the application</link> </p></item>
      <item><p> <link xref="#imports">Libraries to import</link> </p></item>
      <item><p> <link xref="#mainwindow">Creating the main window for the application</link> </p></item>
      <item><p> <link xref="#buttons">Buttons for the tunes</link> </p></item>
      <item><p> <link xref="#playSound">Making the sounds with GStreamer</link> </p></item>
      <item><p> <link xref="#connecting">Connecting buttons to playSound</link> </p></item>
      <item><p> <link xref="#guitarjs">The whole program</link> </p></item>
      <item><p> <link xref="#terminal">Running the application form 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: 329.63, 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 = Gst.ElementFactory.make("audiotestsrc","source");
  var sink = 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.NULL);
	  return false;
  });
}]]></code>
   <p>The first thing we need to do is decide what tunes we want to make when we push a button. The frequencies list takes care of that. After that we get to actually making the sounds with the function playSound. For function playSound we give as an input a frequency (that we just defined in the frequencies variable). First thing we need to construct is a pipeline, a source and a sink. For the source we set the frequency. To the pipeline we add both the source and the sink and then we tell it to keep playing. As a last thing we use the const Mainloop to get the pipeline to stop after a 500ms.</p>
   <p>Now we have the method of playing a tune when clicking a button. Next well make the connections between pushing a button and playing the correct sound from that button.</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 <code>E.connect("clicked",
   function(){playSound(frequencies.E);});</code> The <code>connect</code>
   tells that when pushing E, something should happen. The <code>clicked</code>
   tells the type of the signal happening to E and then in the
   <code>function(){};</code> we call playSound with the correct note that
   should be associated with the button.</p>
  </section>
  <section id="guitarjs">
    <title>Le programme complet</title>
    <p>So this is what all the parts combined looks like. When running this code, you should be able to tune your guitar (if you have correctly calibrated speakers).</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: 329.63, 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 = Gst.ElementFactory.make("audiotestsrc","source");
  var sink = 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.NULL);
	  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>