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

  <info>

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

    <desc>간단한 그놈용 기타 조율 프로그램을 만들 때 <link href="http://developer.gnome.org/platform-overview/stable/gtk">GTK+</link>와 <link href="http://developer.gnome.org/platform-overview/stable/gstreamer">지스트리머</link>를 활용합니다. 인터페이스 사용 방법을 보여드립니다.</desc>

    <revision pkgversion="0.1" version="0.1" date="2012-02-09" status="candidate"/>

    <credit type="author">

      <name>그놈 문서 프로젝트</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>Tiffany Antopolski</name>

      <email its:translate="no">tiffany.antopolski@gmail.com</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>조성호</mal:name>

      <mal:email>shcho@gnome.org</mal:email>

      <mal:years>2017</mal:years>

    </mal:credit>

  </info>

<title>기타 조율기</title>

<synopsis>

  
이 따라하기 지침서를 통해 기타를 조율할 때 활용할 수 있는 기타 음 재생 프로그램을 만듭니다. 다음 내용을 배웁니다:

  <list type="numbered">

    <item>
<link xref="getting-ready">안주타 IDE</link>로 기본 프로젝트를 설정합니다.
</item>

    <item>
<app>안주타</app> 사용자 인터페이스 디자이너로 간단한 GUI를 만듭니다.
</item>

    <item>
소리 재생에 <link href="http://developer.gnome.org/platform-overview/stable/gstreamer">지스트리머</link> 라이브러리를 사용합니다.
</item>

  </list>

  
이 지침을 따라갈 수 있으려면 다음이 필요합니다:

  <list>

    <item>
<link href="https://live.gnome.org/Vala/Tutorial">Vala</link> 프로그래밍 언어 기본 지식.
</item>

    <item>
<app>안주타</app> 설치 사본.
</item>

  </list>

</synopsis>

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

<section id="anjuta">

  <title><app>안주타</app> 프로젝트 만들기</title>

  
코딩을 시작하기 전에 안주타에서 새 프로젝트를 설정해야합니다. 이 프로그램은 빌드에 필요한 모든 파일을 만들고 그 다음 코드를 실행합니다. 또한 이 모든 상태를 유지 관리하는데 쓸만합니다.

  <steps>

    <item>

    
<app>안주타</app> 를 시작하고 <gui>새 프로젝트 만들기</gui> 또는 <guiseq><gui>파일</gui><gui>새로 만들기</gui><gui>프로젝트</gui></guiseq> 를 눌러 프로젝트 마법사를 여십시오.

    </item>

    <item>

    
<gui>Vala</gui> 탭을 누른 후 <gui>GTK+ (단순)</gui> 항목을 선택하십시오. <gui>계속</gui>을 누르고 다음 일부 페이지에서 세부 내용을 채워나가십시오. 프로젝트 이름과 디렉터리 이름을 <file>guitar-tuner</file>로 설정하십시오.

   	</item>

    <item>

    
<gui>외부 패키지 설정</gui>을 <gui>켬</gui>으로 설정했는지 확인하십시오. 다음 페이지의 목록에서 <link href="http://valadoc.org/gstreamer-0.10/index.htm">gstreamer-0.10</link>를 선택하여 프로젝트에 지스트리머 라이브러리를 넣으십시오. <gui>계속</gui>을 누르십시오.

    </item>

    <item>

    
<gui>적용</gui>을 누르면 프로젝트를 만들어줍니다. <gui>프로젝트</gui>나 <gui>파일</gui>탭에서 <file>src/guitar_tuner.vala</file> 파일을 두 번 눌러 여십시오. 다음 줄로 시작하는 일부 코드를 볼 수 있습니다:

using GLib;

using Gtk;

    </item>

  </steps>

</section>

<section id="build">

  <title>첫 코드 작성</title>

  
이 코드는 (빈) 창을 사용자 인터페이스 설명 파일에서 불러오고 화면에 나타냅니다. 자세한 내용은 아래에 있습니다. 기본을 이해하셨다면 이 부분은 넘어가셔도 됩니다:

  <list>

  <item>

    
using 선언부 두줄은 이름 여역을 가져오므로 굳이 이름을 적어넣을 필요는 없습니다.

   </item>

   <item>

    
