1 | .\" RoarAudio |
---|
2 | .TH "roartut" "7" "November 2010" "RoarAudio" "System Manager's Manual: RoarAuido" |
---|
3 | |
---|
4 | .SH NAME |
---|
5 | roartut \- RoarAudio sound library developer tutorial |
---|
6 | |
---|
7 | .\".SH SYNOPSIS |
---|
8 | |
---|
9 | .\" #include <roaraudio.h> |
---|
10 | |
---|
11 | .SH "DESCRIPTION" |
---|
12 | This tutorial descipes some basics with working with libroar. We will create a simple application |
---|
13 | that can play a file and one that can play some sines. |
---|
14 | A lot of other examples can be found in RoarAudio's sources in the roarclients directory. |
---|
15 | |
---|
16 | This tutorial will cover some basics of the so called VS API. |
---|
17 | The VS API is a abstract layer ontop of the normal API. It is designed to be simple |
---|
18 | yet powerful. The VS API is all you need for most applications. If you need |
---|
19 | more control over what you do you must use the normal. If you need only |
---|
20 | a little of those extra power you can mix VS API and normal API. |
---|
21 | |
---|
22 | .SH "PLAYING A FILE" |
---|
23 | Playing back a file is a easy task with libroar. The VS API has some special support to play |
---|
24 | back files in a very simple way. This is shown here. |
---|
25 | |
---|
26 | First of all we need to include the needed header files: |
---|
27 | #include <roaraudio.h> /* libroar */ |
---|
28 | |
---|
29 | This main header already includes all we need to use the VS API. |
---|
30 | |
---|
31 | Now we can start our main(). We need to declare a object for the |
---|
32 | VS API as it is object oriented. This object is used to interact with the server |
---|
33 | and send all audio data to it: |
---|
34 | roar_vs_t * vss; |
---|
35 | int err; /* see later */ |
---|
36 | |
---|
37 | Next we need to open the connection to the server. The most simple function |
---|
38 | to do this is \fBroar_vs_new_from_file\fR(3) if we are going to play a file. |
---|
39 | It takes the folloing arguments: |
---|
40 | .TP |
---|
41 | \fBserver address\fR |
---|
42 | This is the address of the server. In general case This should be set to NULL. |
---|
43 | |
---|
44 | .TP |
---|
45 | \fBprogram name\fR |
---|
46 | This is the name of our program. This should be set to some name the user |
---|
47 | will recognize like "some App", "some Game". It \fBshould not\fR contain the filename |
---|
48 | of the process like "/usr/bin/someapp.bin". |
---|
49 | |
---|
50 | .TP |
---|
51 | \fBfile name\fR |
---|
52 | This is the name of the file we want to play. In fact this is a URL. |
---|
53 | VS API uses so called DSTR API to open files. DSTR API supports local files as well as |
---|
54 | for example HTTP. Examples include: "somefile.ogg", "file:///data/bla.wav", |
---|
55 | "http://radiostation.org:8000/bla.ogg". |
---|
56 | |
---|
57 | .TP |
---|
58 | \fBerror var\fR |
---|
59 | This is a pointer to a int used to store the error value in case of error. |
---|
60 | This can be set to NULL but should not. The function \fBroar_vs_strerr\fR(3) |
---|
61 | can be used to get a lion readable string of the error. |
---|
62 | |
---|
63 | .P |
---|
64 | Our call to \fBroar_vs_new_from_file\fR(3) will look like this: |
---|
65 | vss = roar_vs_new_from_file(NULL, "some App", "somefile.ogg", &err); |
---|
66 | if ( vss == NULL ) { |
---|
67 | roar_vio_printf(roar_stderr, "Error: Can not connect to server: %s\n", roar_vs_strerr(err)); |
---|
68 | return 1; |
---|
69 | } |
---|
70 | |
---|
71 | Next we need to continuously feed in the data so the server can do the playback. |
---|
72 | Again most simple way is to use \fBroar_vs_run\fR(3). |
---|
73 | |
---|
74 | if ( roar_vs_run(vss, &err) == \-1 ) { |
---|
75 | roar_vio_printf(roar_stderr, "Error: can not loop: %s\n", roar_vs_strerr(err)); |
---|
76 | } |
---|
77 | |
---|
78 | This will block untill all of the file is played. |
---|
79 | |
---|
80 | After it returned must close the VS object. This should be done directly |
---|
81 | after \fBroar_vs_run\fR(3) returned. This is done this way: |
---|
82 | if ( roar_vs_close(vss, ROAR_VS_FALSE, &err) == \-1 ) { |
---|
83 | roar_vio_printf(roar_stderr, "Error: Can not close connection to server: %s\n", roar_vs_strerr(err)); |
---|
84 | return 1; |
---|
85 | } |
---|
86 | |
---|
87 | After adding some standard main() construct we should have something like this: |
---|
88 | //vsfile.c: |
---|
89 | |
---|
90 | #include <roaraudio.h> |
---|
91 | |
---|
92 | int main (void) { |
---|
93 | roar_vs_t * vss; |
---|
94 | int err; /* see later */ |
---|
95 | |
---|
96 | vss = roar_vs_new_from_file(NULL, "some App", "somefile.ogg", &err); |
---|
97 | if ( vss == NULL ) { |
---|
98 | roar_vio_printf(roar_stderr, "Error: Can not connect to server: %s\n", roar_vs_strerr(err)); |
---|
99 | return 1; |
---|
100 | } |
---|
101 | |
---|
102 | if ( roar_vs_run(vss, &err) == \-1 ) { |
---|
103 | roar_vio_printf(roar_stderr, "Error: can not loop: %s\n", roar_vs_strerr(err)); |
---|
104 | } |
---|
105 | |
---|
106 | if ( roar_vs_close(vss, ROAR_VS_FALSE, &err) == \-1 ) { |
---|
107 | roar_vio_printf(roar_stderr, "Error: Can not close connection to server: %s\n", roar_vs_strerr(err)); |
---|
108 | return 1; |
---|
109 | } |
---|
110 | |
---|
111 | return 0; |
---|
112 | } |
---|
113 | |
---|
114 | //ll |
---|
115 | |
---|
116 | To compile and link we can use a command like this one: |
---|
117 | cc \-o vsfile vsfile.c `roar\-config \-\-libs \-\-cflags` |
---|
118 | |
---|
119 | The tool \fBroar-config\fR(1) will keep care for us about all flags needed for libroar. |
---|
120 | |
---|
121 | .SH "PLAYING A SINE" |
---|
122 | Now we want to write a application playing a sine for some secs. |
---|
123 | We start the same way by including the correct header files: |
---|
124 | #include <math.h> /* sin() */ |
---|
125 | #include <roaraudio.h> /* libroar */ |
---|
126 | |
---|
127 | After that we need some basic varibales with data about the audio we want to play back: |
---|
128 | int rate = ROAR_RATE_DEFAULT; |
---|
129 | int bits = 16; |
---|
130 | int channels = 1; /* mono */ |
---|
131 | |
---|
132 | Next we need to set the 'codec'. The codec is how the data is encoded. |
---|
133 | We want PCM as signed ints in the native byte order of our machine. |
---|
134 | int codec = ROAR_CODEC_DEFAULT; |
---|
135 | |
---|
136 | Now we need to store the frequency of our sine: |
---|
137 | float freq = 523.2; /* middle C */ |
---|
138 | float step = M_PI*2*freq/rate; /* how much time per sample we have to encode ... */ |
---|
139 | |
---|
140 | In addition we need some variables to store the current time and the length of time sine: |
---|
141 | float t = 0; /* current time */ |
---|
142 | float length = 5; /* 5 sec */ |
---|
143 | |
---|
144 | Next we need the buffer to hold the data as well as a varible used to go thru the buffer |
---|
145 | on generation of data. |
---|
146 | int16_t out[1024]; |
---|
147 | int i; |
---|
148 | |
---|
149 | last we need the VS object again as well as our error var: |
---|
150 | roar_vs_t * vss; |
---|
151 | int err; |
---|
152 | |
---|
153 | This time we open the connection to the server using \fBroar_vs_new_playback\fR(3). |
---|
154 | It is similar to \fBroar_vs_new_from_file\fR(3) but takes some other options: |
---|
155 | .TP |
---|
156 | \fBserver address\fR |
---|
157 | Same as above. |
---|
158 | |
---|
159 | .TP |
---|
160 | \fBprogram name\fR |
---|
161 | same as above. |
---|
162 | |
---|
163 | .TP |
---|
164 | \fBsample rate\fR |
---|
165 | The number of audio frames per sec. |
---|
166 | |
---|
167 | .TP |
---|
168 | \fBchannels\fR |
---|
169 | The number of samples (one per channel) per audio frame. |
---|
170 | |
---|
171 | .TP |
---|
172 | \fBcodec\fR |
---|
173 | The codec to be used. This is one of ROAR_CODEC_*. |
---|
174 | In our case we use ROAR_CODEC_DEFAULT which is signed PCM in CPU native format. |
---|
175 | |
---|
176 | .TP |
---|
177 | \fBbits\fR |
---|
178 | The number of bits per sample. |
---|
179 | |
---|
180 | .TP |
---|
181 | \fBerror var\fR |
---|
182 | same as above. |
---|
183 | |
---|
184 | .P |
---|
185 | The call looks like this: |
---|
186 | vss = roar_vs_new_playback(NULL, "vssin", rate, channels, codec, bits, &err); |
---|
187 | if ( vss == NULL ) { |
---|
188 | roar_vio_printf(roar_stderr, "Error: Can not connect to server: %s\n", roar_vs_strerr(err)); |
---|
189 | return 1; |
---|
190 | } |
---|
191 | |
---|
192 | Now we want to loop for \fBlength\fR seconds: |
---|
193 | while (t < 2*M_PI*freq*length) { |
---|
194 | } |
---|
195 | |
---|
196 | In this loop we need to calculate our samples: |
---|
197 | for (i = 0; i < (sizeof(out)/sizeof(*out)); i++) { |
---|
198 | out[i] = 32767.f*sin(t); |
---|
199 | t += step; |
---|
200 | } |
---|
201 | |
---|
202 | The sine is multiplyed by 32767 as our amplitude range for 16 bit signed int is from \-32768 to +32767. |
---|
203 | |
---|
204 | After we have our current data in \fBout\fR we want to write them to the server: |
---|
205 | if ( roar_vs_write(vss, out, sizeof(out), &err) == \-1 ) { |
---|
206 | roar_vio_printf(roar_stderr, "Error: Can not write audio data to server: %s\n", roar_vs_strerr(err)); |
---|
207 | break; |
---|
208 | } |
---|
209 | |
---|
210 | \fBNOTE:\fR In a real application you may want to check the return value for short writes: |
---|
211 | Those are writes shorter than the requested amount of data to be written. If you got any short writes |
---|
212 | you should try to rewrite the rest of your buffer later. This is not a error case. |
---|
213 | |
---|
214 | After we are finished with our main loop we have to close the connection to the server. |
---|
215 | This is done by \fBroar_vs_close\fR(3) as we already done in the file playback example: |
---|
216 | if ( roar_vs_close(vss, ROAR_VS_FALSE, &err) == \-1 ) { |
---|
217 | roar_vio_printf(roar_stderr, "Error: Can not close connection to server: %s\n", roar_vs_strerr(err)); |
---|
218 | return 1; |
---|
219 | } |
---|
220 | |
---|
221 | After adding some standard main() construct we should have something like this: |
---|
222 | //vssin.c: |
---|
223 | |
---|
224 | #include <roaraudio.h> |
---|
225 | #include <math.h> |
---|
226 | |
---|
227 | int main (void) { |
---|
228 | roar_vs_t * vss; |
---|
229 | int rate = ROAR_RATE_DEFAULT; |
---|
230 | int bits = 16; |
---|
231 | int channels = 1; /* mono */ |
---|
232 | int codec = ROAR_CODEC_DEFAULT; |
---|
233 | float freq = 523.2; /* middle C */ |
---|
234 | float step = M_PI*2*freq/rate; /* how much time per sample we have to encode ... */ |
---|
235 | float t = 0; /* current time */ |
---|
236 | float length = 5; /* 5 sec */ |
---|
237 | int16_t out[1024]; |
---|
238 | size_t i; |
---|
239 | int err; |
---|
240 | |
---|
241 | vss = roar_vs_new_playback(NULL, "vssin", rate, channels, codec, bits, &err); |
---|
242 | if ( vss == NULL ) { |
---|
243 | roar_vio_printf(roar_stderr, "Error: Can not connect to server: %s\n", roar_vs_strerr(err)); |
---|
244 | return 1; |
---|
245 | } |
---|
246 | |
---|
247 | while (t < 2*M_PI*freq*length) { |
---|
248 | for (i = 0; i < (sizeof(out)/sizeof(*out)); i++) { |
---|
249 | out[i] = 32768.f*sin(t); |
---|
250 | t += step; |
---|
251 | } |
---|
252 | |
---|
253 | if ( roar_vs_write(vss, out, sizeof(out), &err) == \-1 ) { |
---|
254 | roar_vio_printf(roar_stderr, "Error: Can not write audio data to server: %s\n", roar_vs_strerr(err)); |
---|
255 | break; |
---|
256 | } |
---|
257 | } |
---|
258 | |
---|
259 | if ( roar_vs_close(vss, ROAR_VS_FALSE, &err) == \-1 ) { |
---|
260 | roar_vio_printf(roar_stderr, "Error: Can not close connection to server: %s\n", roar_vs_strerr(err)); |
---|
261 | return 1; |
---|
262 | } |
---|
263 | |
---|
264 | return 0; |
---|
265 | } |
---|
266 | |
---|
267 | //ll |
---|
268 | |
---|
269 | To compile and link we can use a command like this one: |
---|
270 | cc \-o vssin vssin.c \-lm `roar\-config \-\-libs \-\-cflags` |
---|
271 | |
---|
272 | We need to use \fB-lm\fR to link the math library for \fBsin()\fR. |
---|
273 | The tool \fBroar-config\fR(1) will keep care for us about all flags needed for libroar. |
---|
274 | |
---|
275 | Now we should have a working binary \fBvssin\fR playing a sin() for 5 sec. |
---|
276 | |
---|
277 | Happy hacking! |
---|
278 | |
---|
279 | .SH "SEE ALSO" |
---|
280 | \fBroar-config\fR(1), |
---|
281 | \fBroarcat\fR(1), |
---|
282 | \fBlibroar\fR(7). |
---|
283 | \fBRoarAudio\fR(7). |
---|
284 | |
---|
285 | .\"ll |
---|