<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE chapter>

<!-- Copyright (C) 2005-2018 Jo\u00EBl Kr\u00E4hemann -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->

<chapter xmlns="http://docbook.org/ns/docbook"
	 xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0">
  <title>AgsAudio a container of AgsChannel</title>
  <para>
    AgsAudio contains a pointer to your notation and automation data. It has its
    own recall context, AgsRecallAudio. It organizes your recycling contices and
    thus having an associated AgsRecallID for running contices. Further AgsAudio
    is your topmost nesting level of AgsAudioSignal. You might traverse the layers
    in following order:
  </para>

  <orderedlist numeration="lowerroman">
    <listitem>
      AgsAudio
    </listitem>
    <listitem>
      AgsChannel
    </listitem>
    <listitem>
      AgsRecycling
    </listitem>
    <listitem>
      AgsAudioSignal
    </listitem>
  </orderedlist>

  <para>
    In order the audio processing threads are capable to iterate the audio tree, you
    need to set either (AGS_AUDIO_SYNC) or (AGS_AUDIO_SYNC | AGS_AUDIO_ASYNC)
    flags. Further if your AgsAudio is a source of AgsAudioSignal you need to set
    both flags (AGS_AUDIO_OUTPUT_HAS_RECYCLING | AGS_AUDIO_INPUT_HAS_RECYCLING).
  </para>

  <para>
    If you set AGS_AUDIO_SYNC flag, this causes the output and input channels to be aligned
    straight. Eg. input line 0 goes to output line 0, input line 1 goes to output line 1 ...
  </para>

  <para>
    If you set both flags AGS_AUDIO_SYNC and AGS_AUDIO_ASYNC, output and input is
    not aligned straight. Eg. you have 2 audio channels, 1 output pad and 8 input pads, then
    input line 0 goes to output line 0, input line 1 goes to output line 1, input line 3 goes to
    output line 0 ...
  </para>

  <para>
    It is only possible to have mulitple output pads if you have AgsRecycling assigned to
    AgsOutput of AgsAudio. This is usually done by sources like instruments.
  </para>
  
  <para>
    AgsAudioSignal keeps your audio data as a GList of buffers. AgsRecycling is your
    nested tree to AgsChannel, giving you the opportunity to emit ::add_audio_signal
    or ::remove_audio_signal by producer and to have many consumers. AgsChannel is your
    opposite to an audio channel representing a single line. AgsAudio keeps track of
    all of them. You might want to add your audio object to an AgsSoundcard.
  </para>

  <para>
    You may resize the count of pads or audio channels with <code language="C">void ags_audio_set_pads(AgsAudio*, GType, guint, guint)</code>
    and <code language="C">void ags_audio_set_audio_channels(AgsAudio*, guint, guint)</code>. Like in the following example the channels are
    adjusted and notation is added.
  </para>

  <example>
    <title>Using AgsAudio</title>
    <programlisting language="C">
<xi:include href="../listings/audio.c" parse="text" />
    </programlisting>
  </example>

  <sect1>
    <title>AgsNotation and AgsNote</title>
    <para>
      AgsAudio provides many AgsNotation objects for one single audio channel. They all have a different :timestamp property. Usually a new
      AgsNotation object is introduced as AGS_NOTATION_DEFAULT_OFFSET is exceeded. So AgsNotation can hold at most 1024 x-positions of AgsNote.
    </para>

    <para>
      You might want to query a GList of AgsNotation by the matching AgsTimestamp using AGS_TIMESTAMP_OFFSET.
    </para>

    <itemizedlist mark="bullet">
      <listitem>
	<code language="C">void ags_notation_find_near_timestamp(GList*, guint, AgsTimestamp*)</code>
      </listitem>
    </itemizedlist>
        
    <para>
      The notation object stores your notes as a GList. You can add or remove a note
      by calling appropriate function:
    </para>

    <itemizedlist mark="bullet">
      <listitem>
	<code language="C">void ags_notation_add_note(AgsNotation*, AgsNote*, gboolean)</code>
      </listitem>
      <listitem>
	<code language="C">gboolean ags_notation_remove_note_at_position(AgsNotation, guint, guint)</code>
      </listitem>
    </itemizedlist>
    
    <para>
      The notation object supports selection of notes. There are functions available
      to select a single point or a region of the notation. You may find specific
      notes by calling:
    </para>

    <itemizedlist mark="bullet">
      <listitem>
	<code language="C">AgsNote* ags_notation_find_point(AgsNotation*, guint, guint, gboolean)</code>
      </listitem>
      <listitem>
	<code language="C">GList* ags_notation_find_region(AgsNotation*, guint, guint, guint, guint, gboolean)</code>
      </listitem>
    </itemizedlist>

    <para>
      To copy &amp; paste notes you might want to select a region first. Then copy the selection and insert it using new x_offset later.
    </para>

  <example>
    <title>Using AgsNotation Clipboard</title>
    <programlisting language="C">
