NAME
YIntro - introduction to YLib
OVERVIEW
YLib is a function interface library for the Y sound system, which
enables multiple client and network transparent sound support.
To determine if your machine supports YLib, check for the existance of
libY2.* in the expected library locations on your machine. Typical
locations are /usr/lib/libY2.* or /usr/local/lib/libY2.*.
An application that supports Y sound system implmentations and uses
YLib is called a Y client application. All Y client applications will
connect to the Y server using the YLib function YOpenConnection. While
running and connected to the Y server, the Y client application will
call YGetNextEvent to manage the YLib internal resources and handle
YEvents. Lastly when the Y client no longer needs to use of the Y
server, it will call YCloseConnection (and in some rare cases,
YShutdownServer) to disconnect from the Y server.
EXAMPLES
Below is an example to create a Y client application, have it connect
to the Y server and play a sound file. Once the sound is done playing,
the Y client application will close the connection to the Y server.
#include <stdio.h>
#include <unistd.h>
#include <Y2/Y.h>
#include <Y2/Ylib.h>
int main(int argc, char *argv[])
{
YID yid;
YEvent event;
YConnection *con = YOpenConnection(
"/usr/sbin/starty",
"127.0.0.1:9433"
);
if(con == NULL)
return(1);
/* Start playing a sound file, make sure that
* you have the Y server set to the proper
* Audio values.
*/
yid = YStartPlaySoundObjectSimple(
con, "/usr/share/sounds/info.wav"
);
if(yid == YIDNULL)
{
/* Could not play sound file. */
YCloseConnection(con, False);
return(1);
}
/* Enter main program while() loop, keep running
* untill connection is marked NULL.
*/
while(con != NULL)
{
/* Get next event if any, no block. */
if(YGetNextEvent(con, &event, False) <= 0)
continue;
switch(event.type)
{
case YSoundObjectKill:
/* Our sound object
* finished playing?
*/
if(event.kill.yid == yid)
{
yid = YIDNULL;
/* Close connection and set
* con = NULL so while() loop
* will break.
*/
YCloseConnection(con, False);
con = NULL;
}
break;
case YDisconnect:
case YShutdown:
/* Server disconnected or went
* down, must close connection.
*/
YCloseConnection(con, False);
con = NULL;
break;
}
usleep(1000); /* Don’t hog cpu. */
}
/* Close the connection, note that con may already
* be NULL (but YCloseConnection double checks
* that).
*/
YCloseConnection(con, False);
return(0);
}
COMPILING
To compile a Y client application source file, you need to link it to
libY2. Typically a C compiler command to achieve this would be as
follows:
cc myprog.c -o myprog -lY2
If you have libY2 installed in a directory that is not searched through
by your linker and not defined in the environment variable
LD_LIBRARY_PATH, then you may need to specify the -L argument. For
example:
cc myprog.c -o myprog -lY2 -L/usr/nonstandard/lib
NOTES
Make sure that you specify the absolute path to a sound file that
exists on the computer that the Y server is running on. If you specify
a relative path then the location of the sound object will be searched
through the Y server’s internal list of sound paths.
If the sound came out garbled or distorted, then the Audio values on
the Y server were probably not set properly prior to running the
example program.
If you want your Y client application to modify the Audio mode values
then you may want to take a look at the source for the command line
program yplay which comes with most YIFF sound server distributions.
Generally modification of the Audio mode is discuraged as it may
interrupt other Y client applications.
SEE ALSO
YOpenConnection(3) YCloseConnection(3) YStartPlaySoundObjectSimple(3)
YStartPlaySoundObject(3) YGetNextEvent(3) YEvent(3) YGetAudioModes(3)
YChangeAudioModePreset(3) YGetAudioStats(3) YSetCycle(3)
YCalculateCycle(3) YGetServerStats(3) YSHMOpenSound(3)
YSHMCloseSound(3) YGetAudioCDTracks(3) YPlayAudioCDTrack(3)
YStopAudioCD(3)