<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" type="topic" id="guitar-tuner.vala" 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>
  <credit type="translator copyright"><name>조성호</name><email>shcho@gnome.org</email><years>2017-2019.</years></credit></info>

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

<synopsis>
  <p>이 따라하기 지침서를 통해 기타를 조율할 때 활용할 수 있는 기타 음 재생 프로그램을 만듭니다. 다음 내용을 배웁니다:</p>
  <list type="numbered">
    <item><p><link xref="getting-ready">안주타 IDE</link>로 기본 프로젝트를 설정합니다.</p></item>
    <item><p><app>안주타</app> 사용자 인터페이스 디자이너로 간단한 GUI를 만듭니다.</p></item>
    <item><p>소리 재생에 <link href="http://developer.gnome.org/platform-overview/stable/gstreamer">지스트리머</link> 라이브러리를 사용합니다.</p></item>
  </list>
  <p>이 지침을 따라갈 수 있으려면 다음이 필요합니다:</p>
  <list>
    <item><p><link href="https://live.gnome.org/Vala/Tutorial">Vala</link> 프로그래밍 언어 기본 지식.</p></item>
    <item><p><app>안주타</app> 설치 사본.</p></item>
  </list>
</synopsis>

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

<section id="anjuta">
  <title><app>안주타</app> 프로젝트 만들기</title>
  <p>코딩을 시작하기 전에 안주타에서 새 프로젝트를 설정해야합니다. 이 프로그램은 빌드에 필요한 모든 파일을 만들고 그 다음 코드를 실행합니다. 또한 이 모든 상태를 유지 관리하는데 쓸만합니다.</p>
  <steps>
    <item>
    <p><app>안주타</app> 를 시작하고 <gui>새 프로젝트 만들기</gui> 또는 <guiseq><gui>파일</gui><gui>새로 만들기</gui><gui>프로젝트</gui></guiseq> 를 눌러 프로젝트 마법사를 여십시오.</p>
    </item>
    <item>
    <p><gui>Vala</gui> 탭을 누른 후 <gui>GTK+ (단순)</gui> 항목을 선택하십시오. <gui>계속</gui>을 누르고 다음 일부 페이지에서 세부 내용을 채워나가십시오. 프로젝트 이름과 디렉터리 이름을 <file>guitar-tuner</file>로 설정하십시오.</p>
   	</item>
    <item>
    <p><gui>외부 패키지 설정</gui>을 <gui>켬</gui>으로 설정했는지 확인하십시오. 다음 페이지의 목록에서 <link href="http://valadoc.org/gstreamer-0.10/index.htm"><em>gstreamer-0.10</em></link>를 선택하여 프로젝트에 지스트리머 라이브러리를 넣으십시오. <gui>계속</gui>을 누르십시오.</p>
    </item>
    <item>
    <p><gui>적용</gui>을 누르면 프로젝트를 만들어줍니다. <gui>프로젝트</gui>나 <gui>파일</gui>탭에서 <file>src/guitar_tuner.vala</file> 파일을 두 번 눌러 여십시오. 다음 줄로 시작하는 일부 코드를 볼 수 있습니다:</p>
    <code mime="text/x-csharp">
using GLib;
using Gtk;</code>
    </item>
  </steps>
</section>

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

  <list>
  <item>
    <p><code>using</code> 선언부 두줄은 이름 여역을 가져오므로 굳이 이름을 적어넣을 필요는 없습니다.</p>
   </item>
   <item>
    <p><code>Main</code> 클래스 생성자는 GtkBuilder 파일을 열어 새 창을 만들고(위 몇 줄에 정의한 <file>src/guitar-tuner.ui</file>), 시그널을 연결한 다음 창을 화면에 띄웁니다. GtkBiulder 파일에는 사용자 인터페이스 설명과 구성요소 모두를 담고 있습니다. 안주타 편집기를 사용하여 GtkBuilder 사용자 인터페이스를 디자인할 수 있습니다.</p>
    <note>
    <p>시그널 연결은 단추를 눌렀을 때 또는 다른 어떤 일이 일어났을 때 일어날 행동을 정의하는 방식입니다. 여기서 <code>on_destroy</code> 함수는 창을 닫을 때 호출(하고 끝내기) 합니다.</p>
    </note>
   </item>
   <item>
    <p>정적 <code>main</code> 함수는 Vala 프로그램을 시작할 때 기본으로 실행합니다. Main 클래스를 만들고 설정한 다음 프로그램을 실행하는 일부 함수를 호출합니다. <code>Gtk.main</code> 함수는 사용자 인터페이스를 실행하고 (마우스 누름과 키 누름 같은) 이벤트를 기다리기 시작하는 GTK 메인 루프를 시작합니다.</p>
   </item>
  </list>

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

