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

  <info>

    <title type="text">Afinador de guitarra (C)</title>

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

    <desc>Usar GTK+ y GStreamer para construir un sencillo afinador de guitarra para GNOME. Muestra cómo usar el diseñador de interfaces.</desc>

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

    <credit type="author">

      <name>Proyecto de documentación de 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>

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">

      <mal:name>Daniel Mustieles</mal:name>

      <mal:email>daniel.mustieles@gmail.com</mal:email>

      <mal:years>2011 - 2017</mal:years>

    </mal:credit>

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">

      <mal:name>Nicolás Satragno</mal:name>

      <mal:email>nsatragno@gmail.com</mal:email>

      <mal:years>2012 - 2013</mal:years>

    </mal:credit>

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">

      <mal:name>Jorge González</mal:name>

      <mal:email>jorgegonz@svn.gnome.org</mal:email>

      <mal:years>2011</mal:years>

    </mal:credit>

  </info>

<title>Afinador de guitarra</title>

<synopsis>

  
En este tutorial se va a hacer un programa que reproduce tonos que puede usar para afinar su guitarra. Aprenderá a:

  <list>

    <item>
Configurar un proyecto básico en Anjuta
</item>

    <item>
Crear una IGU sencilla con el diseñador IU de Anjuta
</item>

    <item>
Usar GStreamer para reproducir sonidos
</item>

  </list>

  
Necesitará lo siguiente para poder seguir este tutorial:

  <list>

    <item>
Una copia instalada del <link xref="getting-ready">EID Anjuta</link>
</item>

    <item>
Conocimiento básico del lenguaje de programación C
</item>

  </list>

</synopsis>

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

<section id="anjuta">

  <title>Crear un proyecto en Anjuta</title>

  
Antes de empezar a programar, deberá configurar un proyecto nuevo en Anjuta. Esto creará todos los archivos que necesite para construir y ejecutar el código más adelante. También es útil para mantener todo ordenado.

  <steps>

    <item>

    
Inicie Anjuta y pulse <guiseq><gui>Archivo</gui><gui>Nuevo</gui><gui>Proyecto</gui></guiseq> para abrir el asistente de proyectos.

    </item>

    <item>

    
Seleccione <gui>GTK+ (simple)</gui> en la pestaña <gui>C</gui>, pulse <gui>Continuar</gui>, y rellene sus detalles en las siguientes páginas. Use <file>afinador-guitarra</file> como nombre del proyecto y de la carpeta.

   	</item>

    <item>

    
Asegúrese de que <gui>Configurar paquetes externos</gui> está <gui>activada</gui>. En la siguiente página, seleccione gstreamer-0.10 de la lista para incluir la biblioteca GStreamer en su proyecto.

    </item>

    <item>

    
Pulse <gui>Aplicar</gui> y se creará el proyecto. Abra <file>src/main.c</file> desde las pestañas <gui>Proyecto</gui> o <gui>Archivo</gui>. Debería ver algo de código que comience con las líneas:

#include <config.h>

#include <gtk/gtk.h>

    </item>

  </steps>

</section>

<section id="build">

  <title>Construir el código por primera vez</title>

  
C es un lenguaje más detallado, por lo que no se sorprenda de que el archivo contiene un gran cantidad de código. La mayor parte es código de plantilla. Carga una ventana (vacía) desde el archivo de descripción de la interfaz de usuario y la muestra. A continuación se ofrecen más detalles; omita esta lista si entiende los conceptos básicos:

  <list>

  <item>

    
Las tres líneas #include en la parte superior incluyen las bibliotecas config (útil para definiciones de construcción de autoconf), gtk (interfaz de usuario) y gi18n (internacionalización). Las funciones de estas bibliotecas se usan en el resto del código.

   </item>

   <item>

    
La función create_window crea una ventana nueva abriendo un archivo de GtkBuilder (<file>src/guitar-tuner.ui</file>, definido unas pocas líneas más arriba), conectando sus señales y mostrándolo en una ventana. El archivo de GtkBuilder contiene una descripción de una interfaz de usuario y de todos sus elementos. Puede usar el editor Anjuta para diseñar interfaces de usuario con GtkBuilder.

    
Conectar señales es como se define lo que pasa cuando pulsa un botón, o cuando ocurre algún otro evento. Aquí, se llama a la función destroy (y se sale de la aplicación) cuando cierra la ventana.

   </item>

   <item>

    