Main 클래스 생성자는 GtkBuilder 파일을 열어 새 창을 만들고(위 몇 줄에 정의한 <file>src/guitar-tuner.ui</file>), 시그널을 연결한 다음 창을 화면에 띄웁니다. GtkBiulder 파일에는 사용자 인터페이스 설명과 구성요소 모두를 담고 있습니다. 안주타 편집기를 사용하여 GtkBuilder 사용자 인터페이스를 디자인할 수 있습니다.

    <note>

    
시그널 연결은 단추를 눌렀을 때 또는 다른 어떤 일이 일어났을 때 일어날 행동을 정의하는 방식입니다. 여기서 on_destroy 함수는 창을 닫을 때 호출(하고 끝내기) 합니다.

    </note>

   </item>

   <item>

    
정적 main 함수는 Vala 프로그램을 시작할 때 기본으로 실행합니다. Main 클래스를 만들고 설정한 다음 프로그램을 실행하는 일부 함수를 호출합니다. Gtk.main 함수는 사용자 인터페이스를 실행하고 (마우스 누름과 키 누름 같은) 이벤트를 기다리기 시작하는 GTK 메인 루프를 시작합니다.

   </item>

  </list>

  
이 코드를 사용할 준비가 끝났기에 <guiseq><gui>빌드</gui><gui>프로젝트 빌드</gui></guiseq>(또는 <keyseq><key>Shift</key><key>F7</key></keyseq>키)를 눌러 컴파일할 수 있습니다. 이 과정을 수행하면 대화상자가 나타납니다.  <gui>설정</gui>을 <gui>기본</gui>으로 바꾸고 <gui>실행</gui>을 눌러 빌드 디렉터리를 설정하십시오. 처음 빌드하실 때 한 번만 실행하시면 됩니다.

</section>

<section id="ui">

  <title>사용자 인터페이스 만들기</title>

  
사용자 인터페이스(UI)설명은 클래서 상단에 정의한 <file>src/guitar_tuner.ui</file> GtkBuilder 파일에 있습니다. 사용자 인터페이스를 편집하려면 <gui>프로젝트</gui> 또는 <gui>파일</gui> 섹션에서 <file>src/guitar_tuner.ui</file> 파일을 두 번 눌러 여십시오. 이 동작을 통해 인터페이스 디자이너 프로그램으로 옮겨갑니다. 디자인 창은 가운데 있고, <gui>위젯</gui> 과 위젯 속성은 오른편에, 사용할 수 있는 위젯의 <gui>팔레트</gui>는 왼편에 있습니다.

  
GTK+의 모든 UI 배치는 상자와 테이블 안에 모아둡니다. 기타 줄 각 한개를 의미하는 GtkButton 6개를 모아둘 수직 방향 GtkButtonBox를 사용해보겠습니다.

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

  <steps>

   <item>

   
<gui>컨테이너</gui> 섹션의 <gui>팔레트-</gui> 탭에서 아이콘을 눌러 <gui>Button Box</gui>(GtkButtonBox)를 선택하십시오. 그 후 디자인 창 한가운데를 눌러 창에 넣으십시오. <gui>항목 수</gui>를 <input>6</input>으로 설정할 수 있는 대화상자가 나타납니다. 설정하고 나면 <gui>만들기</gui>를 누르십시오.

 <note>
우측 <gui>일반</gui> 탭에서 <gui>항목 수</gui>와 <gui>방향</gui>을 설정할 수도 있습니다.
</note>

   </item>

   <item>

    
이제 <gui>팔레트</gui>의 <gui>컨트롤 및 표시</gui> 섹션에서  <gui>Button</gui> (GtkButton)을 눌러 선택하십시오. 처음 섹션을 눌러서 GtkButtonBox의 처음 섹션에 두십시오.

   </item>

   <item>

    
단추를 선택한 상태라면 우측 <gui>일반</gui> 탭에서 스크롤을 내려 <gui>레이블</gui> 속성을 찾아 <gui>E</gui>로 바꾸십시오. 낮은 E 음 기타 현 입니다.

  <note>
<gui>일반</gui> 탭은 우측 <gui>위젯</gui> 섹션에 있습니다.
</note>

    </item>

    <item>

     