<section id="ui">
  <title>사용자 인터페이스 만들기</title>
  <p>사용자 인터페이스(UI)설명은 클래서 상단에 정의한 <file>src/guitar_tuner.ui</file> GtkBuilder 파일에 있습니다. 사용자 인터페이스를 편집하려면 <gui>프로젝트</gui> 또는 <gui>파일</gui> 섹션에서 <file>src/guitar_tuner.ui</file> 파일을 두 번 눌러 여십시오. 이 동작을 통해 인터페이스 디자이너 프로그램으로 옮겨갑니다. 디자인 창은 가운데 있고, <gui>위젯</gui> 과 위젯 속성은 오른편에, 사용할 수 있는 위젯의 <gui>팔레트</gui>는 왼편에 있습니다.</p>
  <p>GTK+의 모든 UI 배치는 상자와 테이블 안에 모아둡니다. 기타 줄 각 한개를 의미하는 GtkButton 6개를 모아둘 수직 방향 GtkButtonBox를 사용해보겠습니다.</p>

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

  <steps>
   <item>
   <p><gui>컨테이너</gui> 섹션의 <gui>팔레트-</gui> 탭에서 아이콘을 눌러 <gui>Button Box</gui>(GtkButtonBox)를 선택하십시오. 그 후 디자인 창 한가운데를 눌러 창에 넣으십시오. <gui>항목 수</gui>를 <input>6</input>으로 설정할 수 있는 대화상자가 나타납니다. 설정하고 나면 <gui>만들기</gui>를 누르십시오.</p>
 <note><p>우측 <gui>일반</gui> 탭에서 <gui>항목 수</gui>와 <gui>방향</gui>을 설정할 수도 있습니다.</p></note>
   </item>
   <item>
    <p>이제 <gui>팔레트</gui>의 <gui>컨트롤 및 표시</gui> 섹션에서  <gui>Button</gui> (GtkButton)을 눌러 선택하십시오. 처음 섹션을 눌러서 GtkButtonBox의 처음 섹션에 두십시오.</p>
   </item>
   <item>
    <p>단추를 선택한 상태라면 우측 <gui>일반</gui> 탭에서 스크롤을 내려 <gui>레이블</gui> 속성을 찾아 <gui>E</gui>로 바꾸십시오. 낮은 E 음 기타 현 입니다.</p>
  <note><p><gui>일반</gui> 탭은 우측 <gui>위젯</gui> 섹션에 있습니다.</p></note>
    </item>
    <item>
     <p>우측의 <gui>위젯</gui> 섹션에서 <gui>시그널</gui>을 누르고 단추의 <code>clicked</code> 시그널을 찾으십시오. 단추를 사용자가 눌렀을 때 호출할 시그널 핸들러에 이 시그널을 연결할 수 있습니다. 이렇게 하려면 시그널을 선택하고 <gui>핸들러</gui> 열에 <code>main_on_button_clicked</code>를 입력한 후 <key>Enter</key>키를 누르십시오.</p>
    </item>
    <item>
    <p>다른 단추에 대해서도 그 다음 줄 이름 <em>A</em>, <em>D</em>, <em>G</em>, <em>B</em>, <em>e</em>를 추가하여 위 단계를 반복하십시오.</p>
    </item>
    <item>
    <p>UI 디자인을 저장(<guiseq><gui>파일</gui><gui>저장</gui></guiseq> 누름)하시고 열어둔 상태로 두십시오.</p>
    </item>
  </steps>
</section>

<section id="gstreamer">
  <title>지스트리머 파이프라인</title>
  <p>이 섹션은 음을 재생하는 코드를 작성하는 법을 보여줍니다. <link href="http://developer.gnome.org/platform-overview/stable/gstreamer">지스트리머</link>는 그놈 멀티미디어 프레임워크입니다. 동영상, 오디오, 웹캠 스트림 같은 매체를 재생하고, 녹음/녹화하고 처리할 때 이 프레임워크를 사용할 수 있습니다. 여기서는 단일 주파수 음을 재생할 때 이 프레임워크를 사용하겠습니다.</p>
  <p>개념상 지스트리머든 다음과 같이 동작합니다.  <em>source</em>에서 <em>sink</em>(출력)으로의 다양한 처리 흐름을 담는 <link href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/manual/html/section-intro-basics-bins.html"><em>파이프라인</em></link>을 만듭니다. source는 그림 파일, 동영상, 음악 파일이 될 수 있으며, 출력 모양새는 위젯 또는 사운드 카드의 출력일 수 있습니다.</p>
  <p>source와 sink 사이에서 다양한 필터와 변환 프로그램을 적용하여 효과를 처리하거나, 형식을 변환하는 등을 할 수 있습니다. 각 파이프라인 구성 요소에는 동작을 바꿀 수 있는 속성이 있습니다.</p>
  <media type="image" mime="image/png" src="media/guitar-tuner-pipeline.png">
    <p>지스트리머 파이프라인 예제입니다.</p>
  </media>
