What's with audio and gretl?
===========================

Introduction
============

This note describes what is going on with audio in gretl, and also
what you need in terms of additional software to make use of this
facility.

What and Why?
=============

I teach a course in Economic Data Analysis, using gretl, and in the
Fall of 2004 I will have a blind student in my class.  So as of summer
2004 I am working to try to make gretl more friendly to those without
sight.

There are two aspects to this, so far: audio graphs, and the speaking
of the content of certain gretl windows.

As for audio graphs, the idea is that we sighted people can get a
useful initial handle on a data set by looking at various time-series
graphs or X-Y scatter-plots, as appropriate, and I'm trying to work
out an audio counterpart for the non-sighted.

The basic idea is that we represent the x-axis variable by the passage
of time (even if it's not actually time on the x-axis, as it is in a
time-series plot), and the magnitude(s) on the y-axis by a musical
note whose pitch corresponds to the magnitude (normalized to a
reasonable auditory range).  This is implemented via a MIDI file. Up
to two y-axis magnitudes can be represented by this sort of "data
sonification" (as it is called in the literature), separated by timbre
(choice of MIDI "instrument" or patch file) and by stereo channel.

As regards the speaking of window content, blind people have various
resources available already, which do "text to speech" (TTS) on window
contents.  But after a little experimentation it became clear to me
that this is not necessarily very useful.  A tabular presentation of
output, which is quite clear to the eye, may be hopelessly confusing
when "read out" on a strict left-to-right, top-to-bottom basis.
("What was the meaning of this column?  Which column are we in,
anyway?")  

I have therefore taken some time to construct specifically auditory
representations of the content of some gretl windows (so far, only a
few).  These representations (a) skip some detail which cannot be
given perspicuously in auditory mode, while (b) offering some
(hopefully) helpful redundancy in respect of the basics. 

Dependencies
============

The gretl audio facilities depend on (a) speech synthesis and (b) a
MIDI player.

Speech synthesis: This can be supported either by the flite (Festival
Lite) library on Linux and other unices, or the Microsoft Speech API
(SAPI) on Windows.  I have experimented with both of these (for the MS
SAPI I used Windows XP "Professional").  

For flite, see:

  http://www.speech.cs.cmu.edu/flite/

and for the Windows SAPI, see:

  http://www.microsoft.com/speech/download/sdk51/

MIDI player: On Linux this is typically timidity, 

  http://timidity.sourceforge.net/

and on Windows it is typically Winamp.  On Linux you can choose a MIDI
player (and its options) using an environment variable (see below).
On Windows the MIDI player is whatever is offered by the Windows
ShellExecute() function as applied to a MIDI file.

How To
======

* If you are using gretl on Windows, audio support is built in at the
gretl end; you "just" need to ensure that your Windows installation
supports TTS and MIDI playing.

* If you're using gretl on Linux, you should compile gretl from source
yourself to get audio support (first installing flite as mentioned
above).  The following two configure options are relevant:

  --with-audio=yes
  --with-flite-prefix=<whatever>

The first of these options is required to get gretl interested in
supporting audio.  The second may be needed if flite is installed in a
location where it will not readily be found.  On my own system, I give

  --with-flite-prefix=/opt/speech

because I chose to install the flite libraries and headers under
/opt/speech.

Regardless of OS, gretl's audio support resides in a dynamically
loaded "plugin" (either audio.so or audio.dll).

Activating audio in gretl
=========================

Assuming gretl was built with audio support, here are the controls:

(1) When a graph is displayed, with focus in the graph window press
    the "a" (for audio) key.  You should get a brief
    speech-synthesized description followed by a MIDI play-through of
    the graph.

(2) When a gretl text window is displayed, again press the "a" key to
    get an audio representation.  Press "x" to stop the read-out.  In
    some cases the read-out will be a simple TTS rendering of the
    visible content of the window, which may or may not be very useful
    to a blind user.  In the following cases (to be extended) it will
    be a purpose-designed auditory rendition of the window's content:

    - Summary statistics, for a variable or set of variables
    - Correlation matrix for a set of variables
    - OLS models
    - Confidence intervals for regression coefficients
    - Covariance matrix for regression coefficients

Under Linux or other unices, you can control the MIDI player used for
graphs via the environment variable GRETL_MIDI_PLAYER, which can be
assigned the name of a player program plus zero or more options.  The
default is equivalent to

  GRETL_MIDI_PLAYER="timidity -A500"

where the "-A500" option raises the volume a bit relative to the
default (which is a bit too quiet on my system).  Personally, I use

  GRETL_MIDI_PLAYER="timidity -A500 -ig"

to get timidity to present its GTK user interface (see the timidity
man-page for details).  You might wish to use

  GRETL_MIDI_PLAYER="xmms"

if you have the midi plugin for xmms.

Allin Cottrell
Wake Forest university
May 2004