우측의 <gui>위젯</gui> 섹션에서 <gui>시그널</gui>을 누르고 단추의 clicked 시그널을 찾으십시오. 단추를 사용자가 눌렀을 때 호출할 시그널 핸들러에 이 시그널을 연결할 수 있습니다. 이렇게 하려면 시그널을 선택하고 <gui>핸들러</gui> 열에 main_on_button_clicked를 입력한 후 <key>Enter</key>키를 누르십시오.

    </item>

    <item>

    
다른 단추에 대해서도 그 다음 줄 이름 A, D, G, B, e를 추가하여 위 단계를 반복하십시오.

    </item>

    <item>

    
UI 디자인을 저장(<guiseq><gui>파일</gui><gui>저장</gui></guiseq> 누름)하시고 열어둔 상태로 두십시오.

    </item>

  </steps>

</section>

<section id="gstreamer">

  <title>지스트리머 파이프라인</title>

  
이 섹션은 음을 재생하는 코드를 작성하는 법을 보여줍니다. <link href="http://developer.gnome.org/platform-overview/stable/gstreamer">지스트리머</link>는 그놈 멀티미디어 프레임워크입니다. 동영상, 오디오, 웹캠 스트림 같은 매체를 재생하고, 녹음/녹화하고 처리할 때 이 프레임워크를 사용할 수 있습니다. 여기서는 단일 주파수 음을 재생할 때 이 프레임워크를 사용하겠습니다.

  
개념상 지스트리머든 다음과 같이 동작합니다.  source에서 sink(출력)으로의 다양한 처리 흐름을 담는 <link href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/manual/html/section-intro-basics-bins.html">파이프라인</link>을 만듭니다. source는 그림 파일, 동영상, 음악 파일이 될 수 있으며, 출력 모양새는 위젯 또는 사운드 카드의 출력일 수 있습니다.

  
source와 sink 사이에서 다양한 필터와 변환 프로그램을 적용하여 효과를 처리하거나, 형식을 변환하는 등을 할 수 있습니다. 각 파이프라인 구성 요소에는 동작을 바꿀 수 있는 속성이 있습니다.

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

    
지스트리머 파이프라인 예제입니다.

  </media>

</section>

<section id="pipeline">

  <title>파이프라인 구성</title>

  
여기 단순 예제에서는 audiotestsrc 라는 음 재생기 소스를 사용하고 기본 시스템 사운드 장치 autoaudiosink로 출력을 내보내겠습니다. 우리는 여기서 음 재생기 주파수만 설정하면 됩니다.  audiotestsrc의 freq 속성을 사용하면 됩니다.

  
지스트리머를 초기화하는 코드 한 줄을 넣어야합니다. 다음 코드를 main 함수의 Gtk.init 코드 위에 넣으십시오:

  Gst.init (ref args);

  
그리고 다음 함수 코드를 Main 클래스의 <file>guitar_tuner.vala</file> 파일 안에 복사해넣으십시오:

Gst.Element sink;

Gst.Element source;

Gst.Pipeline pipeline;

private void play_sound(double frequency)

{

	pipeline = new Gst.Pipeline ("note");

	source   = Gst.ElementFactory.make ("audiotestsrc",

	                                    "source");

	sink     = Gst.ElementFactory.make ("autoaudiosink",

	                                    "output");

	/* set frequency */

	source.set ("freq", frequency);

	pipeline.add (source);

	pipeline.add (sink);

	source.link (sink);

	pipeline.set_state (Gst.State.PLAYING);

	/* stop it after 200ms */

	var time = new TimeoutSource(200);

	time.set_callback(() => {

		pipeline.set_state (Gst.State.NULL);

		return false;

	});

	time.attach(null);

}

  <steps>

    <item>

    
처음 다섯줄에서는 source와 sink 지스트리머 구성 요소(<link href="http://valadoc.org/gstreamer-0.10/Gst.Element.html">Gst.Element</link>), <link href="http://valadoc.org/gstreamer-0.10/Gst.Pipeline.html">파이프라인 구성 요소</link>(source와 sink의 컨테이너로 활용)를 만듭니다. 여기 언급한 구성요소는 클래스 변수이므로 밖에서는 메서드로 정의합니다. 파이프라인 이름은 "note"라고 지어둡니다. source는 "source"로 이름 붙이고 audiotestsrc로 설정합니다. sink는 "output"으로 이름 붙이고 autoaudiosink sink로 설정합니다(기본은 사운드 카드 출력).

    </item>

    <item>

    
