|
|
EUROPEAN
SOUTHERN OBSERVATORY Organisation Européenne pour des Recherches
Astronomiques dans l'Hémisphère Austral Europäische Organisation für astronomische
Forschung in der südlichen Hemisphäre |
VERY LARGE TELESCOPE
VLT Software
---
HOS / Audio
Software User Manual
VLT-MAN-ESO-17220-3676
Issue 1
Date: 26/10/2005
Prepared: E. Allaert............................... 26/10/2005.....................................................
Name Date Signature
Approved: K.
Wirenstrand............................................... .................................................................................
Name Date Signature
Released: M.
Cullum....................................... .................................................................................
Name Date Signature
CHANGE RECORD
|
Issue |
Date |
Affected
Paragraphs(s) |
Reason/Initiation/Remarks |
|
1 |
|
All |
First version |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
TABLE OF
CONTENTS
1.5 List of Abbreviations/Acronyms
2.3 The audioServer
application
2.7 A cookbook recipe for Tcl-applications
4.1 Frequently Asked Questions
LIST OF
TABLES
Table
1: compatibility of the audio package with various client/server platforms
LIST OF
FIGURES
Figure
1: flow of audio request
Figure
2: the volume control panel
The information contained in this manual is intended to be used in the
ESO VLT project by ESO and authorized contractors only.
While every precaution has been taken in the development of the software
and in the preparation of this documentation, ESO assumes no responsibility for
errors or omissions, or for damage resulting from the use of the software of
the information contained herein.
1. INTRODUCTION
1.1 Purpose
This document is the User Manual for the HOS / Audio Software, version 1.12 and is intended to provide all the necessary information for the installation, configuration and use of the software, from a system administrator’s and application programmer’s point of view.
1.2 Scope
This document describes how to configure and use the audio module, as a component of high level tools and utilities.
1.3 Applicable Documents
The following documents, of the exact issue shown, form a part of this document to the extent specified herein. In the event of conflict between the documents referenced herein and the contents of this document, the contents of this document shall be considered as a superseding requirement.
|
Reference |
Document
Number |
Issue |
Date |
Title |
|
VLT-SPE-ESO-10000-0011 |
2.0 |
|
VLT
Software Requirements Specification |
|
|
VLT-PRO-ESO-10000-0228 |
1.0 |
|
VLT
Software Programming Standards |
|
|
VLT-MAN-ESO-17210-0667 |
1.3 |
|
Guidelines
for VLT applications. |
1.4 Reference Documents
The following documents are referenced in this document.
|
Reference |
Document
Number |
Issue |
Date |
Title |
|
VLT-MAN-ESO-17200-2238 |
4 |
|
VLT
Common SW – Combined Installation Manual |
|
|
VLT-MAN-ESO-17200-2009 |
4 |
|
VLT
Common SW – Linux Installation Mnl |
|
|
VLT-MAN-ESO-17200-0642 |
4 |
|
VLT
Common Software Installation Manual |
|
|
VLT-MAN-ESO-17220-0737 |
3.0 |
|
HOS -
Sequencer User Manual |
1.5 List of Abbreviations/Acronyms
This document employs several abbreviations and acronyms to refer concisely to an item, after it has been introduced. The following list is aimed to help the reader in recalling the extended meaning of each short expression:
|
GUI |
Graphical
User Interface |
|
HW |
Hardware |
|
I/O |
Input/output |
|
LAN |
Local
Area Network |
|
N/A |
Not
Applicable |
|
SW |
Software |
|
TBC |
To Be
Clarified |
|
TBD |
To Be
Defined |
|
UIF |
(Portable)
User Interface (Toolkit) |
|
VLT |
Very
Large Telescope |
|
WS |
Workstation |
1.6 Glossary
No special definition is introduced in this manual. The following concepts are repeated here for clarity’s sake:
client
The application process that wants to have an audio
file played on the server.
local
host
Host where a particular application runs; in the
absence of a reference to such application, the client application is meant.
server
The process that receives requests to play a
sound-file from a client. Also the host where this server process executes.
1.7 Stylistic Conventions
The following styles are used:
bold
in the text, for commands, filenames, pre/suffixes as they have to be typed.
italic
In the text, for parts that have to be substituted with the real content before typing.
teletype
for examples.
<name>
in the examples, for parts that have to be substituted with the real content before typing.
bold and italic are also used to highlight words.
1.8 Problem Reporting
The form described in [RD 03] shall be used.
2. USER’s guide
2.1 The basis: snack
Users can benefit from applications that have the possibility to give audio messages, e.g. warnings if particular ranges are about to be exceeded, or indications that during longer processing a particular stage is reached. Typically this involves an application running on one piece of hardware (e.g. an application server machine in the computer room) which would like to produce some sounds on a different box (e.g. a PC used as an X-terminal). There are plenty of solutions available for networked audio in the Unix/Linux world, but several of these are proprietary, have not been tested on all the HW combinations we use, are no longer maintained, do not have matching versions for our HW, or are not very practical to install, configure or operate:
· HP Envizex X-terminals can have audio HW and corresponding audio-server software can run on these boxes, but the audio clients need to access this server via HP’s proprietary HP-UX audio library software. In other words, the use of audio on an HP-Envizex X-terminal requires that the application is running on an HP-UX box.
· NCD X-terminals come with audio-HW and some binaries to be used from an HP-UX workstation to send sound-files to these X-terminals. In fact, rather than sending the audio-files across the network, the name of the audio file is passed, and the X-terminal will require accessing this file via NFS. In other words, this requires that some directories on the HP-UX workstations are exported to the NCD X-terminals.
· The Enlightened Sound Daemon or EsounD (see also http://www.tux.org/~ricdude/EsounD.html) is audio server software that comes from the Linux world, but it also compiles under HP-UX. It works similar as HP’s send_sound application, sending the content of an audio file from a client to the audio server. However, EsounD has not been maintained since 2000 so it is not a good candidate to start any new project.
· The Network Audio System or NAS (see also http://radscan.com/nas.html). NAS has the same software architecture as HP has for its proprietary implementation, it is still actively maintained and it provides a far completer set of utilities than EsounD does. But building this software on HP and Solaris in a VLTSW environment is not trivial (due to its use of imake, which relies on a bunch of specific configuration files), and it requires quite some tweaking, as the directory paths it expects by default is not what you find in a VLTSW environment. Although there is also a binary NAS distribution for MS-Windows available, it is however not up-to-date, and on top of that it requires CygWin. As mentioned before, NAS cannot talk to the HP proprietary Audio Server on HP-UX boxes or Envizex terminals – and there is no documented way to cross-compile the NAS server for these terminals either.
· Agnula (see http://www.agnula.org/) is a pretty new sound project funded by the European Commission. However, it is exclusively targeted at Linux platforms.
· aRts (see http://www.arts-project.org/index.html) is KDE's sound project. Doesn’t seem to have evolved since 2002.
Fortunately one of the components of the
VLT Common Software can deal very well with sound: the snack Tcl-extension (see http://www.speech.kth.se/snack/).
It actually takes very few lines of Tcl-code to create an audio server using
this snack audio extension. And as
there are also binary Tcl-binaries including snack for MS-Windows freely available, we can use the same
audio-server source code on MS-Windows (relevant in
development environments using MS-Windows based PCs with X-emulator
applications). This option is superior to ones listed above for following
reasons:
·
snack can play most audio formats (WAV,
MP3, AU, SND,
· runtime control over many audio parameters like selection of output devices. I.e. one can with snack switch between internal loudspeaker and line-out. With NAS e.g. this is in a configuration file read at start-up of the server; to change any of these properties, the configuration-file needs to be modified, the server needs to be stopped and re-started.
· out-of-the-box compilation of the snack extension on Windows 95/98/NT/2K/XP, Linux, Macintosh, Sun Solaris, HP-UX, FreeBSD, NetBSD, and SGI IRIX. E.g. in the case of HP-UX, snack uses the HP audio library to communicate with HP audio devices, i.e. it can be used to play sounds either locally on an HP-UX WS or to an HP X-terminal. In fact, we've included the snack sound extension to our TCLTK_ROOT since many releases. This means no extra effort, compared to e.g. NAS for HP-UX and Solaris, with its dependency on imake – which we normally don’t use.
· only a minimal amount of extra code to add to current VLT Common SW; obviously we have full control over this source code.
· all snack code ends up under standard directories; for NAS we'd have to edit some of the source code if we don't want e.g. to add directories to PATH.
· availability of excellent documentation and plenty of sample code (incl. powerful user interfaces) to deal with audio - if anyone wants to do more serious work with audio.
2.2 Architecture
From a Tcl-application programmer’s perspective, the use of audio is very simple: (s)he just has to request to play a sound-file. This is presented in Figure 1.
Figure 1: flow of audio request
As shown in this figure with the full arrows, the application is not even concerned about the communication with the audioServer – it relies on the audio library functions to deal with that. It is then up to this audioServer to ensure that the message arrives at the end-user. While the application uses to the audio-library on the local machine, the audio-server can also be hosted locally, or on a different workstation, or even on an X-terminal (provided the local workstation is an HP-UX host – see further below).
The audio library will determine at run-time where the audio-server is (presumably) running, based on the settings of the AUDIO and/or DISPLAY environment variable settings when the application started.
Remark that a single workstation (HP-UX, Solaris or Linux) can have only one audioServer process running.
2.3 The audioServer application
The audioServer application is an implementation of an audio-server for workstations (i.e. not for HP Envizex or NCD X-terminals). It is implemented in Tcl/Tk and relies on the snack audio extension. It is a server process, listening on a particular TCP/IP port. It reacts on the data it receives, assuming this data is structured according to the conventions of the internal audio protocol. After receiving the audio file, it will send it to the audio hardware of its own local host, by means of snack commands.
As it is based on snack, it can perfectly deal with all the platforms and audio HW for which snack offers support, whereby the particular platforms of our own interest are HP-UX, Solaris, Linux and to some extent MS-Windows.
Remark that in the current implementation there are no access-limitations to audioServer. I.e. hosts that can communicate over the network with the box hosting the audioServer can also play sounds on it - provided the audioServer itself has been started by a user who can read/write from/to the audio devices.
2.4 The audioPlay procedure
This procedure will play a sound-file. Before doing so, it will first of all look at the AUDIO or DISPLAY environment variables to determine the host where the audio-server is supposed to reside. Then it will apply the following strategy trying to determine the nature of the audio-server:
1. Try if there is an audioServer based on the audio module listening on a particular TCP/IP port on the audio-host - see section 2.3. If this fails, it means the host pointed to by AUDIO/DISPLAY does not currently have an active audioServer application, and the next steps are attempted.
2. If the client process is running on HP-UX, try the client application for NCD X-terminals, i.e. check if the audio-host is an NCD X-terminal. If this fails, proceed to the next step.
3. If the client application calling audioPlay is running on HP-UX, try directly the local snack Tcl-extension, which uses the HP proprietary audio library and HP’s audio server (Aserver). This allows sending sounds to either other HP-UX boxes or HP Envizex X-terminals (local or remote according to the AUDIO or DISPLAY environment variables settings).
This determination of the server type takes place the first time a sound file is sent to a particular server. If none of the types fit, subsequent calls to this procedure will only look for an audioServer – hoping the absence of this server will be noted and will be corrected at some point.
Both audioServer and HP’s Aserver can be running on a different host than the local one (where the audioPlay client application executes). But due to the proprietary nature of HP’s audio software library, access to Aserver can only work if the audioPlay client too is running on HP-UX.
For NCD X-terminals, the NCD client software must be installed on the local machine – and this is only available for HP-UX; the AUDIO or DISPLAY variable must of course in this case point to the NCD X-terminal (on top of some other requirements listed in the manpages).
Remark that the check for an HP Aserver will take ~30 seconds if AUDIO/DISPLAY is pointing to an HP box without audio hardware (or with HP’s Aserver not active), due to HP’s audio software library implementation. However, this will only be for the first attempt to play a sound on that server. Subsequent attempts will fail immediately, as only the existence of an active audioServer will be verified - see above.
2.5 The audioPlay utility
The audioPlay utility is a Tcl script – which of course uses internally the audioPlay procedure mentioned above in section 2.4. This utility will play a single sound-file and terminate.
As it relies on the audioPlay procedure, all what has been said about this procedure is also applicable to this utility: the AUDIO or DISPLAY environment variables will determine the host where the audio-server presumably resides, and the same strategy is applied trying to determine the nature of the audio-server.
Remark that the check for an HP server will take ~30 seconds if AUDIO/DISPLAY is pointing to an HP box without audio hardware (or with HP’s Aserver not active). In this case the audioPlay utility will be “hanging” for that amount of time, and finally terminate in silence, after printing an error message to stderr.
2.6 audioVolume
The audioVolume utility is also a Tcl script, allowing to retrieve or to set the volume of the mixer-device. It will get/set the master volume, print out the current setting, and terminate. The master volume usually regulates the volume of the internal loudspeaker(s) of the audio server, and depending on the audio hardware, the line-out volume may or may not be linked to this master volume setting.
Similar to audioPlay, it relies on the audioVolume procedure, i.e. there is a Tcl library procedure of the same name with the same functionality. These procedures and utilities share the library functions to determine e.g. the host where the audio-server presumably resides, and the nature of the audio-server.
2.7 A cookbook recipe for Tcl-applications
What follows is a short set of instructions to use sounds from within a Tcl-application, using the VLT Common SW (release JAN2006 or newer):
1.
Call the audioPlay procedure, which is part of the audio package. In other words, insert code like the following at
the appropriate place(s):
....
# load package audio (typically at start-up)
package require Audio
# import the audio* commands into the local namespace
# if you do not want to prefix them with "::audio::"
###namespace import ::audio::audio*
# if you want to verify if the audio system is OK before
# actually attempting to play a sound, do the following
if {[catch {::audio::audioVerify} msg]} {
error "audio(Server) problem:
$msg"
}
...
# now play the soundfile
if {[catch {::audio::audioPlay $soundFile} msg]} {
error "audio(Server) problem:
$msg"
}
Remark that this assumes the presence of the audio module, i.e. this requires JAN2006 or newer. If you need to produce code that runs under both APR2004 and JAN2006, and if installing the audio module on APR2004 would not be a valid option, check the FAQ in the troubleshooting section.
2. Indicate to which host you want to send audio output by setting the AUDIO environment variable to a hostname or an IP address; if AUDIO is not set, the audioPlay library procedure will take the value of the DISPLAY environment variable. If neither is set, the "localhost" will be taken (i.e. you will then only be able to play sounds on the host where your Tcl-application is running)
3. The next step depends on what type of host this audio-server actually is running on:
a.
If the host selected to play
sounds is an HP-UX, Solaris or Linux box, ensure that on this host the audioServer is running. If it is not,
start it up as follows:
audioServer &
Remark that there can be only one such audioServer per host.
b. If the host selected to play sounds is an MS-Windows box, ensure that it has Tcl installed (this installation requires admin rights; a binary distribution of Tcl for MS-Windows can be obtained from http://www.activestate.com/Products/Download/Download.plex?id=ActiveTcl). Now copy $VLTROOT/bin/audioServer into audioServer.tcl (e.g. on your MS-Windows Desktop), and double click the latter file on your MS-Windows box. Here too there can be only one such audioServer per host.
c. If you want to have sounds on e.g. an HP Envizex terminal, you don't need this audioServer; but sound on X terminals will work only if the application sending sounds is running on HP-UX.
4. Run your Tcl-application.
The above recipe is surely not the only way to do things - there are options, alternatives, and additional tools. See the previous sections and also the manpages of audioPlay(1), audioCtrl(1), audioVerify(1), audioVolume(1) and audioServer(1) in section 5.2.
2.8 The audioCtrl panel
The audioCtrl utility is an auxiliary panel made to control the audio-volume of a sound server. It can do so for any audioServer sound server just as well as local HP sound servers (using the snack Tcl-extension). To determine what kind of audio-server it is dealing with and where this server is hosted, it uses the same library procedures as audioPlay (see section 2.4).
Figure 2: the volume control panel
To communicate with audioServer, it will use the usual TCP/IP port assigned for this purpose. In other words, it is a client-server networked application: the audioCtrl utility does not need to run on the same host as where audioServer is running.
The “Mute” button will effectively change the hardware audio-volume setting to zero, i.e. it is just an alternative to moving the slider to the extreme left; it is not linked to any hardware “mute” function of the audio devices (as these are not accessible to Snack). This implies that native audio-mixer applications will show their volume-slider at 0 when this “Mute” button has been pressed. On the other hand, the effect on the audioCtrl slider position depends on the type of audioServer: for HP sound servers the slider will be moved to the zero position, while for the other cases the slider will not move (thereby allowing to restore the original volume quickly). This difference in behaviour has to do with the availability of internal flags - for details see the FAQ section 4.1. Remark that while muted, moving the audioCtrl slider will have no audible effect. And in the case of HP server hardware, the slider will remain locked at the zero position until the muting has been disabled.
There can in principle be any amount of audioCtrl applications running for the same audio-server – although that would not be very practical for obvious reasons. The actual status of the server is updated via a polling loop. So although setting the volume, or muting, is sent immediately to the sound server, the feedback of the actual server status to audioCtrl may be delayed due to this polling loop. This is of course most obvious if several audioCtrl applications are simultaneously controlling the same audio server, or if the utility/procedure audioPlay is invoked passing it a particular volume setting.
Remark that this application is not intended as a replacement for audio-mixer applications or native volume control applications; audioCtrl should rather be seen as an example on how the volume can be controlled or monitored. The constraints listed above, in particular in the case of multiple instances of this panel, and the potential conflicts with audioPlay or native volume control panels for the “ownership” of the volume-setting and the muting for the mixer-device make it clear that this application can under certain circumstances confuse users. Still, it is very useful if you want e.g. to control the audio-volume of your own HP X-terminal.
2.9 Compatibility matrix
Table 1demonstrates which combinations are possible/supported with the audio software package. Of course, this assumes that on the server side there is the corresponding audio-HW, and the system has been configured such that there are e.g. no permission problems.
|
server client |
HP-UX |
Solaris |
Linux |
MS-Windows |
Envizex |
NCD |
|
HP-UX |
a, b |
a |
a |
a |
b, c |
d |
|
Solaris |
a |
a |
a |
a |
- |
- |
|
Linux |
a |
a |
a |
a |
- |
- |
Table 1:
compatibility of the audio package with various client/server platforms
a. with audioServer running on this server
b. without audioServer, but with HP’s Aserver running on this server
d. without audioServer, but with the NCD client software on the client side
3. CONFIGURATION
If the VLT Common SW has been properly installed on a host which itself is installed according to the Installation Manual (see [RD 01], [RD 02] and [RD 03]), audio is likely to work out of the box – if the audio HW itself has no problems. In any case, below follow a few instructions that may help to customize some settings or diagnose and cure some of the most common issues.
3.1 HP-UX
For audio to work on HP-UX, the Aserver process must be running. This is normally the case if the instructions in the VLT Combined Installation Manual (see [RD 03]) have been followed. On top of that, HP’s audio system is “secured”, i.e. by default only users logged in on the console can access the audio services. To modify this, the asecure command needs to be issued with the proper options.
See also the manpages of aserver(1) and asecure(1).
3.2 Linux
On a standard RedHat or Scientific Linux installation, the ownership and permissions for the sound-devices (/dev/dsp*, /dev/audio*, /dev/midi*, /dev/mixer*, /dev/sequencer, /dev/sound/* and /dev/beep) will be modified when someone logs in/out on the system – see /etc/security/console.perms. Therefore the VLT SW has its own modified version of that file, giving read/write permissions to all users for these sound-devices.
3.3 Solaris
See the audio(7I) manpage.
3.4 The audio module
The audio module as installed by default comes with a number of settings that should permit it to operate out-of-the-box. There are however a number of settings that if needed can be modified, simply by editing the file audio/src/Makefile. They are in particular:
· PORT: the port number used by the audioServer. Defaults to 33962.
· SERVERTYPES: types of audio servers to support. Can be "Snack", "HP" or "NCD", plus any combination (list separated by blanks). Remark that the order in which such list is given determines the sequence of type checking when a particular server is accessed the first time. It is by default set to “Snack NCD HP”.
· NCDPATH: path where the xpsh local client application for NCD X-terminals can be found. Set to /opt/tekxp/bin/hp700.
· POLLPERIOD: for the audioCtrl application, the period for polling the audioServer (units: ms). Currently set to 2000.
4. Troubleshooting
4.1 Frequently Asked Questions
Q1. I have a Tcl- application
that needs to run unmodified both in an APR2004 and a JAN2006 VLT SW
environment. How do I deal with this?
For applications that need backward compatibility with APR2004 (i.e. you do not know in advance if the audio module is available): suppose the original APR2004 of your sound-procedure is in a library file <mod>Sound.tcl and contains
proc <mod>Sound {soundFile} {
....
# Snack commands here
....
# or exec HP-UX send_sound there
...
# or use of the NCD utilities
}
Change this procedure to look as follows:
# Try to find the
"audio" package and load the audioPlay proc. This
# will be executed only the first time the <mod>Sound procedure is
# called, as Tcl's "unknown" procedure will source this file.
catch {package require Audio; auto_load audio::audioPlay}
proc <mod>Sound {soundFile} {
...
if {[string equal [info command
::audio::audioPlay] ::audio::audioPlay]} {
# means the Audio
package was found
if {[catch {::audio::audioPlay $soundFile} msg]} {
error "audio(Server) problem:
$msg"
}
return
}
# If we get here, it means Audio is
not available; must be APR2004
# Snack commands here
....
# or exec HP-UX send_sound there
...
# or use the NCD utilities
}
Q2. I followed all your
instructions to have audioServer running on a Linux box, but yet I do not
manage to play any sounds on that box. What could be wrong?
It is possible that your PC does not have (standard) audio HW, or the audio HW is defect. Verify this by logging in on the console, and use one of the Linux utilities to try to play a sound on the internal loudspeaker(s). If this works, check that the permissions of the sound-devices are OK (see section 3.2). If the file /etc/security/console.perms does not specify the right permissions, it means the VLT installation procedure was not followed to the letter, or there is a problem with this installation procedure. In the latter case, please report the problem to ESO.
Remark that the audioVolume utility regulates only the master volume (or at least, the volume of the sub-device considered by snack to be the master). If you have e.g. an external amplifier and loudspeakers connected via the server’s line-out plug, this volume is possibly not controlled via the master volume.
Q3. I have a short
Tcl-application that uses audioPlay to send sounds to an audio-server.
Sometimes when this application finishes, I get an error and/or the sound
currently playing is interrupted before it gets to the end. How do I prevent
this?
Call the audioFlush procedure before exiting (see section 5.2.2). The point is that audioPlay will just initiate the transfer of the file to the audio-server, and return before the entire audio-file has been transmitted. Your application must be finishing before this transmission is complete. Stopping this data-stream in the middle may of course confuse the audio server. The audioFlush procedure ensures that the currently transmitted audio-file is sent completely, before it returns to the calling level. Remark that this does NOT mean that this audio-file has been played as well – it has merely been received by the server, playing is a different issue.
Q4. If I play 2 sounds within
quick succession, their audio output overlaps. Is this normal?
Yes, it is. Although audioPlay will only transmit one file at a time, the play-back is a different matter, left in the capable hands of the snack software and the audio hardware.
Q5. If I play 2 sounds within
quick succession, only one is played, and this one can be re-played as often as
one wants, while other sound-files do not produce any output from that point
on. Why is this?
There is apparently an issue with Snack 2.2.9, when playing simultaneously sound-streams with different sample rates. When this occurs, the only solution is to stop and re-start the audioServer.
The audioServer software could in principle attempt to avoid this simultaneous play in such cases, provided it is able to know in advance what these individual sample rates are. Unfortunately, Snack itself gives only access to this parameter once a sound is playing (or when it reads the sound-file - which is at the client side, i.e. not accessible by audioServer).
If this needs to be fixed (i.e. working around the Snack problem), the audioServer code will have to be modified to either first store the data-stream into a temporary file, or use another tool (e.g. SndInfo from the Stanford SndLib) to determine the sample rate.
By the way, one can easily determine the sampling rate of a sound-file with the following shell command:
echo
"package require sound; \
puts [lindex [[snack::sound -file
[lindex \$argv 1]] info] 1]; \
exit" | tclsh -- <soundFile>
Remark that
this is best done on a host with working audio-hardware, to avoid that Snack
would throw errors or takes its time to initialize when the sound package is
loaded.
Q6. Why does audioCtrl’s mute-button impact the volume
slider of native sound-mixer panels?
As there is no API available in snack to control or monitor the audio hardware property corresponding to muting, independent from the volume setting, audioCtrl’s mute-button is rather linked to the hardware volume setting. Native mixer panels will usually monitor periodically the current volume setting, and therefore activating the mute-button in audioCtrl will lead the native mixer’s volume setting to go down to zero. This means as well that this muting status is only known and shared between applications using the audio utilities/procedures.
Q7. Why is the behaviour of
audioCtrl’s mute-button different on HP audio hardware?
As there is no API available in snack to control or monitor the audio hardware property corresponding to muting, independent from the volume setting, the separation of these two properties requires the use of flags internal to the audioCtrl and audioServer applications. In the case of audioCtrl controlling directly an HP Aserver (e.g. an HP Envizex X-terminal), there is no central audioServer application to administers these flags. For that reason, the only way audioCtrl can in such case truthfully represent the actual status when the mute-button is pressed is by moving the volume-slider to the zero position.
If this is disturbing, one can of course use a more indirect path, i.e. passing over an audioServer to address the HP Aserver.
5. Reference
5.1 Error messages
5.2
Manpages
5.2.1 audioCtrl
NAME
audioCtrl - control the volume of a sound server
SYNOPSIS
audioCtrl ?-server <hostname>?
DESCRIPTION
audioCtrl will start up a panel made to control an audio
server. It
can do so for any audioServer just as well as any HP Aserver.
To
communicate with audioServer, it will use the TCP/IP port
as set in a
macro defined in the Makefile of the audio module.
To determine where the audio server is located, the AUDIO
or DISPLAY
environment variable settings are used, as explained in
the section
ENVIRONMENT below, unless the option -server
<hostname> is specified.
There can be any amount of audioCtrl applications running
for the same
audio server. The actual status of the server is updated
via a polling
loop, with period as defined in the Makefile.
ENVIRONMENT
The environment variable AUDIO is used to determine the
hostname of the
audio-server. It can be set to a hostname or IP address.
If AUDIO is not
set, the environment variable DISPLAY will be used (i.e.
the value up to
the colon). If neither is set, it is assumed that the
audio-server runs
on the localhost. This algorithm can be overridden by
specifying
explicitly the option -server <hostname>.
CAUTIONS
Setting the volume, or muting, is sent immediately to the
sound server.
The feedback of the actual server settings to audioCtrl
however may be
delayed by the polling loop. This is of course most
obvious if several
audioCtrl applications are simultaneously controlling the
same audio
server, or if the utility/procedure audioPlay is invoked
passing it a
particular volume setting.
SEE ALSO
audioServer(1), audioPlay(n),
The Snack Sound Toolkit (http://www.speech.kth.se/snack/)
### generated by docDeroff ###
5.2.2 audioFlush
NAME
audioFlush - flush the sounds currently being sent
SYNOPSIS
audioFlush
DESCRIPTION
This procedure will wait till the sending of any
audio-file initiated
previously via an audioPlay call is completed. This
guarantees that the
corresponding sound server will deal with the full
audio-file.
This is useful if you need to ensure that the sound is
being played before
you proceed, or also if you want to exit your application
without
interrupting the sounds being played.
RETURN VALUES
None.
SEE ALSO
audioPlay(n)
### generated by docDeroff ###
5.2.3 audioPlay
NAME
audioPlay - play a soundfile
SYNOPSIS
audioPlay ?-volume <volume>? <soundFile>
DESCRIPTION
audioPlay will play a <soundFile>. If the -volume
option is specified,
the gain will first be adjusted to <volume> (on a
scale from 0 to 100); in
the latter case (option -volume specified) the
audio-server will also
be un-muted if it was muted; after playing the
<soundFile>, the volume will
be set back to its original setting.
The supported formats of <soundFile> are of course
determined by
the sound server. For the Snack-based server this is WAV,
AU, AIFF, MP3,
CSL, SND, SD, SMP, RAW and NIST/Sphere. For the HP
audio-server, this is
AU, SND, WAV and RAW.
The list of supported servers is given by the macro
SUPPORT, which is
set in the Makefile. It can be any list of the words
Snack, HP and
NCD. Apart from specifying which audio-servers are
supported, it also
sets the order in which they will be tested in case a
sound is sent to
a not yet known audio-server.
The following strategy is applied trying to determine the
nature of the
various types of sound servers:
1. First, the host of the server is given by the
AUDIO/DISPLAY
environment
variable (see below).
2. For Snack, try to connect to an audioServer. These
servers are
listening on a
particular TCP/IP port, as defined by the macro PORT.
If this fails,
the audioServer is not (anymore) active.
3. For NCD, and if the client process is running on
HP-UX, try the
local client
application for NCD X-terminals. The path to this client
program is given
in the Makefile by the variable NCDPATH.
4. For HP, and if the client process is running on HP-UX,
try directly
the local snack
Tcl-extension, which uses the HP audio library.
This determination of the server type takes place the
first time a sound
file is sent to a particular server. If none of the types
fit, subsequent
calls to this procedure will only look for an
audioServer.
Remark that the check for an HP server will take ~30
seconds if
AUDIO/DISPLAY is pointing to an HP box without audio
hardware (or with
the Aserver not active). However, if audioPlay is used as
a procedure,
this will only be for the first attempt to play a sound
on that server.
Subsequent attempts will fail immediately, as only the
existence of an
active audioServer will be verified - see above.
ENVIRONMENT
The environment variable AUDIO is used to determine the
hostname of the
audio-server. It can be set to a hostname or IP address.
If AUDIO is not
set, the environment variable DISPLAY will be used (i.e.
the value up to
the colon). If neither is set, it is assumed that the
audio-server runs
on the localhost.
RETURN VALUES
In case of success, the audio-server type is returned. It
can take the
value of Snack, HP or NCD, depending also on the set of
supported
devices audioPlay has been configured for via the
Makefile.
CAUTIONS
Use of audio on NCD terminals requires that the sound
files are on a
directory which the terminal can NFS-mount. On top of
that, the NCD
software must on the HP-UX box be installed under a
particular directory,
as defined in the module's Makefile. If this is not the
case, there will
be no audio played on the NCD terminal.
Both audioServer and HP's Aserver can be running on a
different host than
where the audioPlay client runs. But due to the
proprietary nature of HP's
audio software library, the use of HP's Aserver can only
work if the
audioPlay client too is running on HP-UX. For NCD
X-terminals, the NCD
client software must be installed on the local machine -
and this is only
available for HP-UX; the AUDIO or DISPLAY variable must
of course in this
case point to the NCD X-terminal (on top of the other
requirements listed
above).
EXAMPLES
You have the choice between giving the fully qualified
commandname (i.e.
including its namespace) or importing it into your
current namespace.
For that reason, the following 2 examples are equivalent:
...
tcl>package require Audio
...
tcl>namespace import audio::*
tcl>audioPlay -volume 92 $env(VLTROOT)/sounds/flush.au
Snack
tcl>
...
tcl>package require Audio
...
tcl>audio::audioPlay -volume 92
$env(VLTROOT)/sounds/flush.au
Snack
tcl>
SEE ALSO
audioServer(1), audioCtrl(1),
The Snack Sound Toolkit (http://www.speech.kth.se/snack/)
### generated by docDeroff ###
5.2.4 audioServer
NAME
audioServer - start up a Snack-based sound server
SYNOPSIS
audioServer
DESCRIPTION
audioServer will start up a server process, listening on
a particular
TCP/IP port (as set in a macro defined in the Makefile of
the audio
module). It will react on the following commands coming
in via this port:
- play: play a sound-stream
- fply: forced play, i.e. override the mute setting
- stop: stop the sound-stream
- setv: set the volume to a value (on a scale from 0 to
100)
- getv: return the current actual audio-gain and the set
volume (they
can be
different, e.g. if the "mute" command is active)
- mute: mute the sound; remark that the procedure/utility
audioPlay can
override this
setting, by passing explicitly a volume level.
- voce: opposite to mute
- exit: close the port and quit.
- vers: return the versionr; format: "audioServer
$Revision: 1.11 $"
CAUTIONS
In the current implementation there are no access
limitations to
audioServer, i.e. hosts that can communicate over the
network with the
box hosting the audioServer can also play sounds on it -
provided the
audioServer itself has been started by a user who can
read/write from/to
the audio devices.
SEE ALSO
audioPlay(n), audioCtrl(1),
The Snack Sound Toolkit (http://www.speech.kth.se/snack/)
### generated by docDeroff ###
5.2.5 audioVerify
NAME
audioVerify - verify the audio system
SYNOPSIS
audioVerify
DESCRIPTION
audioVerify will check the audio-server. The list of
supported servers is
given by the macro SUPPORT, which is set in the Makefile.
It can be any
list of the words Snack, HP and NCD. Apart from
specifying which
audio-servers are supported, it also sets the order in
which they will be
tested.
The following strategy is applied trying to determine the
nature of the
various types of sound servers:
1. First, the host of the server is given by the
AUDIO/DISPLAY
environment
variable (see below).
2. For type Snack, try to connect to an audioServer.
These servers are
listening on a
particular TCP/IP port, as defined by the macro PORT.
If this fails,
the audioServer is not (anymore) active.
3. For NCD, and if the client process is running on
HP-UX, try the
local client
application for NCD X-terminals. The path to this client
program is given
in the Makefile by the variable NCDPATH.
4. For HP, and if the client process is running on HP-UX,
try directly
the local snack
Tcl-extension, which uses the HP audio library.
This determination of the server type takes place the
first time a sound
file is sent to a particular server, or the first time
this procedure is
called. If none of the types fit, subsequent calls to
audioPlay or this
procedure will only look for an audioServer.
Remark that the check for an HP server will take ~30
seconds if
AUDIO/DISPLAY is pointing to an HP box without audio
hardware (or with
the Aserver not active). However, if audioVerify is used
as a procedure,
this will only be for the first attempt to play a sound
on that server.
Subsequent attempts will fail immediately, as only the
existence of an
active audioServer will be verified - see above.
ENVIRONMENT
The environment variable AUDIO is used to determine the
hostname of the
audio-server. It can be set to a hostname or IP address.
If AUDIO is not
set, the environment variable DISPLAY will be used (i.e.
the value up to
the colon). If neither is set, it is assumed that the
audio-server runs
on the localhost.
RETURN VALUES
In case of success, the audio-server type is returned. It
can take the
value of Snack, HP or NCD, depending also on the set of
supported
devices audioVerify has been configured for via the
Makefile.
CAUTIONS
Use of audio on NCD terminals requires that the sound
files are on a
directory which the terminal can NFS-mount. On top of
that, the NCD
software must on the HP-UX box be installed under a
particular directory,
as defined in the module's Makefile. If this is not the
case, there will
be no audio played on the NCD terminal.
Both audioServer and HP's Aserver can be running on a
different host than
where the audioVerify client runs. But due to the
proprietary nature of HP's
audio software library, the use of HP's Aserver can only
work if the
audioVerify client too is running on HP-UX. For NCD
X-terminals, the NCD
client software must be installed on the local machine -
and this is only
available for HP-UX; the AUDIO or DISPLAY variable must
of course in this
case point to the NCD X-terminal (on top of the other
requirements listed
above).
EXAMPLES
You have the choice between giving the fully qualified
commandname (i.e.
including its namespace) or importing it into your
current namespace.
For that reason, the following 2 examples are equivalent:
...
tcl>package require Audio
...
tcl>namespace import audio::*
tcl>audioVerify
Snack
tcl>
...
tcl>package require Audio
...
tcl>audio::audioVerify
Snack
tcl>
SEE ALSO
audioServer(1), audioCtrl(1), audioPlay(1)
The Snack Sound Toolkit (http://www.speech.kth.se/snack/)
### generated by docDeroff ###
5.2.6 audioVolume
NAME
audioVolume - get or set the audio volume
SYNOPSIS
audioVolume ?<volume>?
DESCRIPTION
audioVolume without further arguments will return the
current setting of
the audio-gain, on a scale from 0 to 100.
If <volume> is given, on a scale from 0 to 100, the
audio-gain will be set
to <volume>; if the audio-server was muted, muting
will be turned off.
The strategy trying to determine the type of the sound
server is the one
implemented in the audioVerify procedure.
ENVIRONMENT
The environment variables AUDIO or DISPLAY will be used
to determine
the hostname of the audio-server. See the manpage of
audioVerify.
RETURN VALUES
In case of success, the volume is returned.
CAUTIONS
NCD terminals are not really supported by this
procedure/utility. Getting
the volume will always return 100, setting it will have
no effect.
In the case of HP's Aserver, the volume returned will be
0 if the server
is muted, even if the audioCtrl application shows that
the gain is
not 0. This is because for HP's Aserver there is no way
to distinguish
between a gain of 0 and muting. In an attempt to keep
these two things
apart, setting the <volume> to 0 on such server
will actually set it to 1.
For Snack-based audio-servers, the audio-gain and muting
are two separate
issues.
EXAMPLES
You have the choice between giving the fully qualified
commandname (i.e.
including its namespace) or importing it into your
current namespace.
For that reason, the following 2 examples are equivalent:
...
tcl>package require Audio
...
tcl>namespace import audio::*
tcl>audioVolume
92
tcl>
...
tcl>package require Audio
...
tcl>audio::audioVolume 85
85
tcl>
SEE ALSO
audioServer(1), audioCtrl(1), audioVerify(n),
The Snack Sound Toolkit (http://www.speech.kth.se/snack/)
### generated by docDeroff ###