YIntro - introduction to YLib

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.

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(1); /* Don't hog cpu. */

}

/* Close the connection, note that con may already

* be NULL (but YCloseConnection double checks

* that).

*/

YCloseConnection(con, False);

return(0);

}

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

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.

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)