NAME
       Speech::Swift - Perl extension for the Cepstral Text-to-Speech Engine

SYNOPSIS
       use Speech::Swift;

DESCRIPTION
       ENGINE FUNCTIONS

       swift_engine_open($params)
           opens a new swift engine instance. $params is a swift_params object returned by
           swift_params_new().

           returns a new swift_engine instance.

           $engine = swift_engine_open($params);

       swift_engine_close($engine)
           closes a swift engine instance. $engine is swift_engine instance returned by
           swift_engine_open()

           swift_engine_close($engine);

       PORT FUNCTIONS

       swift_port_open($engine, $params)
           opens a new swift port. $engine is swift_engine instance returned by
           swift_engine_open(). $params is a swift_params object returned by
           swift_params_new().

           $port = swift_port_open($engine, $params);

       swift_port_close($port)
           closes a swift port. $port is a swift_port object opened by swift_port_open();

           swift_port_close($port);

       swift_port_language_encoding($port)
           returns the current language encoding used by this port. $port is a swift_port
           object

           $encoding = swift_port_language_encoding($port);

           $encoding can be "pcm16", "pcm8", "ulaw" or "alaw"

       swift_port_load_sfx($port, $sfx_file)
           load a sound effects file to use on a port. $port is a swift_port object to load
           the sound effects on, $sfx_file is the path to a sound effects file.

           $res = swift_port_load_sfx($port, $sfx_file);

           returns a swift_result object.

       swift_port_get_wave(_port, _text)

       PARAMS FUNCTIONS

       swift_params_new()
           creates and returns a new swift_params object.

           $params = swift_params_new();

       swift_params_set_string($params, $name, $value)
       swift_params_set_int($params, $name, $value)
           sets a parameter value on the params object. $params is a swift_params object.
           $name is the text name of the param value to set. $value is either a string or int.

           $name can be:

           "audio/encoding"    - encoding type, can be "pcm16", "pcm8", "ulaw" or "alaw"
           "audio/channels"    - number of channels, can be 1 or 2
           "audio/deadair"     - strip dead air from the audio, 1 or 0

       VOICE FUNCTIONS

       swift_port_set_voice($port, $voice)
           sets a voice to use on a given port. $port is the swift_port to set the voice on.
           $voice is the swift_voice object to assign to this port.

           $res = swift_port_set_voice($port, $voice);

           returns a swift_result object.

       swift_port_set_voice_by_name($port, $voice_name)
           sets a voice to use on a given port. $port is the swift_port to set the voice on.
           $voice_name is the name of a swift voice to assign to this port.

           $voice = swift_port_set_voice_by_name($port, "Allison");

           returns a swift_voice object.

       swift_port_set_voice_from_dir($port, $dir)
           sets a voice to use on a given port. $port is the swift_port to set the voice on.
           $dir is a directory that contains the voice to use.

           $voice = swift_port_set_voice_from_dir($port, "/dir/to/voice");

           returns a swift_voice object.

       swift_port_get_current_voice($port)
           returns a swift_voice object for the current voice assigned to port $port.

           $voice = swift_port_get_current_voice($port);

       swift_voice_get_attribute($voice, $name)
           returns the value for the given attribute name, from the swift_voice object $voice.

           $value = swift_voice_get_attribute($voice, "speaker/name");

           attribute names can be one of the following:

           "id"
           "name"
           "path"
           "version"
           "buildstamp"
           "sample-rate"
           "license/key"
           "language/tag"
           "language/name"
           "language/version"
           "lexicon/name"
           "lexicon/version"
           "speaker/name"
           "speaker/gender"
           "speaker/age"
       swift_port_find_first_voice($port, $search_criteria, $order_criteria)
           finds the first available voice on the swift_port $port. $search_criteria and
           $order_criteria are attribute names to limit the voice list. see
           swift_voice_get_attribute() for the list of available attributes.

           $voice = swift_port_find_first_voice($port, "speaker/gender=male", "speaker/name");

           returns a swift_voice object.

       swift_port_find_next_voice($port)
           returns the next voice in the search list after a call to
           swift_port_find_first_voice(). $port is a swift_port object.

           $voice = swift_port_find_next_voice($port);

           returns a swift_voice object.

       swift_port_rewind_voices($port)
           rewinds the search results after a call to swift_port_find_first_voice(). $port is
           swift_port object.

           $voice = swift_port_rewind_voices($port);

           returns a swift_voice object.

       WAVEFORM FUNCTIONS

       swift_waveform_new()
           creates and returns a new waveform object.

           $wave = swift_waveform_new();

           returns a swift_waveform object.

       swift_waveform_save($wave, $filename, $format)
           saves a waveform to a file. $wave is a swift_waveform object. $filename is the file
           name to write the waveform to. $format is the format of the format to save the wav
           as.

           $res = swift_waveform_save($wave, "out.wav", "riff");

           returns a swift_result object.

           format can be one of:

           "riff"   - Microsoft RIFF (WAV) file
           "snd"    - Sun/NeXT .au (SND) format.
           "raw"    - unheadered audio data, native byte order
           "le"     - unheadered audio data, little-endian (LSB first)
           "be"     - unheadered audio data, big-endian (MSB first)
       swift_waveform_get_sps($wave)
           returns the sample rate of the given swift_waveform object $wave

           $sample_rate = swift_waveform_get_sps($wave);

       swift_waveform_get_encoding($wave)
           returns the encoding of the given swift_waveform object $wave

           $encoding = swift_waveform_get_encoding($wave);

           $encoding can be one of can be "pcm16", "pcm8", "ulaw" or "alaw".

       swift_waveform_get_channels($wave)
           returns the channels setting for the given swift_waveform $wave

           $channels = swift_waveform_get_channels($wave);

           $channels will be 1 or 2.

       swift_waveform_resample($wave, $new_sps)
           resample the given swift_waveform object $wave, to the given sample rate $new_sps.

           $res = swift_waveform_resample($wave, 8000);

           returns a swift_result object.

       swift_waveform_convert($wave, $encoding)
           changes the encoding of the given swift_waveform object $wave, to the given
           encoding type $encoding. $encoding can be one of can be "pcm16", "pcm8", "ulaw" or
           "alaw".

           $res = swift_waveform_convert($wave, $encoding);

           returns a swift_result object.

       swift_waveform_set_channels($wave, $channels)
           changes the given swift_waveform object $wave, to the number of channels specified
           by $channels. $channels can be either 1 or 2.

           $res = swift_waveform_set_channels($wave, $channels);

           returns a swift_result object.

       swift_waveform_get_samples($wave)
           returns the raw audio samples for the given swift_waveform object $wave.

           @samples = swift_waveform_get_samples($wave);

           the raw audio is returned as a array of 16bit samples. the wav header isn’t
           included.

       ERROR HANDLING

       swift_failed($result)
           returns 1 or 0 if the given swift_result object is failed.

       swift_strerror($result)
           returns the error message for the given swift_result object

DEPENDENCIES
       Cepstral Text-to-Speech engine, libswift.so

SEE ALSO
       Cepstral - http://cepstral.com/

AUTHOR
       Mike Pultz <mike@mikepultz.com>

LICENCE AND COPYRIGHT
       Copyright (c) 2011, Mike Pultz <mike@mikepultz.com>. All rights reserved.

       This module is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY
       BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE
       SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN
       WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT
       WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE
       RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE
       PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY
       COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS
       PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL,
       SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO
       USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
       INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO
       OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED
       OF THE POSSIBILITY OF SUCH DAMAGES.
