1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
API
The libao API makes a distinction between drivers and devices. A
driver is a set of functions that allow audio to be played on a
particular platform (i.e. Solaris, ESD, etc.). A device is a
particular output target that uses a driver. For example, on my
system, I use the OSS driver to play to the /dev/dsp device.
Using the libao API is fairly simple. Your program should go like
this:
* Include the <ao/ao.h> header into your program.
* Call ao_initialize() to initialize the library.
* Call ao_get_driver_id() with a string corresponding to the short
name of the device (i.e. "oss", "wav", etc.).
* Create an option list pointer of type (ao_option_t *) and
initialize it to NULL.
* Through successive calls to ao_append_option(), add any driver
specific options you need. Note that the options take the
form of key-value pairs where supported keys are listed in the
DRIVER file.
* Call ao_open() and save the returned device pointer.
* Call ao_play() to output each block of audio.
* Call ao_close() to close the device. Note that this will
automatically free the memory that was allocated for the device.
Do not attempt to free the device pointer yourself
* Call ao_shutdown() to close the library.
FUNCTIONS
Before reading the function descriptions below, you should read
through the <ao/ao.h> header file and see the data structures used.
---
void ao_initialize(void)
Purpose: initialize the library.
Parameters: none.
---
void ao_shutdown(void)
Purpose: shuts down the library.
Parameters: none.
---
int ao_get_driver_id(const char *short_name)
Purpose: Get the id number for a particular driver.
Parameters:
const char* short_name - The short name of the driver
Returns: The driver id number or -1 if the driver does not exist.
---
ao_info_t *ao_get_driver_info(int driver_id)
Parameters:
int driver_id - The number returned from ao_get_driver_id(). Or one
of the standard drivers.
Purpose: To get the ao_info_t structure that describes this driver.
Returns: A pointer to the info structure. Do not modify this
structure.
---
int ao_append_option(ao_option_t **options, const char *key, const char *value)
Purpose: Append an option to a linked list of options.
Parameters:
ao_option_t **options - Address of a pointer to the head of the
option list, which may be NULL.
const char* key - The option key
const char* value - the setting for this particular option
Returns: 1 if the option was appended successfully
0 if the option was not appended (either due to memory
allocation failure or incorrect option format)
---
void ao_free_options(ao_option_t *options)
Purpose: Free all of the memory allocated to an option list, including
the key and value strings.
Parameters:
ao_option_t *options - A pointer to the option list.
---
ao_device_t* ao_open(int driver_id, uint_32 bits, uint_32 rate,
uint_32 channels, ao_option_t *options)
Purpose: To open a particular device for writing.
Parameters:
int driver_id - ID number for the driver to use with this device
uint_32 bits - Bits per audio sample (8 or 16)
uint_32 rate - Samples per second (44100, 22050, etc.)
uint_32 channels - Audio channels (1 = mono, 2 = stereo)
ao_option_t *options - Option list
Returns: Pointer to internal data used for this device. Must be used
in later calls to ao_play() or ao_close(). NULL is returned if the
device cannot be opened.
---
void ao_play(ao_device_t *device, void* output_samples,
uint_32 num_bytes)
Purpose: To ouput some audio data to the device.
Parameters:
ao_device_t *device - Device pointer
void *output_samples - Memory buffer containing audio data
uint_32 num_bytes - Number of bytes of audio data in memory buffer
---
void ao_close(ao_device_t *device)
Purpose: To close the audio device and free device memory. [Do not free
device memory yourself!]
Parameters
ao_device_t *device - Device pointer
|
