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
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
|
/*
Copyright (C) 2000 Stefan Westerfeld
stefan@space.twc.de
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Library General Public License
along with this library; see the file COPYING.LIB. If not, write to
the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301, USA.
*/
#ifndef ARTSC_H
#define ARTSC_H
#include "artsc_export.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @libdoc aRts plain C API
*
* The aRts plain C API aims at easily writing/porting plain C apps to the
* arts sound server. What is provided is streaming functionality, in a
* blocking way. So for most apps, you simply remove the few system calls
* that deal with your audio device, and replace them with the appropriate
* arts calls.
*/
/**
* the type of streams (simply treat these as black boxes)
*/
typedef void *arts_stream_t;
/* error codes */
#define ARTS_E_NOSERVER ( -1 )
#define ARTS_E_NOBACKEND ( -2 )
#define ARTS_E_NOSTREAM ( -3 )
#define ARTS_E_NOINIT ( -4 )
#define ARTS_E_NOIMPL ( -5 )
/**
* the values for stream parameters
*
* @see arts_parameter_t
*/
enum arts_parameter_t_enum {
ARTS_P_BUFFER_SIZE = 1,
ARTS_P_BUFFER_TIME = 2,
ARTS_P_BUFFER_SPACE = 3,
ARTS_P_SERVER_LATENCY = 4,
ARTS_P_TOTAL_LATENCY = 5,
ARTS_P_BLOCKING = 6,
ARTS_P_PACKET_SIZE = 7,
ARTS_P_PACKET_COUNT = 8,
ARTS_P_PACKET_SETTINGS = 9
};
/**
* parameters for streams
*
* @li ARTS_P_BUFFER_SIZE (rw)
* The size of the internal buffers used for streaming to the server - this
* directly affects the latency that will occur. If you never set it
* explicitly, this value defaults to at least 65536 (64kb). Generally,
* it is important to know that the server itself gives some constraints
* which makes buffer sizes below a certain value impossible. So setting
* this parameter will always result in either getting what you wanted,
* or a larger streaming buffer due to server limitations.
*
* @li ARTS_P_BUFFER_TIME (rw)
* The time the buffer used for streaming to the server takes to play in
* milliseconds. This is just a more human readable method to set the buffer
* size, so setting ARTS_P_BUFFER_SIZE affects this parameter and the other
* way round. As aRts chooses reasonable buffer sizes for streaming (rather
* 3*16kb than 40234 bytes), setting this parameter will often end up with
* a slightly larger value than you requested.
*
* @li ARTS_P_BUFFER_SPACE (r)
* The amount of bytes that can be read/written without blocking (depending
* whether this is a record or play stream). As requesting this parameter
* does a few system calls (but no remote invocation) to verify that it is
* up-to-date, don't overuse it.
*
* @li ARTS_P_SERVER_LATENCY (r)
* The amount of latency the server creates (due to hardware buffering)
* in milliseconds.
*
* @li ARTS_P_TOTAL_LATENCY (r)
* The overall latency in milliseconds it takes (at most), from the time
* when you write a byte into a stream, until it gets played on the
* soundcard. This is simply a shortcut to the sum of ARTS_P_BUFFER_TIME
* and ARTS_P_SERVER_LATENCY.
*
* @li ARTS_P_BLOCKING (rw)
* If this parameter is 1 (the default), arts_read/arts_write will block
* when not all data can be read/written successfully, and wait until it
* works. If this parameter is 0, arts_read/arts_write will return
* the number of successfully read/written bytes immediately.
*
* @li ARTS_P_PACKET_SIZE (r)
* This returns the size of the packets used for buffering. The optimal
* size for arts_stream_write is always writing one packet. The buffering of
* streams works with audio packets. So the ARTS_P_BUFFER_SIZE parameter of
* streams (which specifies how many bytes of a stream are prebuffered),
* really consists of (ARTS_P_PACKET_SIZE) * (ARTS_P_PACKET_COUNT).
*
* @li ARTS_P_PACKET_COUNT (r)
* This returns the number of the packets are used for buffering. See
* ARTS_P_PACKET_SIZE for more.
*
* @li ARTS_P_PACKET_SETTINGS (rw)
* This is a way to configure packet size & packet count at the same time.
* The format is 0xCCCCSSSS, where 2^SSSS is the packet size, and CCCC is
* the packet count. Note that when writing this, you don't necessarily
* get the settings you requested.
*/
typedef enum arts_parameter_t_enum arts_parameter_t;
/**
* initializes the aRts C API, and connects to the sound server
*
* @return 0 if everything is all right, an error code otherwise
*/
ARTSC_EXPORT int arts_init(void);
/**
* disconnects from the sound server and frees the aRts C API internals
*/
ARTSC_EXPORT void arts_free(void);
/**
* asks aRtsd to free the DSP device and return 1 if it was successful,
* 0 if there were active non-suspendable modules
*/
ARTSC_EXPORT int arts_suspend(void);
/**
* asks aRtsd if the DSP device is free and return 1 if it is,
* 0 if not
*/
ARTSC_EXPORT int arts_suspended(void);
/**
* converts an error code to a human readable error message
*
* @param errorcode the errorcode (from another arts function that failed)
* @returns a text string with the error message
*/
ARTSC_EXPORT const char *arts_error_text(int errorcode);
/**
* open a stream for playing
*
* @param rate the sampling rate (something like 44100)
* @param bits how many bits each sample has (8 or 16)
* @param channels how many channels, 1 is mono, 2 is stereo
* @param name the name of the stream (these will be used so that the user can
* assign streams to effects/mixer channels and similar)
*
* @return a stream
*/
ARTSC_EXPORT arts_stream_t arts_play_stream(int rate, int bits, int channels, const char *name);
/**
* open a stream for recording
*
* @param rate the sampling rate (something like 44100)
* @param bits how many bits each sample has (8 or 16)
* @param channels how many channels, 1 is mono, 2 is stereo
* @param name the name of the stream (these will be used so that the user can
* assign streams to effects/mixer channels and similar)
*
* @return a stream
*/
ARTSC_EXPORT arts_stream_t arts_record_stream(int rate, int bits, int channels, const char *name);
/**
* close a stream
*/
ARTSC_EXPORT void arts_close_stream(arts_stream_t stream);
/**
* read samples from stream
*
* @param stream a previously opened record stream
* @param buffer a buffer with sample data
* @param count the number of bytes contained in the buffer
*
* @returns number of read bytes on success or error code
*/
ARTSC_EXPORT int arts_read(arts_stream_t stream, void *buffer, int count);
/**
* write samples to to stream
*
* @param stream a previously opened play stream
* @param buffer a buffer with sample data
* @param count the number of bytes contained in the buffer
*
* @returns number of written bytes on success or error code
*/
ARTSC_EXPORT int arts_write(arts_stream_t stream, const void *buffer, int count);
/**
* configure a parameter of a stream
*
* @param stream an opened record or play stream
* @param parameter the parameter you want to modify
* @param value the new value
*
* @returns the new value of the parameter (which may or may not be the value
* you wanted to have), or an error code if something went wrong
*/
ARTSC_EXPORT int arts_stream_set(arts_stream_t stream, arts_parameter_t param, int value);
/**
* query a parameter of a stream
*
* @param stream an opened record or play stream
* @param parameter the parameter you want to query
*
* @returns the value of the parameter, or an error code
*/
ARTSC_EXPORT int arts_stream_get(arts_stream_t stream, arts_parameter_t param);
#ifdef __cplusplus
}
#endif
#endif /* ARTSC_H */
|