</section>

<section id="pipeline">
  <title>파이프라인 구성</title>
  <p>여기 단순 예제에서는 <code>audiotestsrc</code> 라는 음 재생기 소스를 사용하고 기본 시스템 사운드 장치 <code>autoaudiosink</code>로 출력을 내보내겠습니다. 우리는 여기서 음 재생기 주파수만 설정하면 됩니다.  <code>audiotestsrc</code>의 <code>freq</code> 속성을 사용하면 됩니다.</p>

  <p>지스트리머를 초기화하는 코드 한 줄을 넣어야합니다. 다음 코드를 <code>main</code> 함수의 <code>Gtk.init</code> 코드 위에 넣으십시오:</p>
  <code mime="text/x-csharp">Gst.init (ref args);</code>
  <p>그리고 다음 함수 코드를 <code>Main</code> 클래스의 <file>guitar_tuner.vala</file> 파일 안에 복사해넣으십시오:</p>
  <code mime="text/x-csharp">
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(() =&gt; {
		pipeline.set_state (Gst.State.NULL);
		return false;
	});
	time.attach(null);
}</code>

  <steps>
    <item>
    <p>처음 다섯줄에서는 source와 sink 지스트리머 구성 요소(<link href="http://valadoc.org/gstreamer-0.10/Gst.Element.html"><code>Gst.Element</code></link>), <link href="http://valadoc.org/gstreamer-0.10/Gst.Pipeline.html">파이프라인 구성 요소</link>(source와 sink의 컨테이너로 활용)를 만듭니다. 여기 언급한 구성요소는 클래스 변수이므로 밖에서는 메서드로 정의합니다. 파이프라인 이름은 "note"라고 지어둡니다. source는 "source"로 이름 붙이고 <code>audiotestsrc</code>로 설정합니다. sink는 "output"으로 이름 붙이고 <code>autoaudiosink</code> sink로 설정합니다(기본은 사운드 카드 출력).</p>
    </item>
    <item>
    <p><code>play_sound</code> 함수 인자로 넘긴 <code>frequency</code> 값을 <link href="http://valadoc.org/gobject-2.0/GLib.Object.set.html"><code>source.set</code></link> 호출로 source 구성 요소의 <code>freq</code>  속성을 설정합니다. 이 값은 헤르쯔 단위의 주파수입니다 쓸만한 주파수 값은 나중에 정의하겠습니다.</p>
    </item>
    <item>
    <p><link href="http://valadoc.org/gstreamer-0.10/Gst.Bin.add.html"><code>pipeline.add</code></link>  파이프라인에 source와 sink를 둡니다. 파이프라인은 다른 지스트리머 구성 요소를 여럿 넣을 수 있는 <link href="http://valadoc.org/gstreamer-0.10/Gst.Bin.html"><code>Gst.Bin</code></link> 입니다. 보통 <code>pipeline.add</code> 에 호출을 추가하여 원하는 만큼 구성 요소를 넣을 수 있습니다.</p>
    </item>
    <item>
    <p>다음, <link href="http://valadoc.org/gstreamer-0.10/Gst.Element.link.html"><code>sink.link</code></link>는 구성 요소를 서로 연결하여 source의 출력이 sink의 입력으로 들어가게 할 때(그리고 나중에 이 흐름은 사운드 카드로 출력함) 사용합니다. 그 다음 <link href="http://www.valadoc.org/gstreamer-0.10/Gst.Element.set_state.html"><code>pipeline.set_state</code></link>로 <link href="http://www.valadoc.org/gstreamer-0.10/Gst.State.html">파이프라인 상태</link>를 재생(<code>Gst.State.PLAYING</code>) 상태로 설정하여 재생을 시작합니다.</p>
    </item>
    <item>
    <p>음을 무한정 지겹게 재생하고 싶지는 않기 때문에 <code>play_sound</code> 함수에서 <link href="http://www.valadoc.org/glib-2.0/GLib.TimeoutSource.html"><code>TimeoutSource</code></link>를 추가합니다. TimeoutSource로 음 재생을 멈출 제한 시간을 설정합니다. 파이프라인을 멈추고 해체하는 코드를 정의한 시그널 핸들러를 호출하기 전 200 밀리초 동안 기다립니다. 주어진 시간이 지나면 자체를 해체할 목적으로 <code>false</code>를 반환합니다. 그렇지 않으면 200 밀리초마다 계속 실행합니다.</p>
    </item>
  </steps>
</section>