<xi:include href="../listings/notation_clipboard.c" parse="text" />
    </programlisting>
  </example>
    
  </sect1>

  <sect1>
    <title>AgsAutomation and AgsAcceleration</title>
    <para>
      The automation objects stores your accelerations as a GList. There are analogous
      to notation functions to add or remove accelerations.
    </para>
    
    <itemizedlist mark="bullet">
      <listitem>
	<code language="C">void ags_automation_add_acceleration(AgsAutomation*, AgsAcceleration*, gboolean)</code>
      </listitem>
      <listitem>
	<code language="C">gboolean ags_automation_remove_acceleration_at_position(AgsAutomation*, guint, gdouble)</code>
      </listitem>
    </itemizedlist>

    <para>
      The automation object provides functions to lookup a specific point or region, too.
    </para>

    <itemizedlist mark="bullet">
      <listitem>
	<code language="C">AgsAcceleration* ags_automation_find_point(AgsAutomation*, guint, gdouble, gboolean)</code>
      </listitem>
      <listitem>
	<code language="C">GList* ags_automation_find_region(AgsAutomation*, guint, gdouble, guint, gdouble, gboolean)</code>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1>
    <title>AgsWave and AgsBuffer</title>
    <para>
      The wave objects stores your buffers as a GList. There are analogous
      to notation functions to add or remove buffers.
    </para>
    
    <itemizedlist mark="bullet">
      <listitem>
	<code language="C">void ags_wave_add_buffer(AgsWave*, AgsBuffer*, gboolean)</code>
      </listitem>
      <listitem>
	<code language="C">gboolean ags_wave_remove_buffer(AgsWave*, AgsBuffer*, gboolean)</code>
      </listitem>
    </itemizedlist>

    <para>
      AgsAudio holds a sorted list of AgsWave objects, <code language="C">gint ags_wave_sort_func(gconstpointer, gconstpointer)</code>
      does the actual sorting. You can use it with <code language="C">GList* g_list_insert_sorted(GList*, gpointer, GCompareFunc)</code>.
    </para>

    <para>
      AgsWave holds a sorted list of AgsBuffer objects, <code language="C">gint ags_buffer_sort_func (gconstpointer, gconstpointer)</code>
      does the actual sorting. You can use it with <code language="C">GList* g_list_insert_sorted(GList*, gpointer, GCompareFunc)</code>.
      AgsWave:timestamp uses sample position with matching samplerate. As using
      <code language="C">void ags_timestamp_set_ags_offset (AgsTimestamp*, guint64)</code> ags_offset equals 0
      is your very first sample. You have to introduce after <code language="C">AGS_WAVE_DEFAULT_BUFFER_LENGTH * samplerate</code> samples
      a new AgsWave object. The actual playback recall does bisect AgsWave and AgsBuffer in order to get current playing audio data.
    </para>

    <para>
      AgsBuffer:data contains your actual audio data of AgsBuffer:format type. AgsBuffer:x is the actual
      sample position with matching samplerate.
    </para>

    <para>
      Note audio effects are not applied to AgsWave but to AgsAudioSignal. The program flow is as following:
    </para>

    <orderedlist numeration="arabic">
      <listitem>
	ags-fx-playback does feed AgsWave to AgsAudioSignal of AgsInput.
      </listitem>
      <listitem>
	ags-fx-buffer does buffer AgsAudioSignal from AgsInput to AgsOutput.
      </listitem>
      <listitem>
	Another AgsAudio containing ags-fx-playback, then it plays it on your soundcard. Assumed you prior linked
	the the audio tree.
      </listitem>
    </orderedlist>

    <para>
      In this example, we first read audio data from 2 different files and concat the returned AgsWave objects. Note
      if you want to read multi-channel data, you have to modify the example with a for loop or such, to copy overlapping
      AgsBuffer. AgsBuffer:x shall be unique for specific audio channel.
    </para>

    <example>
    <title>Concat AgsWave</title>
    <programlisting language="C">
