<appendix xmlns="http://docbook.org/ns/docbook" xml:id="appendix.wings_filter">
  <title>Wings Filter</title>
  <sect1 xml:id="sect.wings_filter.overview">
    <title>Overview</title>
    <para>
      Wings Filter is a script designed to be used to import existing audio
      and meta-data from an AirForce 'Wings' automation system.
    </para>
  </sect1>

  <sect1 xml:id="sect.wings_filter.usage">
    <title>Usage</title>
    <para>
      <command>wings_filter
      <arg choice="req">-g <replaceable>default-group</replaceable></arg>
      <arg choice="req">-d <replaceable>db-file</replaceable></arg>
      <arg choice="req">-A <replaceable>audio-dir</replaceable></arg>
      <arg choice="opt">-e <replaceable>audio-ext</replaceable></arg>
      </command>
    </para>
    <variablelist>
      <varlistentry>
	<term>-g <replaceable>default-group</replaceable></term>
	<listitem>
	  <para>
	    The name of the group in which to place carts
            belonging to a source tab in Wings for which there
            is no corresponding destination Group.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>-d <replaceable>db-file</replaceable></term>
	<listitem>
	  <para>
	    The path to the Wings database file.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>-A <replaceable>audio-dir</replaceable></term>
	<listitem>
	  <para>
	    The path to the directory containing the Wings ATX
            audio files.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>-s <replaceable>audio-ext</replaceable></term>
	<listitem>
	  <para>
	    The filetype extension fo the Wings ATX files. By
            default, this is 'ATX', but can be changed to
            other values here if necessary.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
  </sect1>

  <sect1 xml:id="sect.wings_filter.procedure">
    <title>Procedure</title>
    <para>
      In order import audio from an existing Wings system, proceed as
      follows:
    </para>
    <sect2 xml:id="sect.wings_filter.procedure.create_rivendell_groups">
      <title>Create Rivendell Groups</title>
      <para>
	In RDAdmin->ManageGroups, create a Group to correspond to each Wings
	Tab value that exists in the library to be imported, and an additional
	group to catch any Wings entries that may not have a valid Group.
	When creating these groups, it is essential that a default cart number
	range be configured for each group that is large enough to accomodate
	all anticipated imports.
      </para>
    </sect2>
    <sect2 xml:id="sect.wings_filter.procedure.locate_the__wings__database_and_audio_files">
      <title>Locate the 'Wings' Database and Audio Files</title>
      <para>
	These can be mounted from a remote system if needs be.  Read-only
	access is adequate, as the script does not modify these items in any
	way.
      </para>
    </sect2>
    <sect2 xml:id="sect.wings_filter.procedure.verify_available_disk_space">
      <title>Verify Available Disk Space</title>
      <para>
	Verify that enough disk space is available in the '/var/snd/'
	directory to accomodate the audio to be imported.  You should have at
	least the amount of space currently occupied by the Wings ATX files,
	plus 5 percent additional.
      </para>
    </sect2>
    <sect2 xml:id="sect.wings_filter.procedure.invoke_script">
      <title>Invoke Script</title>
      <para>
	Start up the script, as described in
	<xref linkend="sect.wings_filter.usage" />. The script will print progress
	reports as it proceeds, or notify you of
	error conditions as required.
      </para>
    </sect2>
    <sect2 xml:id="sect.wings_filter.procedure.clean_up">
      <title>Clean Up</title>
      <para>
	If desired, use RDAdmin->ManageGroups to rename the single-letter
	import groups to more intuitive names.
      </para>
    </sect2>
    <caution xml:id="caution.wings_filter.procedure.note_on_audio_processing">
      <title>Note on Audio Processing</title>
      <para>
	Wings Filter does not alter or reencode the audio sample data in any
	way, and thus does *not* incurr any generation or transcoding loss of
	quality.  At the same time, this means that the incoming audio will be
	brought into Rivendell *exactly* as it exists in the Wings system,
	with all parameters (e.g. sample rate, bit rate, level, etc)
	unaltered.  If you need to alter one or more of these parameters as
	part of the import process, we suggest you use the RDImport script
	instead.
      </para>
    </caution>
  </sect1>
</appendix>