<section id="signal">
  <title>시그널 핸들러 만들기</title>
  <p>UI 디자이너에서 모든 단추를 만들어서 이 단추에 동일한 함수 단추를 눌렀을 때 동일한 함수 <gui>on_button_clicked</gui>를 호출하도록 연결할 차례입니다. 실제로 UI 디자이너에서 입력한 <gui>main_on_button_clicked</gui>는 Main의 메서드를 말합니다. 소스 파일에 이 함수를 추가해야합니다.</p>
  <p>소스 파일에 함수를 추가하려면 사용자 인터페이스 파일(guitar_tuner.ui)에서 단추 하나를 눌러 선택하고, (가운데 탭을 눌러) <file>guitar_tuner.vala</file> 파일을 여십시오. 시그널 이름을 설정하는 오른편의 <gui>시그널</gui> 탭으로 옮겨가십시오. 이제 앞서 설정한 <gui>clicked</gui> 시그널 줄을 클래스 앞부분의 소스 파일에 끌어다 높으십시오. 이 동작을 통해 소스 파일에 다음 코드를 추가합니다:</p>
<code mime="text/x-csharp">
public void on_button_clicked (Gtk.Button sender) {

}</code>

 <note><p>끌어다 놓는 방식 대신 클래스 앞 부분에 코드를 직접 입력할 수도 있습니다.</p></note>
  <p>시그널 핸들러의 인자는 <link href="http://valadoc.org/gtk+-3.0/Gtk.Widget.html"><code>Gtk.Widget</code></link>(우리 같은 경우, 항상 <link href="http://valadoc.org/gtk+-3.0/Gtk.Button.html"><code>Gtk.Button</code></link>) 하나뿐입니다.</p>
</section>


<section id="handler">
  <title>시그널 핸들러 정의</title>
  <p>사용자가 단추를 누르면 올바른 음이 나오게 하려고 합니다. 이렇게 하려면 위에서 정의한 시그널 핸들러에 코드를 덧붙여야합니다. 모든 단추에 각자 다른 시그널 핸들러를 연결할 수 있지만, 같은 코드를 여러번 쓸 수 있습니다. 이 대신 어떤 단추를 눌렀는지 판단할 때 단추 레이블을 활용할 수 있습니다:</p>
  <code mime="text/x-csharp">
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;
	}
}
</code>
  <p>누른 <code>Gtk.Button</code>는 <code>on_button_clicked</code>의 인자(<code>sender</code>)로 전달합니다. <code>get_child</code>로 단추의 레이블을 가져올 수 있고, 해당 레이블에서 <code>get_label</code>로 텍스트를 가져올 수 있습니다.</p>
  <p>switch 구문은 우리가 연주할 수 있는 음의 레이블 텍스트를 비교하고, 표시 음에 적당한 주파수로 <code>play_sound</code>를 호출합니다. 이 동작 과정을 통해 음을 재생합니다. 이렇게 하여 동작하는 기타 조율 프로그램을 만들었습니다!</p>
</section>

<section id="run">
  <title>프로그램 빌드 및 실행</title>
  <p>모든 코드를 실행할 준비가 됐습니다. <guiseq><gui>빌드</gui><gui>프로젝트 빌드</gui></guiseq>를 눌러 프로젝트 전체를 다시 빌드하고, <guiseq><gui>실행</gui><gui>실행</gui></guiseq>을 눌러 프로그램을 시작하십시오.</p>
  <p>아직 끝내지 않았다면 나타난 대화상자에서 <file>Debug/src/guitar-tuner</file>  프로그램을 선택하십시오. 마지막으로 <gui>Run</gui>를 눌러 만든 프로그램을 즐기시죠!</p>
</section>

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

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

<section id="next">
  <title>다음 단계</title>
  <p>여기 간단한 시험 프로그램에 여러분이 추가로 넣을 수 있는 몇가지 아이디어가 있습니다:</p>
  <list>
   <item>
   <p>프로그램에 음 재생 자동 주기 기능 넣기.</p>
   </item>
   <item>
   <p>프로그램에 실제 기타 현을 퉁겼을 때의 음을 녹음하여 재생하기.</p>
   <p>이 동작을 구현하려면 음악 파일을 불러와서 재생할 수 있도록 지스트리머 파이프라인을 좀 더 복잡하게 설정해야합니다. 녹음 음원의 파일 형식에 따른<link href="http://gstreamer.freedesktop.org/documentation/plugins.html">decoder와 demuxer</link> 지스트리머 구성 요소를 선택해야 할 수도 있습니다. 예를 들자면 MP3는 Ogg Vorbis 파일과는 다른 구성 요소를 활용합니다.</p>
   <p>좀 더 복잡한 식으로 구성 요소를 연결해야 할 수도 있습니다. <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>  명령을 찾아볼 수도 있습니다.</p>
   </item>
   <item>
   <p>사용자 연주 음을 자동으로 분석.</p>
   <p>마이크를 연결하고 <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> 같은 것으로 어떤 음을 재생했는지 알 수 있겠죠?</p>
   </item>
  </list>
</section>

</page>