play_sound 함수 인자로 넘긴 frequency 값을 <link href="http://valadoc.org/gobject-2.0/GLib.Object.set.html">source.set</link> 호출로 source 구성 요소의 freq  속성을 설정합니다. 이 값은 헤르쯔 단위의 주파수입니다 쓸만한 주파수 값은 나중에 정의하겠습니다.

    </item>

    <item>

    
<link href="http://valadoc.org/gstreamer-0.10/Gst.Bin.add.html">pipeline.add</link>  파이프라인에 source와 sink를 둡니다. 파이프라인은 다른 지스트리머 구성 요소를 여럿 넣을 수 있는 <link href="http://valadoc.org/gstreamer-0.10/Gst.Bin.html">Gst.Bin</link> 입니다. 보통 pipeline.add 에 호출을 추가하여 원하는 만큼 구성 요소를 넣을 수 있습니다.

    </item>

    <item>

    
다음, <link href="http://valadoc.org/gstreamer-0.10/Gst.Element.link.html">sink.link</link>는 구성 요소를 서로 연결하여 source의 출력이 sink의 입력으로 들어가게 할 때(그리고 나중에 이 흐름은 사운드 카드로 출력함) 사용합니다. 그 다음 <link href="http://www.valadoc.org/gstreamer-0.10/Gst.Element.set_state.html">pipeline.set_state</link>로 <link href="http://www.valadoc.org/gstreamer-0.10/Gst.State.html">파이프라인 상태</link>를 재생(Gst.State.PLAYING) 상태로 설정하여 재생을 시작합니다.

    </item>

    <item>

    
음을 무한정 지겹게 재생하고 싶지는 않기 때문에 play_sound 함수에서 <link href="http://www.valadoc.org/glib-2.0/GLib.TimeoutSource.html">TimeoutSource</link>를 추가합니다. TimeoutSource로 음 재생을 멈출 제한 시간을 설정합니다. 파이프라인을 멈추고 해체하는 코드를 정의한 시그널 핸들러를 호출하기 전 200 밀리초 동안 기다립니다. 주어진 시간이 지나면 자체를 해체할 목적으로 false를 반환합니다. 그렇지 않으면 200 밀리초마다 계속 실행합니다.

    </item>

  </steps>

</section>

<section id="signal">

  <title>시그널 핸들러 만들기</title>

  
UI 디자이너에서 모든 단추를 만들어서 이 단추에 동일한 함수 단추를 눌렀을 때 동일한 함수 <gui>on_button_clicked</gui>를 호출하도록 연결할 차례입니다. 실제로 UI 디자이너에서 입력한 <gui>main_on_button_clicked</gui>는 Main의 메서드를 말합니다. 소스 파일에 이 함수를 추가해야합니다.

  
소스 파일에 함수를 추가하려면 사용자 인터페이스 파일(guitar_tuner.ui)에서 단추 하나를 눌러 선택하고, (가운데 탭을 눌러) <file>guitar_tuner.vala</file> 파일을 여십시오. 시그널 이름을 설정하는 오른편의 <gui>시그널</gui> 탭으로 옮겨가십시오. 이제 앞서 설정한 <gui>clicked</gui> 시그널 줄을 클래스 앞부분의 소스 파일에 끌어다 높으십시오. 이 동작을 통해 소스 파일에 다음 코드를 추가합니다:

public void on_button_clicked (Gtk.Button sender) {

}

 <note>
끌어다 놓는 방식 대신 클래스 앞 부분에 코드를 직접 입력할 수도 있습니다.
</note>

  
시그널 핸들러의 인자는 <link href="http://valadoc.org/gtk+-3.0/Gtk.Widget.html">Gtk.Widget</link>(우리 같은 경우, 항상 <link href="http://valadoc.org/gtk+-3.0/Gtk.Button.html">Gtk.Button</link>) 하나뿐입니다.

</section>

<section id="handler">

  <title>시그널 핸들러 정의</title>

  
사용자가 단추를 누르면 올바른 음이 나오게 하려고 합니다. 이렇게 하려면 위에서 정의한 시그널 핸들러에 코드를 덧붙여야합니다. 모든 단추에 각자 다른 시그널 핸들러를 연결할 수 있지만, 같은 코드를 여러번 쓸 수 있습니다. 이 대신 어떤 단추를 눌렀는지 판단할 때 단추 레이블을 활용할 수 있습니다:

public void on_button_clicked (Gtk.Button sender) {

	var label = sender.get_child () as Gtk.Label;

	switch (label.get_label()) {

		case "E":

			play_sound (329.63);

			break;

		case "A":

			play_sound (440);

			break;

		case "D":

			play_sound (587.33);

			break;

		case "G":

			play_sound (783.99);

			break;

		case "B":

			play_sound (987.77);

			break;

		case "e":

			play_sound (1318);

			break;

		default:

			break;

	}

}

  
누른 Gtk.Button는 on_button_clicked의 인자(sender)로 전달합니다. get_child로 단추의 레이블을 가져올 수 있고, 해당 레이블에서 get_label로 텍스트를 가져올 수 있습니다.

  
switch 구문은 우리가 연주할 수 있는 음의 레이블 텍스트를 비교하고, 표시 음에 적당한 주파수로 play_sound를 호출합니다. 이 동작 과정을 통해 음을 재생합니다. 이렇게 하여 동작하는 기타 조율 프로그램을 만들었습니다!

</section>

<section id="run">

  <title>프로그램 빌드 및 실행</title>

  
모든 코드를 실행할 준비가 됐습니다. <guiseq><gui>빌드</gui><gui>프로젝트 빌드</gui></guiseq>를 눌러 프로젝트 전체를 다시 빌드하고, <guiseq><gui>실행</gui><gui>실행</gui></guiseq>을 눌러 프로그램을 시작하십시오.

  
아직 끝내지 않았다면 나타난 대화상자에서 <file>Debug/src/guitar-tuner</file>  프로그램을 선택하십시오. 마지막으로 <gui>Run</gui>를 눌러 만든 프로그램을 즐기시죠!

</section>

<section id="impl">

 <title>참조 구현체</title>

 
지침서를 따라하는 실행하는 과정에 문제가 있다면, <link href="guitar-tuner/guitar-tuner.vala">참조 코드</link>와 여러분의 코드를 비교해보십시오.

</section>

<section id="further">

<title>더 읽을거리</title>

Vala 프로그래밍 언어에 대해 더 알아보려면 <link href="http://live.gnome.org/Vala/Tutorial">Vala 따라하기 지침서</link>와 <link href="http://valadoc.org/">Vala API 문서</link>를 확인해보시면 좋습니다.

</section>

<section id="next">

  <title>다음 단계</title>

  
여기 간단한 시험 프로그램에 여러분이 추가로 넣을 수 있는 몇가지 아이디어가 있습니다:

  <list>

   <item>

   
프로그램에 음 재생 자동 주기 기능 넣기.

   </item>

   <item>

   
프로그램에 실제 기타 현을 퉁겼을 때의 음을 녹음하여 재생하기.

   
이 동작을 구현하려면 음악 파일을 불러와서 재생할 수 있도록 지스트리머 파이프라인을 좀 더 복잡하게 설정해야합니다. 녹음 음원의 파일 형식에 따른<link href="http://gstreamer.freedesktop.org/documentation/plugins.html">decoder와 demuxer</link> 지스트리머 구성 요소를 선택해야 할 수도 있습니다. 예를 들자면 MP3는 Ogg Vorbis 파일과는 다른 구성 요소를 활용합니다.

   
좀 더 복잡한 식으로 구성 요소를 연결해야 할 수도 있습니다. <link href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/manual/html/section-intro-basics-pads.html">pads</link>와 같이 우리가 지침서에서 다룰 수 없는 <link href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/manual/html/chapter-intro-basics.html">지스트리머 개념</link>이 들어갈 수도 있습니다. 쓸만한 <cmd>gst-inspect</cmd>  명령을 찾아볼 수도 있습니다.

   </item>

   <item>

   
사용자 연주 음을 자동으로 분석.

   
마이크를 연결하고 <link href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-good-plugins/html/gst-plugins-good-plugins-autoaudiosrc.html">input source</link>로 음을 녹음할 수 있습니다. 아마도 <link href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-good-plugins/html/gst-plugins-good-plugins-plugin-spectrum.html">스펙트럼 분석</link> 같은 것으로 어떤 음을 재생했는지 알 수 있겠죠?

   </item>

  </list>

</section>

</page>