<xi:include href="../listings/wave_concat.c" parse="text" />
    </programlisting>
  </example>
    
  </sect1>
  
  <sect1>
    <title>AgsRecallID and AgsRecyclingContext</title>
    <para>
      As mentioned previously in this chapter AgsAudio organizes your recall ids and
      recycling contices. The following functions are here to add and remove them.
    </para>
    
    <itemizedlist mark="bullet">
      <listitem>
	<code language="C">void ags_audio_add_recall_id(AgsAudio*, GObject*)</code>
      </listitem>
      <listitem>
	<code language="C">void ags_audio_remove_recall_id(AgsAudio*, GObject*)</code>
      </listitem>
      <listitem>
	<code language="C">void ags_audio_add_recycling_context(AgsAudio*, GObject*)</code>
      </listitem>
      <listitem>
	<code language="C">void ags_audio_remove_recycling_context(AgsAudio*, GObject*)</code>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1>
    <title>Dealing with recalls</title>
    <para>
      Since AgsAudio is your entry point to do sound processing there are some useful
      functions to set it up, but later on them. Instances of AgsRecallAudio base object
      may be added or removed with <code language="C">void ags_audio_add_recall(AgsAudio*, GObject*, gboolean)</code>
      and <code language="C">void ags_audio_remove_recall(AgsAudio*, GObject*, gboolean)</code>.
    </para>
    
    <para>
      All audio processing is performed by one single function. Wheter you want to initialize, run or cancel playback.
      This is all done by <code language="C">void ags_channel_recursive_run_stage(AgsChannel*, gint, guint)</code>.
    </para>

    <para>
      The following signals are triggered during playback ::play, ::tact and ::done - 
      ::cancel and ::remove during termination.
    </para>

    <sect2>
      <title>Get port of recall</title>
      <para>
	Ports are accessed as <code language="C">GList*</code> from recall by accessing AgsRecall:port property.
      </para>

      <para>
	Below an example shows howto instantiate an application context implementation, obtain it by its generic function
	<code language="C">ags_application_context_get_instance()</code> and create an audio object with ags-fx recalls.
      </para>

      <para>
	The recalls port &quot;./volume[0]&quot; is modified by <code language="C">ags_port_safe_write(AgsPort*, GValue*)</code>.
      </para>

      <example>
	<title>Modify recall port</title>
	<programlisting language="C">
<xi:include href="../listings/find_port.c" parse="text" />
	</programlisting>
      </example>
    </sect2>
  </sect1>

  <sect1>
    <title>Open audio files</title>
    <para>
      There is a handy function called <code language="C">void ags_audio_open_files(AgsAudio*, GSList*, gboolean, gboolean)</code>
      taking as parameter filenames as GSList, overwrite_channels and create_channels as boolean. Filenames is a single
      linked list of strings, overwrite_channels means use pre-allocated channels and
      create_channels to allow instantiate new channels. The boolean parameters can be combined
      as you want.
    </para>
    
    <sect2>
      <title>Audio container</title>
      <para>
	The AgsAudioContainer object can open Soundfont2, Gig and DLS2 files by using libinstpatch. The AgsAudioContainer:sound-container
	field implements AgsSoundContainer and provides you many functions to dealing with container formats.
      </para>

      <para>
	There are convenient functions to obtain a GObject subtype implementing AgsSoundResource:
      </para>

      <itemizedlist>
	<listitem>
	  GList* ags_sound_container_get_resource_all()
	</listitem>
	<listitem>
	  GList* ags_sound_container_get_resource_by_name()
	</listitem>
	<listitem>
	  GList* ags_sound_container_get_resource_by_index()
	</listitem>
	<listitem>
	  GList* ags_sound_container_get_resource_current()
	</listitem>
      </itemizedlist>
    </sect2>

    <sect2>
      <title>Audio file</title>
      <para>
	The AgsAudioFile object can open FLAC, WAV, AIFF and OGG using libsndfile. The AgsAudioFile:sound-resource
	field implements AgsSoundResource and provides you many functions to dealing with audio file formats.
      </para>

      <itemizedlist>
	<listitem>
	  void ags_sound_resource_info()
	</listitem>
	<listitem>
	  void ags_sound_resource_set_presets()
	</listitem>
	<listitem>
	  void ags_sound_resource_get_presets()
	</listitem>
	<listitem>
	  guint ags_sound_resource_read()
	</listitem>
	<listitem>
	  void ags_sound_resource_write()
	</listitem>
	<listitem>
	  void ags_sound_resource_flush()
	</listitem>
	<listitem>
	  void ags_sound_resource_seek()
	</listitem>
      </itemizedlist>
    </sect2>
  </sect1>
</chapter>