La función main se ejecuta de manera predeterminada cuando inicia una aplicación en C. Llama a unas pocas funciones que configuran y ejecutan la aplicación. La función gtk_main inicia el bucle principal de GTK+, que ejecuta la interfaz de usuario y comienza a escuchar eventos (como pulsaciones del ratón y del teclado).

   </item>

   <item>

    
La definición condicional ENABLE_NLS configura gettext, que es un entorno de trabajo para traducir aplicaciones. Estas funciones especifican cómo deben manejar su aplicación las herramientas de traducción cuando las ejecuta.

   </item>

  </list>

  
Este código está listo para usarse, por lo que puede compilarlo pulsando <guiseq><gui>Construir</gui><gui>Construir proyecto</gui></guiseq> (o pulsando <keyseq><key>Mayús</key><key>F7</key></keyseq>).

  
Pulse <gui>Ejecutar</gui> en la siguiente ventana que aparece para configurar una construcción de depuración. Esto sólo necesita hacer una vez para la primera construcción.

</section>

<section id="ui">

  <title>Crear la interfaz de usuario</title>

  
El archivo de GtkBuilder contiene una descripción de la interfaz de usuario (IU). Para editar la interfaz de usuario, abra <file>src/guitar_tuner.ui</file>. Esto cambiará al diseñador de interfaces. La ventana de diseño está en el centro; los widgets y sus propiedades están a la izquierda, y la paleta de los widgets disponibles está a la derecha.

  
La distribución de cualquier IU en GTK+ se organiza usando cajas y tablas. Aquí se usará una <gui>GtkButtonBox</gui> vertical para asignar seis <gui>GtkButtons</gui>, uno para cada una de las cuerdas de la guitarra.

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

  <steps>

   <item>

   
Seleccione una <gui>GtkButtonBox</gui> de la sección <gui>Contenedor</gui> de la <gui>Paleta</gui> de la derecha y póngalo en la ventana. En el panel de <gui>Propiedades</gui>, establezca el número de elementos a «6» (para las seis cuerdas) y la orientación a «vertical».

   </item>

   <item>

    
Ahora, elija un <gui>GtkButton</gui> de la paleta y póngalo en la primera parte de la caja.

   </item>

   <item>

    
Mientras el botón esté seleccionado, cambie la propiedad <gui>Etiqueta</gui> en la pestaña <gui>Widgets</gui> a <gui>E</gui>. Esta será la cuerda Mi grave.

    </item>

    <item>

     
Cambie a la pestaña <gui>Señales</gui> (dentro de la pestaña <gui>Widgets</gui>) y busque la señal clicked del botón. Puede usar esto para conectar un manejador de señal al que se llamará cuando el usuario pulse el botón. Para hacer esto, pulse sobre la señal, escriba on_button_clicked en la columna <gui>Manejador</gui> y pulse <key>Intro</key>.

    </item>

    <item>

    
Repita los pasos anteriores para el resto de botones, añadiendo las 5 cuerdas restantes con los nombres A, D, G, B, y e.

    </item>

    <item>

    
Guarde el diseño de la IU (pulsando <guiseq><gui>Archivo</gui><gui>Guardar</gui></guiseq>) y déjelo abierto.

    </item>

  </steps>

</section>

<section id="signal">

  <title>Crear el manejador de señales</title>

  
El el diseñador de interfaces, se ha hecho que todos los botones llamen a la misma función, <gui>on_button_clicked</gui>, cuando se pulsan. Se debe añadir esta función al archivo de código fuente.

  
Para hacer esto, abra <file>main.c</file> mientras el archivo de la interfaz de usuario está abierto. Cambie a la pestaña <gui>Señales</gui>, que ya ha usado para establecer el nombre de la señal. Ahora vaya a la fila en la que estableció la señal <gui>clicked</gui> y arrástrela al archivo de código fuente, fuera de cualquier función. Se añadirá el siguiente código a su archivo de código fuente:

void on_button_clicked (GtkWidget* button, gpointer user_data)

{

}

  
El manejador de la señal tiene dos argumentos. un puntero al GtkWidget que llamó a la función (en este caso, siempre es un GtkButton), y un puntero a ciertos «datos de usuario» que puede definir, pero que aquí no se usan. (Puede establecer los datos de usuario llamando a gtk_builder_connect_signals; normalmente se usa para pasar un puntero a una estructura de datos a la que puede necesitar acceder dentro del manejador de la señal.)

  
Por ahora, se dejará el manejador de la señal vacío mientras se escribe el código para producir sonidos.

</section>

<section id="gstreamer">

  <title>Tuberías de Gstreamer</title>

  
GStreamer es el entorno multimedia de trabajo de GNOME: puede usarlo para reproducir, grabar y procesar vídeo, sonido, flujos de la cámara web y similares. En este caso, se usará para generar tonos de frecuencia única.

  
Conceptualmente. GStreamer funciona de la siguiente manera: puede crear una tubería que contenga varios elementos de procesado que van desde la fuente hasta el sumidero (salida). La fuente puede ser, por ejemplo, un archivo de imagen, un vídeo o un archivo de música, y la salida puede ser un widget o la tarjeta de sonido.

  
Entre la fuente y el sumidero, puede aplicar varios filtros y conversores para manejar efectos, conversiones de formato, etc. Cada elemento de la tubería tiene propiedades que se pueden usar para cambiar este comportamiento.

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

    
Un ejemplo de tubería de GStreamer.

  </media>

</section>

<section id="pipeline">

  <title>Configurar la tubería</title>

  
En este sencillo ejemplo se usará un generador de tonos llamado audiotestsrc y se enviará la salida al dispositivo de sonido predeterminado del sistema, autoaudiosink. Sólo es necesario configurar la frecuencia del generador de tonos; esto es accesible a través de la propiedad freq de audiotestsrc.

  
Inserte la siguiente línea en <file>main.c</file>, justo a continuación de la línea #include <gtk/gtk.h>:

  #include <gst/gst.h>

  
Esto incluye la bilbioteca GStreamer. También necesita añadir una línea para inicializar GStreamer; ponga la siguiente línea de código antes de la llamada gtk_init en la función main:

  gst_init (&argc, &argv);

  
Después, copie la siguiente función en <file>main.c</file> encima de la función on_button_clicked vacía:

  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");

	/* set frequency */

	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);

	/* stop it after 500ms */

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

}

  <steps>

    <item>

    
Las cinco primeras líneas crean los elementos «fuente» y «sumidero» de GStreamer (GstElement), y un elemento de tubería (que se usará como contenedor de los otros dos elementos). A la tubería se le asigna el nombre «note»; la fuente se llama «source» y se asocia a la fuente audiotestsrc y el sumidero se llama «output» y se asocia con el sumidero autoaudiosink (la salida de la tarjeta de sonido predeterminada).

    </item>

    <item>

    
La llamada a g_object_set establece la propiedad freq del elemento fuente a frequency, que se pasa como argumento a la función play_sound. Esto sólo es la frecuencia de la nota en Hercios; más adelante se definirán algunas frecuencias útiles.

    </item>

    <item>

    
gst_bin_add_many añade la fuente y el sumidero a la tubería. La tubería es un GstBin, que es un elemento que puede contener otros muchos elementos de GStreamer. En general, puede añadir tantos elementos como quiera a una tubería añadiendo más argumentos a gst_bin_add_many.

    </item>

    <item>

    
Después, se usa gst_element_link para conectar los elementos de forma conjunta, de tal forma que la salida de source (un tono) va a la entrada de sink (que es después la salida de la tarjeta de sonido). gst_element_set_state se usa al iniciar la reproducción, configurando el estado de la tubería a reproduciendo (GST_STATE_PLAYING).

    </item>

  </steps>

</section>

<section id="stop">

  <title>Detener la reproducción</title>

  
No se quiere reproducir un tono molesto para siempre, por lo que lo último que play_sound hace es llamar a g_timeout_add. Esto establece un tiempo de expiración para detener el sonido; espera LENGTH milisegundos antes de llamar a la función pipeline_stop, y se queda llamando a pipeline_stop hasta que devuelve FALSE.

  
Ahora, se escribirá el código de la función pipeline_stop, llamada por g_timeout_add. Inserte el código siguiente encima de la función play_sound:

