.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PerlSpeak 3pm"
.TH PerlSpeak 3pm "2014-04-11" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\& PerlSpeak \- Perl Module for text to speech with festival, espeak, cepstral and others.
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& my $ps = PerlSpeak\->new([property => value, property => value, ...]);
.Ve
.SS "\s-1METHODS\s0"
.IX Subsection "METHODS"
.Vb 2
\& $ps = PerlSpeak\->new([property => value, property => value, ...]);
\& # Creates a new instance of the PerlSpeak object.
\&
\& $ps\->say("Text to speak.");
\& $ps\->say("file_name");
\& # The basic text to speech interface.
\& 
\& $ps\->readfile("file_name");
\& # Reads contents of a text file.
\& 
\& $ps\->file2wave("text_file_in", "audio_file_out");
\& # Converts a text file to an audio file.
\&
\& $path = $ps\->filepicker("/start/directory");
\& # An audio file selector that returns a path to a file. If "dir_return" is true
\& # "filepicker" may also return the path to a directory.
\&
\& $path = $ps\->dirpicker("/start/directory");
\& # An audio directory selector that returns a path to a directroy.
\&
\& $chr = $ps\->getchr(); 
\& # Returns next character typed on keyboard
\&
\& $ps\->menu($prompt => $callback, ...)
\& # An audio menu executes callback when item is selected
\&
\& $item = $ps\->menu_list(@list);
\& # Returns element of @list selected by user.
\&
\& $string = $ps\->getString([$prompt]);
\& # Returns a string speaking each character as you type. Also handles backspaces
\&
\& $boolean = $ps\->confirm([$prompt]);
\& # Returns boolean. Prompts user to enter Y for yes or N for no.  Enter also returns true.
\&
\& $ps\->config_voice("voice_name", $voice_rate, $voice_volume, $voice_pitch);
\& # Configures voice. Excepts standard parameters for festival and espeak.
\& # For festival:
\& #   The voice rate values should be between 0.50 and 2.00;
\& #   The voice volume values should be between 0.33 and 6.00;
\& #   The voice pitch is not used.
\& # For espeak:
\& #   The voice rate values are words per minute. 160 is a standard setting;
\& #   The voice volume values should be between 0 and 20. 10 is a standard setting;
\& #   The voice pitch values should be between 0 and 99. 50 is a standard setting;
\& 
\& $ps\->config_festival("voice_name", $voice_speed, $voice_volume);
\& # See as config_voice above.
\&
\& $tts = $ps\->tts_engine(["tts_engine"]); # Gets or Sets tts_engine property.
\& $voice = $ps\->set_voice(["voice_name"]); # See config_voice above.
\& $rate = $ps\->set_rate([$rate]); # See config_voice above.
\& $volume = $ps\->set_volume([$volume]); # See config_voice above.
\& $pitch = $ps\->set_pitch([$pitch]); # See config_voice above.
\&
\& $voices = $ps\->get_voices();
\& # Returns a refrence to a list of available voices in the language of $self\->{lang} property.
\&
\& $ps\->festival_connect([$host, $port]);
\& # Must be used if using festival_server as the tts_engine.
\&
\& $mime_type = $ps\->getType($filename); # Returns Mime Type for $filename.
.Ve
.SS "\s-1PROPERTIES\s0"
.IX Subsection "PROPERTIES"
.Vb 3
\& # The default property settings should work in most cases. The exception is
\& # if you want to use a tts system other than festival or cepstral. The rest
\& # of the properties are included because I found them useful in some instances.
\&
\& $ps\->{tts_engine} => $text; # Default is "festival_pipe"
\& # Valid values are "festival", "festival_server", "festival_pipe", "espeak" or
\& # "cepstral" Other tts engines can be used by using the tts command properties.
\& 
\& $ps\->{tts_command} => "command text_arg"; # Default is ""
\& # Command to read a text string. "text_arg" = text string.
\& 
\& $ps\->{tts_file_command} => "command file_arg" # Default is ""
\& # Command to read a text file. "file_arg"  = path to text file to be read.
\& 
\& $ps\->{file2wave_command} => "command IN OUT"; # Default is ""
\& # Command for text file to wave file. "IN" = input file "OUT" = output file.
\& # Not needed if tts_engine is festival" or "cepstral.
\& 
\& $ps\->{no_dot_files} => $boolean; # Default is 1
\& $ Hides files that begin with a \*(Aq.\*(Aq
\& 
\& $ps\->{hide_extentions} => $boolean;  # Default is 0
\& # Will hide file extensions.
\& # NOTE: If hiding extensions the no_dot_files property must be set to 1.
\& 
\& $ps\->{make_readable} => "regexp pattern"; # default is "[_\e\e]"  
\& # will substitute spaces for regexp pattern 
\& 
\& $ps\->{browsable} => $boolean; # Default is 1
\& # If true filepicker can browse other directories via the right and left arrows. 
\& 
\& $ps\->{dir_return} => $boolean; # Default is 1
\& # If true filepicker may return directories as well as files.
\& 
\& $ps\->{file_prefix} => $text; # Default is "File"
\& # For filepicker. Sets text to speak prior to file name. 
\& 
\& $ps\->{dir_prefix} => "text"; # Default is "Folder"
\& # For filepicker and dirpicker. Sets text to speak prior to directory name. 
\&
\& $ps\->{echo_off} => $boolean; # Default is 0
\& # If set to true, turns off printing of text to screen.
\&
\& $ps\->{voice} => $text; # # Use set_voice($voice) instead.
\& # Must be set to a valid voice name for tts_engine used. This is especially
\& # true for festival_server and festival_pipe
\&
\& $ps\->{lang} => $text; # Default is "en" for english.
\& # Used only if espeak is the tts_engine.
\&
\& $ps\->{rate} => $double; # Use set_rate($rate) instead.
\&
\& $ps\->{volume} => $double; # Use set_volume($volume) instead.
\&
\& $ps\->{pitch} => $double; # Use set_pitch($pitch) instead.
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.Vb 6
\&  PerlSpeak.pm is Perl Module for text to speech with festival or cepstral.
\&  (Other tts systems may be used by setting the tts command properties).
\&  PerlSpeak.pm includes several useful interface methods like an audio file 
\&  selector and menu system. PerlSpeak.pm was developed to use in the 
\&  Linux Speaks system, an audio interface to linux for blind users. 
\&  More information can be found at the authors website http://www.joekamphaus.net
.Ve
.SH "CHANGES"
.IX Header "CHANGES"
.Vb 1
\& 1/9/2007 ver 0.03
\&
\& * Fixed error handling for opendir and readdir.
\&
\& * Added property tts_command => $string 
\&    (insert "text_arg" where the text to speak should be.)
\&
\& * Added property no_dot_files => $boolean default is 1
\&    (Set to 0 to show hidden files)
\&
\& * Fixed bug in tts_engine => "cepstral" (previously misspelled as cepstrel)
\&
\& * Added funtionality to traverse directory tree up as well as down.
\&    (user can now use the arrow keys for browsing and selecting
\&    up and down browses files in current directory. Right selects the 
\&    file or directory. Left moves up one directory like "cd ..")
\&
\& * Added property hide_extentions => $boolean to turn off speaking of file
\&    extensions with the filepicker method. Default is 0.
\&    (NOTE: If hiding extensions the no_dot_files property must be set to 1)
\&    
\& * Added property "make_readable" which takes a regular expression as an
\&    argument. PerlSpeak.pm substitues a space for characters that match
\&    expression. The default is "[_\e\e]" which substitutes a space for "\e"
\&    and "_".
\&
\&
\&
\& 1/9/2007 ver 0.50
\& 
\& * Added funtionality for reading a text file. Method "say" will now take
\&    text or a file name as an argument. Also added method "readfile" which
\&    takes a file name as an argument. The property tts_file_command was also
\&    added to accommodate tts systems other than festival or cepstral.
\&
\& * Added funtionality for converting a text file to a wave file via the
\&    "file2wave" method and optionally the "file2wave_command" property.
\& 
\& * Added properties "file_prefix" and "dir_prefix" to enable changing
\&    text to speak prior to file and directory names in the "filepicker"
\&    and "dirpicker" methods.
\&    
\& * Added "browsable", a boolean property which will togle the browsable feature
\&    of the "filepicker" method. 
\&    
\& * Added "dir_return", a boolean property which will allows the "filepicker" 
\&    method to return the path to a directory as well as the path to a file.
\&    
\& * Changed required version of perl to 5.6. I see no reason why PerlSpeak.pm
\&    should not work under perl 5.6, however, this has not yet been tested. If
\&    you have problems with PerlSpeak on your version of perl let me know.
\&    
\&    
\&
\& 10/10/2007 ver 1.50
\&  * Added boolean property echo_off to turn off printing of text said to screen.
\&
\&  * Added method menu_list(@list) Returns element of @list selected by user.
\&
\&  * Added method getString() Returns a string speaking each character as you
\&    type. Also handles backspaces.
\&
\&  * Added method conirm(). Returns boolean. Prompts user to enter Y for yes
\&    or N for no.  Enter also returns true.
\&
\&  * Added shortcuts to the menu() method. You can press the number of menu
\&    index or the letter of the first word in menu item to jump to that item.
\&
\& 01/02/2008 ver 2.01
\&  * Added support for festival_server, festival_pipe, and espeak text to speech
\&    engines. This includes several methods and properties such as voice, pitch
\&    volume, and rate.
\&
\&  * Added method getType(filename) Returns mime type for filename.
.Ve
.SH "EXAMPLE"
.IX Header "EXAMPLE"
.Vb 2
\&  # Several examples can be found in the example directory included with the
\&  # tarball for this module.
\&
\&  use PerlSpeak;
\&  
\&  my $ps = PerlSpeak\->new();
\&  
\&  # Set properties
\&  $ps\->{tts_engine} = "festival"; # or cepstrel
\&  # Optionally set your own tts command use text_arg where the text goes
\&  $ps\->{tts_command} => ""; 
\&  $ps\->{no_dot_files} => 1;
\&  $ps\->{hide_extentions} => 0;
\&    
\&   
\&  # Audio file selectors
\&  my $file = $ps\->filepicker($ENV{HOME}); # Returns a file.
\&  my $dir = $ps\->dirpicker($ENV{HOME}); # Returns a directory.
\&  
\&  $ps\->say("Hello World!"); # The computer talks.
\&
\&  # Returns the next character typed on the keyboard
\&  # May take 2 or 3 calls for escape sequences.
\&  print $ps\->getch(); 
\&
\&  # Make some sub refs to pass to menu  
\&  my $email = sub {
\&        print "Email\en";
\&  };
\&  my $internet = sub {
\&        print "Internet\en";
\&  };
\&  my $docs = sub {
\&        print "Documents\en"
\&  };
\&  my $mp3 = sub {
\&        print "MP3\en";  
\&  };
\&  my $cdaudio = sub {
\&        print "CD Audio\en"
\&  };
\&  my $help = sub {
\&        print "Browse Help\en"
\&  };
\&
\&  # menu is a audio menu
\&  # Pass menu a hash of "text to speak" => $callback pairs
\&  $ps\->menu(
\&        "E\-mail Menu" => $email,
\&        "Internet Menu" => $internet,
\&        "Documents Menu" => $docs,
\&        "M P 3 audio" => $mp3,
\&        "C D audio" => $cdaudio,
\&        "Browse help files" => $help,
\&  };
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.Vb 1
\&  More information can be found at the authors website http://www.joekamphaus.net
\&  
\&  The Festival Speech Synthesis System can be found at:
\&    http://www.cstr.ed.ac.uk/projects/festival/
\&
\&  The eSpeak text to speech synthesizer can be found at:
\&    http://espeak.sourceforge.net/
\&
\&  Reasonably priced high quality proprietary software voices from Cepstral 
\&  can be found at: http://www.cepstral.com.
\&
\&  The Flite (festival\-lite) Speech Synthesis System can be found at:
\&    http://www.speech.cs.cmu.edu/flite/index.html
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Joe Kamphaus, <joe@joekamphaus.net>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2007 by Joe Kamphaus
.PP
# This program is free software; you can redistribute it and/or modify
# it under the terms of the \s-1GNU\s0 General Public License as published by
# the Free Software Foundation; version 2 of the License.
.PP
# This module is distributed in the hope that it will be useful,
# but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
# \s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE. \s0 See the
# \s-1GNU\s0 General Public License for more details.