AuCreatePlay(3X) — Series 700 Only

NAME

AuCreatePlay − create an audio play widget

SYNOPSIS

#include <audio/Play.h>

extern Widget AuCreatePlay(

Widget parent,

String *name,

ArgList *arglist,

Cardinal argcount

);

DESCRIPTION

AuCreatePlay() creates a play widget.

If you use the streams facility, the toolkit creates a file descriptor in connectFd during AuInvokePlay(). After calling AuInvokePlay(), retrieve the file descriptor by calling XtSetArg(args[0], AuNconnectFd, &stream_fd); and then call XtGetValue(playWidget,args,1);. Then, use the select(), read(), and write() system calls.

Call AStopAudio() to stop the transaction. A callback routine for AuNStopped can close() the file descriptor.

Note that for a play streams operation to work, a callback routine for AuNdataNeeded must be added using AtAddCallback().

To enable an application to use a widget after it is created, bind the widget library with the application as follows:

ld my_file.o... -lAt -lAlib

Arguments

parent Name of the parent widget

name Name for this widget

arglist The argument list for the widget

argcount The number of arguments in arglist.

arglist can contain the following:

gain Volume, in percent of total gain. Acceptable values are from 0 to 100. Default is system dependent.

fileFormat Audio file format. Acceptable values are:

AuFAlaw AuFLinear8Offset AuFSun
AuFMulaw AuFLinear16 AuFUnknown
AuFLinear8 AuFRiff

Default is AuFUnknown.

dataFormat Audio data format. Acceptable values are:

AuDMulaw AuDLinear16 AuDLinear8Offset
AuDAlaw AuDLinear8 AuDUnknown

Default is AuDUnknown.

durationType Duration units. Acceptable values are:

AuSamples AuFullLength AuMilliseconds

Default is AuFullLength.

duration Number of units to play. Acceptable values are -1 to MAX_INT. Default is ~0 (-1, play until notified).

fileName Name of the file to play (must be set prior to invocation of the play widget). There is no default value.

startTimeType Type of start time unit. Acceptable values are AuSamples and AuMilliseconds. Default is AuMilliseconds.

startTime Number of units into the file to begin recording. Acceptable values are 0 to MAX_INT. Default value is 0 (BOF).

pause Start in paused state. Acceptable values are ON or OFF. Default is OFF.

stop Stop mode. Acceptable values are:

AuStopLinkTrans AuStopEndLoopTrans
AuStopThisTrans AuStopNone

Default is AuStopNone.

audioConnection Pointer to Audio structure for this connection, returned by AOpenAudio(). Specifying a valid pointer for this argument is mandatory; the default value is NULL, which causes the program to fail.

streamOrFile Source of audio data. Acceptable values are AuStream or AuFile. Default is AuFile.

SStream Pointer to SStream structure for this AuStream-type widget. Specifying a valid pointer for this argument is mandatory; the default value is NULL, which causes the program to fail.

connectFd File descriptor of the non-blocking connection made for the stream by the toolkit; created during AuInvokeRecord().

reserved

speaker Speaker choice. Acceptable values are AuInternal or AuExternal. Default is AuInternal.

link name of another play widget; when link is finished playing, the current widget starts immediately and automatically. Default is NULL.

The link feature enables two or more play widgets to be linked into a continuous play operation. Follow these steps to link two or more widets:

1. Create widget A with pause ON and with NULL specified in link.

2. Create widget B with pause ON and with A’s name specified in link.

3. Repeat step 2 for as many widgets as you want in the chain (creating C with B’s name in link, and so on).

4. Invoke widget A.

loopCount Number of times to play this widget. Acceptable values are -1 to MAX_INT. Default is 0. Note that a value of -1 specifies an infinite loop.

priority Priority level of play request. Acceptable values are:

AuUrgent AuNormal AuHigh AuLow

Default is AuNormal.

channels Number of channels. Acceptable values are 1 or 2. Default is 1.

samplingRate Number of cycles per second. Most Series 700 systems support the following values:

5512 11025 22050 44100
8000 16000 32000 48000

Default is 8000.

To double-check the values that your system supports, use ASamplingRates().

Values between 0.995 and 1.0125 times any of the supported values are handled at the supported rate. Rates outside these tolerances are converted by sound bucket transactions to the nearest supported rate but cause streams transactions to fail and return AEBadSamplingRate.

leftChannel Gain, in %. Acceptable values are 1 through 100. Default is system dependent.

rightChannel Gain, in %. Acceptable values are 1 through 100. Default is system dependent.

RETURN VALUE

Upon successful completion, AuCreatePlay() returns the widget ID.

ERRORS

AuCreatePlay() does not return an error status.

DEPENDENCIES

This function belongs to the Audio Application Program Interface widget library. The audio server must run on a system that has audio hardware. To find out whether or not your system has audio hardware, refer to the hardware manual that accompanies your system.

AUTHOR

AuCreatePlay() was developed by HP.

Museum

Related Articles