#define LENGTH 500 /* Length of playing in ms */

static gboolean

pipeline_stop (GstElement* pipeline)

{

	gst_element_set_state (pipeline, GST_STATE_NULL);

	g_object_unref (pipeline);

	return FALSE;

}

  
La llamada a gst_element_set_state detiene la reproducción de la tubería y g_object_unref desreferencia la tubería, la destruye y libera su memoria.

</section>

<section id="tones">

  <title>Definir los tonos</title>

  
Se quiere reproducir el sonido correcto cuando un usuario pulsa un botón. En primer lugar, se necesita conocer las frecuencias de las seis cuerdas de la guitarra, que están definidas (al principio de <file>main.c</file>) de la siguiente manera:

/* Frequencies of the strings */

#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

  
Ahora se se profundiza en el manejador de la señal definido anteriormente, on_button_clicked. Se podría haber conectado cada botón a un manejador de la señal diferente, pero esto había supuesto duplicar mucho código. En su lugar, se puede usar la etiqueta del botón para saber cuál de ellos se ha pulsado:

/* Callback for the buttons */

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);

}

  
A on_button_clicked se le pasa como argumento (button) un puntero al GtkButton que se ha pulsado. Se puede obtener el texto de este botón usando gtk_label_get_label.

  
El texto se compara con las notas que se tiene usando g_str_equal, y se llama a play_sound con la frecuencia correspondiente a cada nota. Esto reproduce el tono; el afinador de guitarra ya está funcionando.

</section>

<section id="run">

  <title>Construir y ejecutar la aplicación</title>

  
Todo el código debería estar listo para ejecutarse. Pulse <guiseq><gui>Construir</gui><gui>Construir proyecto</gui></guiseq> para construir todo otra vez y pulse <guiseq><gui>Ejecutar</gui><gui>Ejecutar</gui></guiseq> para iniciar la aplicación.

  
Si todavía no lo ha hecho, elija la aplicación <file>Debug/src/afinador-guitarra</file> en el diálogo que aparece. Finalmente, pulse <gui>Ejecutar</gui> y disfrute.

</section>

<section id="impl">

 <title>Implementación de referencia</title>

 
Si tiene problemas con este tutorial, compare su código con este <link href="guitar-tuner/guitar-tuner.c">código de referencia</link>.

</section>

<section id="next">

  <title>Siguientes pasos</title>

  
Aquí hay algunas ideas sobre cómo puede extender esta sencilla demostración:

  <list>

   <item>

   
Hacer que el programa recorra las notas automáticamente.

   </item>

   <item>

   
Hacer que el programa reproduzca grabaciones de cuerdas de guitarras que se están afinando.

   
PAra hacer esto, debe configurar una tubería de GStreamer más complicada, que le permite cargar y reproducir archivos de música. Deberá elegir un los elementos <link href="http://gstreamer.freedesktop.org/documentation/plugins.html">decodificador y demultiplexor</link> de GStreamer basándose en el formato del archivo de sus sonidos grabados; los MP3 usan elementos diferentes de los de los archivos Ogg Vorbis, por ejemplo.

   
Puede querer conectar los elementos de maneras más complicadas. Esto puede implicar usar <link href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/manual/html/chapter-intro-basics.html">conceptos de GStreamer</link> que no se han comentado en este tutorial, tales como <link href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/manual/html/section-intro-basics-pads.html">interfaces</link>. Es posible que encuentre útil el comando <cmd>gst-inspect</cmd>.

   </item>

   <item>

   
Analizar automáticamente las notas que toca el músico.

   
Puede conectar un micrófono y grabar sonidos con él usando una <link href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-good-plugins/html/gst-plugins-good-plugins-autoaudiosrc.html">fuente de entrada</link>. ¿Es posible que algún tipo de <link href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-good-plugins/html/gst-plugins-good-plugins-plugin-spectrum.html">análisis de espectro</link> le permita saber qué notas se están reproduciendo?

   </item>

  </list>

</section>

</page>