source: roaraudio/doc/man7/roartut.7 @ 4610:5802dc34dda3

Last change on this file since 4610:5802dc34dda3 was 4610:5802dc34dda3, checked in by phi, 12 years ago

updated manpage

File size: 9.0 KB
Line 
1.\" RoarAudio
2.TH "roartut" "7" "July 2008" "RoarAudio" "System Manager's Manual: RoarAuido"
3
4.SH NAME
5roartut \- RoarAudio sound library developer tutorial
6
7.\".SH SYNOPSIS
8
9.\" #include <roaraudio.h>
10
11.SH "DESCRIPTION"
12This tutorial descipes some basics with working with libroar. We will create a simple application
13that can play a file and one that can play some sines.
14A lot of other examples can be found in RoarAudio's sources in the roarclients directory.
15
16This tutorial will cover some basics of the so called VS API.
17The VS API is a abstract layer ontop of the normal API. It is designed to be simple
18yet powerful. The VS API is all you need for most applications. If you need
19more control over what you do you must use the normal. If you need only
20a little of those extra power you can mix VS API and normal API.
21
22.SH "PLAYING A FILE"
23Playing back a file is a easy task with libroar. The VS API has some special support to play
24back files in a very simple way. This is shown here.
25
26First of all we need to include the needed header files:
27 #include <roaraudio.h>  /* libroar */
28
29This main header already includes all we need to use the VS API.
30
31Now we can start our main(). We need to declare a object for the
32VS API as it is object oriented. This object is used to interact with the server
33and send all audio data to it:
34 roar_vs_t * vss;
35 int err; /* see later */
36
37Next we need to open the connection to the server. The most simple function
38to do this is \fBroar_vs_new_from_file\fR(3) if we are going to play a file.
39It takes the folloing arguments:
40.TP
41\fBserver address\fR
42This is the address of the server. In general case This should be set to NULL.
43
44.TP
45\fBprogram name\fR
46This is the name of our program. This should be set to some name the user
47will recognize like "some App", "some Game". It \fBshould not\fR contain the filename
48of the process like "/usr/bin/someapp.bin".
49
50.TP
51\fBfile name\fR
52This is the name of the file we want to play. In fact this is a URL.
53VS API uses so called DSTR API to open files. DSTR API supports local files as well as
54for example HTTP. Examples include: "somefile.ogg", "file:///data/bla.wav",
55"http://radiostation.org:8000/bla.ogg".
56
57.TP
58\fBerror var\fR
59This is a pointer to a int used to store the error value in case of error.
60This can be set to NULL but should not. The function \fBroar_vs_strerr\fR(3)
61can be used to get a lion readable string of the error.
62
63.P
64Our 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
71Next we need to continuously feed in the data so the server can do the playback.
72Again 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
78This will block untill all of the file is played.
79
80After it returned must close the VS object. This should be done directly
81after \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
87After 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
116To compile and link we can use a command like this one:
117 cc \-o vsfile vsfile.c `roar\-config \-\-libs \-\-cflags`
118
119The tool \fBroar-config\fR(1) will keep care for us about all flags needed for libroar.
120
121.SH "PLAYING A SINE"
122Now we want to write a application playing a sine for some secs.
123We start the same way by including the correct header files:
124 #include <math.h>       /* sin() */
125 #include <roaraudio.h>  /* libroar */
126
127After 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
132Next we need to set the 'codec'. The codec is how the data is encoded.
133We want PCM as signed ints in the native byte order of our machine.
134 int codec    = ROAR_CODEC_DEFAULT;
135
136Now 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
140In 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
144Next we need the buffer to hold the data as well as a varible used to go thru the buffer
145on generation of data.
146 int16_t out[1024];
147 int i;
148
149last we need the VS object again as well as our error var:
150 roar_vs_t * vss;
151 int err;
152
153This time we open the connection to the server using \fBroar_vs_new_playback\fR(3).
154It is similar to \fBroar_vs_new_from_file\fR(3) but takes some other options:
155.TP
156\fBserver address\fR
157Same as above.
158
159.TP
160\fBprogram name\fR
161same as above.
162
163.TP
164\fBsample rate\fR
165The number of audio frames per sec.
166
167.TP
168\fBchannels\fR
169The number of samples (one per channel) per audio frame.
170
171.TP
172\fBcodec\fR
173The codec to be used. This is one of ROAR_CODEC_*.
174In our case we use ROAR_CODEC_DEFAULT which is signed PCM in CPU native format.
175
176.TP
177\fBbits\fR
178The number of bits per sample.
179
180.TP
181\fBerror var\fR
182same as above.
183
184.P
185The 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
192Now we want to loop for \fBlength\fR seconds:
193 while (t < 2*M_PI*freq*length) {
194 }
195
196In 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
202The sine is multiplyed by 32767 as our amplitude range for 16 bit signed int is from \-32768 to +32767.
203
204After 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:
211Those are writes shorter than the requested amount of data to be written. If you got any short writes
212you should try to rewrite the rest of your buffer later. This is not a error case.
213
214After we are finished with our main loop we have to close the connection to the server.
215This 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
221After 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
269To compile and link we can use a command like this one:
270 cc \-o vssin vssin.c \-lm `roar\-config \-\-libs \-\-cflags`
271
272We need to use \fB-lm\fR to link the math library for \fBsin()\fR.
273The tool \fBroar-config\fR(1) will keep care for us about all flags needed for libroar.
274
275Now we should have a working binary \fBvssin\fR playing a sin() for 5 sec.
276
277Happy 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
Note: See TracBrowser for help on using the repository browser.